Kindsys: Replace "Declaration" with "Definition" (#62515)

* s/Declaration/Definition/g

* s/DeclForGen/DefForGen/g

* Rename some local vars

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 {
+	coreKindsGen := codejen.JennyListWithNamer(func(def *codegen.DefForGen) string {
-		return decl.Properties.Common().MachineName
+		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")

pkg/codegen/generators.go

@@ -10,44 +10,45 @@ import (
 	"github.com/grafana/thema"
 )
 
-type OneToOne codejen.OneToOne[*DeclForGen]
+type OneToOne codejen.OneToOne[*DefForGen]
-type OneToMany codejen.OneToMany[*DeclForGen]
+type OneToMany codejen.OneToMany[*DefForGen]
-type ManyToOne codejen.ManyToOne[*DeclForGen]
+type ManyToOne codejen.ManyToOne[*DefForGen]
-type ManyToMany codejen.ManyToMany[*DeclForGen]
+type ManyToMany codejen.ManyToMany[*DefForGen]
 
-// ForGen is a codejen input transformer that converts a pure kindsys.SomeDecl into
+// ForGen is a codejen input transformer that converts a pure kindsys.SomeDef into
-// a DeclForGen by binding its contained lineage.
+// a DefForGen by binding its contained lineage.
-func ForGen(rt *thema.Runtime, decl kindsys.SomeDecl) (*DeclForGen, error) {
+func ForGen(rt *thema.Runtime, def kindsys.SomeDef) (*DefForGen, error) {
-	lin, err := decl.BindKindLineage(rt)
+	lin, err := def.BindKindLineage(rt)
 	if err != nil {
 		return nil, err
 	}
 
-	return &DeclForGen{
+	return &DefForGen{
-		SomeDecl: decl,
+		SomeDef: def,
-		lin:      lin,
+		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 {
+// TODO this type is unneeded - kindsys.Kind is sufficient.
-	kindsys.SomeDecl
+type DefForGen struct {
+	kindsys.SomeDef
 	lin thema.Lineage
 }
 
-// Lineage returns the [thema.Lineage] for the underlying [kindsys.SomeDecl].
+// Lineage returns the [thema.Lineage] for the underlying [kindsys.SomeDef].
-func (decl *DeclForGen) Lineage() thema.Lineage {
+func (def *DefForGen) Lineage() thema.Lineage {
-	return decl.lin
+	return def.lin
 }
 
 // ForLatestSchema returns a [SchemaForGen] for the latest schema in this
-// DeclForGen's lineage.
+// DefForGen's lineage.
-func (decl *DeclForGen) ForLatestSchema() SchemaForGen {
+func (def *DefForGen) ForLatestSchema() SchemaForGen {
-	comm := decl.Properties.Common()
+	comm := def.Properties.Common()
 	return SchemaForGen{
 		Name:    comm.Name,
-		Schema:  decl.Lineage().Latest(),
+		Schema:  def.Lineage().Latest(),
 		IsGroup: comm.LineageIsGroup,
 	}
 }

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)
 	}

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 {
+		cfg.GenDirName = func(def *DefForGen) string {
-			return decl.Properties.Common().MachineName
+			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.
+	// generated. Defaults to DefForGen.Lineage().Name() if nil.
-	GenDirName func(*DeclForGen) string
+	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) {
+func (gen *coreKindJenny) Generate(def *DefForGen) (*codejen.File, error) {
-	if !decl.IsCore() {
+	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{

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) {
+func (j docsJenny) Generate(def *DefForGen) (*codejen.File, error) {
-	f, err := jsonschema.GenerateSchema(decl.Lineage().Latest())
+	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.<types> 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 }}",
 	}

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) {
+func (j *lmox) Generate(def *DefForGen) (codejen.Files, error) {
-	comm := decl.Properties.Common()
+	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 {

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 {
+	for _, def := range decls {
-		sch := decl.Lineage().Latest()
+		sch := def.Lineage().Latest()
 		f, err := typescript.GenerateTypes(sch, &typescript.TypeConfig{
-			RootName: decl.Properties.Common().Name,
+			RootName: def.Properties.Common().Name,
-			Group:    decl.Properties.Common().LineageIsGroup,
+			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) {
+func (gen *genTSVeneerIndex) extractTSIndexVeneerElements(def *DefForGen, tf *ast.File) ([]ast.Decl, error) {
-	lin := decl.Lineage()
+	lin := def.Lineage()
-	comm := decl.Properties.Common()
+	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 {
+		if ex, is := def.(ast.ExportKeyword); is {
-			decl = ex.Decl
+			def = ex.Decl
 		}
 
-		switch x := decl.(type) {
+		switch x := def.(type) {
 		case ast.TypeDecl:
 			if x.Name.Name == name {
 				p.T = &x.Name

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) {
+func (j *latestj) Generate(def *DefForGen) (*codejen.File, error) {
-	comm := decl.Properties.Common()
+	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

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

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
+// directory containing the .cue files in which this kind is defined. Necessary
-// for runtime errors related to the declaration and/or lineage to provide
+// 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] {
+func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] {
-  return k.decl
+  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
 }

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 {
+		for _, def := range x.Decls {
-			comments := decl.Decorations().Start.All()
+			comments := def.Decorations().Start.All()
-			decl.Decorations().Start.Clear()
+			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"))
 					}
 				}
 			}

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
+// directory containing the .cue files in which this kind is defined. Necessary
-// for runtime errors related to the declaration and/or lineage to provide
+// 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] {
+func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] {
-	return k.decl
+	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
 }

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
+// directory containing the .cue files in which this kind is defined. Necessary
-// for runtime errors related to the declaration and/or lineage to provide
+// 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] {
+func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] {
-	return k.decl
+	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
 }

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
+// directory containing the .cue files in which this kind is defined. Necessary
-// for runtime errors related to the declaration and/or lineage to provide
+// 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] {
+func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] {
-	return k.decl
+	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
 }

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
+// directory containing the .cue files in which this kind is defined. Necessary
-// for runtime errors related to the declaration and/or lineage to provide
+// 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] {
+func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] {
-	return k.decl
+	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
 }

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
+// directory containing the .cue files in which this kind is defined. Necessary
-// for runtime errors related to the declaration and/or lineage to provide
+// 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] {
+func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] {
-	return k.decl
+	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
 }

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
+// directory containing the .cue files in which this kind is defined. Necessary
-// for runtime errors related to the declaration and/or lineage to provide
+// 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] {
+func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] {
-	return k.decl
+	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
 }

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
+// directory containing the .cue files in which this kind is defined. Necessary
-// for runtime errors related to the declaration and/or lineage to provide
+// 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] {
+func (k *Kind) Def() kindsys.Def[kindsys.CoreProperties] {
-	return k.decl
+	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
 }

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.
+* **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 declarations, validating them against the CUE framework, and representing them consistently in Go.
+* **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 declared as a `pkg/codegen/jenny_*.go` file.
+* **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.
 

pkg/kindsys/bind.go

@@ -7,42 +7,42 @@ import (
 var _ Composable = genericComposable{}
 
 type genericComposable struct {
-	decl Decl[ComposableProperties]
+	def Def[ComposableProperties]
-	lin  thema.Lineage
+	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] {
+func (k genericComposable) Def() Def[ComposableProperties] {
-	return k.decl
+	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,
+		def: decl,
-		lin:  lin,
+		lin: lin,
 	}, nil
 }

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")
 

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]
 }

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

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

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"
 

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 {
+type SomeDef struct {
-	// V is the cue.Value containing the entire Kind declaration.
+	// 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 {
+func (def SomeDef) IsCore() bool {
-	_, is := decl.Properties.(CoreProperties)
+	_, is := def.Properties.(CoreProperties)
 	return is
 }
 
 // IsCustom indicates whether the represented kind is a custom kind.
-func (decl SomeDecl) IsCustom() bool {
+func (def SomeDef) IsCustom() bool {
-	_, is := decl.Properties.(CustomProperties)
+	_, is := def.Properties.(CustomProperties)
 	return is
 }
 
 // IsComposable indicates whether the represented kind is a composable kind.
-func (decl SomeDecl) IsComposable() bool {
+func (def SomeDef) IsComposable() bool {
-	_, is := decl.Properties.(ComposableProperties)
+	_, 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 {
+type Def[T KindProperties] struct {
-	// V is the cue.Value containing the entire Kind declaration.
+	// 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.
+// Some converts the typed Def to the equivalent typeless SomeDef.
-func (decl Decl[T]) Some() SomeDecl {
+func (def Def[T]) Some() SomeDef {
-	return SomeDecl{
+	return SomeDef{
-		V:          decl.V,
+		V:          def.V,
-		Properties: any(decl.Properties).(SomeKindProperties),
+		Properties: any(def.Properties).(SomeKindProperties),
 	}
 }
 
-// LoadCoreKind loads and validates a core kind declaration of the kind category
+// LoadCoreKind loads and validates a core kind definition of the kind category
-// indicated by the type parameter. On success, it returns a [Decl] which
+// indicated by the type parameter. On success, it returns a [Def] which
-// contains the entire contents of the kind declaration.
+// 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) {
+func LoadCoreKind(defpath string, ctx *cue.Context, overlay fs.FS) (Def[CoreProperties], error) {
-	none := Decl[CoreProperties]{}
+	none := Def[CoreProperties]{}
-	vk, err := cuectx.BuildGrafanaInstance(ctx, declpath, "kind", overlay)
+	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

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],
+// When .cue file(s) containing a Core definition is loaded through the standard
-// func, it is fully validated and populated according to all rules specified
+// [LoadCoreKind], func, it is fully validated and populated according to all
-// in CUE for Core kinds.
+// 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 {

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",

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 returns the cue.Value representing the meta-schema that is the
-// contract between core or custom kinds that compose the meta-schema, and the
+// contract between core/custom kinds that consume schemas that are instances
-// plugin-declared composable kinds that implement the meta-schema.
+// of the SchemaInterface contract, and composable kinds that produce such schemas.
-func (s SchemaInterface) Interface() cue.Value {
+func (s SchemaInterface) Contract() cue.Value {
 	return s.raw.LookupPath(ip)
 }
 

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 {

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(),
 			})
 		}
 	}

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,
 		})

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]
+// 	PanelCfg kindsys.Def[kindsys.ComposableProperties]
-// 	Queries  kindsys.Decl[kindsys.ComposableProperties]
+// 	Queries  kindsys.Def[kindsys.ComposableProperties]
-// 	DSCfg    kindsys.Decl[kindsys.ComposableProperties]
+// 	DSCfg    kindsys.Def[kindsys.ComposableProperties]
 // }

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] {
+func toDeclForGen(j codejen.OneToOne[*corecodegen.DefForGen]) codejen.OneToOne[*pfs.PluginDecl] {
-	return codejen.AdaptOneToOne(j, func(pd *pfs.PluginDecl) *corecodegen.DeclForGen {
+	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")