---
title: Check Report
description: Look up Check Report completeness, fields, ordering, diagnostics, JSON, streams, exit status, and recovery.
sidebar:
  label: Check Report
  order: 7
---

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.

```json
{
  "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](/cli/#presswork-check) for command options and [Glossary](/glossary/) for canonical report vocabulary.