Check Report

Look up Check Report completeness, fields, ordering, diagnostics, JSON, streams, exit status, and recovery.

A Check Report is the complete or explicitly incomplete result of a Check. It contains deterministically ordered Violations and any Operational Diagnostics. presswork check --json writes the report as one JSON object followed by a newline.

Complete and incomplete reports

complete is the report discriminant:

A complete report has complete: true and operationalDiagnostics: []. It may still contain Violations.
An incomplete report has complete: false and at least one Operational Diagnostic. It retains Violations found before or alongside those diagnostics.

Every report has schemaVersion: 1. The Check Report schema version is independent of the Configuration Version and Profile Version.

{
  "schemaVersion": 1,
  "complete": true,
  "repositoryRoot": "/absolute/path/to/repository",
  "profile": { "name": "basic", "version": 1 },
  "markdownDialect": "github",
  "counts": {
    "recognizedDocuments": 0,
    "checkedDocuments": 0
  },
  "violations": [],
  "operationalDiagnostics": []
}

Report fields

Field	Meaning
`schemaVersion`	The Check Report contract version. The current value is `1`.
`complete`	`true` when no operational condition prevented completion; otherwise `false`.
`repositoryRoot`	The selected Repository Root as an absolute real path.
`profile`	The selected Profile name and Profile Version.
`markdownDialect`	The Markdown Dialect used for link and heading semantics.
`counts.recognizedDocuments`	The number of documents produced by discovery.
`counts.checkedDocuments`	The number of documents fully evaluated by Rules, including documents with Violations. Documents affected by an operational read or target-inspection failure are excluded.
`violations`	Rule failures found during completed evaluations.
`operationalDiagnostics`	Conditions that prevented all or part of the Check from completing.

Violations

Each Violation contains:

ruleId, a stable Rule identifier
sourcePath, a repository-relative source document
line and column, the one-based source position
destination, the relevant target or an empty string when no destination applies
message, an explanation of the failed requirement
recovery, the action to correct the documentation
optional documentType, present for Template Violations associated with a Document Type and omitted for unrelated Rules

Violations are ordered by source directory, source document, line, column, Rule identifier, and destination. Human output preserves this order and groups Violations under their source document.

Operational Diagnostics

An Operational Diagnostic is distinct from a Violation. It explains why Presswork could not complete an operation rather than identifying documentation that failed a Rule.

Each report diagnostic contains a stable code, message, path, and recovery action. Diagnostics are ordered by path, code, message, and recovery. Public diagnostics omit caught causes, Git standard error, platform error text, and stacks.

Examples include unavailable document discovery, an unreadable Recognized Document, or a local target that cannot be inspected. Presswork continues independent evaluation when it can, retains established Violations, and excludes any incompletely evaluated document from counts.checkedDocuments.

Human output and JSON

Human output starts with Check complete or Check incomplete. It then reports the Repository Root, Profile, Markdown Dialect, Recognized Documents, Checked Documents, Violation count, and Operational Diagnostic count before any grouped Violation details.

--json writes the complete Check Report to standard output with no banner, progress, color, ANSI control sequences, or unrelated logs. Redirected human output and --no-color output also contain no ANSI control sequences.

Streams and exit status

The Check Report uses standard output in both human and JSON modes. Operational Diagnostics are also written to standard error. In JSON mode, each diagnostic is one JSON object followed by a newline.

Exit	Report outcome
`0`	The report is complete and contains no Violations.
`1`	The report is complete and contains one or more Violations.
`2`	The report is incomplete.

Repository Root and configuration failures that occur before Presswork can create a Check Report write one diagnostic to standard error, leave standard output empty, and exit 2.

Recovery

For each Violation, change the identified documentation according to its recovery guidance. For each Operational Diagnostic, restore the resource or operation named by its recovery action. Run presswork check again after recovery.

Completion requires a report with complete: true, violations: [], and operationalDiagnostics: [], which exits 0.

See the CLI reference for command options and Glossary for canonical report vocabulary.