cuectx

Documentation

Index

• Variables
• func BuildGrafanaInstance(ctx *cue.Context, relpath string, pkg string, overlay fs.FS) (cue.Value, error)
• func ConvertImport(im *ast.ImportSpec) (tsast.ImportSpec, error)
• func GrafanaCUEContext() *cue.Context
• func GrafanaThemaRuntime() *thema.Runtime
• func JSONtoCUE(path string, b []byte) (cue.Value, error)
• func LoadCoreKindDef(defpath string, ctx *cue.Context, overlay fs.FS) (kindsys.Def[kindsys.CoreProperties], error)
• func LoadGrafanaInstance(relpath string, pkg string, overlay fs.FS) (*build.Instance, error)
• func LoadGrafanaInstancesWithThema(path string, cueFS fs.FS, rt *thema.Runtime, opts ...thema.BindOption) (thema.Lineage, error)
• func LoadInstanceWithGrafana(fsys fs.FS, dir string, opts ...load.Option) (*build.Instance, error)
• func MapCUEImportToTS(path string) (string, error)
• func PermittedCUEImports() []string

Variables

var CoreDefParentPath = "kinds"

CoreDefParentPath is the path, relative to the repository root, where each child directory is expected to contain .cue files defining one Core kind.

var GoCoreKindParentPath = filepath.Join("pkg", "kinds")

GoCoreKindParentPath is the path, relative to the repository root, to the directory containing one directory per kind, full of generated Go kind output: types and bindings.

var TSCoreKindParentPath = filepath.Join("packages", "grafana-schema", "src", "raw")

TSCoreKindParentPath is the path, relative to the repository root, to the directory that contains one directory per kind, full of generated TS kind output: types and default consts.

Functions

func BuildGrafanaInstance

func BuildGrafanaInstance(ctx *cue.Context, relpath string, pkg string, overlay fs.FS) (cue.Value, error)

BuildGrafanaInstance wraps LoadGrafanaInstance, additionally building the returned *build.Instance into a cue.Value.

An error is returned if:

• The underlying call to LoadGrafanaInstance returns an error
• The built cue.Value has an error (cue.Value.Err returns non-nil)

NOTE this function will be deprecated in favor of a more generic builder

func ConvertImport

func ConvertImport(im *ast.ImportSpec) (tsast.ImportSpec, error)

ConvertImport converts a CUE import statement, represented in its AST form, to the corresponding TS import, if the CUE import is allowed.

Some CUE imports are allowed but have no corresponding TS import - the CUE types from that package are expected to be inlined.

func GrafanaCUEContext

func GrafanaCUEContext() *cue.Context

GrafanaCUEContext returns Grafana's singleton instance of cue.Context.

All code within grafana/grafana that needs a *cue.Context should get it from this function, when one was not otherwise provided.

func GrafanaThemaRuntime

func GrafanaThemaRuntime() *thema.Runtime

GrafanaThemaRuntime returns Grafana's singleton instance of thema.Runtime.

All code within grafana/grafana that needs a *thema.Runtime should get it from this function, when one was not otherwise provided.

func JSONtoCUE

func JSONtoCUE(path string, b []byte) (cue.Value, error)

JSONtoCUE attempts to decode the given []byte into a cue.Value, relying on the central Grafana cue.Context provided in this package.

The provided path argument determines the name given to the input bytes if later CUE operations (e.g. Thema validation) produce errors related to the returned cue.Value.

This is a convenience function for one-off JSON decoding. It's wasteful to call it repeatedly. Most use cases should probably prefer making their own Thema/CUE decoders.

func LoadCoreKindDef

func LoadCoreKindDef(defpath string, ctx *cue.Context, overlay fs.FS) (kindsys.Def[kindsys.CoreProperties], error)

LoadCoreKindDef loads and validates a core kind definition of the kind category indicated by the type parameter. On success, it returns a [Def] which contains the entire contents of the kind definition.

defpath is the path to the directory containing the core kind definition, relative to the root of the caller's repository. For example, under dashboards are in "kinds/dashboard".

func LoadGrafanaInstance

func LoadGrafanaInstance(relpath string, pkg string, overlay fs.FS) (*build.Instance, error)

LoadGrafanaInstance wraps load.InstanceWithThema to load a *build.Instance corresponding to a particular path within the github.com/grafana/grafana CUE module.

This allows resolution of imports within the grafana or thema CUE modules to work correctly and consistently by relying on the embedded FS at grafana.CueSchemaFS and thema.CueFS.

relpath should be a relative path path within grafana.CueSchemaFS to be loaded. Optionally, the caller may provide an additional fs.FS via the overlay parameter, which will be merged with grafana.CueSchemaFS at relpath, and loaded.

pkg, if non-empty, is set as the value of ["cuelang.org/go/cue/load".Config.Package]. If the CUE package to be loaded is the same as the parent directory name, it should be omitted.

NOTE this function will be deprecated in favor of a more generic loader

func LoadGrafanaInstancesWithThema

func LoadGrafanaInstancesWithThema(path string, cueFS fs.FS, rt *thema.Runtime, opts ...thema.BindOption) (thema.Lineage, error)

LoadGrafanaInstancesWithThema loads CUE files containing a lineage representing some Grafana core model schema. It is expected to be used when implementing a thema.LineageFactory.

This function primarily juggles paths to make CUE's loader happy. Provide the path from the grafana root to the directory containing the lineage.cue. The lineage.cue file must be the sole contents of the provided fs.FS.

More details on underlying behavior can be found in the docs for github.com/grafana/thema/load.InstanceWithThema.

TODO this approach is complicated and confusing, refactor to something understandable

func LoadInstanceWithGrafana

func LoadInstanceWithGrafana(fsys fs.FS, dir string, opts ...load.Option) (*build.Instance, error)

LoadInstanceWithGrafana loads a *build.Instance from .cue files in the provided modFS as ["cuelang.org/go/cue/load".Instances], but fulfilling any imports of CUE packages under:

• github.com/grafana/grafana
• github.com/grafana/thema

This function is modeled after load.InstanceWithThema. It has the same signature and expectations for the modFS.

Attempting to use this func to load files within the github.com/grafana/grafana CUE module will result in an error. Use LoadGrafanaInstance instead.

NOTE This function will be deprecated in favor of a more generic loader

func MapCUEImportToTS

func MapCUEImportToTS(path string) (string, error)

MapCUEImportToTS maps the provided CUE import path to the corresponding TypeScript import path in generated code.

Providing an import path that is not allowed results in an error. If a nil error and empty string are returned, the import path should be dropped in generated code.

func PermittedCUEImports

func PermittedCUEImports() []string

PermittedCUEImports returns the list of import paths that may be imported in Grafana kind definitions.