validate

Validate all ModernizeSpec files in a project against their JSON Schemas.

Usage

npx modernizespec validate [options]

What It Does

1. Locates .agents/modernization/manifest.json
2. Reads the files section to discover all spec files
3. Validates each file against its corresponding JSON Schema
4. Reports errors with file path, field path, and error message

Options

Flag	Description	Default
--dir <path>	Project directory	Current directory
--strict	Fail on warnings (not just errors)	Errors only
--json	Output errors as JSON	Human-readable
--file <name>	Validate a specific file only	All files

Examples

Validate All Files

npx modernizespec validate

Strict Mode (For CI)

npx modernizespec validate --strict

Validate Single File

npx modernizespec validate --file domains.json

JSON Output (For Tooling)

npx modernizespec validate --json

Output

Human-Readable (Default)

Validating ModernizeSpec files...

  manifest.json          ✓ valid
  domains.json           ✗ 2 errors
    - contexts[0].coupling.internal: must be <= 1
    - contexts[1].type: must be "core", "supporting", or "generic"
  complexity.json        ✓ valid
  extraction-plan.json   ✓ valid
  parity-tests.json      ⚠ 1 warning
    - acceptance.parity_threshold: value 2.0 is unusually high (expected 0-1 range)
  migration-state.json   ✓ valid

Result: 2 errors, 1 warning

JSON Output

{
  "valid": false,
  "errors": [
    {
      "file": "domains.json",
      "path": "contexts[0].coupling.internal",
      "message": "must be <= 1",
      "severity": "error"
    }
  ],
  "warnings": [
    {
      "file": "parity-tests.json",
      "path": "acceptance.parity_threshold",
      "message": "value 2.0 is unusually high (expected 0-1 range)",
      "severity": "warning"
    }
  ]
}

Exit Codes

Code	Meaning
0	All files valid (no errors; warnings present only if --strict not set)
1	Validation errors found
2	Spec files not found

CI Integration

# GitHub Actions
- name: Validate ModernizeSpec
  run: npx modernizespec validate --strict

# GitLab CI
validate-spec:
  script: npx modernizespec validate --strict

See Also

• JSON Schemas — Schema design and principles
• Schema Validator — Interactive browser-based validation