From dbe2f0c8f6010d2d7d44de35cfe9ea24d35ee50b Mon Sep 17 00:00:00 2001 From: sam boyer Date: Tue, 31 Jan 2023 04:50:08 -0500 Subject: [PATCH] Kindsys: Replace "Declaration" with "Definition" (#62515) * s/Declaration/Definition/g * s/DeclForGen/DefForGen/g * Rename some local vars --- kinds/gen.go | 6 +- pkg/codegen/generators.go | 43 ++++++------ pkg/codegen/jenny_basecorereg.go | 4 +- pkg/codegen/jenny_corekind.go | 16 ++--- pkg/codegen/jenny_docs.go | 8 +-- pkg/codegen/jenny_eachmajor.go | 10 +-- pkg/codegen/jenny_tsveneerindex.go | 36 +++++----- pkg/codegen/latest_jenny.go | 10 +-- pkg/codegen/tmpl.go | 2 +- pkg/codegen/tmpl/kind_core.tmpl | 26 ++++---- pkg/codegen/util_go.go | 10 +-- pkg/kinds/dashboard/dashboard_kind_gen.go | 26 ++++---- .../librarypanel/librarypanel_kind_gen.go | 26 ++++---- pkg/kinds/playlist/playlist_kind_gen.go | 26 ++++---- pkg/kinds/preferences/preferences_kind_gen.go | 26 ++++---- .../publicdashboard_kind_gen.go | 26 ++++---- .../serviceaccount/serviceaccount_kind_gen.go | 26 ++++---- pkg/kinds/team/team_kind_gen.go | 26 ++++---- pkg/kindsys/EXTENDING.md | 12 ++-- pkg/kindsys/bind.go | 22 +++---- pkg/kindsys/errors.go | 2 +- pkg/kindsys/kind.go | 18 ++--- pkg/kindsys/kindcat_composable.cue | 2 +- pkg/kindsys/kindcat_custom.cue | 2 +- pkg/kindsys/kindcats.cue | 4 +- pkg/kindsys/load.go | 66 +++++++++---------- pkg/kindsys/{kindmetas.go => props.go} | 12 ++-- pkg/kindsys/report.go | 4 +- pkg/kindsys/schema_interface.go | 8 +-- pkg/plugins/pfs/decl.go | 2 +- pkg/plugins/pfs/decl_parser.go | 2 +- pkg/plugins/pfs/pfs.go | 2 +- pkg/plugins/pfs/plugin.go | 8 +-- public/app/plugins/gen.go | 4 +- 34 files changed, 262 insertions(+), 261 deletions(-) rename pkg/kindsys/{kindmetas.go => props.go} (85%) diff --git a/kinds/gen.go b/kinds/gen.go index 638647b7492..930a157d2ca 100644 --- a/kinds/gen.go +++ b/kinds/gen.go @@ -31,8 +31,8 @@ func main() { // Core kinds composite code generator. Produces all generated code in // grafana/grafana that derives from core kinds. - coreKindsGen := codejen.JennyListWithNamer(func(decl *codegen.DeclForGen) string { - return decl.Properties.Common().MachineName + coreKindsGen := codejen.JennyListWithNamer(func(def *codegen.DefForGen) string { + return def.Properties.Common().MachineName }) // All the jennies that comprise the core kinds generator pipeline @@ -56,7 +56,7 @@ func main() { groot := filepath.Dir(cwd) rt := cuectx.GrafanaThemaRuntime() - var all []*codegen.DeclForGen + var all []*codegen.DefForGen f := os.DirFS(filepath.Join(groot, kindsys.CoreDeclParentPath)) kinddirs := elsedie(fs.ReadDir(f, "."))("error reading core kind fs root directory") diff --git a/pkg/codegen/generators.go b/pkg/codegen/generators.go index 1c6d0743f9f..2b5e48b61ca 100644 --- a/pkg/codegen/generators.go +++ b/pkg/codegen/generators.go @@ -10,44 +10,45 @@ import ( "github.com/grafana/thema" ) -type OneToOne codejen.OneToOne[*DeclForGen] -type OneToMany codejen.OneToMany[*DeclForGen] -type ManyToOne codejen.ManyToOne[*DeclForGen] -type ManyToMany codejen.ManyToMany[*DeclForGen] +type OneToOne codejen.OneToOne[*DefForGen] +type OneToMany codejen.OneToMany[*DefForGen] +type ManyToOne codejen.ManyToOne[*DefForGen] +type ManyToMany codejen.ManyToMany[*DefForGen] -// ForGen is a codejen input transformer that converts a pure kindsys.SomeDecl into -// a DeclForGen by binding its contained lineage. -func ForGen(rt *thema.Runtime, decl kindsys.SomeDecl) (*DeclForGen, error) { - lin, err := decl.BindKindLineage(rt) +// ForGen is a codejen input transformer that converts a pure kindsys.SomeDef into +// a DefForGen by binding its contained lineage. +func ForGen(rt *thema.Runtime, def kindsys.SomeDef) (*DefForGen, error) { + lin, err := def.BindKindLineage(rt) if err != nil { return nil, err } - return &DeclForGen{ - SomeDecl: decl, - lin: lin, + return &DefForGen{ + SomeDef: def, + lin: lin, }, nil } -// DeclForGen wraps [kindsys.SomeDecl] to provide trivial caching of +// DefForGen wraps [kindsys.SomeDef] to provide trivial caching of // the lineage declared by the kind (nil for raw kinds). -type DeclForGen struct { - kindsys.SomeDecl +// TODO this type is unneeded - kindsys.Kind is sufficient. +type DefForGen struct { + kindsys.SomeDef lin thema.Lineage } -// Lineage returns the [thema.Lineage] for the underlying [kindsys.SomeDecl]. -func (decl *DeclForGen) Lineage() thema.Lineage { - return decl.lin +// Lineage returns the [thema.Lineage] for the underlying [kindsys.SomeDef]. +func (def *DefForGen) Lineage() thema.Lineage { + return def.lin } // ForLatestSchema returns a [SchemaForGen] for the latest schema in this -// DeclForGen's lineage. -func (decl *DeclForGen) ForLatestSchema() SchemaForGen { - comm := decl.Properties.Common() +// DefForGen's lineage. +func (def *DefForGen) ForLatestSchema() SchemaForGen { + comm := def.Properties.Common() return SchemaForGen{ Name: comm.Name, - Schema: decl.Lineage().Latest(), + Schema: def.Lineage().Latest(), IsGroup: comm.LineageIsGroup, } } diff --git a/pkg/codegen/jenny_basecorereg.go b/pkg/codegen/jenny_basecorereg.go index d97dfd3e6cc..4be4722881a 100644 --- a/pkg/codegen/jenny_basecorereg.go +++ b/pkg/codegen/jenny_basecorereg.go @@ -31,12 +31,12 @@ func (gen *genBaseRegistry) JennyName() string { return "BaseCoreRegistryJenny" } -func (gen *genBaseRegistry) Generate(decls ...*DeclForGen) (*codejen.File, error) { +func (gen *genBaseRegistry) Generate(defs ...*DefForGen) (*codejen.File, error) { buf := new(bytes.Buffer) if err := tmpls.Lookup("kind_registry.tmpl").Execute(buf, tvars_kind_registry{ PackageName: filepath.Base(gen.path), KindPackagePrefix: filepath.ToSlash(filepath.Join("github.com/grafana/grafana", gen.kindrelroot)), - Kinds: decls, + Kinds: defs, }); err != nil { return nil, fmt.Errorf("failed executing kind registry template: %w", err) } diff --git a/pkg/codegen/jenny_corekind.go b/pkg/codegen/jenny_corekind.go index 806ab2531ad..575ef4fdf11 100644 --- a/pkg/codegen/jenny_corekind.go +++ b/pkg/codegen/jenny_corekind.go @@ -20,8 +20,8 @@ func CoreKindJenny(gokindsdir string, cfg *CoreKindJennyConfig) OneToOne { cfg = new(CoreKindJennyConfig) } if cfg.GenDirName == nil { - cfg.GenDirName = func(decl *DeclForGen) string { - return decl.Properties.Common().MachineName + cfg.GenDirName = func(def *DefForGen) string { + return def.Properties.Common().MachineName } } @@ -34,8 +34,8 @@ func CoreKindJenny(gokindsdir string, cfg *CoreKindJennyConfig) OneToOne { // CoreKindJennyConfig holds configuration options for [CoreKindJenny]. type CoreKindJennyConfig struct { // GenDirName returns the name of the directory in which the file should be - // generated. Defaults to DeclForGen.Lineage().Name() if nil. - GenDirName func(*DeclForGen) string + // generated. Defaults to DefForGen.Lineage().Name() if nil. + GenDirName func(*DefForGen) string } type coreKindJenny struct { @@ -49,14 +49,14 @@ func (gen *coreKindJenny) JennyName() string { return "CoreKindJenny" } -func (gen *coreKindJenny) Generate(decl *DeclForGen) (*codejen.File, error) { - if !decl.IsCore() { +func (gen *coreKindJenny) Generate(def *DefForGen) (*codejen.File, error) { + if !def.IsCore() { return nil, nil } - path := filepath.Join(gen.gokindsdir, gen.cfg.GenDirName(decl), decl.Properties.Common().MachineName+"_kind_gen.go") + path := filepath.Join(gen.gokindsdir, gen.cfg.GenDirName(def), def.Properties.Common().MachineName+"_kind_gen.go") buf := new(bytes.Buffer) - if err := tmpls.Lookup("kind_core.tmpl").Execute(buf, decl); err != nil { + if err := tmpls.Lookup("kind_core.tmpl").Execute(buf, def); err != nil { return nil, fmt.Errorf("failed executing kind_core template for %s: %w", path, err) } b, err := postprocessGoFile(genGoFile{ diff --git a/pkg/codegen/jenny_docs.go b/pkg/codegen/jenny_docs.go index 1d899df3b70..d163e6f895b 100644 --- a/pkg/codegen/jenny_docs.go +++ b/pkg/codegen/jenny_docs.go @@ -34,8 +34,8 @@ func (j docsJenny) JennyName() string { return "DocsJenny" } -func (j docsJenny) Generate(decl *DeclForGen) (*codejen.File, error) { - f, err := jsonschema.GenerateSchema(decl.Lineage().Latest()) +func (j docsJenny) Generate(def *DefForGen) (*codejen.File, error) { + f, err := jsonschema.GenerateSchema(def.Lineage().Latest()) if err != nil { return nil, fmt.Errorf("failed to generate json representation for the schema: %v", err) } @@ -61,10 +61,10 @@ func (j docsJenny) Generate(decl *DeclForGen) (*codejen.File, error) { // fixes the references between the types within a json after making components.schema. the root of the json kindJsonStr := strings.Replace(string(obj.Components.Schemas), "#/components/schemas/", "#/", -1) - kindProps := decl.Properties.Common() + kindProps := def.Properties.Common() data := templateData{ KindName: kindProps.Name, - KindVersion: decl.Lineage().Latest().Version().String(), + KindVersion: def.Lineage().Latest().Version().String(), KindMaturity: string(kindProps.Maturity), Markdown: "{{ .Markdown 1 }}", } diff --git a/pkg/codegen/jenny_eachmajor.go b/pkg/codegen/jenny_eachmajor.go index 1725a2565c1..bd46a66fe94 100644 --- a/pkg/codegen/jenny_eachmajor.go +++ b/pkg/codegen/jenny_eachmajor.go @@ -29,8 +29,8 @@ func (j *lmox) JennyName() string { return "LatestMajorsOrXJenny" } -func (j *lmox) Generate(decl *DeclForGen) (codejen.Files, error) { - comm := decl.Properties.Common() +func (j *lmox) Generate(def *DefForGen) (codejen.Files, error) { + comm := def.Properties.Common() sfg := SchemaForGen{ Name: comm.Name, IsGroup: comm.LineageIsGroup, @@ -39,7 +39,7 @@ func (j *lmox) Generate(decl *DeclForGen) (codejen.Files, error) { do := func(sfg SchemaForGen, infix string) (codejen.Files, error) { f, err := j.inner.Generate(sfg) if err != nil { - return nil, fmt.Errorf("%s jenny failed on %s schema for %s: %w", j.inner.JennyName(), sfg.Schema.Version(), decl.Properties.Common().Name, err) + return nil, fmt.Errorf("%s jenny failed on %s schema for %s: %w", j.inner.JennyName(), sfg.Schema.Version(), def.Properties.Common().Name, err) } if f == nil || !f.Exists() { return nil, nil @@ -51,12 +51,12 @@ func (j *lmox) Generate(decl *DeclForGen) (codejen.Files, error) { } if comm.Maturity.Less(kindsys.MaturityStable) { - sfg.Schema = decl.Lineage().Latest() + sfg.Schema = def.Lineage().Latest() return do(sfg, "x") } var fl codejen.Files - for sch := decl.Lineage().First(); sch != nil; sch = sch.Successor() { + for sch := def.Lineage().First(); sch != nil; sch = sch.Successor() { sfg.Schema = sch.LatestInMajor() files, err := do(sfg, fmt.Sprintf("v%v", sch.Version()[0])) if err != nil { diff --git a/pkg/codegen/jenny_tsveneerindex.go b/pkg/codegen/jenny_tsveneerindex.go index 352d0af1677..ccf1d5d3dbc 100644 --- a/pkg/codegen/jenny_tsveneerindex.go +++ b/pkg/codegen/jenny_tsveneerindex.go @@ -39,20 +39,20 @@ func (gen *genTSVeneerIndex) JennyName() string { return "TSVeneerIndexJenny" } -func (gen *genTSVeneerIndex) Generate(decls ...*DeclForGen) (*codejen.File, error) { +func (gen *genTSVeneerIndex) Generate(decls ...*DefForGen) (*codejen.File, error) { tsf := new(ast.File) - for _, decl := range decls { - sch := decl.Lineage().Latest() + for _, def := range decls { + sch := def.Lineage().Latest() f, err := typescript.GenerateTypes(sch, &typescript.TypeConfig{ - RootName: decl.Properties.Common().Name, - Group: decl.Properties.Common().LineageIsGroup, + RootName: def.Properties.Common().Name, + Group: def.Properties.Common().LineageIsGroup, }) if err != nil { - return nil, fmt.Errorf("%s: %w", decl.Properties.Common().Name, err) + return nil, fmt.Errorf("%s: %w", def.Properties.Common().Name, err) } - elems, err := gen.extractTSIndexVeneerElements(decl, f) + elems, err := gen.extractTSIndexVeneerElements(def, f) if err != nil { - return nil, fmt.Errorf("%s: %w", decl.Properties.Common().Name, err) + return nil, fmt.Errorf("%s: %w", def.Properties.Common().Name, err) } tsf.Nodes = append(tsf.Nodes, elems...) } @@ -60,9 +60,9 @@ func (gen *genTSVeneerIndex) Generate(decls ...*DeclForGen) (*codejen.File, erro return codejen.NewFile(filepath.Join(gen.dir, "index.gen.ts"), []byte(tsf.String()), gen), nil } -func (gen *genTSVeneerIndex) extractTSIndexVeneerElements(decl *DeclForGen, tf *ast.File) ([]ast.Decl, error) { - lin := decl.Lineage() - comm := decl.Properties.Common() +func (gen *genTSVeneerIndex) extractTSIndexVeneerElements(def *DefForGen, tf *ast.File) ([]ast.Decl, error) { + lin := def.Lineage() + comm := def.Properties.Common() // Check the root, then walk the tree rootv := lin.Latest().Underlying() @@ -90,7 +90,7 @@ func (gen *genTSVeneerIndex) extractTSIndexVeneerElements(decl *DeclForGen, tf * name = sels[0].String() } - // Search the generated TS AST for the type and default decl nodes + // Search the generated TS AST for the type and default def nodes pair := findDeclNode(name, tf) if pair.T == nil { // No generated type for this item, skip it @@ -139,7 +139,7 @@ func (gen *genTSVeneerIndex) extractTSIndexVeneerElements(decl *DeclForGen, tf * } vpath := fmt.Sprintf("v%v", thema.LatestVersion(lin)[0]) - if decl.Properties.Common().Maturity.Less(kindsys.MaturityStable) { + if def.Properties.Common().Maturity.Less(kindsys.MaturityStable) { vpath = "x" } @@ -190,7 +190,7 @@ func (gen *genTSVeneerIndex) extractTSIndexVeneerElements(decl *DeclForGen, tf * }) } - // TODO emit a decl in the index.gen.ts that ensures any custom veneer types are "compatible" with current version raw types + // TODO emit a def in the index.gen.ts that ensures any custom veneer types are "compatible" with current version raw types return ret, nil } @@ -205,13 +205,13 @@ type tsVeneerAttr struct { func findDeclNode(name string, tf *ast.File) declPair { var p declPair - for _, decl := range tf.Nodes { + for _, def := range tf.Nodes { // Peer through export keywords - if ex, is := decl.(ast.ExportKeyword); is { - decl = ex.Decl + if ex, is := def.(ast.ExportKeyword); is { + def = ex.Decl } - switch x := decl.(type) { + switch x := def.(type) { case ast.TypeDecl: if x.Name.Name == name { p.T = &x.Name diff --git a/pkg/codegen/latest_jenny.go b/pkg/codegen/latest_jenny.go index c93a2999283..9947559b393 100644 --- a/pkg/codegen/latest_jenny.go +++ b/pkg/codegen/latest_jenny.go @@ -8,7 +8,7 @@ import ( ) // LatestJenny returns a jenny that runs another jenny for only the latest -// schema in a DeclForGen, and prefixes the resulting file with the provided +// schema in a DefForGen, and prefixes the resulting file with the provided // parentdir (e.g. "pkg/kinds/") and with a directory based on the kind's // machine name (e.g. "dashboard/"). func LatestJenny(parentdir string, inner codejen.OneToOne[SchemaForGen]) OneToOne { @@ -31,17 +31,17 @@ func (j *latestj) JennyName() string { return "LatestJenny" } -func (j *latestj) Generate(decl *DeclForGen) (*codejen.File, error) { - comm := decl.Properties.Common() +func (j *latestj) Generate(def *DefForGen) (*codejen.File, error) { + comm := def.Properties.Common() sfg := SchemaForGen{ Name: comm.Name, - Schema: decl.Lineage().Latest(), + Schema: def.Lineage().Latest(), IsGroup: comm.LineageIsGroup, } f, err := j.inner.Generate(sfg) if err != nil { - return nil, fmt.Errorf("%s jenny failed on %s schema for %s: %w", j.inner.JennyName(), sfg.Schema.Version(), decl.Properties.Common().Name, err) + return nil, fmt.Errorf("%s jenny failed on %s schema for %s: %w", j.inner.JennyName(), sfg.Schema.Version(), def.Properties.Common().Name, err) } if f == nil || !f.Exists() { return nil, nil diff --git a/pkg/codegen/tmpl.go b/pkg/codegen/tmpl.go index 3c1668bb216..d0b5071dd70 100644 --- a/pkg/codegen/tmpl.go +++ b/pkg/codegen/tmpl.go @@ -40,7 +40,7 @@ type ( // Header tvars_autogen_header PackageName string KindPackagePrefix string - Kinds []*DeclForGen + Kinds []*DefForGen } tvars_coremodel_imports struct { PackageName string diff --git a/pkg/codegen/tmpl/kind_core.tmpl b/pkg/codegen/tmpl/kind_core.tmpl index eac0d9bc7e2..1ffb689e385 100644 --- a/pkg/codegen/tmpl/kind_core.tmpl +++ b/pkg/codegen/tmpl/kind_core.tmpl @@ -7,8 +7,8 @@ import ( ) // rootrel is the relative path from the grafana repository root to the -// directory containing the .cue files in which this kind is declared. Necessary -// for runtime errors related to the declaration and/or lineage to provide +// directory containing the .cue files in which this kind is defined. Necessary +// for runtime errors related to the definition and/or lineage to provide // a real path to the correct .cue file. const rootrel string = "kinds/{{ .Properties.MachineName }}" @@ -17,7 +17,7 @@ type Kind struct { lin thema.ConvergentLineage[*{{ .Properties.Name }}] jcodec vmux.Codec valmux vmux.ValueMux[*{{ .Properties.Name }}] - decl kindsys.Decl[kindsys.CoreProperties] + def kindsys.Def[kindsys.CoreProperties] } // type guard @@ -25,22 +25,22 @@ var _ kindsys.Core = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) + def, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) if err != nil { return nil, err } k := &Kind{ - decl: decl, + def: def, } - lin, err := decl.Some().BindKindLineage(rt, opts...) + lin, err := def.Some().BindKindLineage(rt, opts...) if err != nil { return nil, err } // Get the thema.Schema that the meta says is in the current version (which // codegen ensures is always the latest) - cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) + cursch := thema.SchemaP(lin, k.def.Properties.CurrentVersion) tsch, err := thema.BindType[*{{ .Properties.Name }}](cursch, &{{ .Properties.Name }}{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -86,19 +86,19 @@ func (k *Kind) JSONValueMux(b []byte) (*{{ .Properties.Name }}, thema.Translatio // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Properties.Maturity + return k.def.Properties.Maturity } -// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// Def returns the [kindsys.Def] containing both CUE and Go representations of the // {{ .Properties.MachineName }} declaration in .cue files. -func (k *Kind) Decl() kindsys.Decl[kindsys.CoreProperties] { - return k.decl +func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] { + return k.def } // Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreProperties], // representing the static properties declared in the {{ .Properties.MachineName }} kind. // -// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +// This method is identical to calling Def().Props. It is provided to satisfy [kindsys.Interface]. func (k *Kind) Props() kindsys.SomeKindProperties { - return k.decl.Properties + return k.def.Properties } diff --git a/pkg/codegen/util_go.go b/pkg/codegen/util_go.go index 7bfd905b23c..2cd172b5d66 100644 --- a/pkg/codegen/util_go.go +++ b/pkg/codegen/util_go.go @@ -126,17 +126,17 @@ func (d prefixmod) applyfunc(c *dstutil.Cursor) bool { // field value specifications that reference those types. d.handleExpr(x.Type) case *dst.File: - for _, decl := range x.Decls { - comments := decl.Decorations().Start.All() - decl.Decorations().Start.Clear() + for _, def := range x.Decls { + comments := def.Decorations().Start.All() + def.Decorations().Start.Clear() // For any reason, sometimes it retrieves the comment duplicated 🤷 commentMap := make(map[string]bool) for _, c := range comments { if _, ok := commentMap[c]; !ok { commentMap[c] = true - decl.Decorations().Start.Append(d.rxpsuff.ReplaceAllString(c, "$1")) + def.Decorations().Start.Append(d.rxpsuff.ReplaceAllString(c, "$1")) if d.replace != "" { - decl.Decorations().Start.Append(d.rxp.ReplaceAllString(c, d.replace+"$1")) + def.Decorations().Start.Append(d.rxp.ReplaceAllString(c, d.replace+"$1")) } } } diff --git a/pkg/kinds/dashboard/dashboard_kind_gen.go b/pkg/kinds/dashboard/dashboard_kind_gen.go index 2f228a3e55a..a77fd521dc7 100644 --- a/pkg/kinds/dashboard/dashboard_kind_gen.go +++ b/pkg/kinds/dashboard/dashboard_kind_gen.go @@ -16,8 +16,8 @@ import ( ) // rootrel is the relative path from the grafana repository root to the -// directory containing the .cue files in which this kind is declared. Necessary -// for runtime errors related to the declaration and/or lineage to provide +// directory containing the .cue files in which this kind is defined. Necessary +// for runtime errors related to the definition and/or lineage to provide // a real path to the correct .cue file. const rootrel string = "kinds/dashboard" @@ -26,7 +26,7 @@ type Kind struct { lin thema.ConvergentLineage[*Dashboard] jcodec vmux.Codec valmux vmux.ValueMux[*Dashboard] - decl kindsys.Decl[kindsys.CoreProperties] + def kindsys.Def[kindsys.CoreProperties] } // type guard @@ -34,22 +34,22 @@ var _ kindsys.Core = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) + def, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) if err != nil { return nil, err } k := &Kind{ - decl: decl, + def: def, } - lin, err := decl.Some().BindKindLineage(rt, opts...) + lin, err := def.Some().BindKindLineage(rt, opts...) if err != nil { return nil, err } // Get the thema.Schema that the meta says is in the current version (which // codegen ensures is always the latest) - cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) + cursch := thema.SchemaP(lin, k.def.Properties.CurrentVersion) tsch, err := thema.BindType[*Dashboard](cursch, &Dashboard{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -95,19 +95,19 @@ func (k *Kind) JSONValueMux(b []byte) (*Dashboard, thema.TranslationLacunas, err // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Properties.Maturity + return k.def.Properties.Maturity } -// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// Def returns the [kindsys.Def] containing both CUE and Go representations of the // dashboard declaration in .cue files. -func (k *Kind) Decl() kindsys.Decl[kindsys.CoreProperties] { - return k.decl +func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] { + return k.def } // Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreProperties], // representing the static properties declared in the dashboard kind. // -// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +// This method is identical to calling Def().Props. It is provided to satisfy [kindsys.Interface]. func (k *Kind) Props() kindsys.SomeKindProperties { - return k.decl.Properties + return k.def.Properties } diff --git a/pkg/kinds/librarypanel/librarypanel_kind_gen.go b/pkg/kinds/librarypanel/librarypanel_kind_gen.go index 564ddfb169c..c5d24146c73 100644 --- a/pkg/kinds/librarypanel/librarypanel_kind_gen.go +++ b/pkg/kinds/librarypanel/librarypanel_kind_gen.go @@ -16,8 +16,8 @@ import ( ) // rootrel is the relative path from the grafana repository root to the -// directory containing the .cue files in which this kind is declared. Necessary -// for runtime errors related to the declaration and/or lineage to provide +// directory containing the .cue files in which this kind is defined. Necessary +// for runtime errors related to the definition and/or lineage to provide // a real path to the correct .cue file. const rootrel string = "kinds/librarypanel" @@ -26,7 +26,7 @@ type Kind struct { lin thema.ConvergentLineage[*LibraryPanel] jcodec vmux.Codec valmux vmux.ValueMux[*LibraryPanel] - decl kindsys.Decl[kindsys.CoreProperties] + def kindsys.Def[kindsys.CoreProperties] } // type guard @@ -34,22 +34,22 @@ var _ kindsys.Core = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) + def, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) if err != nil { return nil, err } k := &Kind{ - decl: decl, + def: def, } - lin, err := decl.Some().BindKindLineage(rt, opts...) + lin, err := def.Some().BindKindLineage(rt, opts...) if err != nil { return nil, err } // Get the thema.Schema that the meta says is in the current version (which // codegen ensures is always the latest) - cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) + cursch := thema.SchemaP(lin, k.def.Properties.CurrentVersion) tsch, err := thema.BindType[*LibraryPanel](cursch, &LibraryPanel{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -95,19 +95,19 @@ func (k *Kind) JSONValueMux(b []byte) (*LibraryPanel, thema.TranslationLacunas, // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Properties.Maturity + return k.def.Properties.Maturity } -// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// Def returns the [kindsys.Def] containing both CUE and Go representations of the // librarypanel declaration in .cue files. -func (k *Kind) Decl() kindsys.Decl[kindsys.CoreProperties] { - return k.decl +func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] { + return k.def } // Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreProperties], // representing the static properties declared in the librarypanel kind. // -// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +// This method is identical to calling Def().Props. It is provided to satisfy [kindsys.Interface]. func (k *Kind) Props() kindsys.SomeKindProperties { - return k.decl.Properties + return k.def.Properties } diff --git a/pkg/kinds/playlist/playlist_kind_gen.go b/pkg/kinds/playlist/playlist_kind_gen.go index 202a8883e42..34ecf687be9 100644 --- a/pkg/kinds/playlist/playlist_kind_gen.go +++ b/pkg/kinds/playlist/playlist_kind_gen.go @@ -16,8 +16,8 @@ import ( ) // rootrel is the relative path from the grafana repository root to the -// directory containing the .cue files in which this kind is declared. Necessary -// for runtime errors related to the declaration and/or lineage to provide +// directory containing the .cue files in which this kind is defined. Necessary +// for runtime errors related to the definition and/or lineage to provide // a real path to the correct .cue file. const rootrel string = "kinds/playlist" @@ -26,7 +26,7 @@ type Kind struct { lin thema.ConvergentLineage[*Playlist] jcodec vmux.Codec valmux vmux.ValueMux[*Playlist] - decl kindsys.Decl[kindsys.CoreProperties] + def kindsys.Def[kindsys.CoreProperties] } // type guard @@ -34,22 +34,22 @@ var _ kindsys.Core = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) + def, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) if err != nil { return nil, err } k := &Kind{ - decl: decl, + def: def, } - lin, err := decl.Some().BindKindLineage(rt, opts...) + lin, err := def.Some().BindKindLineage(rt, opts...) if err != nil { return nil, err } // Get the thema.Schema that the meta says is in the current version (which // codegen ensures is always the latest) - cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) + cursch := thema.SchemaP(lin, k.def.Properties.CurrentVersion) tsch, err := thema.BindType[*Playlist](cursch, &Playlist{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -95,19 +95,19 @@ func (k *Kind) JSONValueMux(b []byte) (*Playlist, thema.TranslationLacunas, erro // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Properties.Maturity + return k.def.Properties.Maturity } -// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// Def returns the [kindsys.Def] containing both CUE and Go representations of the // playlist declaration in .cue files. -func (k *Kind) Decl() kindsys.Decl[kindsys.CoreProperties] { - return k.decl +func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] { + return k.def } // Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreProperties], // representing the static properties declared in the playlist kind. // -// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +// This method is identical to calling Def().Props. It is provided to satisfy [kindsys.Interface]. func (k *Kind) Props() kindsys.SomeKindProperties { - return k.decl.Properties + return k.def.Properties } diff --git a/pkg/kinds/preferences/preferences_kind_gen.go b/pkg/kinds/preferences/preferences_kind_gen.go index 4ffd0a15688..43cd677757b 100644 --- a/pkg/kinds/preferences/preferences_kind_gen.go +++ b/pkg/kinds/preferences/preferences_kind_gen.go @@ -16,8 +16,8 @@ import ( ) // rootrel is the relative path from the grafana repository root to the -// directory containing the .cue files in which this kind is declared. Necessary -// for runtime errors related to the declaration and/or lineage to provide +// directory containing the .cue files in which this kind is defined. Necessary +// for runtime errors related to the definition and/or lineage to provide // a real path to the correct .cue file. const rootrel string = "kinds/preferences" @@ -26,7 +26,7 @@ type Kind struct { lin thema.ConvergentLineage[*Preferences] jcodec vmux.Codec valmux vmux.ValueMux[*Preferences] - decl kindsys.Decl[kindsys.CoreProperties] + def kindsys.Def[kindsys.CoreProperties] } // type guard @@ -34,22 +34,22 @@ var _ kindsys.Core = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) + def, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) if err != nil { return nil, err } k := &Kind{ - decl: decl, + def: def, } - lin, err := decl.Some().BindKindLineage(rt, opts...) + lin, err := def.Some().BindKindLineage(rt, opts...) if err != nil { return nil, err } // Get the thema.Schema that the meta says is in the current version (which // codegen ensures is always the latest) - cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) + cursch := thema.SchemaP(lin, k.def.Properties.CurrentVersion) tsch, err := thema.BindType[*Preferences](cursch, &Preferences{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -95,19 +95,19 @@ func (k *Kind) JSONValueMux(b []byte) (*Preferences, thema.TranslationLacunas, e // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Properties.Maturity + return k.def.Properties.Maturity } -// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// Def returns the [kindsys.Def] containing both CUE and Go representations of the // preferences declaration in .cue files. -func (k *Kind) Decl() kindsys.Decl[kindsys.CoreProperties] { - return k.decl +func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] { + return k.def } // Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreProperties], // representing the static properties declared in the preferences kind. // -// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +// This method is identical to calling Def().Props. It is provided to satisfy [kindsys.Interface]. func (k *Kind) Props() kindsys.SomeKindProperties { - return k.decl.Properties + return k.def.Properties } diff --git a/pkg/kinds/publicdashboard/publicdashboard_kind_gen.go b/pkg/kinds/publicdashboard/publicdashboard_kind_gen.go index 70add7f3adb..cf4d833dffc 100644 --- a/pkg/kinds/publicdashboard/publicdashboard_kind_gen.go +++ b/pkg/kinds/publicdashboard/publicdashboard_kind_gen.go @@ -16,8 +16,8 @@ import ( ) // rootrel is the relative path from the grafana repository root to the -// directory containing the .cue files in which this kind is declared. Necessary -// for runtime errors related to the declaration and/or lineage to provide +// directory containing the .cue files in which this kind is defined. Necessary +// for runtime errors related to the definition and/or lineage to provide // a real path to the correct .cue file. const rootrel string = "kinds/publicdashboard" @@ -26,7 +26,7 @@ type Kind struct { lin thema.ConvergentLineage[*PublicDashboard] jcodec vmux.Codec valmux vmux.ValueMux[*PublicDashboard] - decl kindsys.Decl[kindsys.CoreProperties] + def kindsys.Def[kindsys.CoreProperties] } // type guard @@ -34,22 +34,22 @@ var _ kindsys.Core = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) + def, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) if err != nil { return nil, err } k := &Kind{ - decl: decl, + def: def, } - lin, err := decl.Some().BindKindLineage(rt, opts...) + lin, err := def.Some().BindKindLineage(rt, opts...) if err != nil { return nil, err } // Get the thema.Schema that the meta says is in the current version (which // codegen ensures is always the latest) - cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) + cursch := thema.SchemaP(lin, k.def.Properties.CurrentVersion) tsch, err := thema.BindType[*PublicDashboard](cursch, &PublicDashboard{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -95,19 +95,19 @@ func (k *Kind) JSONValueMux(b []byte) (*PublicDashboard, thema.TranslationLacuna // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Properties.Maturity + return k.def.Properties.Maturity } -// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// Def returns the [kindsys.Def] containing both CUE and Go representations of the // publicdashboard declaration in .cue files. -func (k *Kind) Decl() kindsys.Decl[kindsys.CoreProperties] { - return k.decl +func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] { + return k.def } // Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreProperties], // representing the static properties declared in the publicdashboard kind. // -// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +// This method is identical to calling Def().Props. It is provided to satisfy [kindsys.Interface]. func (k *Kind) Props() kindsys.SomeKindProperties { - return k.decl.Properties + return k.def.Properties } diff --git a/pkg/kinds/serviceaccount/serviceaccount_kind_gen.go b/pkg/kinds/serviceaccount/serviceaccount_kind_gen.go index 8f3e18add3f..ee9237e3b18 100644 --- a/pkg/kinds/serviceaccount/serviceaccount_kind_gen.go +++ b/pkg/kinds/serviceaccount/serviceaccount_kind_gen.go @@ -16,8 +16,8 @@ import ( ) // rootrel is the relative path from the grafana repository root to the -// directory containing the .cue files in which this kind is declared. Necessary -// for runtime errors related to the declaration and/or lineage to provide +// directory containing the .cue files in which this kind is defined. Necessary +// for runtime errors related to the definition and/or lineage to provide // a real path to the correct .cue file. const rootrel string = "kinds/serviceaccount" @@ -26,7 +26,7 @@ type Kind struct { lin thema.ConvergentLineage[*ServiceAccount] jcodec vmux.Codec valmux vmux.ValueMux[*ServiceAccount] - decl kindsys.Decl[kindsys.CoreProperties] + def kindsys.Def[kindsys.CoreProperties] } // type guard @@ -34,22 +34,22 @@ var _ kindsys.Core = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) + def, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) if err != nil { return nil, err } k := &Kind{ - decl: decl, + def: def, } - lin, err := decl.Some().BindKindLineage(rt, opts...) + lin, err := def.Some().BindKindLineage(rt, opts...) if err != nil { return nil, err } // Get the thema.Schema that the meta says is in the current version (which // codegen ensures is always the latest) - cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) + cursch := thema.SchemaP(lin, k.def.Properties.CurrentVersion) tsch, err := thema.BindType[*ServiceAccount](cursch, &ServiceAccount{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -95,19 +95,19 @@ func (k *Kind) JSONValueMux(b []byte) (*ServiceAccount, thema.TranslationLacunas // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Properties.Maturity + return k.def.Properties.Maturity } -// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// Def returns the [kindsys.Def] containing both CUE and Go representations of the // serviceaccount declaration in .cue files. -func (k *Kind) Decl() kindsys.Decl[kindsys.CoreProperties] { - return k.decl +func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] { + return k.def } // Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreProperties], // representing the static properties declared in the serviceaccount kind. // -// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +// This method is identical to calling Def().Props. It is provided to satisfy [kindsys.Interface]. func (k *Kind) Props() kindsys.SomeKindProperties { - return k.decl.Properties + return k.def.Properties } diff --git a/pkg/kinds/team/team_kind_gen.go b/pkg/kinds/team/team_kind_gen.go index 4c08d5de435..0fed5765bc3 100644 --- a/pkg/kinds/team/team_kind_gen.go +++ b/pkg/kinds/team/team_kind_gen.go @@ -16,8 +16,8 @@ import ( ) // rootrel is the relative path from the grafana repository root to the -// directory containing the .cue files in which this kind is declared. Necessary -// for runtime errors related to the declaration and/or lineage to provide +// directory containing the .cue files in which this kind is defined. Necessary +// for runtime errors related to the definition and/or lineage to provide // a real path to the correct .cue file. const rootrel string = "kinds/team" @@ -26,7 +26,7 @@ type Kind struct { lin thema.ConvergentLineage[*Team] jcodec vmux.Codec valmux vmux.ValueMux[*Team] - decl kindsys.Decl[kindsys.CoreProperties] + def kindsys.Def[kindsys.CoreProperties] } // type guard @@ -34,22 +34,22 @@ var _ kindsys.Core = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) + def, err := kindsys.LoadCoreKind(rootrel, rt.Context(), nil) if err != nil { return nil, err } k := &Kind{ - decl: decl, + def: def, } - lin, err := decl.Some().BindKindLineage(rt, opts...) + lin, err := def.Some().BindKindLineage(rt, opts...) if err != nil { return nil, err } // Get the thema.Schema that the meta says is in the current version (which // codegen ensures is always the latest) - cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) + cursch := thema.SchemaP(lin, k.def.Properties.CurrentVersion) tsch, err := thema.BindType[*Team](cursch, &Team{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -95,19 +95,19 @@ func (k *Kind) JSONValueMux(b []byte) (*Team, thema.TranslationLacunas, error) { // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Properties.Maturity + return k.def.Properties.Maturity } -// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// Def returns the [kindsys.Def] containing both CUE and Go representations of the // team declaration in .cue files. -func (k *Kind) Decl() kindsys.Decl[kindsys.CoreProperties] { - return k.decl +func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] { + return k.def } // Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreProperties], // representing the static properties declared in the team kind. // -// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +// This method is identical to calling Def().Props. It is provided to satisfy [kindsys.Interface]. func (k *Kind) Props() kindsys.SomeKindProperties { - return k.decl.Properties + return k.def.Properties } diff --git a/pkg/kindsys/EXTENDING.md b/pkg/kindsys/EXTENDING.md index c1902d2c5e2..6e534376699 100644 --- a/pkg/kindsys/EXTENDING.md +++ b/pkg/kindsys/EXTENDING.md @@ -1,6 +1,6 @@ # Kind System -This package contains Grafana's kind system, which defines the rules that govern all Grafana kind declarations, including both core and plugin kinds. It contains many contracts on which public promises of backwards compatibility are made. All changes must be considered with care. +This package contains Grafana's kind system, which defines the rules that govern all Grafana kind definitions, including both core and plugin kinds. It contains many contracts on which public promises of backwards compatibility are made. All changes must be considered with care. While this package is maintained by @grafana/grafana-as-code, contributions from others are a main goal! Any time you have the thought, "I wish this part of Grafana's codebase was consistent," rather than writing docs (that people will inevitably miss), it's worth seeing if you can express that consistency as a kindsys extension instead. @@ -8,11 +8,11 @@ This document is the guide to extending kindsys. But first, we have to identify ## Elements of kindsys -* **CUE framework** - the collection of .cue files in this directory, `pkg/kindsys`. These are schemas that define how Kinds are declared. -* **Go framework** - the Go package in this directory containing utilities for loading individual kind declarations, validating them against the CUE framework, and representing them consistently in Go. -* **Code generators** - written using the `github.com/grafana/codejen` framework, which applies the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) to code generation, allowing us to compose modular code generators. Each jenny - a modular generator with a single responsibility - is declared as a `pkg/codegen/jenny_*.go` file. +* **CUE framework** - the collection of .cue files in this directory, `pkg/kindsys`. These are schemas that define how Kinds are defined. +* **Go framework** - the Go package in this directory containing utilities for loading individual kind definitions, validating them against the CUE framework, and representing them consistently in Go. +* **Code generators** - written using the `github.com/grafana/codejen` framework, which applies the [single responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) to code generation, allowing us to compose modular code generators. Each jenny - a modular generator with a single responsibility - is written as a `pkg/codegen/jenny_*.go` file. * **Registries** - generated lists of all or a well-defined subset of kinds that can be used in code. `pkg/registries/corekind` is a registry of all core `pkg/kindsys.Interface` implementations; `packages/grafana-schema/src/index.gen.ts` is a registry of all the TypeScript types generated from the current versions of each kind's schema. -* **Kind declarations** - the declarations of individual kinds. By kind category: +* **Kind definitions** - the definitions of individual kinds. By kind category: * **Core** - each child directory of `kinds`. * **Composable** - In Grafana core, `public/app/plugins/*/*/models.cue` files. * **Custom** - No examples in Grafana core. See [operator-app-sdk](https://github.com/grafana/operator-app-sdk) (TODO that repo is private; make it public, or point to public examples). @@ -48,7 +48,7 @@ While the main path for extending kindsys is through adding metadata, there are * Controlling nuanced behavior of code generators for some field or type. Example: [@cuetsy](https://github.com/grafana/cuetsy#usage) attributes, which govern TS output * Expressing some kind of structured TODO or WIP information on a field or type that can be easily analyzed and fed into other systems. Example: a kind marked at least `stable` maturity may not have any `@grafanamaturity` attributes -In both of these cases, attributes are a tool _for the individual kind author_ to convey something to downstream consumers of kind declarations. It is essential. While attributes allow consistency in _how_ a particular task is accomplished, they leave _when_ to apply the rule up to the judgment of the kind author. +In both of these cases, attributes are a tool _for the individual kind author_ to convey something to downstream consumers of kind definitions. It is essential. While attributes allow consistency in _how_ a particular task is accomplished, they leave _when_ to apply the rule up to the judgment of the kind author. Attributes occupy an awkward middle ground. They are more challenging to implement than standard kind framework properties, and less consistent than general codegen transformers while still imposing a cognitive burden on kind authors. They should be the last tool you reach for - but may be the only tool available when field-level schema metadata is required. diff --git a/pkg/kindsys/bind.go b/pkg/kindsys/bind.go index f6acdded8b9..848867b4771 100644 --- a/pkg/kindsys/bind.go +++ b/pkg/kindsys/bind.go @@ -7,42 +7,42 @@ import ( var _ Composable = genericComposable{} type genericComposable struct { - decl Decl[ComposableProperties] - lin thema.Lineage + def Def[ComposableProperties] + lin thema.Lineage } func (k genericComposable) Props() SomeKindProperties { - return k.decl.Properties + return k.def.Properties } func (k genericComposable) Name() string { - return k.decl.Properties.Name + return k.def.Properties.Name } func (k genericComposable) MachineName() string { - return k.decl.Properties.MachineName + return k.def.Properties.MachineName } func (k genericComposable) Maturity() Maturity { - return k.decl.Properties.Maturity + return k.def.Properties.Maturity } -func (k genericComposable) Decl() Decl[ComposableProperties] { - return k.decl +func (k genericComposable) Def() Def[ComposableProperties] { + return k.def } func (k genericComposable) Lineage() thema.Lineage { return k.lin } -func BindComposable(rt *thema.Runtime, decl Decl[ComposableProperties], opts ...thema.BindOption) (Composable, error) { +func BindComposable(rt *thema.Runtime, decl Def[ComposableProperties], opts ...thema.BindOption) (Composable, error) { lin, err := decl.Some().BindKindLineage(rt, opts...) if err != nil { return nil, err } return genericComposable{ - decl: decl, - lin: lin, + def: decl, + lin: lin, }, nil } diff --git a/pkg/kindsys/errors.go b/pkg/kindsys/errors.go index 18deb8ae54c..aa6159235e8 100644 --- a/pkg/kindsys/errors.go +++ b/pkg/kindsys/errors.go @@ -9,7 +9,7 @@ var ( ErrValueNotExist = errors.New("cue value does not exist") // ErrValueNotAKind indicates that a provided CUE value is not any variety of - // Interface. This is almost always a user error - they oops'd and provided the + // Kind. This is almost always a user error - they oops'd and provided the // wrong path, file, etc. ErrValueNotAKind = errors.New("not a kind") diff --git a/pkg/kindsys/kind.go b/pkg/kindsys/kind.go index 9e360889b70..71479a2a021 100644 --- a/pkg/kindsys/kind.go +++ b/pkg/kindsys/kind.go @@ -45,16 +45,16 @@ func (m Maturity) String() string { return string(m) } -// Interface describes a Grafana kind object: a Go representation of the definition of +// Kind describes a Grafana kind object: a Go representation of the definition of // one of Grafana's categories of kinds. -type Interface interface { +type Kind interface { // Props returns a [kindsys.SomeKindProps], representing the properties // of the kind as declared in the .cue source. The underlying type is // determined by the category of kind. // // This method is largely for convenience, as all actual kind categories are // expected to implement one of the other interfaces, each of which contain - // a Decl() method through which these same properties are accessible. + // a Def() method through which these same properties are accessible. Props() SomeKindProperties // TODO docs @@ -71,22 +71,22 @@ type Interface interface { } type Core interface { - Interface + Kind // TODO docs - Decl() Decl[CoreProperties] + Def() Def[CoreProperties] } type Custom interface { - Interface + Kind // TODO docs - Decl() Decl[CustomProperties] + Def() Def[CustomProperties] } type Composable interface { - Interface + Kind // TODO docs - Decl() Decl[ComposableProperties] + Def() Def[ComposableProperties] } diff --git a/pkg/kindsys/kindcat_composable.cue b/pkg/kindsys/kindcat_composable.cue index 2813de68f76..bbd5b893076 100644 --- a/pkg/kindsys/kindcat_composable.cue +++ b/pkg/kindsys/kindcat_composable.cue @@ -7,7 +7,7 @@ package kindsys // and alerting rules. // // Each Composable is an implementation of exactly one Slot, a shared meta-schema -// defined by Grafana itself that constrains the shape of schemas declared in +// defined by Grafana itself that constrains the shape of schemas defined in // that ComposableKind. Composable: S={ _sharedKind diff --git a/pkg/kindsys/kindcat_custom.cue b/pkg/kindsys/kindcat_custom.cue index d8f30275749..9644df48bb1 100644 --- a/pkg/kindsys/kindcat_custom.cue +++ b/pkg/kindsys/kindcat_custom.cue @@ -2,7 +2,7 @@ package kindsys // Custom specifies the kind category for plugin-defined arbitrary types. // Custom kinds have the same purpose as Core kinds, differing only in -// that they are declared by external plugins rather than in Grafana core. As such, +// that they are defined by external plugins rather than in Grafana core. As such, // this specification is kept closely aligned with the Core kind. // // Grafana provides Kubernetes apiserver-shaped HTTP APIs for interacting with custom diff --git a/pkg/kindsys/kindcats.cue b/pkg/kindsys/kindcats.cue index cbf7077d327..cdbe09f5946 100644 --- a/pkg/kindsys/kindcats.cue +++ b/pkg/kindsys/kindcats.cue @@ -58,7 +58,7 @@ _sharedKind: { // object that is expected to exist in the wild // // This value of this field is set by the kindsys framework. It cannot be changed - // in the declaration of any individual kind. + // in the definition of any individual kind. // // This is likely to eventually become a first-class property in Thema: // https://github.com/grafana/thema/issues/62 @@ -79,7 +79,7 @@ _sharedKind: { maturity: *"merged" | "experimental" } -// Maturity indicates the how far a given kind declaration is in its initial +// Maturity indicates the how far a given kind definition is in its initial // journey. Mature kinds still evolve, but with guarantees about compatibility. Maturity: "merged" | "experimental" | "stable" | "mature" diff --git a/pkg/kindsys/load.go b/pkg/kindsys/load.go index 44f1592bb50..ab6413aa93a 100644 --- a/pkg/kindsys/load.go +++ b/pkg/kindsys/load.go @@ -13,7 +13,7 @@ import ( ) // CoreDeclParentPath is the path, relative to the repository root, where -// each child directory is expected to contain .cue files declaring one +// each child directory is expected to contain .cue files defining one // Core kind. var CoreDeclParentPath = "kinds" @@ -59,7 +59,7 @@ func doLoadFrameworkCUE(ctx *cue.Context) (cue.Value, error) { // raw CUE files. // // For low-level use in constructing other types and APIs, while still letting -// us declare all the frameworky CUE bits in a single package. Other Go types +// us define all the frameworky CUE bits in a single package. Other Go types // make the constructs in the returned cue.Value easy to use. // // Calling this with a nil [cue.Context] (the singleton returned from @@ -114,75 +114,75 @@ func ToKindProps[T KindProperties](v cue.Value) (T, error) { return *props, nil } -// SomeDecl represents a single kind declaration, having been loaded and +// SomeDef represents a single kind definition, having been loaded and // validated by a func such as [LoadCoreKind]. // // The underlying type of the Properties field indicates the category of kind. -type SomeDecl struct { - // V is the cue.Value containing the entire Kind declaration. +type SomeDef struct { + // V is the cue.Value containing the entire Kind definition. V cue.Value - // Properties contains the kind's declared properties. + // Properties contains the kind's declarative non-schema properties. Properties SomeKindProperties } -// BindKindLineage binds the lineage for the kind declaration. +// BindKindLineage binds the lineage for the kind definition. // // For kinds with a corresponding Go type, it is left to the caller to associate // that Go type with the lineage returned from this function by a call to // [thema.BindType]. -func (decl SomeDecl) BindKindLineage(rt *thema.Runtime, opts ...thema.BindOption) (thema.Lineage, error) { +func (def SomeDef) BindKindLineage(rt *thema.Runtime, opts ...thema.BindOption) (thema.Lineage, error) { if rt == nil { rt = cuectx.GrafanaThemaRuntime() } - return thema.BindLineage(decl.V.LookupPath(cue.MakePath(cue.Str("lineage"))), rt, opts...) + return thema.BindLineage(def.V.LookupPath(cue.MakePath(cue.Str("lineage"))), rt, opts...) } // IsCore indicates whether the represented kind is a core kind. -func (decl SomeDecl) IsCore() bool { - _, is := decl.Properties.(CoreProperties) +func (def SomeDef) IsCore() bool { + _, is := def.Properties.(CoreProperties) return is } // IsCustom indicates whether the represented kind is a custom kind. -func (decl SomeDecl) IsCustom() bool { - _, is := decl.Properties.(CustomProperties) +func (def SomeDef) IsCustom() bool { + _, is := def.Properties.(CustomProperties) return is } // IsComposable indicates whether the represented kind is a composable kind. -func (decl SomeDecl) IsComposable() bool { - _, is := decl.Properties.(ComposableProperties) +func (def SomeDef) IsComposable() bool { + _, is := def.Properties.(ComposableProperties) return is } -// Decl represents a single kind declaration, having been loaded +// Def represents a single kind definition, having been loaded // and validated by a func such as [LoadCoreKind]. // // Its type parameter indicates the category of kind. -type Decl[T KindProperties] struct { - // V is the cue.Value containing the entire Kind declaration. +type Def[T KindProperties] struct { + // V is the cue.Value containing the entire Kind definition. V cue.Value - // Properties contains the kind's declared properties. + // Properties contains the kind's declarative non-schema properties. Properties T } -// Some converts the typed Decl to the equivalent typeless SomeDecl. -func (decl Decl[T]) Some() SomeDecl { - return SomeDecl{ - V: decl.V, - Properties: any(decl.Properties).(SomeKindProperties), +// Some converts the typed Def to the equivalent typeless SomeDef. +func (def Def[T]) Some() SomeDef { + return SomeDef{ + V: def.V, + Properties: any(def.Properties).(SomeKindProperties), } } -// LoadCoreKind loads and validates a core kind declaration of the kind category -// indicated by the type parameter. On success, it returns a [Decl] which -// contains the entire contents of the kind declaration. +// LoadCoreKind loads and validates a core kind definition of the kind category +// indicated by the type parameter. On success, it returns a [Def] which +// contains the entire contents of the kind definition. // -// declpath is the path to the directory containing the core kind declaration, +// declpath is the path to the directory containing the core kind definition, // relative to the grafana/grafana root. For example, dashboards are in // "kinds/dashboard". // -// The .cue file bytes containing the core kind declaration will be retrieved +// The .cue file bytes containing the core kind definition will be retrieved // from the central embedded FS, [grafana.CueSchemaFS]. If desired (e.g. for // testing), an optional fs.FS may be provided via the overlay parameter, which // will be merged over [grafana.CueSchemaFS]. But in typical circumstances, @@ -191,9 +191,9 @@ func (decl Decl[T]) Some() SomeDecl { // This is a low-level function, primarily intended for use in code generation. // For representations of core kinds that are useful in Go programs at runtime, // see ["github.com/grafana/grafana/pkg/registry/corekind"]. -func LoadCoreKind(declpath string, ctx *cue.Context, overlay fs.FS) (Decl[CoreProperties], error) { - none := Decl[CoreProperties]{} - vk, err := cuectx.BuildGrafanaInstance(ctx, declpath, "kind", overlay) +func LoadCoreKind(defpath string, ctx *cue.Context, overlay fs.FS) (Def[CoreProperties], error) { + none := Def[CoreProperties]{} + vk, err := cuectx.BuildGrafanaInstance(ctx, defpath, "kind", overlay) if err != nil { return none, err } @@ -203,7 +203,7 @@ func LoadCoreKind(declpath string, ctx *cue.Context, overlay fs.FS) (Decl[CorePr return none, err } - return Decl[CoreProperties]{ + return Def[CoreProperties]{ V: vk, Properties: props, }, nil diff --git a/pkg/kindsys/kindmetas.go b/pkg/kindsys/props.go similarity index 85% rename from pkg/kindsys/kindmetas.go rename to pkg/kindsys/props.go index fb0eb6505fc..c289094d270 100644 --- a/pkg/kindsys/kindmetas.go +++ b/pkg/kindsys/props.go @@ -12,13 +12,13 @@ type CommonProperties struct { Maturity Maturity `json:"maturity"` } -// CoreProperties represents the static properties in the declaration of a +// CoreProperties represents the static properties in the definition of a // Core kind that are representable with basic Go types. This // excludes Thema schemas. // -// When a .cue Core declaration is loaded through the standard [LoadCoreKind], -// func, it is fully validated and populated according to all rules specified -// in CUE for Core kinds. +// When .cue file(s) containing a Core definition is loaded through the standard +// [LoadCoreKind], func, it is fully validated and populated according to all +// rules specified in CUE for Core kinds. type CoreProperties struct { CommonProperties CurrentVersion thema.SyntacticVersion `json:"currentVersion"` @@ -29,7 +29,7 @@ func (m CoreProperties) Common() CommonProperties { return m.CommonProperties } -// CustomProperties represents the static properties in the declaration of a +// CustomProperties represents the static properties in the definition of a // Custom kind that are representable with basic Go types. This // excludes Thema schemas. type CustomProperties struct { @@ -42,7 +42,7 @@ func (m CustomProperties) Common() CommonProperties { return m.CommonProperties } -// ComposableProperties represents the static properties in the declaration of a +// ComposableProperties represents the static properties in the definition of a // Composable kind that are representable with basic Go types. This // excludes Thema schemas. type ComposableProperties struct { diff --git a/pkg/kindsys/report.go b/pkg/kindsys/report.go index b853abbe97d..45c5f3a8c9a 100644 --- a/pkg/kindsys/report.go +++ b/pkg/kindsys/report.go @@ -196,7 +196,7 @@ func buildKindStateReport() *KindStateReport { lin := k.Lineage() switch k.Props().(type) { case kindsys.CoreProperties: - links := buildCoreLinks(lin, k.Decl().Properties) + links := buildCoreLinks(lin, k.Def().Properties) r.add(Kind{ SomeKindProperties: k.Props(), Category: "core", @@ -230,7 +230,7 @@ func buildKindStateReport() *KindStateReport { for _, pp := range corelist.New(nil) { for _, si := range all { if ck, has := pp.ComposableKinds[si.Name()]; has { - links := buildComposableLinks(pp.Properties, ck.Decl().Properties) + links := buildComposableLinks(pp.Properties, ck.Def().Properties) r.add(Kind{ SomeKindProperties: ck.Props(), Category: "composable", diff --git a/pkg/kindsys/schema_interface.go b/pkg/kindsys/schema_interface.go index 83aa25bab2f..f9093ec022e 100644 --- a/pkg/kindsys/schema_interface.go +++ b/pkg/kindsys/schema_interface.go @@ -28,10 +28,10 @@ func (s SchemaInterface) Name() string { return s.name } -// Interface returns the cue.Value representing the meta-schema that is the -// contract between core or custom kinds that compose the meta-schema, and the -// plugin-declared composable kinds that implement the meta-schema. -func (s SchemaInterface) Interface() cue.Value { +// Contract returns the cue.Value representing the meta-schema that is the +// contract between core/custom kinds that consume schemas that are instances +// of the SchemaInterface contract, and composable kinds that produce such schemas. +func (s SchemaInterface) Contract() cue.Value { return s.raw.LookupPath(ip) } diff --git a/pkg/plugins/pfs/decl.go b/pkg/plugins/pfs/decl.go index 6ca3b8afe51..cfad1a4d262 100644 --- a/pkg/plugins/pfs/decl.go +++ b/pkg/plugins/pfs/decl.go @@ -13,7 +13,7 @@ type PluginDecl struct { Imports []*ast.ImportSpec PluginPath string PluginMeta plugindef.PluginDef - KindDecl kindsys.Decl[kindsys.ComposableProperties] + KindDecl kindsys.Def[kindsys.ComposableProperties] } func EmptyPluginDecl(path string, meta plugindef.PluginDef) *PluginDecl { diff --git a/pkg/plugins/pfs/decl_parser.go b/pkg/plugins/pfs/decl_parser.go index 2ab45829d1c..299bc9a7ed0 100644 --- a/pkg/plugins/pfs/decl_parser.go +++ b/pkg/plugins/pfs/decl_parser.go @@ -61,7 +61,7 @@ func (psr *declParser) Parse(root fs.FS) ([]*PluginDecl, error) { Imports: pp.CUEImports, PluginMeta: pp.Properties, PluginPath: path, - KindDecl: kind.Decl(), + KindDecl: kind.Def(), }) } } diff --git a/pkg/plugins/pfs/pfs.go b/pkg/plugins/pfs/pfs.go index f50aca6658e..c6c5d4b8ccc 100644 --- a/pkg/plugins/pfs/pfs.go +++ b/pkg/plugins/pfs/pfs.go @@ -220,7 +220,7 @@ func ParsePluginFS(fsys fs.FS, rt *thema.Runtime) (ParsedPlugin, error) { return ParsedPlugin{}, err } - compo, err := kindsys.BindComposable(rt, kindsys.Decl[kindsys.ComposableProperties]{ + compo, err := kindsys.BindComposable(rt, kindsys.Def[kindsys.ComposableProperties]{ Properties: props, V: iv, }) diff --git a/pkg/plugins/pfs/plugin.go b/pkg/plugins/pfs/plugin.go index e28fcfa4ce3..c3ed63b3d75 100644 --- a/pkg/plugins/pfs/plugin.go +++ b/pkg/plugins/pfs/plugin.go @@ -36,13 +36,13 @@ type ParsedPlugin struct { // ComposableKinds represents all the possible composable kinds that may be // defined in a Grafana plugin. // -// The value of each field, if non-nil, is a standard [kindsys.Decl] +// The value of each field, if non-nil, is a standard [kindsys.Def] // representing a CUE definition of a composable kind that implements the // schema interface corresponding to the field's name. (This invariant is // only enforced in [ComposableKinds] returned from [ParsePluginFS].) // // type ComposableKinds struct { -// PanelCfg kindsys.Decl[kindsys.ComposableProperties] -// Queries kindsys.Decl[kindsys.ComposableProperties] -// DSCfg kindsys.Decl[kindsys.ComposableProperties] +// PanelCfg kindsys.Def[kindsys.ComposableProperties] +// Queries kindsys.Def[kindsys.ComposableProperties] +// DSCfg kindsys.Def[kindsys.ComposableProperties] // } diff --git a/public/app/plugins/gen.go b/public/app/plugins/gen.go index c0d169e033d..3497d286437 100644 --- a/public/app/plugins/gen.go +++ b/public/app/plugins/gen.go @@ -91,8 +91,8 @@ func adaptToPipeline(j codejen.OneToOne[corecodegen.SchemaForGen]) codejen.OneTo }) } -func toDeclForGen(j codejen.OneToOne[*corecodegen.DeclForGen]) codejen.OneToOne[*pfs.PluginDecl] { - return codejen.AdaptOneToOne(j, func(pd *pfs.PluginDecl) *corecodegen.DeclForGen { +func toDeclForGen(j codejen.OneToOne[*corecodegen.DefForGen]) codejen.OneToOne[*pfs.PluginDecl] { + return codejen.AdaptOneToOne(j, func(pd *pfs.PluginDecl) *corecodegen.DefForGen { kd, err := corecodegen.ForGen(pd.Lineage.Runtime(), pd.KindDecl.Some()) if err != nil { panic("should be unreachable")