usm/cli-scan

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

Usage

# Scan with defaults (smart merge)
usm scan

# Overwrite all existing .usm files
usm scan --force

# Only extract routes, skip service/package detection
usm scan --routes

# Overwrite mechanical fields, preserve human edits
usm scan --merge overwrite

Why this exists

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.

How it works

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

Guarantees

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

Test specifications

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