---
title: Check Report
description: Look up Check Report completeness, fields, ordering, diagnostics, JSON serialization, streams, exit status, and recovery behavior.
---

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

> **Report completeness**
>
> `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.

This example is a complete report with no Recognized Documents or Violations.

```json title="check-report.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                    | JSON type                               | Required | Meaning                                                             |
| ------------------------ | --------------------------------------- | -------- | ------------------------------------------------------------------- |
| `schemaVersion`          | number, exactly `1`                     | Yes      | Check Report contract version.                                      |
| `complete`               | boolean                                 | Yes      | Report discriminant.                                                |
| `repositoryRoot`         | string                                  | Yes      | Selected Repository Root as an absolute real path.                  |
| `profile`                | object                                  | Yes      | Selected Profile identity.                                          |
| `markdownDialect`        | string, exactly `"github"`              | Yes      | Markdown Dialect used for link and heading semantics.               |
| `counts`                 | object                                  | Yes      | Recognized and checked document counts.                             |
| `violations`             | array of Violation objects              | Yes      | Rule failures found during completed evaluations.                   |
| `operationalDiagnostics` | array of Operational Diagnostic objects | Yes      | Empty for a complete report and non-empty for an incomplete report. |

### `profile`

| Field     | JSON type           | Required | Meaning                      |
| --------- | ------------------- | -------- | ---------------------------- |
| `name`    | string              | Yes      | `"basic"` or `"mattpocock"`. |
| `version` | number, exactly `1` | Yes      | Profile Version.             |

### `counts`

| Field                 | JSON type | Required | Meaning                                                                                                                                                                 |
| --------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recognizedDocuments` | number    | Yes      | Number of documents produced by discovery.                                                                                                                              |
| `checkedDocuments`    | number    | Yes      | Number of documents fully evaluated by Rules, including documents with Violations. Documents affected by an operational read or target-inspection failure are excluded. |

### Discriminated branches

| `complete` | `operationalDiagnostics` JSON type                | Meaning                                                |
| ---------- | ------------------------------------------------- | ------------------------------------------------------ |
| `true`     | empty array                                       | Complete report. `violations` may still be non-empty.  |
| `false`    | non-empty array of Operational Diagnostic objects | Incomplete report that retains established Violations. |

## Violations

| Field          | JSON type | Required | Meaning                                                                                             |
| -------------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `ruleId`       | string    | Yes      | Stable Rule identifier.                                                                             |
| `sourcePath`   | string    | Yes      | Repository-relative source document.                                                                |
| `line`         | number    | Yes      | One-based source line.                                                                              |
| `column`       | number    | Yes      | One-based source column.                                                                            |
| `destination`  | string    | Yes      | Relevant target, or an empty string when no destination applies.                                    |
| `message`      | string    | Yes      | Explanation of the failed requirement.                                                              |
| `recovery`     | string    | Yes      | Action to correct the documentation.                                                                |
| `documentType` | string    | No       | Document Type for an associated Template Violation; omitted when the Violation is unrelated to one. |

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.

| Field      | JSON type | Required | Meaning                                                                                                  |
| ---------- | --------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `code`     | string    | Yes      | `"document-discovery-unavailable"`, `"document-read-unavailable"`, or `"target-inspection-unavailable"`. |
| `message`  | string    | Yes      | Explanation of the operational condition.                                                                |
| `path`     | string    | Yes      | Path associated with the operational condition.                                                          |
| `recovery` | string    | Yes      | Recovery action for the operational condition.                                                           |

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. The [Rules and diagnostics reference](/rules-and-diagnostics/) lists the codes that can occur in a Check Report.

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`.

This illustrative incomplete report uses an evidenced missing-target Violation and target-inspection Operational Diagnostic. The Repository Root remains a path placeholder.

```json title="incomplete-check-report.json"
{
  "schemaVersion": 1,
  "complete": false,
  "repositoryRoot": "/absolute/path/to/repository",
  "profile": { "name": "basic", "version": 1 },
  "markdownDialect": "github",
  "counts": {
    "recognizedDocuments": 1,
    "checkedDocuments": 0
  },
  "violations": [
    {
      "ruleId": "markdown-local-target-missing",
      "sourcePath": "docs/guide.md",
      "line": 1,
      "column": 1,
      "destination": "missing.md",
      "message": "Local Markdown target does not exist: missing.md.",
      "recovery": "Create the target or change the destination to an existing path relative to this document."
    }
  ],
  "operationalDiagnostics": [
    {
      "code": "target-inspection-unavailable",
      "message": "Markdown target could not be inspected for docs/guide.md:2:1: private/z.md.",
      "path": "docs/guide.md",
      "recovery": "Check that the target path is readable, then run the check again."
    }
  ]
}
```

## 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`.

See the [`check` command](/cli/#presswork-check) for invocation options, [Check a repository](/check-a-repository/) for recovery steps, or [Concepts](/concepts/#check-outcomes) for how report outcomes fit the Presswork model.