generate

Documentation

Overview

Package generate provides D2 code generation from structured specifications.

Index

• func Float64Ptr(f float64) *float64
• func GeneratePipeline(spec *PipelineSpec) string
• func GeneratePipelineWithOptions(spec *PipelineSpec, opts PipelineRenderOptions) string
• func IntPtr(i int) *int
• type ActorSpec
• type BranchSpec
• type ColumnSpec
• type ContainerSpec
• type DiagramSpec
• type EdgeSpec
• type ExecutorSpec
• type ExecutorType
  • func (t ExecutorType) Color() string
  • func (t ExecutorType) Label() string
• type FlowSpec
• type Generator
  • func NewGenerator() *Generator
  • func (g *Generator) Generate(spec *DiagramSpec) string
• type GroupSpec
• type MessageSpec
• type NodeSpec
• type PipelineGenerator
  • func NewPipelineGenerator() *PipelineGenerator
  • func (g *PipelineGenerator) Generate(spec *PipelineSpec) string
  • func (g *PipelineGenerator) GenerateWithOptions(spec *PipelineSpec, opts PipelineRenderOptions) string
• type PipelineRenderOptions
• type PipelineSpec
• type ResourceKind
  • func (k ResourceKind) Icon() string
  • func (k ResourceKind) Shape() string
• type ResourceSpec
• type SequenceSpec
• type StageSpec
• type StyleSpec
• type TableSpec

Functions

func Float64Ptr

func Float64Ptr(f float64) *float64

Float64Ptr returns a pointer to a float64 value.

func GeneratePipeline

func GeneratePipeline(spec *PipelineSpec) string

GeneratePipeline is a convenience function to generate D2 from a PipelineSpec.

func GeneratePipelineWithOptions

func GeneratePipelineWithOptions(spec *PipelineSpec, opts PipelineRenderOptions) string

GeneratePipelineWithOptions is a convenience function to generate D2 with options.

func IntPtr

func IntPtr(i int) *int

IntPtr returns a pointer to an int value. Useful for setting StyleSpec fields.

Types

type ActorSpec

type ActorSpec struct {
	ID    string `json:"id" yaml:"id"`
	Label string `json:"label,omitempty" yaml:"label,omitempty"`
	Shape string `json:"shape,omitempty" yaml:"shape,omitempty"` // person, rectangle, etc.
}

ActorSpec defines an actor in a sequence diagram.

type BranchSpec

type BranchSpec struct {
	Label     string `json:"label" yaml:"label"`         // Branch label (e.g., "Yes", "No", "> $1000")
	NextStage string `json:"nextStage" yaml:"nextStage"` // Target stage ID
}

BranchSpec defines a conditional branch from a decision node.

type ColumnSpec

type ColumnSpec struct {
	Name        string   `json:"name" yaml:"name"`
	Type        string   `json:"type" yaml:"type"`
	Constraints []string `json:"constraints,omitempty" yaml:"constraints,omitempty"` // PK, FK, UNQ, NOT NULL
}

ColumnSpec defines a column in an SQL table.

type ContainerSpec

type ContainerSpec struct {
	ID    string `json:"id" yaml:"id"`
	Label string `json:"label,omitempty" yaml:"label,omitempty"`

	// Layout within container
	Direction   string `json:"direction,omitempty" yaml:"direction,omitempty"`
	GridColumns int    `json:"gridColumns,omitempty" yaml:"gridColumns,omitempty"`
	GridRows    int    `json:"gridRows,omitempty" yaml:"gridRows,omitempty"`

	// Style
	Style *StyleSpec `json:"style,omitempty" yaml:"style,omitempty"`

	// Children
	Nodes      []NodeSpec      `json:"nodes,omitempty" yaml:"nodes,omitempty"`
	Containers []ContainerSpec `json:"containers,omitempty" yaml:"containers,omitempty"` // Nested containers
	Edges      []EdgeSpec      `json:"edges,omitempty" yaml:"edges,omitempty"`           // Internal edges
}

ContainerSpec defines a container (cluster/boundary) that holds nodes.

type DiagramSpec

type DiagramSpec struct {
	// Layout settings
	Direction   string `json:"direction,omitempty" yaml:"direction,omitempty"`     // right, down, left, up
	GridColumns int    `json:"gridColumns,omitempty" yaml:"gridColumns,omitempty"` // Force grid layout
	GridRows    int    `json:"gridRows,omitempty" yaml:"gridRows,omitempty"`

	// Top-level elements
	Nodes      []NodeSpec      `json:"nodes,omitempty" yaml:"nodes,omitempty"`
	Containers []ContainerSpec `json:"containers,omitempty" yaml:"containers,omitempty"`
	Edges      []EdgeSpec      `json:"edges,omitempty" yaml:"edges,omitempty"`

	// Special diagram types
	Sequences []SequenceSpec `json:"sequences,omitempty" yaml:"sequences,omitempty"` // Sequence diagrams
	Tables    []TableSpec    `json:"tables,omitempty" yaml:"tables,omitempty"`       // SQL tables
}

