usm/cli-scan

The usm scan command reads usmconfig.json, scans the codebase, and generates .usm files for services, packages, data, and features.

Intent

After init creates the config, scan detects the actual structure — services from package.json, routes from app/ directories, data from Prisma schemas — and writes .usm files. Smart-merge preserves human edits on re-scan.

Flows

Run usm scan (run-scan)

User runs usm scan to generate .usm files from the codebase

1. get → usmconfig.json
   • expects: valid: true
2. parse → package.json in matched service directories
3. parse → app/*/app directories for Next.js routes
4. generate → .usm/services/.usm, .usm/features/.usm, .usm/data/*.usm
5. update → .usm/system.usm index with new findings

Contracts

scan-preserves-edits

Smart-merge preserves human-edited fields (summary, intent, decisions, flows, contracts, tests) on re-scan

Acceptance criteria:

• [ ] PRESERVE_FIELDS are kept if non-default
• [ ] UPDATE_FIELDS ($last_updated, paths, port, depends_on) are overwritten
• [ ] --force bypasses merge

Tests

scan-creates-files

Given:

• config_exists: true

Then:

• assertion: .usm/services/*.usm files created for each matched app
• assertion: .usm/features/*.usm files created from route extraction

scan-smart-merge

Given:

• existing_usm_with_human_edits: true

Then:

• assertion: human-edited summary preserved
• assertion: mechanical fields like $last_updated updated

Implementation

• Primary: src/scan/structural.ts
• Test code status: none

See Also

• usm/cli-init