diff --git a/kinds/gen.go b/kinds/gen.go index 71ff849e8da..8a16ebc3858 100644 --- a/kinds/gen.go +++ b/kinds/gen.go @@ -30,7 +30,7 @@ func main() { // Core kinds composite code generator. Produces all generated code in // grafana/grafana that derives from raw and structured core kinds. coreKindsGen := codejen.JennyListWithNamer(func(decl *codegen.DeclForGen) string { - return decl.Meta.Common().MachineName + return decl.Properties.Common().MachineName }) // All the jennies that comprise the core kinds generator pipeline @@ -63,12 +63,12 @@ func main() { continue } rel := filepath.Join(kindsys.CoreStructuredDeclParentPath, ent.Name()) - decl, err := kindsys.LoadCoreKind[kindsys.CoreStructuredMeta](rel, rt.Context(), nil) + decl, err := kindsys.LoadCoreKind[kindsys.CoreStructuredProperties](rel, rt.Context(), nil) if err != nil { die(fmt.Errorf("%s is not a valid kind: %s", rel, errors.Details(err, nil))) } - if decl.Meta.MachineName != ent.Name() { - die(fmt.Errorf("%s: kind's machine name (%s) must equal parent dir name (%s)", rel, decl.Meta.Name, ent.Name())) + if decl.Properties.MachineName != ent.Name() { + die(fmt.Errorf("%s: kind's machine name (%s) must equal parent dir name (%s)", rel, decl.Properties.Name, ent.Name())) } all = append(all, elsedie(codegen.ForGen(rt, decl.Some()))(rel)) @@ -82,19 +82,19 @@ func main() { continue } rel := filepath.Join(kindsys.RawDeclParentPath, ent.Name()) - decl, err := kindsys.LoadCoreKind[kindsys.RawMeta](rel, rt.Context(), nil) + decl, err := kindsys.LoadCoreKind[kindsys.RawProperties](rel, rt.Context(), nil) if err != nil { die(fmt.Errorf("%s is not a valid kind: %s", rel, errors.Details(err, nil))) } - if decl.Meta.MachineName != ent.Name() { - die(fmt.Errorf("%s: kind's machine name (%s) must equal parent dir name (%s)", rel, decl.Meta.Name, ent.Name())) + if decl.Properties.MachineName != ent.Name() { + die(fmt.Errorf("%s: kind's machine name (%s) must equal parent dir name (%s)", rel, decl.Properties.Name, ent.Name())) } dfg, _ := codegen.ForGen(nil, decl.Some()) all = append(all, dfg) } sort.Slice(all, func(i, j int) bool { - return nameFor(all[i].Meta) < nameFor(all[j].Meta) + return nameFor(all[i].Properties) < nameFor(all[j].Properties) }) jfs, err := coreKindsGen.GenerateFS(all...) @@ -111,18 +111,18 @@ func main() { } } -func nameFor(m kindsys.SomeKindMeta) string { +func nameFor(m kindsys.SomeKindProperties) string { switch x := m.(type) { - case kindsys.RawMeta: + case kindsys.RawProperties: return x.Name - case kindsys.CoreStructuredMeta: + case kindsys.CoreStructuredProperties: return x.Name - case kindsys.CustomStructuredMeta: + case kindsys.CustomStructuredProperties: return x.Name - case kindsys.ComposableMeta: + case kindsys.ComposableProperties: return x.Name default: - // unreachable so long as all the possibilities in KindMetas have switch branches + // unreachable so long as all the possibilities in KindProperties have switch branches panic("unreachable") } } diff --git a/pkg/codegen/generators.go b/pkg/codegen/generators.go index 1a56f71a5b4..1cf3079927f 100644 --- a/pkg/codegen/generators.go +++ b/pkg/codegen/generators.go @@ -67,7 +67,7 @@ func (decl *DeclForGen) Lineage() thema.Lineage { // ForLatestSchema returns a [SchemaForGen] for the latest schema in this // DeclForGen's lineage. func (decl *DeclForGen) ForLatestSchema() SchemaForGen { - comm := decl.Meta.Common() + comm := decl.Properties.Common() return SchemaForGen{ Name: comm.Name, Schema: decl.Lineage().Latest(), diff --git a/pkg/codegen/jenny_corestructkind.go b/pkg/codegen/jenny_corestructkind.go index 0d1fad63e17..98b0d318258 100644 --- a/pkg/codegen/jenny_corestructkind.go +++ b/pkg/codegen/jenny_corestructkind.go @@ -21,7 +21,7 @@ func CoreStructuredKindJenny(gokindsdir string, cfg *CoreStructuredKindGenerator } if cfg.GenDirName == nil { cfg.GenDirName = func(decl *DeclForGen) string { - return decl.Meta.Common().MachineName + return decl.Properties.Common().MachineName } } @@ -54,7 +54,7 @@ func (gen *genCoreStructuredKind) Generate(decl *DeclForGen) (*codejen.File, err return nil, nil } - path := filepath.Join(gen.gokindsdir, gen.cfg.GenDirName(decl), decl.Meta.Common().MachineName+"_kind_gen.go") + path := filepath.Join(gen.gokindsdir, gen.cfg.GenDirName(decl), decl.Properties.Common().MachineName+"_kind_gen.go") buf := new(bytes.Buffer) if err := tmpls.Lookup("kind_corestructured.tmpl").Execute(buf, decl); err != nil { return nil, fmt.Errorf("failed executing kind_corestructured template for %s: %w", path, err) diff --git a/pkg/codegen/jenny_eachmajor.go b/pkg/codegen/jenny_eachmajor.go index 766fcad5bf0..dd95e186ad6 100644 --- a/pkg/codegen/jenny_eachmajor.go +++ b/pkg/codegen/jenny_eachmajor.go @@ -33,7 +33,7 @@ func (j *lmox) Generate(decl *DeclForGen) (codejen.Files, error) { if decl.IsRaw() { return nil, nil } - comm := decl.Meta.Common() + comm := decl.Properties.Common() sfg := SchemaForGen{ Name: comm.Name, IsGroup: comm.LineageIsGroup, @@ -42,7 +42,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.Meta.Common().Name, err) + return nil, fmt.Errorf("%s jenny failed on %s schema for %s: %w", j.inner.JennyName(), sfg.Schema.Version(), decl.Properties.Common().Name, err) } if f == nil || !f.Exists() { return nil, nil diff --git a/pkg/codegen/jenny_rawkind.go b/pkg/codegen/jenny_rawkind.go index 45c1675a01b..b8e967c951f 100644 --- a/pkg/codegen/jenny_rawkind.go +++ b/pkg/codegen/jenny_rawkind.go @@ -21,7 +21,7 @@ func RawKindJenny(gokindsdir string, cfg *RawKindGeneratorConfig) OneToOne { } if cfg.GenDirName == nil { cfg.GenDirName = func(decl *DeclForGen) string { - return decl.Meta.Common().MachineName + return decl.Properties.Common().MachineName } } @@ -51,7 +51,7 @@ func (gen *genRawKind) Generate(decl *DeclForGen) (*codejen.File, error) { return nil, nil } - path := filepath.Join(gen.gokindsdir, gen.cfg.GenDirName(decl), decl.Meta.Common().MachineName+"_kind_gen.go") + path := filepath.Join(gen.gokindsdir, gen.cfg.GenDirName(decl), decl.Properties.Common().MachineName+"_kind_gen.go") buf := new(bytes.Buffer) if err := tmpls.Lookup("kind_raw.tmpl").Execute(buf, decl); err != nil { return nil, fmt.Errorf("failed executing kind_raw template for %s: %w", path, err) diff --git a/pkg/codegen/jenny_tsveneerindex.go b/pkg/codegen/jenny_tsveneerindex.go index 1d5b11dea2c..cfe70117ca5 100644 --- a/pkg/codegen/jenny_tsveneerindex.go +++ b/pkg/codegen/jenny_tsveneerindex.go @@ -48,15 +48,15 @@ func (gen *genTSVeneerIndex) Generate(decls ...*DeclForGen) (*codejen.File, erro sch := decl.Lineage().Latest() f, err := typescript.GenerateTypes(sch, &typescript.TypeConfig{ - RootName: decl.Meta.Common().Name, - Group: decl.Meta.Common().LineageIsGroup, + RootName: decl.Properties.Common().Name, + Group: decl.Properties.Common().LineageIsGroup, }) if err != nil { - return nil, fmt.Errorf("%s: %w", decl.Meta.Common().Name, err) + return nil, fmt.Errorf("%s: %w", decl.Properties.Common().Name, err) } elems, err := gen.extractTSIndexVeneerElements(decl, f) if err != nil { - return nil, fmt.Errorf("%s: %w", decl.Meta.Common().Name, err) + return nil, fmt.Errorf("%s: %w", decl.Properties.Common().Name, err) } tsf.Nodes = append(tsf.Nodes, elems...) } @@ -66,7 +66,7 @@ func (gen *genTSVeneerIndex) Generate(decls ...*DeclForGen) (*codejen.File, erro func (gen *genTSVeneerIndex) extractTSIndexVeneerElements(decl *DeclForGen, tf *ast.File) ([]ast.Decl, error) { lin := decl.Lineage() - comm := decl.Meta.Common() + comm := decl.Properties.Common() // Check the root, then walk the tree rootv := lin.Latest().Underlying() @@ -131,7 +131,7 @@ func (gen *genTSVeneerIndex) extractTSIndexVeneerElements(decl *DeclForGen, tf * } vpath := fmt.Sprintf("v%v", thema.LatestVersion(lin)[0]) - if decl.Meta.Common().Maturity.Less(kindsys.MaturityStable) { + if decl.Properties.Common().Maturity.Less(kindsys.MaturityStable) { vpath = "x" } diff --git a/pkg/codegen/latest_jenny.go b/pkg/codegen/latest_jenny.go index 5f24052a46a..327ef398663 100644 --- a/pkg/codegen/latest_jenny.go +++ b/pkg/codegen/latest_jenny.go @@ -35,7 +35,7 @@ func (j *latestj) Generate(decl *DeclForGen) (*codejen.File, error) { if decl.IsRaw() { return nil, nil } - comm := decl.Meta.Common() + comm := decl.Properties.Common() sfg := SchemaForGen{ Name: comm.Name, Schema: decl.Lineage().Latest(), @@ -44,7 +44,7 @@ func (j *latestj) Generate(decl *DeclForGen) (*codejen.File, 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.Meta.Common().Name, err) + return nil, fmt.Errorf("%s jenny failed on %s schema for %s: %w", j.inner.JennyName(), sfg.Schema.Version(), decl.Properties.Common().Name, err) } if f == nil || !f.Exists() { return nil, nil diff --git a/pkg/codegen/tmpl/kind_corestructured.tmpl b/pkg/codegen/tmpl/kind_corestructured.tmpl index a02a686b687..6e6755224ea 100644 --- a/pkg/codegen/tmpl/kind_corestructured.tmpl +++ b/pkg/codegen/tmpl/kind_corestructured.tmpl @@ -1,4 +1,4 @@ -package {{ .Meta.MachineName }} +package {{ .Properties.MachineName }} import ( "github.com/grafana/grafana/pkg/kindsys" @@ -10,14 +10,14 @@ import ( // directory containing the .cue files in which this kind is declared. Necessary // for runtime errors related to the declaration and/or lineage to provide // a real path to the correct .cue file. -const rootrel string = "kinds/structured/{{ .Meta.MachineName }}" +const rootrel string = "kinds/structured/{{ .Properties.MachineName }}" // TODO standard generated docs type Kind struct { - lin thema.ConvergentLineage[*{{ .Meta.Name }}] + lin thema.ConvergentLineage[*{{ .Properties.Name }}] jcodec vmux.Codec - valmux vmux.ValueMux[*{{ .Meta.Name }}] - decl kindsys.Decl[kindsys.CoreStructuredMeta] + valmux vmux.ValueMux[*{{ .Properties.Name }}] + decl kindsys.Decl[kindsys.CoreStructuredProperties] } // type guard @@ -25,7 +25,7 @@ var _ kindsys.Structured = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind[kindsys.CoreStructuredMeta](rootrel, rt.Context(), nil) + decl, err := kindsys.LoadCoreKind[kindsys.CoreStructuredProperties](rootrel, rt.Context(), nil) if err != nil { return nil, err } @@ -40,14 +40,14 @@ func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { // 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.Meta.CurrentVersion) - tsch, err := thema.BindType[*{{ .Meta.Name }}](cursch, &{{ .Meta.Name }}{}) + cursch := thema.SchemaP(lin, k.decl.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 return nil, err } - k.jcodec = vmux.NewJSONCodec("{{ .Meta.MachineName }}.json") + k.jcodec = vmux.NewJSONCodec("{{ .Properties.MachineName }}.json") k.lin = tsch.ConvergentLineage() k.valmux = vmux.NewValueMux(k.lin.TypedSchema(), k.jcodec) return k, nil @@ -55,12 +55,12 @@ func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { // TODO standard generated docs func (k *Kind) Name() string { - return "{{ .Meta.MachineName }}" + return "{{ .Properties.MachineName }}" } // TODO standard generated docs func (k *Kind) MachineName() string { - return "{{ .Meta.MachineName }}" + return "{{ .Properties.MachineName }}" } // TODO standard generated docs @@ -69,28 +69,37 @@ func (k *Kind) Lineage() thema.Lineage { } // TODO standard generated docs -func (k *Kind) ConvergentLineage() thema.ConvergentLineage[*{{ .Meta.Name }}] { +func (k *Kind) ConvergentLineage() thema.ConvergentLineage[*{{ .Properties.Name }}] { return k.lin } // JSONValueMux is a version multiplexer that maps a []byte containing JSON data -// at any schematized dashboard version to an instance of {{ .Meta.Name }}. +// at any schematized dashboard version to an instance of {{ .Properties.Name }}. // // Validation and translation errors emitted from this func will identify the // input bytes as "dashboard.json". // // This is a thin wrapper around Thema's [vmux.ValueMux]. -func (k *Kind) JSONValueMux(b []byte) (*{{ .Meta.Name }}, thema.TranslationLacunas, error) { +func (k *Kind) JSONValueMux(b []byte) (*{{ .Properties.Name }}, thema.TranslationLacunas, error) { return k.valmux(b) } // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Meta.Maturity + return k.decl.Properties.Maturity } -// TODO standard generated docs -func (k *Kind) Decl() *kindsys.Decl[kindsys.CoreStructuredMeta] { +// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// {{ .Properties.MachineName }} declaration in .cue files. +func (k *Kind) Decl() *kindsys.Decl[kindsys.CoreStructuredProperties] { d := k.decl return &d } + +// Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreStructuredProperties], +// 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]. +func (k *Kind) Props() kindsys.SomeKindProperties { + return k.decl.Properties +} diff --git a/pkg/codegen/tmpl/kind_raw.tmpl b/pkg/codegen/tmpl/kind_raw.tmpl index a38070c67e3..52380de4500 100644 --- a/pkg/codegen/tmpl/kind_raw.tmpl +++ b/pkg/codegen/tmpl/kind_raw.tmpl @@ -1,4 +1,4 @@ -package {{ .Meta.MachineName }} +package {{ .Properties.MachineName }} import ( "github.com/grafana/grafana/pkg/kindsys" @@ -8,7 +8,7 @@ import ( // TODO standard generated docs type Kind struct { - decl kindsys.Decl[kindsys.RawMeta] + decl kindsys.Decl[kindsys.RawProperties] } // type guard @@ -16,7 +16,7 @@ var _ kindsys.Raw = &Kind{} // TODO standard generated docs func NewKind() (*Kind, error) { - decl, err := kindsys.LoadCoreKind[kindsys.RawMeta]("kinds/raw/{{ .Meta.MachineName }}", nil, nil) + decl, err := kindsys.LoadCoreKind[kindsys.RawProperties]("kinds/raw/{{ .Properties.MachineName }}", nil, nil) if err != nil { return nil, err } @@ -28,21 +28,30 @@ func NewKind() (*Kind, error) { // TODO standard generated docs func (k *Kind) Name() string { - return "{{ .Meta.Name }}" + return "{{ .Properties.Name }}" } // TODO standard generated docs func (k *Kind) MachineName() string { - return "{{ .Meta.MachineName }}" + return "{{ .Properties.MachineName }}" } // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Meta.Maturity + return k.decl.Properties.Maturity } -// TODO standard generated docs -func (k *Kind) Decl() *kindsys.Decl[kindsys.RawMeta] { +// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// {{ .Properties.MachineName }} declaration in .cue files. +func (k *Kind) Decl() *kindsys.Decl[kindsys.RawProperties] { d := k.decl return &d } + +// Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.RawProperties], +// 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]. +func (k *Kind) Props() kindsys.SomeKindProperties { + return k.decl.Properties +} diff --git a/pkg/codegen/tmpl/kind_registry.tmpl b/pkg/codegen/tmpl/kind_registry.tmpl index e323903a9f9..dc21571c0ea 100644 --- a/pkg/codegen/tmpl/kind_registry.tmpl +++ b/pkg/codegen/tmpl/kind_registry.tmpl @@ -5,7 +5,7 @@ import ( "sync" {{range .Kinds }} - "{{ $.KindPackagePrefix }}/{{ .Meta.MachineName }}"{{end}} + "{{ $.KindPackagePrefix }}/{{ .Properties.MachineName }}"{{end}} "github.com/grafana/grafana/pkg/cuectx" "github.com/grafana/grafana/pkg/kindsys" "github.com/grafana/thema" @@ -25,19 +25,19 @@ type Base struct { all []kindsys.Interface numRaw, numStructured int {{- range .Kinds }} - {{ .Meta.MachineName }} *{{ .Meta.MachineName }}.Kind{{end}} + {{ .Properties.MachineName }} *{{ .Properties.MachineName }}.Kind{{end}} } // type guards var ( {{- range .Kinds }} - _ kindsys.{{ if .IsRaw }}Raw{{ else }}Structured{{ end }} = &{{ .Meta.MachineName }}.Kind{}{{end}} + _ kindsys.{{ if .IsRaw }}Raw{{ else }}Structured{{ end }} = &{{ .Properties.MachineName }}.Kind{}{{end}} ) {{range .Kinds }} -// {{ .Meta.Name }} returns the [kindsys.Interface] implementation for the {{ .Meta.MachineName }} kind. -func (b *Base) {{ .Meta.Name }}() *{{ .Meta.MachineName }}.Kind { - return b.{{ .Meta.MachineName }} +// {{ .Properties.Name }} returns the [kindsys.Interface] implementation for the {{ .Properties.MachineName }} kind. +func (b *Base) {{ .Properties.Name }}() *{{ .Properties.MachineName }}.Kind { + return b.{{ .Properties.MachineName }} } {{end}} @@ -49,11 +49,11 @@ func doNewBase(rt *thema.Runtime) *Base { } {{range .Kinds }} - reg.{{ .Meta.MachineName }}, err = {{ .Meta.MachineName }}.NewKind({{ if .IsCoreStructured }}rt{{ end }}) + reg.{{ .Properties.MachineName }}, err = {{ .Properties.MachineName }}.NewKind({{ if .IsCoreStructured }}rt{{ end }}) if err != nil { - panic(fmt.Sprintf("error while initializing the {{ .Meta.MachineName }} Kind: %s", err)) + panic(fmt.Sprintf("error while initializing the {{ .Properties.MachineName }} Kind: %s", err)) } - reg.all = append(reg.all, reg.{{ .Meta.MachineName }}) + reg.all = append(reg.all, reg.{{ .Properties.MachineName }}) {{end}} return reg diff --git a/pkg/kinds/dashboard/dashboard_kind_gen.go b/pkg/kinds/dashboard/dashboard_kind_gen.go index 71c47986121..f99cd07950c 100644 --- a/pkg/kinds/dashboard/dashboard_kind_gen.go +++ b/pkg/kinds/dashboard/dashboard_kind_gen.go @@ -26,7 +26,7 @@ type Kind struct { lin thema.ConvergentLineage[*Dashboard] jcodec vmux.Codec valmux vmux.ValueMux[*Dashboard] - decl kindsys.Decl[kindsys.CoreStructuredMeta] + decl kindsys.Decl[kindsys.CoreStructuredProperties] } // type guard @@ -34,7 +34,7 @@ var _ kindsys.Structured = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind[kindsys.CoreStructuredMeta](rootrel, rt.Context(), nil) + decl, err := kindsys.LoadCoreKind[kindsys.CoreStructuredProperties](rootrel, rt.Context(), nil) if err != nil { return nil, err } @@ -49,7 +49,7 @@ func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { // 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.Meta.CurrentVersion) + cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) tsch, err := thema.BindType[*Dashboard](cursch, &Dashboard{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -95,11 +95,20 @@ func (k *Kind) JSONValueMux(b []byte) (*Dashboard, thema.TranslationLacunas, err // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Meta.Maturity + return k.decl.Properties.Maturity } -// TODO standard generated docs -func (k *Kind) Decl() *kindsys.Decl[kindsys.CoreStructuredMeta] { +// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// dashboard declaration in .cue files. +func (k *Kind) Decl() *kindsys.Decl[kindsys.CoreStructuredProperties] { d := k.decl return &d } + +// Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreStructuredProperties], +// representing the static properties declared in the dashboard kind. +// +// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +func (k *Kind) Props() kindsys.SomeKindProperties { + return k.decl.Properties +} diff --git a/pkg/kinds/playlist/playlist_kind_gen.go b/pkg/kinds/playlist/playlist_kind_gen.go index e67a4bc3dc2..ee9026aedcd 100644 --- a/pkg/kinds/playlist/playlist_kind_gen.go +++ b/pkg/kinds/playlist/playlist_kind_gen.go @@ -26,7 +26,7 @@ type Kind struct { lin thema.ConvergentLineage[*Playlist] jcodec vmux.Codec valmux vmux.ValueMux[*Playlist] - decl kindsys.Decl[kindsys.CoreStructuredMeta] + decl kindsys.Decl[kindsys.CoreStructuredProperties] } // type guard @@ -34,7 +34,7 @@ var _ kindsys.Structured = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind[kindsys.CoreStructuredMeta](rootrel, rt.Context(), nil) + decl, err := kindsys.LoadCoreKind[kindsys.CoreStructuredProperties](rootrel, rt.Context(), nil) if err != nil { return nil, err } @@ -49,7 +49,7 @@ func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { // 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.Meta.CurrentVersion) + cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) tsch, err := thema.BindType[*Playlist](cursch, &Playlist{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -95,11 +95,20 @@ func (k *Kind) JSONValueMux(b []byte) (*Playlist, thema.TranslationLacunas, erro // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Meta.Maturity + return k.decl.Properties.Maturity } -// TODO standard generated docs -func (k *Kind) Decl() *kindsys.Decl[kindsys.CoreStructuredMeta] { +// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// playlist declaration in .cue files. +func (k *Kind) Decl() *kindsys.Decl[kindsys.CoreStructuredProperties] { d := k.decl return &d } + +// Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreStructuredProperties], +// representing the static properties declared in the playlist kind. +// +// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +func (k *Kind) Props() kindsys.SomeKindProperties { + return k.decl.Properties +} diff --git a/pkg/kinds/svg/svg_kind_gen.go b/pkg/kinds/svg/svg_kind_gen.go index b3f6a4f3150..117a525c8a8 100644 --- a/pkg/kinds/svg/svg_kind_gen.go +++ b/pkg/kinds/svg/svg_kind_gen.go @@ -15,7 +15,7 @@ import ( // TODO standard generated docs type Kind struct { - decl kindsys.Decl[kindsys.RawMeta] + decl kindsys.Decl[kindsys.RawProperties] } // type guard @@ -23,7 +23,7 @@ var _ kindsys.Raw = &Kind{} // TODO standard generated docs func NewKind() (*Kind, error) { - decl, err := kindsys.LoadCoreKind[kindsys.RawMeta]("kinds/raw/svg", nil, nil) + decl, err := kindsys.LoadCoreKind[kindsys.RawProperties]("kinds/raw/svg", nil, nil) if err != nil { return nil, err } @@ -45,11 +45,20 @@ func (k *Kind) MachineName() string { // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Meta.Maturity + return k.decl.Properties.Maturity } -// TODO standard generated docs -func (k *Kind) Decl() *kindsys.Decl[kindsys.RawMeta] { +// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// svg declaration in .cue files. +func (k *Kind) Decl() *kindsys.Decl[kindsys.RawProperties] { d := k.decl return &d } + +// Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.RawProperties], +// representing the static properties declared in the svg kind. +// +// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +func (k *Kind) Props() kindsys.SomeKindProperties { + return k.decl.Properties +} diff --git a/pkg/kinds/team/team_kind_gen.go b/pkg/kinds/team/team_kind_gen.go index 0401069ee17..2a8fd883210 100644 --- a/pkg/kinds/team/team_kind_gen.go +++ b/pkg/kinds/team/team_kind_gen.go @@ -26,7 +26,7 @@ type Kind struct { lin thema.ConvergentLineage[*Team] jcodec vmux.Codec valmux vmux.ValueMux[*Team] - decl kindsys.Decl[kindsys.CoreStructuredMeta] + decl kindsys.Decl[kindsys.CoreStructuredProperties] } // type guard @@ -34,7 +34,7 @@ var _ kindsys.Structured = &Kind{} // TODO standard generated docs func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { - decl, err := kindsys.LoadCoreKind[kindsys.CoreStructuredMeta](rootrel, rt.Context(), nil) + decl, err := kindsys.LoadCoreKind[kindsys.CoreStructuredProperties](rootrel, rt.Context(), nil) if err != nil { return nil, err } @@ -49,7 +49,7 @@ func NewKind(rt *thema.Runtime, opts ...thema.BindOption) (*Kind, error) { // 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.Meta.CurrentVersion) + cursch := thema.SchemaP(lin, k.decl.Properties.CurrentVersion) tsch, err := thema.BindType[*Team](cursch, &Team{}) if err != nil { // Should be unreachable, modulo bugs in the Thema->Go code generator @@ -95,11 +95,20 @@ func (k *Kind) JSONValueMux(b []byte) (*Team, thema.TranslationLacunas, error) { // TODO standard generated docs func (k *Kind) Maturity() kindsys.Maturity { - return k.decl.Meta.Maturity + return k.decl.Properties.Maturity } -// TODO standard generated docs -func (k *Kind) Decl() *kindsys.Decl[kindsys.CoreStructuredMeta] { +// Decl returns the [kindsys.Decl] containing both CUE and Go representations of the +// team declaration in .cue files. +func (k *Kind) Decl() *kindsys.Decl[kindsys.CoreStructuredProperties] { d := k.decl return &d } + +// Props returns a [kindsys.SomeKindProps], with underlying type [kindsys.CoreStructuredProperties], +// representing the static properties declared in the team kind. +// +// This method is identical to calling Decl().Props. It is provided to satisfy [kindsys.Interface]. +func (k *Kind) Props() kindsys.SomeKindProperties { + return k.decl.Properties +} diff --git a/pkg/kindsys/kind.go b/pkg/kindsys/kind.go index 9839954fb69..2add53e98ad 100644 --- a/pkg/kindsys/kind.go +++ b/pkg/kindsys/kind.go @@ -41,15 +41,25 @@ func (m Maturity) Less(om Maturity) bool { return maturityIdx(m) < maturityIdx(om) } -// TODO docs +// Interface describes a Grafana kind object: a Go representation of the definition of +// one of Grafana's categories of kinds. type Interface interface { - // TODO docs + // 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. + Props() SomeKindProperties + + // TODO remove, unnecessary with Props() Name() string - // TODO docs + // TODO remove, unnecessary with Props() MachineName() string - // TODO docs + // TODO remove, unnecessary with Props() Maturity() Maturity // TODO unclear if we want maturity for raw kinds } @@ -58,7 +68,7 @@ type Raw interface { Interface // TODO docs - Decl() *Decl[RawMeta] + Decl() *Decl[RawProperties] } type Structured interface { @@ -68,7 +78,7 @@ type Structured interface { Lineage() thema.Lineage // TODO docs - Decl() *Decl[CoreStructuredMeta] // TODO figure out how to reconcile this interface with CustomStructuredMeta + Decl() *Decl[CoreStructuredProperties] // TODO figure out how to reconcile this interface with CustomStructuredProperties } // type Composable interface { @@ -78,5 +88,5 @@ type Structured interface { // Lineage() thema.Lineage // // // TODO docs -// Meta() CoreStructuredMeta // TODO figure out how to reconcile this interface with CustomStructuredMeta +// Properties() CoreStructuredProperties // TODO figure out how to reconcile this interface with CustomStructuredProperties // } diff --git a/pkg/kindsys/kindmetas.go b/pkg/kindsys/kindmetas.go index 5470d8e26d6..0e366434337 100644 --- a/pkg/kindsys/kindmetas.go +++ b/pkg/kindsys/kindmetas.go @@ -2,8 +2,8 @@ package kindsys import "github.com/grafana/thema" -// CommonMeta contains the metadata common to all categories of kinds. -type CommonMeta struct { +// CommonProperties contains the metadata common to all categories of kinds. +type CommonProperties struct { Name string `json:"name"` PluralName string `json:"pluralName"` MachineName string `json:"machineName"` @@ -12,63 +12,78 @@ type CommonMeta struct { Maturity Maturity `json:"maturity"` } -// TODO generate from type.cue -type RawMeta struct { - CommonMeta +// RawProperties represents the static properties in a #Raw kind declaration that are +// trivially representable with basic Go types. +// +// When a .cue #Raw declaration is loaded through the standard [LoadCoreKind], +// func, it is fully validated and populated according to all rules specified +// in CUE for #Raw kinds. +type RawProperties struct { + CommonProperties Extensions []string `json:"extensions"` } -func (m RawMeta) _private() {} -func (m RawMeta) Common() CommonMeta { - return m.CommonMeta +func (m RawProperties) _private() {} +func (m RawProperties) Common() CommonProperties { + return m.CommonProperties } -// TODO -type CoreStructuredMeta struct { - CommonMeta +// CoreStructuredProperties represents the static properties in the declaration of a +// #CoreStructured kind that are representable with basic Go types. This +// excludes Thema schemas. +// +// When a .cue #CoreStructured declaration is loaded through the standard [LoadCoreKind], +// func, it is fully validated and populated according to all rules specified +// in CUE for #CoreStructured kinds. +type CoreStructuredProperties struct { + CommonProperties CurrentVersion thema.SyntacticVersion `json:"currentVersion"` } -func (m CoreStructuredMeta) _private() {} -func (m CoreStructuredMeta) Common() CommonMeta { - return m.CommonMeta +func (m CoreStructuredProperties) _private() {} +func (m CoreStructuredProperties) Common() CommonProperties { + return m.CommonProperties } -// TODO -type CustomStructuredMeta struct { - CommonMeta +// CustomStructuredProperties represents the static properties in the declaration of a +// #CustomStructured kind that are representable with basic Go types. This +// excludes Thema schemas. +type CustomStructuredProperties struct { + CommonProperties CurrentVersion thema.SyntacticVersion `json:"currentVersion"` } -func (m CustomStructuredMeta) _private() {} -func (m CustomStructuredMeta) Common() CommonMeta { - return m.CommonMeta +func (m CustomStructuredProperties) _private() {} +func (m CustomStructuredProperties) Common() CommonProperties { + return m.CommonProperties } -// TODO -type ComposableMeta struct { - CommonMeta +// ComposableProperties represents the static properties in the declaration of a +// #Composable kind that are representable with basic Go types. This +// excludes Thema schemas. +type ComposableProperties struct { + CommonProperties CurrentVersion thema.SyntacticVersion `json:"currentVersion"` } -func (m ComposableMeta) _private() {} -func (m ComposableMeta) Common() CommonMeta { - return m.CommonMeta +func (m ComposableProperties) _private() {} +func (m ComposableProperties) Common() CommonProperties { + return m.CommonProperties } -// SomeKindMeta is an interface type to abstract over the different kind -// metadata struct types: [RawMeta], [CoreStructuredMeta], -// [CustomStructuredMeta]. +// SomeKindProperties is an interface type to abstract over the different kind +// property struct types: [RawProperties], [CoreStructuredProperties], +// [CustomStructuredProperties], [ComposableProperties]. // // It is the traditional interface counterpart to the generic type constraint -// KindMetas. -type SomeKindMeta interface { +// KindProperties. +type SomeKindProperties interface { _private() - Common() CommonMeta + Common() CommonProperties } -// KindMetas is a type parameter that comprises the base possible set of +// KindProperties is a type parameter that comprises the base possible set of // kind metadata configurations. -type KindMetas interface { - RawMeta | CoreStructuredMeta | CustomStructuredMeta | ComposableMeta +type KindProperties interface { + RawProperties | CoreStructuredProperties | CustomStructuredProperties | ComposableProperties } diff --git a/pkg/kindsys/load.go b/pkg/kindsys/load.go index 81bf9073c9f..710cb425b49 100644 --- a/pkg/kindsys/load.go +++ b/pkg/kindsys/load.go @@ -83,52 +83,52 @@ func CUEFramework(ctx *cue.Context) cue.Value { // ToKindMeta takes a cue.Value expected to represent a kind of the category // specified by the type parameter and populates the Go type from the cue.Value. -func ToKindMeta[T KindMetas](v cue.Value) (T, error) { - meta := new(T) +func ToKindMeta[T KindProperties](v cue.Value) (T, error) { + props := new(T) if !v.Exists() { - return *meta, ErrValueNotExist + return *props, ErrValueNotExist } fw := CUEFramework(v.Context()) var kdef cue.Value - anymeta := any(*meta).(SomeKindMeta) - switch anymeta.(type) { - case RawMeta: + anyprops := any(*props).(SomeKindProperties) + switch anyprops.(type) { + case RawProperties: kdef = fw.LookupPath(cue.MakePath(cue.Def("Raw"))) - case CoreStructuredMeta: + case CoreStructuredProperties: kdef = fw.LookupPath(cue.MakePath(cue.Def("CoreStructured"))) - case CustomStructuredMeta: + case CustomStructuredProperties: kdef = fw.LookupPath(cue.MakePath(cue.Def("CustomStructured"))) - case ComposableMeta: + case ComposableProperties: kdef = fw.LookupPath(cue.MakePath(cue.Def("Composable"))) default: - // unreachable so long as all the possibilities in KindMetas have switch branches + // unreachable so long as all the possibilities in KindProperties have switch branches panic("unreachable") } item := v.Unify(kdef) if err := item.Validate(cue.Concrete(false), cue.All()); err != nil { - return *meta, ewrap(item.Err(), ErrValueNotAKind) + return *props, ewrap(item.Err(), ErrValueNotAKind) } - if err := item.Decode(meta); err != nil { + if err := item.Decode(props); err != nil { // Should only be reachable if CUE and Go framework types have diverged panic(errors.Details(err, nil)) } - return *meta, nil + return *props, nil } // SomeDecl represents a single kind declaration, having been loaded // and validated by a func such as [LoadCoreKind]. // -// The underlying type of the Meta field indicates the category of +// 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. V cue.Value - // Meta contains the kind's metadata settings. - Meta SomeKindMeta + // Properties contains the kind's declared properties. + Properties SomeKindProperties } // BindKindLineage binds the lineage for the kind declaration. nil, nil is returned @@ -140,10 +140,10 @@ func (decl *SomeDecl) BindKindLineage(rt *thema.Runtime, opts ...thema.BindOptio if rt == nil { rt = cuectx.GrafanaThemaRuntime() } - switch decl.Meta.(type) { - case RawMeta: + switch decl.Properties.(type) { + case RawProperties: return nil, nil - case CoreStructuredMeta, CustomStructuredMeta, ComposableMeta: + case CoreStructuredProperties, CustomStructuredProperties, ComposableProperties: return thema.BindLineage(decl.V.LookupPath(cue.MakePath(cue.Str("lineage"))), rt, opts...) default: panic("unreachable") @@ -152,25 +152,25 @@ func (decl *SomeDecl) BindKindLineage(rt *thema.Runtime, opts ...thema.BindOptio // IsRaw indicates whether the represented kind is a raw kind. func (decl *SomeDecl) IsRaw() bool { - _, is := decl.Meta.(RawMeta) + _, is := decl.Properties.(RawProperties) return is } // IsCoreStructured indicates whether the represented kind is a core structured kind. func (decl *SomeDecl) IsCoreStructured() bool { - _, is := decl.Meta.(CoreStructuredMeta) + _, is := decl.Properties.(CoreStructuredProperties) return is } // IsCustomStructured indicates whether the represented kind is a custom structured kind. func (decl *SomeDecl) IsCustomStructured() bool { - _, is := decl.Meta.(CustomStructuredMeta) + _, is := decl.Properties.(CustomStructuredProperties) return is } // IsComposable indicates whether the represented kind is a composable kind. func (decl *SomeDecl) IsComposable() bool { - _, is := decl.Meta.(ComposableMeta) + _, is := decl.Properties.(ComposableProperties) return is } @@ -178,18 +178,18 @@ func (decl *SomeDecl) IsComposable() bool { // and validated by a func such as [LoadCoreKind]. // // Its type parameter indicates the category of kind. -type Decl[T KindMetas] struct { +type Decl[T KindProperties] struct { // V is the cue.Value containing the entire Kind declaration. V cue.Value - // Meta contains the kind's metadata settings. - Meta T + // Properties contains the kind's declared properties. + Properties T } // Some converts the typed Decl to the equivalent typeless SomeDecl. func (decl *Decl[T]) Some() *SomeDecl { return &SomeDecl{ - V: decl.V, - Meta: any(decl.Meta).(SomeKindMeta), + V: decl.V, + Properties: any(decl.Properties).(SomeKindProperties), } } @@ -210,7 +210,7 @@ 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[T RawMeta | CoreStructuredMeta](declpath string, ctx *cue.Context, overlay fs.FS) (*Decl[T], error) { +func LoadCoreKind[T RawProperties | CoreStructuredProperties](declpath string, ctx *cue.Context, overlay fs.FS) (*Decl[T], error) { vk, err := cuectx.BuildGrafanaInstance(ctx, declpath, "kind", overlay) if err != nil { return nil, err @@ -218,7 +218,7 @@ func LoadCoreKind[T RawMeta | CoreStructuredMeta](declpath string, ctx *cue.Cont decl := &Decl[T]{ V: vk, } - decl.Meta, err = ToKindMeta[T](vk) + decl.Properties, err = ToKindMeta[T](vk) if err != nil { return nil, err }