DiagramSpec defines the structure for generating D2 diagrams. This can be serialized as TOON, JSON, or YAML.

type EdgeSpec

type EdgeSpec struct {
	From  string `json:"from" yaml:"from"` // Source node ID
	To    string `json:"to" yaml:"to"`     // Target node ID
	Label string `json:"label,omitempty" yaml:"label,omitempty"`

	// Arrow style
	SourceArrow string `json:"sourceArrow,omitempty" yaml:"sourceArrow,omitempty"` // none, triangle, diamond, etc.
	TargetArrow string `json:"targetArrow,omitempty" yaml:"targetArrow,omitempty"`

	Style *StyleSpec `json:"style,omitempty" yaml:"style,omitempty"`
}

EdgeSpec defines a connection between nodes.

type ExecutorSpec

type ExecutorSpec struct {
	Name string       `json:"name" yaml:"name"`
	Type ExecutorType `json:"type" yaml:"type"`

	// Type-specific metadata
	Endpoint string `json:"endpoint,omitempty" yaml:"endpoint,omitempty"` // For API
	Command  string `json:"command,omitempty" yaml:"command,omitempty"`   // For program
	Model    string `json:"model,omitempty" yaml:"model,omitempty"`       // For LLM
	Prompt   string `json:"prompt,omitempty" yaml:"prompt,omitempty"`     // For LLM/agent
	Agent    string `json:"agent,omitempty" yaml:"agent,omitempty"`       // For agent type
}

ExecutorSpec defines what runs in a stage.

type ExecutorType

type ExecutorType string

ExecutorType represents the type of executor.

const (
	// ExecutorProgram is an external program or binary.
	ExecutorProgram ExecutorType = "program"

	// ExecutorAPI is a REST/gRPC API call.
	ExecutorAPI ExecutorType = "api"

	// ExecutorDeterministic is custom code where same input = same output.
	ExecutorDeterministic ExecutorType = "deterministic"

	// ExecutorLLM is LLM inference (non-deterministic).
	ExecutorLLM ExecutorType = "llm"

	// ExecutorAgent is an autonomous agent execution.
	ExecutorAgent ExecutorType = "agent"
)

func (ExecutorType) Color

func (t ExecutorType) Color() string

Color returns a suggested fill color for the executor type.

func (ExecutorType) Label

func (t ExecutorType) Label() string

Label returns a human-readable label for the executor type.

type FlowSpec

type FlowSpec struct {
	From      string `json:"from" yaml:"from"`                               // stage.output ID path
	To        string `json:"to" yaml:"to"`                                   // stage.input ID path
	Label     string `json:"label,omitempty" yaml:"label,omitempty"`         // Edge label
	Transform string `json:"transform,omitempty" yaml:"transform,omitempty"` // Optional transformation description
	Async     bool   `json:"async,omitempty" yaml:"async,omitempty"`         // Async data flow
}

FlowSpec defines data flow between stages.

type Generator

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

Generator converts DiagramSpec to D2 code.

func NewGenerator

func NewGenerator() *Generator

NewGenerator creates a new D2 code generator.

func (*Generator) Generate

func (g *Generator) Generate(spec *DiagramSpec) string

Generate converts a DiagramSpec to D2 code.

type GroupSpec

type GroupSpec struct {
	ID       string        `json:"id" yaml:"id"`
	Label    string        `json:"label,omitempty" yaml:"label,omitempty"`
	Messages []MessageSpec `json:"messages" yaml:"messages"`
}

GroupSpec defines a group/fragment in a sequence diagram.

type MessageSpec

type MessageSpec struct {
	From  string `json:"from" yaml:"from"`
	To    string `json:"to" yaml:"to"`
	Label string `json:"label,omitempty" yaml:"label,omitempty"`
}

MessageSpec defines a message between actors.

type NodeSpec

type NodeSpec struct {
	ID    string     `json:"id" yaml:"id"`
	Label string     `json:"label,omitempty" yaml:"label,omitempty"`
	Shape string     `json:"shape,omitempty" yaml:"shape,omitempty"` // rectangle, cylinder, circle, etc.
	Icon  string     `json:"icon,omitempty" yaml:"icon,omitempty"`   // Icon URL or name
	Style *StyleSpec `json:"style,omitempty" yaml:"style,omitempty"`
}

NodeSpec defines a single node in the diagram.

type PipelineGenerator

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

PipelineGenerator generates D2 code from PipelineSpec.

func NewPipelineGenerator

func NewPipelineGenerator() *PipelineGenerator

NewPipelineGenerator creates a new pipeline generator.

func (*PipelineGenerator) Generate

func (g *PipelineGenerator) Generate(spec *PipelineSpec) string

Generate produces D2 code from a PipelineSpec using default options.

func (*PipelineGenerator) GenerateWithOptions

func (g *PipelineGenerator) GenerateWithOptions(spec *PipelineSpec, opts PipelineRenderOptions) string

GenerateWithOptions produces D2 code from a PipelineSpec with custom options.

