usm/cli-validate

The usm validate command checks .usm files against the v1 JSON Schema and reports errors.

Usage

# Validate all .usm files in the .usm/ directory
usm validate .usm

# Validate a single file
usm validate .usm/system.usm

# Validate from current directory (scans all .usm dirs)
usm validate .

Why this exists

Users need to verify that their .usm files conform to the schema before generating docs. Validate catches missing required fields, wrong types, and invalid enum values.

How it works

Run usm validate (run-validate)

User runs usm validate on one or more .usm files

1. Parse — each .usm file path
2. Observe — v1 JSON Schema via Ajv
   • expects: valid: true
3. Submit — validation result per file
4. Observe — exit code 0 if all pass, 1 if any fail

Flow Diagrams

sequenceDiagram
    participant User
    participant Browser
    participant Server

    User->>Browser: parse each .usm file path
    Browser-->>User: shows v1 JSON Schema via Ajv
    Note over Server: valid: true
    User->>Browser: submit validation result per file
    Browser-->>User: shows exit code 0 if all pass, 1 if any fail

Guarantees

validate-against-v1-schema

Validate must use the v1.json schema with Ajv and report all errors

Acceptance criteria:

• [ ] Uses Ajv with allErrors: true
• [ ] Reports path and message for each error
• [ ] Exit code 1 if any file fails

Test specifications

validate-valid-file

Given:

• valid_usm_file: true

Then:

• assertion: output shows ✓ for the file
• assertion: exit code 0

validate-invalid-file

Given:

• usm_missing_required_fields: true

Then:

• assertion: output shows ✗ with error details
• assertion: exit code 1

Implementation

• Primary: src/validate.ts
• Test code status: none

See Also

• usm/schema-v1