usm/cli-validate

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

Intent

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.

Flows

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

Contracts

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

Tests

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