Skip to content
Crosswalker
🚧 Early alpha — building the foundation. See the roadmap →

v0.1.1 — Type system + validation foundation

Updated

Goal

Section titled “Goal”

Make the schema artifacts spec/tier1.schema.json and spec/recipe.schema.json the active source of truth for plugin types and runtime validation, replacing the ad-hoc TypeScript types in src/types/config.ts. This is the load-bearing implementation step for the schema-as-primitive architectural commitment — the v0.1 schema spec becomes the contract any producer must satisfy, not just the bundled engine.

Status

Section titled “Status”

✅ Done (2026-05-04). 27 unit tests + 5 validation E2E tests passing. AJV (Ajv2020) + ajv-formats wired into plugin startup; validator handles exposed on plugin instance for E2E reachability; spec/*.schema.json compiled at load with fail-fast on schema malformation. CrosswalkerConfig interface renamed to ImportRecipe across the codebase (4 source files); semantic migration to the spec-shape ImportRecipe deferred to v0.1.2 where render() lands.

Open question status (decided 2026-05-04):

  • ✅ Q1: Generated TS types committed to src/types/generated/ for PR-diff visibility on schema impact
  • ⏸ Q2: AJV strict mode deferred — current setup is strict: false; revisit at v0.2 once we have more spec experience
  • ✅ Q3: Type rename done now (CrosswalkerConfig → ImportRecipe); semantic migration via Phase-0 compat shim deferred to v0.1.2 where the engine refactor naturally absorbs it

Dependencies

Section titled “Dependencies”

Blocks: v0.1.2 needs typed Recipe interface; v0.1.3 needs typed Tier1ConceptNote interface for the generation engine refactor.

Scope

Section titled “Scope”

In:

  • TS type generation pipeline (json-schema-to-typescript or equivalent)
  • AJV validator instance loaded at plugin startup
  • Recipe validation on loadRecipe() (reject malformed early; show line+column errors to user)
  • Tier 1 frontmatter validation before write (generation-engine.ts)
  • CI step: bun run fixtures then validate every generated .md against spec/tier1.schema.json

Out:

  • AJV strict-mode opt-in (defer; could be a v0.1.5+ refinement)
  • Custom format validators beyond what ajv-formats provides
  • Schema migration tooling (deferred to v0.1 phase 2 of the 4-phase migration plan)

Concrete tasks

Section titled “Concrete tasks”
  • Add json-schema-to-typescript and ajv + ajv-formats to devDependencies
  • Add bun run codegen script: generates src/types/generated/tier1.ts and src/types/generated/recipe.ts from spec/*.schema.json
  • Replace src/types/config.ts CrosswalkerConfig interface with the generated ImportRecipe type (rename ripples — see Ch 22 §10.7 4-phase migration plan)
  • Phase-0 compatibility shim: legacy hierarchy column-role still loads as syntactic sugar for the new target.layout form
  • New src/validation/validator.ts — exports validateRecipe(obj), validateTier1Frontmatter(obj) using AJV instances loaded from spec
  • Wire validator into plugin startup (main.ts); fail-fast with clear error if a recipe is malformed
  • CI workflow step: run bun run fixtures, then validate every emitted markdown’s frontmatter against tier1.schema.json
  • Unit tests in tests/validation.test.ts covering: valid recipe, missing required field, bad mechanism enum value, malformed CURIE, mechanism-heading-without-level_depth

Success criteria

Section titled “Success criteria”
  • bun run build produces output with zero any referring to recipe / Tier 1 frontmatter types
  • AJV catches malformed recipes with line + column error messages users can act on
  • CI fails (red) if any fixture violates tier1.schema.json
  • Re-running bun run codegen after a schema bump regenerates types deterministically (no manual edits needed)
  • E2E: tests/e2e/validation.spec.ts passes (bun run e2e) — load a malformed recipe via the import wizard; assert that an AJV error surfaces in a user-facing Notice rather than silently corrupting Tier 1 output (see testing-patterns skill)

Files to touch

Section titled “Files to touch”
  • package.json — new devDeps + codegen script
  • src/types/config.ts — replaced by generated types; legacy types removed
  • src/types/generated/ — new (generated, gitignored OR committed for diff visibility — pick one)
  • src/validation/validator.ts — new
  • src/main.ts — wire validator at startup
  • src/generation/generation-engine.ts — call validateTier1Frontmatter() before write
  • src/import/import-wizard.ts — call validateRecipe() on save
  • .github/workflows/*.yml — fixture validation step
  • tests/validation.test.ts — new
  • docs/src/content/docs/development/testing.mdx — document the new CI step

Estimated effort

Section titled “Estimated effort”

1–2 days

Open questions

Section titled “Open questions”
  • Commit generated types to git or gitignore? (Pro-commit: easier code review of schema impact. Pro-gitignore: no drift risk.)
  • AJV strict mode now or defer? (Strict catches more bugs; can be noisy initially.)
Section titled “Related”

Concept pages:

Agent context:

  • v0.1 schema spec — the build target this milestone makes runtime
  • Vision — runtime-agnostic recipe schema is the central modularity commitment
  • Tradeoffs — strict vs. lenient validation tradeoffs

Design decisions (synthesis logs):

Research deliverables:

Spec & schema files:

Other milestones: