Code Generation

Code generation is the dev-time step that turns the TypeSpec model in schema/model/ into checked-in runtime and documentation artifacts.

Prompty’s TypeSpec files are the source of truth for type shapes. Generation keeps every runtime aligned with those shapes so no runtime hand-maintains its own model code.

What generation produces

Running cd schema && npm run build generates:

Output	Location
TypeScript model code and tests	runtime/typescript/packages/core/src/model/, runtime/typescript/packages/core/tests/model/
Python model code and tests	runtime/python/prompty/prompty/model/, runtime/python/prompty/tests/model/
C# model code and tests	runtime/csharp/Prompty.Core/Model/, runtime/csharp/Prompty.Core.Tests/Model/
Go model code and tests	runtime/go/prompty/model/
Rust model code and tests	runtime/rust/prompty/src/model/, runtime/rust/prompty/tests/model/
VS Code JSON Schema	vscode/prompty/schemas/
Markdown schema reference	web/src/content/docs/reference/

Generated files are committed to the repository. Users of Prompty do not need TypeSpec or the generator installed.

How generation works

Generation is driven by two TypeSpec emitters, configured in schema/tspconfig.yaml:

• @typra/emitter — the multi-language code generator. It reads the Prompty model graph, lowers it into a language-neutral intermediate representation, and emits idiomatic model code, tests, and Markdown reference docs for every target runtime.
• @typespec/json-schema — emits the JSON Schema consumed by the VS Code extension into vscode/prompty/schemas/.

Both are ordinary npm dependencies pinned in schema/package.json; there is no in-repo generator source to build. The npm run generate script runs the TypeSpec compiler over schema/model/main.tsp with that config, then runs a post-processing pass (see below).

The generated output should be deterministic. If neither the TypeSpec files nor the pinned generator version changed, npm run build should not produce meaningful diffs.

Directory map

Path	Purpose
schema/model/	Prompty TypeSpec source files (source of truth)
schema/tspconfig.yaml	Emitters and per-target output paths
schema/package.json	Pinned @typra/emitter and TypeSpec dependencies
schema/scripts/normalize-typra-output.mjs	Post-generation normalization for deterministic output
schema/scripts/verify-typra.mjs	Schema-drift verification against the committed baseline
schema/tsp-output/	Typra generation metadata (manifest, export surfaces, JSON AST)

Supporting scripts

The schema/scripts/ folder holds the Node helpers that wrap generation:

• normalize-typra-output.mjs runs at the end of npm run generate. It normalizes the generation timestamp in the Typra manifest, collapses empty generated Python test files, and trims trailing whitespace in generated Go files so regeneration produces clean, diff-stable output.
• verify-typra.mjs backs npm run verify:typra. It compares the current Typra export surfaces, manifest, hydration seams, and JSON AST against the committed HEAD baseline and reports schema drift — including whether a change is additive or a governance-relevant major change.

Common workflow

cd schema
npm install
npm run build

npm run build formats TypeSpec, regenerates all targets (npm run generate), and formats the generated Rust. Run it whenever you change TypeSpec.

Editing rules

• Edit schema/model/**/*.tsp for schema changes. Keep provider-specific field names out of the canonical models — express them as wire mappings under schema/model/wire/**.
• To change generation behavior itself, update the pinned @typra/emitter version in schema/package.json (and re-run npm install).
• Do not hand-edit generated reference pages or generated runtime model files unless you are debugging; the next generation run will overwrite them.
• Commit TypeSpec changes together with the regenerated output.