Add --output-format to prek run

[pygarap]

Summary

Add --output-format <OUTPUT_FORMAT> to prek run to control how prek prints hook diagnostics and execution results.

--output-format <OUTPUT_FORMAT>
    The format to use for printing diagnostic messages and hook results
    [default: text]
    [possible values: text, full, concise, grouped, json, json-lines, sarif, junit, rdjson, github, gitlab, azure, pylint]

Proposal

prek should format the reporting data it owns, including the project, hook ID, name, alias, status, exit code, duration, file-modification status, and captured hook output. File, line, column, and rule metadata should be included when available.

Output from external hooks should remain opaque and be preserved as captured output. --output-format must not parse or rewrite arbitrary hook output, change hook arguments, or forward the option to hook commands.

Possible values

Human-readable formats

These formats are intended for people and are not stable parsing surfaces. Their presentation may change for readability.

Format	Behavior
text	Preserve the current status-oriented output and render location-aware diagnostics as file:line:col: [RULE] message. This is the default.
full	Include source lines and caret underlines for location-aware diagnostics, together with full hook result details and captured output.
concise	Print minimal hook results and diagnostics as file:line:col rule message, omitting unavailable location fields.
grouped	Group hook results by project and diagnostics by file, with a header for each group.

Machine-readable formats

These are committed output surfaces intended for programmatic consumption and compatibility across versions.

Format	Behavior
json	Serialize the complete report as a single JSON document after all results have been collected.
json-lines	Serialize each report record as a separate JSON object on its own line as it becomes available.
sarif	Serialize diagnostics and hook failures using SARIF 2.1.0.
junit	Serialize each hook execution as a JUnit XML test case and attach its captured output.
rdjson	Serialize diagnostics using Reviewdog Diagnostic Format JSON.

Integration formats

These are stable integrations but may track changes to the formats expected by their target platforms.

Format	Behavior
github	Print failures and diagnostics as GitHub Actions ::warning and ::error annotations.
gitlab	Serialize diagnostics using the GitLab Code Quality JSON format.
azure	Print failures and diagnostics using Azure Pipelines logging commands.
pylint	Print location-aware diagnostics using a Pylint-compatible text format.

Example

repos:
  - repo: builtin
    hooks:
      - id: check-yaml

Usage

$ prek run --all-files --output-format json > prek-results.json

Acceptance criteria

• prek run --help documents --output-format, its default, and every supported value.
• text remains the default and preserves the existing human-readable reporting style.
• Existing hook selection, execution, concurrency, modification detection, and exit status behavior remain unchanged.
• Machine-readable and integration formats are not mixed with progress output or ANSI styling.
• Structured output includes complete prek-owned hook result metadata and preserves captured external hook output without parsing it.
• Human-readable formats are documented as unstable presentation surfaces.
• Machine-readable formats are documented as committed compatibility surfaces.
• Integration formats are documented as tracking their target platform formats.
• Passing, failing, skipped, file-modifying, and concurrently executed hooks are covered by tests.
• The CLI reference is updated.

References

• Support --output-format=json in prek list #430
• Proposal: Add an option to collect runtime metrics from prek run #1458
• prek CLI reference
• Ruff output-format
• ty check --output-format
• uv audit --output-format
• rumdl output formats

[udaya2899]

We currently explicitly route prek's output to reviewdog, do some efm matching to post lint annotations back to github code. Having this could help us avoid that.

[newtob]

An AI efficient format would be ace, would that be concise?
If concise is the best format for AI's to analyse the output, perhaps the docs or description could mark it as such?

[j178]

I think I'll start with just two values for --output-format: pre-commit (the current output, kept as the default) and concise, and leave other formats for future requests.
I've opened #2851 to track this smaller scope.