USM

Appearance

usm/cli-generate ​

The usm generate command reads all .usm files and produces markdown, OpenAPI, Mermaid, ArchiMate, TOGAF, AGENTS.md, and Vitest test specs.

Usage ​

bash
# Generate all docs from .usm files
usm generate

# Check if generated files are up to date (dry run)
usm generate --check

Why this exists ​

After scanning and enriching, generate produces all output artifacts from the .usm source. It runs 6 passes: per-file markdown, area overviews, aggregator docs, surface tables, Mermaid diagrams, and TOGAF deliverables.

How it works ​

Generate pipeline (6 passes) (run-generate) ​

System pipeline behind usm generate: parse all .usm files and write every derived artifact.

  1. Parse — all .usm files in monorepo
  2. Observe — duplicate $id detection
  3. Generate — per-file markdown for each validated .usm
  4. Generate — aggregator docs (risks, roadmap, AGENTS.md, OpenAPI, test specs)
  5. Generate — surface tables injected into overview.md files
  6. Generate — Mermaid diagrams (architecture, ER, service deps)
  7. Generate — TOGAF ADM phase deliverables

Regenerate all docs from specs (regenerate-outputs) ​

A spec author edits .usm files and regenerates every derived artifact, confirming the browser preview stays current.

  1. Run — usm generate from the repo root
  2. Review — regenerated docs in the running usm docs serve preview — hot reload picks up changes
  3. Commit — regenerated artifacts only after lint and typecheck pass

Build against generated test specs (build-against-contracts) ​

  1. Fill — in the emitted e2e skeletons under tests/auto-generated/e2e/ for journeys, replacing TODO markers with real locators

Flow Diagrams ​

mermaid
sequenceDiagram
    participant User
    participant Browser

    User->>Browser: fill in the emitted e2e skeletons under tests/auto-generated/e2e/ for journeys, replacing TODO markers with real locators

Guarantees ​

generate-from-source-only ​

Generate must read .usm files directly — never derive docs from other docs

Acceptance criteria:

  • [ ] All outputs derived from parsed .usm data
  • [ ] Duplicate $ids detected and warned
  • [ ] --check mode compares without writing
  • [ ] Missing outputs outside git's tracked set are reported as (skipped: untracked) and do not fail --check — CI on a fresh clone can pass; missing tracked outputs still fail (issue #42)
  • [ ] The skip summary states the count and remedy (run usm generate) so absence is never silent

Test specifications ​

generate-produces-outputs ​

Given:

  • valid_usm_files: true

When: regenerate-outputs

Then:

  • assertion: markdown files written for each .usm
  • assertion: aggregator docs written if system.usm present

generate-check-mode ​

Given:

  • existing_outputs: true

Then:

  • assertion: reports up-to-date or out-of-date without writing

Implementation ​

  • Primary: src/cli/index.ts (generate command)
  • Test code status: none

See Also ​

  • usm/cli-scan