[james-d12]

Closes #66

Summary

validate --format json no longer serialises the internal ValidationResult. It writes an explicit, versioned ValidationReportV1 DTO (CodeGuard.Reporting/Contracts/), built by ValidationReportMapper.ToV1.

• Adds schemaVersion ("1.0"), toolVersion, durationMs, and a metrics block.
• status keeps the existing values: passed, failed, partiallyEvaluated.
• Publishes a JSON Schema (draft 2020-12) at CodeGuard.Reporting/Schemas/validation-report.v1.schema.json, embedded as a resource. Every object has additionalProperties: false.
• Tests validate real reporter output against the schema: with violations, with none, and with evaluation errors and analysis warnings. A separate test checks that the schema is itself valid Draft 2020-12.
• Docs: docs/architecture/RESULT_CONTRACT.md (shape, field meanings, versioning policy), linked from docs/USAGE.md and docs/README.md.

This is a breaking change to --format json. The rule counts (rulesEvaluated, rulesPassed, rulesFailed, rulesErrored) moved under metrics. Violation and error field names are unchanged.

Sample output

{
  "schemaVersion": "1.0",
  "toolVersion": "0.1.4-alpha.0.27",
  "status": "failed",
  "evaluatedAtUtc": "2026-10-13T14:42:10.7202958+00:00",
  "durationMs": 6705,
  "metrics": {
    "rulesEvaluated": 11,
    "rulesPassed": 7,
    "rulesFailed": 4,
    "rulesErrored": 0,
    "violationCount": 4,
    "violationsBySeverity": { "info": 0, "warning": 0, "error": 3, "critical": 1 },
    "evaluationErrorCount": 0,
    "analysisWarningCount": 0
  },
  "violations": [ { "ruleId": "DDD-ENTITY-001", "ruleVersion": 1, "severity": "error", "...": "..." } ],
  "evaluationErrors": [],
  "analysisWarnings": []
}

Design decisions

• Status is derived from the post---severity-threshold result, the same as before. It describes the report, not the exit code. --fail-on can still give exit 0 with status: "failed".
• durationMs is an integer, measured from the start of the validate action until just before the report is written. Library callers that do not measure get 0.
• toolVersion comes from the CLI assembly's informational version with the +commit suffix stripped. Reporting cannot read it itself because MinVer is only on the CLI project.
• Duration and version are passed through the JsonViolationReporter constructor, not IViolationReporter.WriteAsync, so the other reporters are untouched.
• Enums map through explicit switch expressions, so renaming an internal enum member cannot change the wire format.
• Optional fields (file, line, symbol, ...) are omitted when unknown, as before. line/column may be 0 for unknown locations, so the schema allows 0.

Not in v1 (deferred)

From roadmap section 15: rulesVersion, repository, commit, branch, and a separate timestamp. Also not included: projects and types analysed. None of these is on ValidationResult, so they need run context passed into the reporter.

Test plan

• dotnet build: 0 errors, 0 warnings
• dotnet test: 945 passed (1 + 220 + 49 + 460 + 7 + 117 + 67 + 24 across 8 projects)
• dotnet format --verify-no-changes: clean
• validate --format json on the integration fixture: output shape confirmed by hand
• Independent JSON Schema validator run on CLI output (none installed locally; covered by the in-repo schema tests)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Xouw37Lmze9pVQhpCJZKix

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
86.4% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud