@cisstech/specsmith

Parse and validate a project spec: the folder of markdown files that is the single source of truth for a product's screens and navigation.

What it does

Reads a spec/ folder, turns it into a typed model, and runs a fixed set of coherence checks. A spec with a broken transition, an unreachable screen, a list missing its empty/loading states, an overlay with no way out, or a nav pointing nowhere does not pass. This is the gate that keeps a spec from drifting.

It does not render anything, and does not yet check form/detail states or that destructive actions confirm.

The spec folder

spec/
  project.md        identity, nav shell, global rules, ordered flow list
  flows/<name>.md   one flow per file: prose plus a single spec: YAML block

Each file mixes prose with exactly one spec: block holding the machine-read facts. The fields and the authoring rules are documented in the Spec format reference; ledger, aurora and lueur are complete examples.

API

import { loadProject, validate } from '@cisstech/specsmith';

const project = await loadProject('path/to/spec'); // read + parse the folder
const report = validate(project);                  // { ok, findings }

if (!report.ok) process.exit(1);

• loadProject(dir) returns a Project. Throws SpecParseError on malformed YAML or a file that fails its schema.
• validate(project) returns a Report = { ok, findings }. ok is false when any finding has severity error.
• parseProjectSpec / parseFlow / extractSpecBlock / extractProse parse from strings. Parsed flows and the project also carry their prose (the markdown outside the spec block) so downstream tools like a renderer can read the intent.

This is a library. To validate a spec from the command line, use foundry check, which runs these checks and exits non zero on any error.

Checks

Six coherence checks run today: dangling edges, unreachable screens, lists without an empty or loading state, overlays with no way out, nav pointing at an unknown flow, and flow files missing from the plan. Four are errors, two are warnings. They are defined in src/validate.ts, the source of truth, and documented for authors in the Spec format reference. New guarantees join the set as the rule library grows.