cog

README

cog

cog is a CLI tool to generate code from schemas.

Maturity

The code in this repository should be considered experimental. Documentation is only available alongside the code. It comes with no support, but we are keen to receive feedback on the product and suggestions on how to improve it, though we cannot commit to resolution of any particular issue. No SLAs are available. It is not meant to be used in production environments, and the risks are unknown/high.

Grafana Labs defines experimental features as follows:

Projects and features in the Experimental stage are supported only by the Engineering teams; on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.

Experimental projects or features are primarily intended for open source engineers who want to participate in ensuring systems stability, and to gain consensus and approval for open source governance projects.

Projects and features in the Experimental phase are not meant to be used in production environments, and the risks are unknown/high.

Goals

• Support common schema formats: JSON Schema, OpenAPI, ...
• Generate code in a wide range of languages: Golang, Typescript, Java, ...
• Generate types described by schemas
• Generate developer-friendly builder libraries, allowing the creation of complex Grafana-related objects as-code

Usage

For the kind-registry:

$ git clone https://github.com/grafana/kind-registry ../kind-registry
$ devbox run gen-sdk-dev

Development setup

cog relies on devbox to manage all the tools and programming languages it targets.

A shell including all the required tools is accessible via:

$ devbox shell

This shell can be exited like any other shell, with exit or CTRL+D.

One-off commands can be executed within the devbox shell as well:

$ devbox run go version

Packages can be installed using:

devbox add go@1.23

Available packages can be found on the NixOS package repository.

Documentation

Overview

Example (CueModule)

ExampleCueModule demonstrates how to generate types from a CUE module living on the filesystem.

files, err := TypesFromSchema().
	CUEModule("/path/to/cue/module").
	Golang(GoConfig{}).
	Run(context.Background())
if err != nil {
	panic(err)
}

if len(files) != 1 {
	panic("expected a single file :(")
}

fmt.Println(string(files[0].Data))

Example (CueValue)

ExampleCueValue demonstrates how to generate types from a CUE value.

schema := `
// Contains things.
Container: {
    str: string
}

// This is a bar.
Bar: {
       type: "bar"
       foo: string
}
`

cueValue := cuecontext.New().CompileString(schema)
if cueValue.Err() != nil {
	panic(cueValue.Err())
}

files, err := TypesFromSchema().
	CUEValue("sandbox", cueValue).
	Golang(GoConfig{}).
	Run(context.Background())
if err != nil {
	panic(err)
}

if len(files) != 1 {
	panic("expected a single file :(")
}

fmt.Println(string(files[0].Data))

Example (GoOutput)

ExampleGoOutput demonstrates how to generate Go types from a CUE value.

schema := `
// Contains things.
Container: {
    str: string
}

// This is a bar.
Bar: {
       type: "bar"
       foo: string
}
`

cueValue := cuecontext.New().CompileString(schema)
if cueValue.Err() != nil {
	panic(cueValue.Err())
}

files, err := TypesFromSchema().
	CUEValue("sandbox", cueValue).
	Golang(GoConfig{}).
	Run(context.Background())
if err != nil {
	panic(err)
}

if len(files) != 1 {
	panic("expected a single file :(")
}

fmt.Println(string(files[0].Data))

Example (SchemaTransformations)

ExampleSchemaTransformations demonstrates how apply transformations to input schemas.

schema := `
// Contains things.
Container: {
    str: string
}

// This is a bar.
Bar: {
       type: "bar"
       foo: string
}
`

cueValue := cuecontext.New().CompileString(schema)
if cueValue.Err() != nil {
	panic(cueValue.Err())
}

files, err := TypesFromSchema().
	CUEValue("sandbox", cueValue).
	Golang(GoConfig{}).
	SchemaTransformations(
		AppendCommentToObjects("Transformed by cog."),
		PrefixObjectsNames("Example"),
	).
	Run(context.Background())
if err != nil {
	panic(err)
}

if len(files) != 1 {
	panic("expected a single file :(")
}

fmt.Println(string(files[0].Data))

Example (TypescriptOutput)

ExampleTypescriptOutput demonstrates how to generate Typescript types from a CUE value.

schema := `
// Contains things.
Container: {
    str: string
}

// This is a bar.
Bar: {
       type: "bar"
       foo: string
}
`

cueValue := cuecontext.New().CompileString(schema)
if cueValue.Err() != nil {
	panic(cueValue.Err())
}

files, err := TypesFromSchema().
	CUEValue("sandbox", cueValue).
	Typescript(TypescriptConfig{}).
	Run(context.Background())
if err != nil {
	panic(err)
}

if len(files) != 1 {
	panic("expected a single file :(")
}

fmt.Println(string(files[0].Data))

Index

• func AppendCommentToObjects(comment string) compiler.Pass
• func PrefixObjectsNames(prefix string) compiler.Pass
• type CUEOption
  • func CUEImports(importsMap map[string]string) CUEOption
  • func ForceEnvelope(envelopeName string) CUEOption
  • func NameFunc(nameFunc simplecue.NameFunc) CUEOption
