Check Report

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

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.

{
  "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

profile

counts

Discriminated branches

Violations

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. The Rules and diagnostics reference 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.

{
  "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.

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 for invocation options, Check a repository for recovery steps, or Concepts for how report outcomes fit the Presswork model.