Canonical diagnostic schema 1.0

ZemDomu Core owns semantic analysis, rule identity, source evidence, and the versioned diagnostic contract. The CLI, VS Code extension, and GitHub Action consume that same result and only adapt how it is presented. They do not run separate rule implementations or define a second issue model.

Required fields

Every canonical diagnostic contains these fields. Source line and column values are zero-based; presentation adapters convert them when the destination format uses one-based coordinates.

Field	Type	Meaning
schemaVersion	"1.0"	Version of the canonical machine-readable contract.
rule	string	Stable rule name used by configuration and documentation routes.
code	string	Stable public rule code, such as ZMD004.
severity	"error" \| "warning" \| "info"	Canonical severity before a presentation adapter renders it.
message	string	Developer-facing explanation of the finding.
source	ZemDomuSourceLocation	Primary source evidence for the finding.

Optional context fields

Consumers must handle these fields being absent. Core omits context it cannot resolve safely instead of inventing a page, edit target, provenance, or confidence value.

Field	Type	Meaning
page	string	Page or document entry point associated with project-aware analysis.
componentPath	string[]	Resolved composition path from the page to the reported component.
relatedLocations	ZemDomuRelatedLocation[]	Additional source evidence; each item contains source and an optional message.
preferredEditLocation	ZemDomuSourceLocation	Preferred edit target, emitted only when Core resolves it deterministically.
suggestion	ZemDomuDiagnosticSuggestion	Guidance with a required message and optional replacement text.
provenance	ZemDomuDiagnosticProvenance	Evidence kind plus optional analyzer and explanation.
confidence	"certain" \| "inferred" \| "unknown"	Core's confidence in the evidence for this individual diagnostic.

Nested field shapes

ZemDomuSourceLocation: Required file, line, and column; optional zero-based absolute offset.
ZemDomuRelatedLocation: Required source plus an optional explanatory message.
ZemDomuDiagnosticSuggestion: Required guidance message plus optional replacementtext for consumers that can apply a safe edit.
ZemDomuDiagnosticProvenance: Required kind of source, cross-component, or inference; optional analyzer anddescription.

CLI JSON

Use JSON for scripts that need canonical fields. The CLI writes the JSON array to standard output and exits with code 1 when diagnostics are present, so capture the output even when the check reports findings.

npx zemdomu check "src/**/*.{html,jsx,tsx,vue}" --cross --format json

[
  {
    "schemaVersion": "1.0",
    "rule": "requireAltText",
    "code": "ZMD004",
    "severity": "error",
    "message": "<img> tag missing alt attribute",
    "source": {
      "file": "src/Hero.tsx",
      "line": 6,
      "column": 8,
      "offset": 142
    },
    "page": "src/App.tsx",
    "componentPath": ["App", "Hero"],
    "preferredEditLocation": {
      "file": "src/Hero.tsx",
      "line": 6,
      "column": 8
    },
    "suggestion": {
      "message": "Add alt text that describes the image's purpose."
    },
    "provenance": {
      "kind": "cross-component",
      "analyzer": "ProjectLinter"
    },
    "confidence": "certain"
  }
]

VS Code presentation

The extension turns source into a VS Code range, maps canonical severity to the matching editor severity, and exposescode as the documentation link. Page, component path, and suggestion text appear in the diagnostic message. Related and preferred edit locations appear as related information.

Problems

src/Hero.tsx:7:9 — ZMD004: <img> tag missing alt attribute [ZemDomu]

VS Code coordinates are displayed as one-based values even though the underlying editor range and canonical location are zero-based.

GitHub Action and SARIF

The Action maps error, warning, and info to GitHub error, warning, and notice annotations. It also writes a SARIF 2.1.0 file and exposes its absolute path through the sarif output.

- uses: actions/checkout@v4
- id: zemdomu
  uses: Zemdomu/ZemDomu-action@main
  with:
    files: "src/**/*.{html,jsx,tsx,vue}"
    crossComponentAnalysis: "true"

- name: Upload ZemDomu SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ${{ steps.zemdomu.outputs.sarif }}

SARIF uses one-based regions. Rule identity remains in ruleId, while ZemDomu-specific context is preserved in namespaced result properties and native related locations.

{
  "version": "2.1.0",
  "runs": [{
    "results": [{
      "ruleId": "ZMD004",
      "level": "error",
      "message": { "text": "<img> tag missing alt attribute" },
      "locations": [{
        "physicalLocation": {
          "artifactLocation": { "uri": "src/Hero.tsx" },
          "region": { "startLine": 7, "startColumn": 9 }
        }
      }],
      "properties": {
        "zemdomu/schemaVersion": "1.0",
        "zemdomu/rule": "requireAltText",
        "zemdomu/componentPath": ["App", "Hero"]
      }
    }]
  }]
}

Compatibility and migration

Import public APIs from the zemdomu package root. Do not import Core source files, build output, or wildcard subpaths.
The 1.x line keeps lint, ProjectLinter, and the compatibility LintResult model. Canonical ZemDomuDiagnostic is an additive integration contract.
Check schemaVersion, tolerate absent optional fields, and ignore additive fields you do not yet consume.
Removing deprecated wildcard subpaths requires a major release and a release-note migration notice.

Read the accepted public API and integration-boundaries decision and the Core changelog before migrating an integration.