Diagnostics & repair (LLM-oriented)

X07 treats tooling output as a first-class API.

Goals

• Diagnostics are machine-readable
• Error codes are stable across releases
• Suggested fixes are JSON Patch (apply-able deterministically)

Diagnostic model (x07diag)

Diagnostics include:

• code (stable ID)
• severity
• message (human)
• loc (where in x07AST or text)
• optional quickfix (JSON Patch)

Agents should never scrape text; they should parse the structured payload.

Repair loop

x07 run, x07 build, and x07 bundle run the canonical repair loop automatically by default (format → lint → quickfix, repeatable).

For explicit control (or when you want the raw reports), use x07 fmt / x07 lint / x07 fix / x07 ast apply-patch and see Repair loop.

Output contracts (agent-friendly)

• Raw diagnostics output: x07diag (schema: spec/x07diag.schema.json)
• Tool reports (--json): spec/x07-tool-<scope>.report.schema.json (base: spec/x07-tool.report.schema.json)
• Tool streaming events (--jsonl): spec/x07-tool.events.schema.json (schema_version: "x07.tool.events@0.1.0")
• Diagnostics catalog (source of truth): catalog/diagnostics.json (schema: spec/x07-diag.catalog.schema.json)
• Diagnostics coverage report: x07.diag.coverage@0.1.0 (schema: spec/x07-diag.coverage.schema.json)

Agents should treat these as APIs: parse JSON, key off schema_version, and avoid scraping text.

Catalog workflows

• Validate and regenerate canonical artifacts:
  • x07 diag catalog --catalog catalog/diagnostics.json --format both
• Guard against source/catalog drift:
  • x07 diag check
• Measure quickfix coverage:
  • x07 diag coverage --severity error,warning --min-coverage <threshold>
  • CI gate target (roadmap): x07 diag coverage --severity error,warning --min-coverage 0.90