usm/gen-source-mapping [built]

Source mapping generator — reads all service and feature specs to build a bidirectional file-to-feature-to-service-to-module mapping, then renders multiple views from that one mapping. Available views: file-tree (code navigator with descriptions), coverage-matrix (which files are specced vs unspecced), orphan-report (files with no governing spec). Each view is a reference_pages source on system.usm, rendered through the generic content-block renderer. Universal — reads the project's own .usm specs, no USM-specific content. Backward compatible: no reference_pages entries = no output.

Status: built

Why this exists

USM specs already capture the file-to-feature relationship bidirectionally: feature specs point at implementation.primary and routes[].file_path, and service specs group files into modules with paths and purposes. But this data is never rendered as a file-level view — the technical docs show feature pages and service pages but no code navigator, no coverage matrix, no orphan report. For agents and developers, the most useful question is "which files do what, and which are undocumented?" Source mapping answers that by inverting the implementation relationship across all specs, building one mapping, and rendering multiple views from it. This is drift detection at the file level — files in the codebase not claimed by any feature spec are orphans, and that's a signal the spec coverage is incomplete.

Design decisions

source-mapping-name [accepted]

Decision: Name the feature source mapping rather than code navigator or file tree, because the capability is building a bidirectional source-to-spec mapping and rendering multiple views from it.

Rationale: Code navigator describes one view (the file tree). Source mapping describes the capability — the underlying file-to-feature-to-service relationship that powers file-tree, coverage-matrix, and orphan-report views. The name should reflect the general capability, not one output.

Consequences: The feature id is usm/gen-source-mapping. Reference page sources are file-tree, coverage-matrix, orphan-report.

reference-pages-sources [accepted]

Decision: Source mapping views are reference_pages sources on system.usm, rendered through the generic content-block renderer.

Rationale: The content-block system already supports source-based reference pages (detectors, schema, config). Adding file-tree, coverage-matrix, and orphan-report as new sources keeps the architecture uniform — one generator, one renderer, multiple sources. No bespoke generator functions.

Consequences: system.usm declares which views to generate. The referencePages generator dispatches to source-specific builders.

no-new-schema-fields [accepted]

Decision: Use existing spec fields only — service modules[] and feature implementation — no new schema fields.

Rationale: The data already exists. Adding schema fields would be unnecessary. The generator reads service.usm modules[].paths[] for directory grouping and feature.usm implementation.primary for file ownership. The filesystem walk fills the gap between specs and actual files.

Consequences: No v1.json changes. No migration needed. The generator is purely additive.

filesystem-walk-for-completeness [accepted]

Decision: The generator walks the filesystem within service paths[] to enumerate actual files, not just the files mentioned in specs.

Rationale: Specs point at implementation files but don't list every file in a directory. To build a complete file tree and detect orphans, the generator must walk the filesystem. Files not mentioned in any spec are orphans — that's the coverage signal.

Consequences: The generator needs filesystem access at generation time. Exclude patterns (node_modules, dist, .git) are respected.

How it works

Build the source mapping from all specs (build-source-map)

The generator reads all service.usm files (for modules[] and paths[]) and all feature.usm files (for implementation.primary, implementation.test_code, routes[].file_path). It walks the filesystem within each service's paths[], matching each file to: (1) a module by directory, (2) a feature by implementation.primary, (3) a route by routes[].file_path. Files matching nothing are orphans. The result is a SourceMap data structure that all views render from.

1. Read — all service.usm files for modules name purpose and paths
2. Read — all feature.usm files for implementation.primary, test_code, routes file_path
3. Walk — filesystem within each service paths directory
4. Match — each file to a module by directory, a feature by implementation.primary, a route by file_path
5. Collect — files matching nothing as orphans
6. Return — SourceMap with files, features, orphans, modules

Render the file-tree view (code navigator) (render-file-tree)

Renders the source map as a directory tree with file descriptions, grouped by service and module. Each file shows its module purpose and the feature that owns it (if any). Files with no feature are marked as unspecced. Source: file-tree on a reference_pages entry.

1. Read — SourceMap from the build-source-map flow
2. Group — files by service then by module
3. Render — directory tree with file names and descriptions
4. Annotate — each file with its owning feature or unspecced marker
5. Render — through the generic content-block renderer as a reference page

Render the coverage-matrix view (render-coverage-matrix)

Renders the source map as a matrix showing which files have feature specs vs which are unspecced. Useful for spotting drift — code that exists but has no governing spec. Source: coverage-matrix on a reference_pages entry.

1. Read — SourceMap
2. Build — table with columns file, module, owning feature, spec status
3. Render — through the generic content-block renderer as a reference page

Render the orphan-report view (render-orphan-report)

Renders only the orphan files — files in the codebase not claimed by any feature spec. This is the drift signal: code with no spec governing it. Source: orphan-report on a reference_pages entry.

1. Read — SourceMap orphans
2. Group — orphans by service and module
3. Render — table or list of orphan files with their directory
4. Render — through the generic content-block renderer as a reference page

Guarantees

bidirectional-mapping

The generator builds a bidirectional file-to-feature-to-service-to-module mapping from existing spec data.

Acceptance criteria:

• [ ] Reads service.usm modules name, purpose, and paths for directory-level grouping
• [ ] Reads feature.usm implementation.primary and implementation.test_code for file-level ownership
• [ ] Reads feature.usm routes file_path for route source files
• [ ] Walks the filesystem within each service paths directory to enumerate actual files
• [ ] Matches each file to a module by directory, a feature by implementation.primary, and a route by file_path

multiple-views-one-mapping

Multiple views render from one SourceMap data structure, each as a reference_pages source.

Acceptance criteria:

• [ ] file-tree source renders a directory tree with descriptions, grouped by service and module
• [ ] coverage-matrix source renders a table of file, module, owning feature, spec status
• [ ] orphan-report source renders only files with no governing feature spec
• [ ] All views render through the generic content-block renderer as reference pages

universal-not-usm-specific

The source mapping generator works for any USM project, reading the project's own specs.

Acceptance criteria:

• [ ] No USM-specific content baked into the generator
• [ ] Reads the project's service and feature specs, not hardcoded file lists
• [ ] A project with no reference_pages source-mapping entries produces no output (backward compatible)
• [ ] File descriptions come from module purpose and feature summary, not from the generator

backward-compatible

Existing projects without source-mapping reference_pages entries are unaffected.

Acceptance criteria:

• [ ] No reference_pages entries with file-tree/coverage-matrix/orphan-report sources means no output
• [ ] All existing tests pass without modification
• [ ] No new schema fields required — uses existing modules, implementation.primary, routes file_path

orphan-detection

Files in the codebase not claimed by any feature spec are identified as orphans.

Acceptance criteria:

• [ ] A file in a service paths directory with no matching implementation.primary is an orphan
• [ ] Orphan files are excluded from exclude patterns (node_modules, dist, .git, etc.)
• [ ] The orphan-report view lists orphans grouped by service and module

Test specifications

file-tree-renders

Given:

• service_with_modules: true
• feature_with_implementation: true
• reference_pages_source: "file-tree"

Then:

• assertion: output contains a directory tree grouped by service and module
• assertion: each file shows its module purpose
• assertion: files with implementation.primary show their owning feature

coverage-matrix-renders

Given:

• service_with_modules: true
• feature_with_implementation: true
• unspecced_file: true
• reference_pages_source: "coverage-matrix"

Then:

• assertion: output contains a table with file, module, owning feature, spec status columns
• assertion: specced files show their owning feature
• assertion: unspecced files show no feature

orphan-report-renders

Given:

• service_with_modules: true
• unspecced_file: true
• no_feature_for_unspecced: true
• reference_pages_source: "orphan-report"

Then:

• assertion: output lists the unspecced file
• assertion: specced files are not listed

no-reference-pages-no-output

Given:

• no_reference_pages: true
• service_with_modules: true

Then:

• assertion: generate produces no source-mapping output

orphan-excludes-node-modules

Given:

• service_with_modules: true
• node_modules_present: true

Then:

• assertion: files in node_modules are not listed as orphans

Implementation

• Primary: src/generators/sourceMapping.ts
• Test code: tests/sourceMapping.test.ts
• Test code status: manual

See Also

• usm/gen-content-blocks
• usm/cli-generate
• usm/cli-multi-lang-scan