# Repo Report

> Generate a metrics report and a shareable deliverable for a git repository: lines of code, language mix, merged PRs and their complexity tiers, test-to-code ratio, untested files, functions/classes, commits, contributors, issue references, CI and reproducibility signals, and license class — plus charts over time (commits, merged PRs and active contributors per month), representative code excerpts, up to 3 sample PRs with diffs, and flags for secrets or PII. Runs offline on a local checkout and packages a PDF, an Excel workbook, JSON, CSV and SVG charts into a single zip. Use when asked to profile, summarise, or document a codebase, produce repo statistics, assess test coverage signals, or pull representative code and PR samples. Trigger phrases: 'generate a repo report', 'analyse this codebase', 'repo stats', 'summarise this repository', 'what does this codebase look like', 'pull sample code and PRs'.

- Skill: `benchflow-ai/repo-report` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add benchflow-ai/repo-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/benchflow-ai/repo-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: benchflow-ai (https://skillmd.com/u/benchflow-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/benchflow-ai/repo-report

---


# Repo report

Profile a git repository: metrics, representative code, sample pull requests, and hygiene flags.
It measures and describes — it does not score, rank, or grade.

## Workflow

1. Confirm a local git checkout. Without git history most metrics are unavailable — say so and
   still run the file scan.

2. Run (stdlib only, no packages):
   ```bash
   python3 scripts/repo_report.py /path/to/repo --out ./report
   ```
   Produces a deliverable zip, `<repo>-report.zip`, containing:

   | File | What |
   |---|---|
   | `report.pdf` | the readable report, with the charts |
   | `metrics.xlsx` | 6 sheets: Summary, Timeline, Languages, Sample PRs, Sample files, Hygiene |
   | `repo_report.json` | everything, machine-readable |
   | `metrics.csv` | one flat row |
   | `report.md` / `report.html` | same report, other formats |
   | `chart-*.svg` | the charts standalone |

   PDF rendering uses whichever engine is installed (Chrome/Chromium/Edge headless, weasyprint,
   or wkhtmltopdf). If none is found it says so and writes `report.html` — open and print it.
   `--no-bundle` writes only JSON + CSV + markdown. Lower `--merge-sample` for a fast pass on a
   very large history.

3. Read `repo_report.json`:
   - `highlights` — the headline facts, ready to quote.
   - `files` / `history` / `environment` — the full metric set. See
     [references/metrics.md](references/metrics.md) for how each is computed.
   - `code_excerpts` — real code, ~40 lines from each of the 3 most substantive files, selected by
     control-flow density so the excerpt shows logic rather than boilerplate.
   - `sample_prs` — up to 3 merged PRs with stats, `touches_tests`, `references_issue`, and a
     truncated `diff_excerpt`. Ranked to show the nature of the work: issue-linked and
     test-touching rank highest; dependency bumps and translation churn are penalised.
   - `timeline_monthly` — commits, merged PRs and distinct authors per month, the series behind
     the activity charts.
   - `cleanup_flags` — **surface these first.** Secrets or PII must be removed from the working
     tree *and* git history before the repo or report is shared.

4. **Review the code before the report leaves the machine.** Excerpts are auto-redacted for
   secret-shaped values, but redaction is not judgement: read each excerpt and diff and confirm
   there is nothing private in them. Swap samples with `--excerpt-files` / `--sample-prs`, or drop
   code entirely with `--no-excerpts`.

## Honesty rules

- Report the metrics as measured; do not editorialise them into a verdict.
- **`% Rich PRs` is a lower bound** — review threads live on the code host, not in git — so say so
  rather than implying the local number is the ceiling.
- Function and class counts are regex **estimates**; label them as such.
- Always surface secret/PII flags. A leaked key or a customer record in a shared repo is a serious
  problem, and catching it first is the point.