{
  "id": "page:generators-00-generator-design",
  "_kind": "Page",
  "_file": "wiki/generators/00-generator-design.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "Generator Design",
    "displayName": "Generator Design",
    "slug": "generators/00-generator-design",
    "articlePath": "wiki/generators/00-generator-design.md",
    "article": "# Generator Design\n\n> Concrete implementation plan for Phase 3. Extends `graph/schema/derivation-spec.md` with the runtime, query layer, template engine, and operational contracts the generators share.\n\n## Language and runtime\n\n- **Language**: TypeScript, compiled to JavaScript ahead of time (no `ts-node`).\n- **Runtime**: Node.js LTS (v22.x at time of writing). Pinned via `.nvmrc` + `engines` in `tools/package.json`.\n- **Module system**: ESM (`\"type\": \"module\"`).\n- **Package manager**: npm. Lockfile committed.\n\nTypeScript is chosen for two reasons. First, it lets us reuse the schema-derived types for the SDK (Phase 6) directly inside generator code — a generator that emits a TypeScript artifact is itself typed against the schema it reads. Second, the toolchain matches the rest of the babysitter monorepo, so generator outputs integrate with existing CI infrastructure without translation.\n\n## Query layer\n\nGenerators do not load raw YAML; they query an in-memory graph. The graph is built once per CLI invocation by the loader in `tools/graph-load.ts`:\n\n1. Walk `graph/schema/ontology-schema.yaml` to learn NodeKinds, EdgeKinds, attribute types, and invariants.\n2. Walk `graph/schema/examples/**/*.yaml` and parse every record into a typed `Node` keyed by `id`.\n3. Resolve every `ref<>` field, edge endpoint, and `evidenceSourceIds` list. Dangling references abort the load (this is the same check the Phase-1 validator stub runs).\n4. Index by NodeKind, by attribute, and by edge (forward + reverse adjacency).\n\nQuery helpers exposed by `tools/query.ts`:\n\n- `getByKind(kind)` → `Node[]` sorted by `id`.\n- `getById(id)` → `Node | undefined`.\n- `outgoing(nodeId, edgeKind?)` / `incoming(nodeId, edgeKind?)` → `Edge[]`.\n- `traverse(startId, path)` where `path` is a list of edge-kind names — returns the set of terminal nodes (used for the wiki page-type queries described in `wiki/01-derivation-mapping.md`).\n- `evidence(nodeId, attribute)` → `EvidenceSource[]` plus freshness metadata.\n\nAll helpers are pure functions over the loaded graph. They do **not** hit the filesystem.\n\n## Template engine\n\n**Handlebars** for markdown / OpenAPI / YAML / mermaid outputs. Handlebars strikes the right balance: powerful enough to express collection iteration and partials, small enough that templates remain reviewable. Custom helpers register at startup:\n\n- `{{slug id}}` — turn a graph id into a slug.\n- `{{trustBadge evidence}}` — render a `TrustLevel` badge.\n- `{{freshness evidence}}` — emit a freshness indicator (green/yellow/red) based on the `EvidencePolicy` in force.\n\nFor TypeScript outputs we use `ts-morph` directly rather than templates — a structured AST is easier to keep deterministic across schema edits than string concatenation.\n\n## I/O contract\n\nEach generator is a Node module exporting:\n\n```ts\nexport interface Generator {\n  id: string;             // matches Generator.id in the graph\n  consumes: { nodeKinds: string[]; edgeKinds: string[] };\n  outputs: { path: string; format: OutputFormat }[];\n  run(ctx: GenerateContext): Promise<GenerateResult>;\n}\n```\n\nThe CLI (`tools/cli.ts`) loads the generator registry, runs the requested generators, writes outputs to `<repo>/<path>` exactly as declared, and writes a sibling `<path>.manifest.json` with:\n\n- `generatorId`\n- `generatedAt` (only in the manifest, never in output content — outputs must remain byte-stable)\n- `sourceCatalogVersion` (read from the graph)\n- `inputs`: `{ nodeIds: [], edgeKinds: [] }` actually traversed\n- `contentHash`: SHA-256 of the rendered output\n\n## Idempotency and content-hashing\n\nAfter each run the CLI compares the new content hash against the existing manifest. If equal, the file is not rewritten (preserves filesystem timestamps and avoids no-op git diffs). If unequal, the file is rewritten and the manifest is updated.\n\nCI's \"regenerate-on-merge\" gate (Phase 5) runs every generator and fails the build if the working tree diff is non-empty *and* the change was not authored in the same PR. This is what enforces \"prose drift is structurally impossible\".\n\n## Determinism rules\n\n- Iterate collections in `id`-sorted order.\n- Render dates only via `freshness` helper (which emits coarse-grained labels, not exact timestamps).\n- Never embed paths absolute to a developer's checkout.\n- Use `\\n` line endings. UTF-8 without BOM.\n\n## Failure modes\n\nA generator MUST fail (non-zero exit, no partial writes) when:\n\n- The graph load fails any invariant.\n- A required NodeKind / EdgeKind it `consumes` is empty.\n- A template references a missing helper or unresolved id.\n- An output's content hash collides with another generator's output (catches accidentally double-owned files).\n\n## Test surface (handed to Phase 5)\n\nEach generator ships:\n\n- A unit test against a hand-rolled in-memory graph fixture.\n- An integration test against `graph/schema/examples/`.\n- A snapshot test of its output under a frozen graph version.\n\nSee `qa/00-qa-architecture.md` for how these slot into the wider test pyramid.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:generators",
      "to": "page:generators-00-generator-design",
      "kind": "contains_page"
    }
  ]
}