generate

Documentation

Overview

Package generate is the engine behind `dockyard generate` — the contract-first code generation verb (RFC §6, §9.1).

It drives the Design A pipeline (RFC §6.2) over a Dockyard project: a tool's typed Go input and output structs are the single source of truth (P1), and generate produces the downstream artifacts — the per-contract JSON Schema files and the TypeScript contract types — never the other way round.

The two halves

TypeScript is generated in-process: internal/codegen.TypeScriptForDir reads the project's internal/contracts/*.go source and emits contracts.ts. It needs only the Go source text, so the `dockyard` binary runs it directly.

JSON Schema is generated by an ephemeral generator (D-081). The schema engine — github.com/google/jsonschema-go — works from a reflect.Type, and the `dockyard` binary cannot reflect on a separate project's compiled contract types; internal/codegen is also not importable from a scaffolded project's module. So generate templates a tiny Go program into a temp directory inside the project, one that imports the project's own contracts package and the public runtime/tool API, and `go run`s it. That program reflects on the real contract types and writes each schema file with runtime/tool.MarshalSchema — the same deterministic marshaller the rest of the pipeline uses.

Idempotency

Both generators are deterministic: identical contract source yields byte-identical output. Run is therefore idempotent — a second run with no source change rewrites the same bytes and Result.Changed is empty. This is a binding Phase 18 acceptance criterion and the property `dockyard validate`'s stale-codegen check relies on.

Index

• Constants
• Variables
• func Plan(opts Options) (map[string][]byte, error)
• func SchemaFileName(toolName, side string) string
• func TSFileName() string
• type Options
• type Result
  • func Run(opts Options) (Result, error)

Constants

const ContractsDir = "internal/contracts"

ContractsDir is the project-relative directory holding the Go contract source and its generated artifacts. It is the directory `dockyard new` scaffolds and the one the codegen pipeline reads and writes (RFC §6.2).

Variables

var ErrGenerate = errors.New("dockyard/internal/generate: code generation failed")

ErrGenerate is the sentinel wrapping every generate failure. Callers branch with errors.Is(err, ErrGenerate).

Functions

func Plan

func Plan(opts Options) (map[string][]byte, error)

Plan runs the Design A codegen pipeline (RFC §6.2) for the project and returns the would-be generated files keyed by project-relative path — without writing anything. It is the dry-run core of Run: `dockyard generate` calls Run (Plan + write); `dockyard validate`'s stale-codegen check calls Plan and diffs the result against what is on disk.

TypeScript is generated in-process from the contracts/*.go source. JSON Schema is generated by an ephemeral generator `go run` inside the project (D-081), because the schema engine reflects on real Go types the `dockyard` binary cannot see. The ephemeral generator writes its schema files into a temp directory, so Plan still touches the filesystem there, but never mutates the project's committed contract artifacts.

Plan is deterministic: identical contract source yields byte-identical output. It builds fresh state per call and holds no shared mutable state.

func SchemaFileName

func SchemaFileName(toolName, side string) string

SchemaFileName returns the project-relative path of a tool contract's generated JSON Schema file. side is "input" or "output". The convention matches `dockyard new`'s scaffold output: <ContractsDir>/<tool>_<side>.schema.json.

It is exported so `dockyard validate`'s stale-codegen check locates the same files generate writes.

func TSFileName

func TSFileName() string

TSFileName is the project-relative path of the generated TypeScript contract file. It is exported so `dockyard validate`'s stale-codegen check locates the same file generate writes.

Types

type Options

type Options struct {
	// ProjectDir is the root of the Dockyard project — the directory holding
	// dockyard.app.yaml. Required.
	ProjectDir string
	// Manifest is the loaded, validated manifest. Required: generate reads the
	// tools list to know which contract types to produce schemas for.
	Manifest *manifest.Manifest
}

Options configures one generate run.

type Result

type Result struct {
	// Written is every generated file, project-relative, sorted.
	Written []string
	// Changed is the subset of Written whose bytes differed from what was
	// already on disk. An empty Changed on a rerun is the idempotency
	// guarantee made observable (RFC §6.2): no source change ⇒ no diff.
	Changed []string
}

Result reports what a generate run produced.

func Run

func Run(opts Options) (Result, error)

Run executes the Design A codegen pipeline (RFC §6.2) for the project: it regenerates the TypeScript contract types and the per-contract JSON Schema files from the Go contract structs, writing the result into the project.

Run is idempotent: a second invocation with no contract-source change writes byte-identical files and returns an empty Result.Changed. Run builds fresh state per call and holds no shared mutable state.