type PipelineRenderOptions

type PipelineRenderOptions struct {
	Simple bool // Hide internal I/O, show only stage boxes
}

PipelineRenderOptions controls how the pipeline is rendered.

type PipelineSpec

type PipelineSpec struct {
	ID          string      `json:"id" yaml:"id"`
	Label       string      `json:"label,omitempty" yaml:"label,omitempty"`
	Description string      `json:"description,omitempty" yaml:"description,omitempty"`
	Direction   string      `json:"direction,omitempty" yaml:"direction,omitempty"` // right, down
	Stages      []StageSpec `json:"stages" yaml:"stages"`
	Flows       []FlowSpec  `json:"flows,omitempty" yaml:"flows,omitempty"` // Cross-stage data flows
}

PipelineSpec defines a multi-stage process pipeline with inputs, outputs, and various executor types including deterministic code and LLM/agents.

type ResourceKind

type ResourceKind string

ResourceKind represents the type of resource.

const (
	// ResourceData is in-memory data structure.
	ResourceData ResourceKind = "data"

	// ResourceFile is a file on disk.
	ResourceFile ResourceKind = "file"

	// ResourceProgram is an executable or script.
	ResourceProgram ResourceKind = "program"

	// ResourceConfig is configuration data.
	ResourceConfig ResourceKind = "config"

	// ResourceModel is ML model weights.
	ResourceModel ResourceKind = "model"

	// ResourcePrompt is a prompt template.
	ResourcePrompt ResourceKind = "prompt"

	// ResourceArtifact is a build artifact.
	ResourceArtifact ResourceKind = "artifact"
)

func (ResourceKind) Icon

func (k ResourceKind) Icon() string

Icon returns a suggested icon identifier for the resource kind. Currently returns empty strings to avoid embedding external icon URLs.

func (ResourceKind) Shape

func (k ResourceKind) Shape() string

Shape returns the D2 shape for the resource kind.

type ResourceSpec

type ResourceSpec struct {
	ID       string       `json:"id" yaml:"id"`
	Label    string       `json:"label,omitempty" yaml:"label,omitempty"`
	Kind     ResourceKind `json:"kind" yaml:"kind"`
	Schema   string       `json:"schema,omitempty" yaml:"schema,omitempty"`     // JSON Schema reference
	Required bool         `json:"required,omitempty" yaml:"required,omitempty"` // For inputs
}

ResourceSpec defines an input or output resource.

type SequenceSpec

type SequenceSpec struct {
	ID     string        `json:"id" yaml:"id"`
	Label  string        `json:"label,omitempty" yaml:"label,omitempty"`
	Actors []ActorSpec   `json:"actors,omitempty" yaml:"actors,omitempty"`
	Steps  []MessageSpec `json:"steps" yaml:"steps"` // Messages in order
	Groups []GroupSpec   `json:"groups,omitempty" yaml:"groups,omitempty"`
}

SequenceSpec defines a sequence diagram.

type StageSpec

type StageSpec struct {
	ID       string         `json:"id" yaml:"id"`
	Label    string         `json:"label,omitempty" yaml:"label,omitempty"`
	Executor ExecutorSpec   `json:"executor" yaml:"executor"`
	Inputs   []ResourceSpec `json:"inputs,omitempty" yaml:"inputs,omitempty"`
	Outputs  []ResourceSpec `json:"outputs,omitempty" yaml:"outputs,omitempty"`

	// Parallelism support
	Parallel []StageSpec `json:"parallel,omitempty" yaml:"parallel,omitempty"` // Fan-out stages
	JoinFrom []string    `json:"joinFrom,omitempty" yaml:"joinFrom,omitempty"` // Fan-in from stage IDs

	// Swimlane support
	Lane string `json:"lane,omitempty" yaml:"lane,omitempty"` // Group stages by lane (system/team)

	// Decision node support
	Branches []BranchSpec `json:"branches,omitempty" yaml:"branches,omitempty"` // Conditional branches
}

StageSpec defines a single stage in the pipeline.

type StyleSpec

type StyleSpec struct {
	Fill         string   `json:"fill,omitempty" yaml:"fill,omitempty"`
	Stroke       string   `json:"stroke,omitempty" yaml:"stroke,omitempty"`
	StrokeWidth  *int     `json:"strokeWidth,omitempty" yaml:"strokeWidth,omitempty"`
	BorderRadius *int     `json:"borderRadius,omitempty" yaml:"borderRadius,omitempty"`
	FontSize     *int     `json:"fontSize,omitempty" yaml:"fontSize,omitempty"`
	Opacity      *float64 `json:"opacity,omitempty" yaml:"opacity,omitempty"`
}

StyleSpec defines visual styling properties. Pointer types are used to distinguish "not set" from "set to zero".

type TableSpec

type TableSpec struct {
	ID      string       `json:"id" yaml:"id"`
	Label   string       `json:"label,omitempty" yaml:"label,omitempty"`
	Columns []ColumnSpec `json:"columns" yaml:"columns"`
}

TableSpec defines an SQL table diagram.