• type GoConfig
• type SchemaToTypesPipeline
  • func TypesFromSchema() *SchemaToTypesPipeline
  • func (pipeline *SchemaToTypesPipeline) CUEModule(modulePath string, opts ...CUEOption) *SchemaToTypesPipeline
  • func (pipeline *SchemaToTypesPipeline) CUEValue(pkgName string, value cue.Value, opts ...CUEOption) *SchemaToTypesPipeline
  • func (pipeline *SchemaToTypesPipeline) Debug(enabled bool) *SchemaToTypesPipeline
  • func (pipeline *SchemaToTypesPipeline) Golang(config GoConfig) *SchemaToTypesPipeline
  • func (pipeline *SchemaToTypesPipeline) Run(ctx context.Context) (codejen.Files, error)
  • func (pipeline *SchemaToTypesPipeline) SchemaTransformations(passes ...compiler.Pass) *SchemaToTypesPipeline
  • func (pipeline *SchemaToTypesPipeline) Typescript(config TypescriptConfig) *SchemaToTypesPipeline
• type TypescriptConfig

Examples

• Package (CueModule)
• Package (CueValue)
• Package (GoOutput)
• Package (SchemaTransformations)
• Package (TypescriptOutput)

Functions

func AppendCommentToObjects

func AppendCommentToObjects(comment string) compiler.Pass

AppendCommentToObjects adds the given comment to every object definition.

func PrefixObjectsNames

func PrefixObjectsNames(prefix string) compiler.Pass

PrefixObjectsNames adds the given prefix to every object's name.

Types

type CUEOption

type CUEOption func(*codegen.CueInput)

func CUEImports

func CUEImports(importsMap map[string]string) CUEOption

CUEImports allows referencing additional libraries/modules.

func ForceEnvelope

func ForceEnvelope(envelopeName string) CUEOption

ForceEnvelope decorates the parsed cue Value with an envelope whose name is given. This is useful for dataqueries for example, where the schema doesn't define any suitable top-level object.

func NameFunc

func NameFunc(nameFunc simplecue.NameFunc) CUEOption

NameFunc specifies the naming strategy used for objects and references. It is called with the value passed to the top level method or function and the path to the entity being parsed.

type GoConfig

type GoConfig struct {
	// GenerateEqual controls the generation of `Equal()` methods on types.
	GenerateEqual bool
}

GoConfig defines a set of configuration options specific to Go outputs.

type SchemaToTypesPipeline

type SchemaToTypesPipeline struct {
	// contains filtered or unexported fields
}

SchemaToTypesPipeline represents a simplified codegen.Pipeline, meant to take a single input schema and generates types for it in a single output language.

func TypesFromSchema

func TypesFromSchema() *SchemaToTypesPipeline

TypesFromSchema generates types from a single input schema and a single output language.

func (*SchemaToTypesPipeline) CUEModule

func (pipeline *SchemaToTypesPipeline) CUEModule(modulePath string, opts ...CUEOption) *SchemaToTypesPipeline

CUEModule sets the pipeline's input to the given cue module.

func (*SchemaToTypesPipeline) CUEValue

func (pipeline *SchemaToTypesPipeline) CUEValue(pkgName string, value cue.Value, opts ...CUEOption) *SchemaToTypesPipeline

CUEValue sets the pipeline's input to the given cue value.

func (*SchemaToTypesPipeline) Debug

func (pipeline *SchemaToTypesPipeline) Debug(enabled bool) *SchemaToTypesPipeline

Debug controls whether debug mode is enabled or not. When enabled, more information is included in the generated output, such as an audit trail of applied transformations.

func (*SchemaToTypesPipeline) Golang

func (pipeline *SchemaToTypesPipeline) Golang(config GoConfig) *SchemaToTypesPipeline

Golang sets the output to Golang types.

func (*SchemaToTypesPipeline) Run

func (pipeline *SchemaToTypesPipeline) Run(ctx context.Context) (codejen.Files, error)

Run executes the codegen pipeline and returns the files generated as a result.

func (*SchemaToTypesPipeline) SchemaTransformations

func (pipeline *SchemaToTypesPipeline) SchemaTransformations(passes ...compiler.Pass) *SchemaToTypesPipeline

SchemaTransformations adds the given transformations to the set of transformations that will be applied to the input schema.

func (*SchemaToTypesPipeline) Typescript

func (pipeline *SchemaToTypesPipeline) Typescript(config TypescriptConfig) *SchemaToTypesPipeline

Typescript sets the output to Typescript types.

type TypescriptConfig

type TypescriptConfig struct {
	// ImportsMap associates package names to their import path.
	ImportsMap map[string]string

	// EnumsAsUnionTypes generates enums as a union of values instead of using
	// an actual `enum` declaration.
	// If EnumsAsUnionTypes is false, an enum will be generated as:
	// “`ts
	// enum Direction {
	//   Up = "up",
	//   Down = "down",
	//   Left = "left",
	//   Right = "right",
	// }
	// “`
	// If EnumsAsUnionTypes is true, the same enum will be generated as:
	// “`ts
	// type Direction = "up" | "down" | "left" | "right";
	// “`
	EnumsAsUnionTypes bool `yaml:"enums_as_union_types"`
}

TypescriptConfig defines a set of configuration options specific to Go outputs.