builddiag checks the build contract of a Rust repository and emits:

• a versioned JSON report (machine-friendly)
• a compact Markdown summary (PR comment friendly)
• optional GitHub Actions annotations

It is designed to be fast and offline by default: it reads manifests and policy files; it does not run cargo commands.

From this repo:

cargo install --path crates/builddiag-cli

builddiag check

Artifacts default to artifacts/builddiag/:

• report.json
• comment.md

To emit GitHub annotations:

builddiag check --annotations github

builddiag check \
  --out artifacts/builddiag/report.json \
  --md artifacts/builddiag/comment.md

The easiest way to integrate builddiag into your CI is using the reusable workflow:

jobs:
  builddiag:
    uses: EffortlessMetrics/builddiag/.github/workflows/builddiag.yml@main
    with:
      profile: oss        # oss, team, or strict
      fail_on: error      # error, warn, or never
      post_comment: true  # Post PR comment with findings
    permissions:
      pull-requests: write  # Required for PR comments

- name: Install builddiag
  uses: taiki-e/install-action@v2
  with:
    tool: builddiag
- name: builddiag (repo truth)
  run: |
    builddiag check \
      --out artifacts/builddiag/report.json \
      --md artifacts/builddiag/comment.md \
      --annotations github

builddiag can be used as a pre-commit hook to validate your build contract before commits:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/EffortlessMetrics/builddiag
    rev: main  # or a specific version tag
    hooks:
      - id: builddiag

Available hook variants:

The hook triggers on changes to Cargo.toml, rust-toolchain.toml, or builddiag.toml.

Install pre-commit and set up the hooks:

pip install pre-commit
pre-commit install

builddiag can output diagnostics in a format compatible with VS Code and other editors:

builddiag check --format diagnostics

This outputs findings in JSON Lines format compatible with VS Code's problem matcher. You can configure a VS Code task to run builddiag and display findings in the Problems panel.

Example .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "builddiag",
      "type": "shell",
      "command": "builddiag",
      "args": ["check", "--format", "diagnostics"],
      "problemMatcher": {
        "owner": "builddiag",
        "fileLocation": ["relative", "${workspaceFolder}"],
        "pattern": {
          "regexp": "^(.*):(\\d+):(\\d+):\\s+(error|warning|info):\\s+\\[(.+)\\]\\s+(.*)$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "code": 5,
          "message": 6
        }
      }
    }
  ]
}

builddiag supports three output formats via --format:

The sensor format wraps the native report in a Cockpit-compatible envelope with structured verdicts, fingerprinted findings, capability tracking, and artifact references.

builddiag check --format sensor --out report.json

The --artifacts-dir flag writes a complete artifact bundle suitable for CI archival:

builddiag check --artifacts-dir artifacts/builddiag

This produces:

artifacts/builddiag/
├── report.json          # sensor.report.v1 envelope
├── comment.md           # Markdown summary (PR comment)
└── extras/
    └── payload.json     # builddiag.report.v1 native payload

When --artifacts-dir is set, --format, --out, and --md are overridden automatically.

For Cockpit CI governance pipelines, use cockpit mode for a single-flag experience:

- name: builddiag (cockpit mode)
  run: builddiag check --mode cockpit

This automatically produces the canonical artifact tree at artifacts/builddiag/:

• report.json — sensor.report.v1 envelope
• comment.md — PR summary
• extras/payload.json — builddiag.report.v1 (native payload)

Cockpit mode exits 0 whenever a report is written (even on policy violations or tool errors), so downstream systems can read the verdict from the report JSON.

The --mode flag controls exit code semantics:

Cockpit mode is designed for CI pipelines where the downstream system reads the report JSON to determine pass/fail. Even on policy violations or tool errors, builddiag writes an error receipt and exits 0 so the pipeline can continue.

builddiag check --mode cockpit --artifacts-dir artifacts/builddiag

Profiles configure check severities as presets. Select with --profile or in config:

Optional config file:

builddiag check --config builddiag.toml

If no config is provided, sensible defaults are used.

Use builddiag-core to embed builddiag in your own tools:

[dependencies]
builddiag-core = "0.2"

use builddiag_core::{Settings, run};

let settings = Settings::default();
let result = run(&settings)?;
println!("Verdict: {:?}", result.report.verdict);

See docs/integration.md for substrate bridge and advanced patterns.

cargo run -p xtask -- schema

MIT OR Apache-2.0