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 CheckOwnershipIndex(projectDir string, planned map[string][]byte) error
- func FindOrphanedArtifacts(projectDir string, planned map[string][]byte) ([]string, error)
- func Plan(opts Options) (map[string][]byte, error)
- func SchemaFileName(toolName, side string) string
- func TSFileName() string
- type Options
- type Result
Constants ¶
const ContractsDir = manifest.ContractsPackage
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).
var ErrMissingOwnershipIndex = errors.New("generated artifact ownership index is missing")
ErrMissingOwnershipIndex reports generated artifacts without the index that proves which bytes Dockyard owns. Generate repairs this state; dry-run gates report it as stale instead of guessing ownership.
Functions ¶
func CheckOwnershipIndex ¶ added in v1.9.0
CheckOwnershipIndex proves that the ownership index exactly describes the current generation plan with the digest of the planned bytes. Generation uses FindOrphanedArtifacts separately so valid obsolete records can be cleaned; dry-run gates reject every extra record, even when its file is already missing or belongs to a nested project.
func FindOrphanedArtifacts ¶ added in v1.9.0
FindOrphanedArtifacts returns previously indexed files that are absent from the current plan and whose current bytes still match the indexed digest. It never infers ownership from a filename. Modified files and symlinked paths are rejected rather than deleted.
func Plan ¶
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 ¶
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
// contains filtered or unexported fields
}
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
// Removed contains obsolete Dockyard-generated files deleted after all
// current artifacts were written successfully.
Removed []string
}
Result reports what a generate run produced.
func Run ¶
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.
Source Files