git-reaper 0.2.0__tar.gz → 0.3.0__tar.gz

{git_reaper-0.2.0 → git_reaper-0.3.0}/.github/workflows/ci.yml

@@ -37,6 +37,20 @@ jobs:
       - run: uv sync
       - run: uv run pytest
 
+  # The base matrix runs without extras, so the GitPython parity tests skip
+  # there. This job installs the [git] extra so that backend is exercised.
+  test-gitpython:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra git
+      - run: uv run --extra git pytest
+
   docs:
     runs-on: ubuntu-latest
     steps:

{git_reaper-0.2.0 → git_reaper-0.3.0}/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-02
+
+Git Necromancy. Mining commit history: who, what, when, and what has died.
+
+### Added
+
+#### Commands
+
+- `reaper chronicle` - extract commit history (SHA, author, date, message,
+  files touched, insertions/deletions) to markdown, JSON, or CSV.
+  `--changelog` groups commits under the tag that heads their release range.
+- `reaper souls` - contributor stats: commits, lines added/removed, first and
+  last seen, and a bus-factor estimate. `--heatmap` renders a day-of-week x
+  hour activity grid (bucketed by each commit's recorded timezone, so output
+  never depends on the machine) and flags the repo's "witching hour."
+- `reaper haunt` - code churn and hotspots: files ranked by change frequency
+  and churn, the classic bug-risk proxy.
+- `reaper autopsy <path>` - deep single-file examination: creation commit,
+  rename history (`--follow`, on by default), authors over time, churn
+  totals, and a blame-based line-age summary.
+- `reaper graveyard` - every file that ever lived and died: path, date of
+  death, the fatal commit, and its author. Renamed-away paths count as deaths.
+- `reaper resurrect <path>` - restore a dead file's last living bytes (read
+  from the parent of the commit that removed it) into the working tree or
+  `--out`. Absolute paths and `..` segments are refused, same as reanimate.
+- `reaper ghosts` - branch hygiene: branches ranked by abandonment, with
+  merged, gone-upstream, and (past `--than 90d`) stale flags.
+- `reaper rot` - staleness report: surviving files ranked by how long they
+  have gone untouched, ages derived from a single log pass.
+- `reaper tombstone` - a stats card for demos and READMEs (born, age,
+  commits, souls, last words, witching hour) as ASCII tombstone art, or JSON.
+
+#### Output and formats
+
+- CSV output (`--format csv`) for `chronicle`, `souls`, `haunt`, `graveyard`,
+  `ghosts`, and `rot`.
+
+#### Library and backends
+
+- The git backend gained the history surface: `log` (with per-file numstat
+  churn), `file_log`, `rename_history`, `deleted_files`, `show_file`,
+  `branches`, and `tags`. Commit records use control-char field separators so
+  multiline messages can never break the parse, and `--no-renames` keeps churn
+  attribution stable.
+- Optional GitPython backend behind the `git-reaper[git]` extra, selectable
+  with `GIT_REAPER_BACKEND=gitpython`. It shares command shapes and parsers
+  with the subprocess backend (`git_reaper.gitio.logparse`), so both return
+  byte-identical results.
+
+### Fixed
+
+- History commands run against a full clone: a full-depth fetch now
+  `--unshallow`s a previously shallow catacombs clone instead of silently
+  seeing only the tip commit.
+- Non-ASCII paths in history output are no longer C-quoted (`core.quotepath`
+  is disabled on log commands), so they read as UTF-8 literals.
+
 ## [0.2.0] - 2026-07-02
 
 Deeper Digging. The conjure/reanimate round trip, repo analysis, and the
@@ -114,6 +171,7 @@ library-first core.
 - Test suite covering the CLI, harvest, tree, ignore matching, cache, and
   schema export; CI workflow; mkdocs documentation site; Makefile.
 
-[Unreleased]: https://github.com/jmcmeen/git-reaper/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/jmcmeen/git-reaper/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/jmcmeen/git-reaper/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/jmcmeen/git-reaper/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/jmcmeen/git-reaper/releases/tag/v0.1.0

{git_reaper-0.2.0 → git_reaper-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-reaper
-Version: 0.2.0
+Version: 0.3.0
 Summary: A spooky utility for data mining git repositories (and any folder foolish enough to hold still).
 Project-URL: Homepage, https://github.com/jmcmeen/git-reaper
 Author: John McMeen
@@ -76,6 +76,8 @@ fallback if the REAPER DAW already owns the short one).
 
 ## Commands
 
+### Reaping and packing
+
 | Command | What it does |
 | --- | --- |
 | `harvest` | Gather files matching a pattern (default `*.md`) from a path or repo URL and concatenate them into one artifact with a provenance header and per-file dividers. |
@@ -89,6 +91,23 @@ fallback if the REAPER DAW already owns the short one).
 | `pulse` | Signs-of-life check: git present, optional extras, cache health. |
 | `banish` | Clear the catacombs (the clone cache). `--older-than 7d` for partial exorcisms. |
 
+### Git necromancy (history mining)
+
+| Command | What it does |
+| --- | --- |
+| `chronicle` | Commit history (SHA, author, date, message, churn) to markdown, JSON, or CSV. `--changelog` groups commits by tag. |
+| `souls` | Contributor stats: commits, lines added/removed, first/last seen, bus factor. `--heatmap` draws a day-of-week x hour activity grid and flags the repo's witching hour. |
+| `haunt` | Code churn and hotspots: files ranked by change frequency and churn, the classic bug-risk proxy. |
+| `autopsy <path>` | Deep single-file exam: creation commit, rename history (`--follow`), authors over time, churn, and a blame-based line-age summary. |
+| `graveyard` | Every file that ever lived and died: path, date of death, the fatal commit, and its author. |
+| `resurrect <path>` | Restore a dead file's last living bytes into the working tree or `--out`. Path traversal is refused outright. |
+| `ghosts` | Branch hygiene: branches ranked by abandonment, with merged, gone-upstream, and (past `--than 90d`) stale flags. |
+| `rot` | Staleness report: surviving files ranked by how long they have gone untouched. |
+| `tombstone` | A stats card for demos and READMEs (born, age, commits, souls, last words, witching hour) as ASCII tombstone art, or JSON. |
+
+History commands need real history, so remote sources are cloned full-depth
+(a previously shallow catacombs clone is unshallowed automatically).
+
 ```sh
 reaper harvest https://github.com/Textualize/rich --pattern "*.md" -o RICH.md
 reaper conjure . --sha256 --split-tokens 100000 -o PACKED.md
@@ -98,6 +117,14 @@ reaper unfinished . --age
 reaper cast nightly-pack
 reaper tree . --format json | jq .file_count
 reaper banish --older-than 7d
+
+reaper chronicle . --changelog
+reaper souls . --heatmap
+reaper haunt . -n 20 --format json | jq '.hotspots[0]'
+reaper autopsy src/git_reaper/cli.py
+reaper graveyard . && reaper resurrect old/module.py --out risen/
+reaper ghosts . --than 90d
+reaper tombstone .
 ```
 
 Recipes live in `.reaperrc` (or `[tool.reaper]` in pyproject.toml):
@@ -158,11 +185,6 @@ make run ARGS="tree ."
 make build      # sdist + wheel
 ```
 
-The version comes from git tags (`hatch-vcs`); there is nothing to bump.
-Publishing a GitHub release for a `vX.Y.Z` tag builds and uploads to PyPI
-via trusted publishing, and docs deploy to GitHub Pages on every push to
-`main`.
-
 ## License
 
 MIT. Rest in peace.

{git_reaper-0.2.0 → git_reaper-0.3.0}/README.md

@@ -18,6 +18,8 @@ fallback if the REAPER DAW already owns the short one).
 
 ## Commands
 
+### Reaping and packing
+
 | Command | What it does |
 | --- | --- |
 | `harvest` | Gather files matching a pattern (default `*.md`) from a path or repo URL and concatenate them into one artifact with a provenance header and per-file dividers. |
@@ -31,6 +33,23 @@ fallback if the REAPER DAW already owns the short one).
 | `pulse` | Signs-of-life check: git present, optional extras, cache health. |
 | `banish` | Clear the catacombs (the clone cache). `--older-than 7d` for partial exorcisms. |
 
+### Git necromancy (history mining)
+
+| Command | What it does |
+| --- | --- |
+| `chronicle` | Commit history (SHA, author, date, message, churn) to markdown, JSON, or CSV. `--changelog` groups commits by tag. |
+| `souls` | Contributor stats: commits, lines added/removed, first/last seen, bus factor. `--heatmap` draws a day-of-week x hour activity grid and flags the repo's witching hour. |
+| `haunt` | Code churn and hotspots: files ranked by change frequency and churn, the classic bug-risk proxy. |
+| `autopsy <path>` | Deep single-file exam: creation commit, rename history (`--follow`), authors over time, churn, and a blame-based line-age summary. |
+| `graveyard` | Every file that ever lived and died: path, date of death, the fatal commit, and its author. |
+| `resurrect <path>` | Restore a dead file's last living bytes into the working tree or `--out`. Path traversal is refused outright. |
+| `ghosts` | Branch hygiene: branches ranked by abandonment, with merged, gone-upstream, and (past `--than 90d`) stale flags. |
+| `rot` | Staleness report: surviving files ranked by how long they have gone untouched. |
+| `tombstone` | A stats card for demos and READMEs (born, age, commits, souls, last words, witching hour) as ASCII tombstone art, or JSON. |
+
+History commands need real history, so remote sources are cloned full-depth
+(a previously shallow catacombs clone is unshallowed automatically).
+
 ```sh
 reaper harvest https://github.com/Textualize/rich --pattern "*.md" -o RICH.md
 reaper conjure . --sha256 --split-tokens 100000 -o PACKED.md
@@ -40,6 +59,14 @@ reaper unfinished . --age
 reaper cast nightly-pack
 reaper tree . --format json | jq .file_count
 reaper banish --older-than 7d
+
+reaper chronicle . --changelog
+reaper souls . --heatmap
+reaper haunt . -n 20 --format json | jq '.hotspots[0]'
+reaper autopsy src/git_reaper/cli.py
+reaper graveyard . && reaper resurrect old/module.py --out risen/
+reaper ghosts . --than 90d
+reaper tombstone .
 ```
 
 Recipes live in `.reaperrc` (or `[tool.reaper]` in pyproject.toml):
@@ -100,11 +127,6 @@ make run ARGS="tree ."
 make build      # sdist + wheel
 ```
 
-The version comes from git tags (`hatch-vcs`); there is nothing to bump.
-Publishing a GitHub release for a `vX.Y.Z` tag builds and uploads to PyPI
-via trusted publishing, and docs deploy to GitHub Pages on every push to
-`main`.
-
 ## License
 
 MIT. Rest in peace.

{git_reaper-0.2.0 → git_reaper-0.3.0}/pyproject.toml

@@ -102,6 +102,11 @@ ignore_missing_imports = true
 module = "tomli"
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+# GitPython ships only in the [git] extra; the base type-check must not need it
+module = "git.*"
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-q"

{git_reaper-0.2.0 → git_reaper-0.3.0}/src/git_reaper/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None

{git_reaper-0.2.0 → git_reaper-0.3.0}/src/git_reaper/art.py

@@ -45,13 +45,18 @@ def banner(version: str, width: int = 80) -> str:
 
 
 def tombstone(lines: list[str]) -> str:
-    """Render lines of text inside ASCII tombstone art."""
-    inner = max(len(line) for line in lines) if lines else 0
+    """Render lines of text inside ASCII tombstone art.
+
+    The frame is sized to the widest line so the right border always closes
+    flush, however long the epitaph runs.
+    """
+    content = ["R I P", "", *lines]
+    inner = max((len(line) for line in content), default=0)
     inner = max(inner, 11)
-    top = "         " + "_" * inner
-    body = [f"        /{' ' * inner}\\"]
-    body.extend(f"       | {line.center(inner - 2)} |" for line in ["R I P", "", *lines])
-    body.append("    ___|" + "_" * inner + "|___")
+    top = "         " + "_" * (inner + 2)
+    body = [f"        /{' ' * (inner + 2)}\\"]
+    body.extend(f"       | {line.center(inner)} |" for line in content)
+    body.append("    ___|" + "_" * (inner + 2) + "|___")
     return "\n".join([top, *body])
 
 

{git_reaper-0.2.0 → git_reaper-0.3.0}/src/git_reaper/cli.py

@@ -21,7 +21,10 @@ from rich.table import Table
 
 from git_reaper import __version__, art, cache, config, fsutil, schemas
 from git_reaper.core import census as census_core
+from git_reaper.core import graveyard as graveyard_core
 from git_reaper.core import harvest as harvest_core
+from git_reaper.core import history as history_core
+from git_reaper.core import hygiene as hygiene_core
 from git_reaper.core import pack as pack_core
 from git_reaper.core import pulse as pulse_core
 from git_reaper.core import scan as scan_core
@@ -67,6 +70,11 @@ def _invocation() -> str:
     return "reaper " + " ".join(shlex.quote(a) for a in sys.argv[1:])
 
 
+def _parse_days(text: str) -> int:
+    """A haunting threshold like '90d' or '12h', floored to whole days."""
+    return int(cache.parse_age(text) // 86400)
+
+
 def _emit(text: str, out: Path | None) -> None:
     """Write an artifact to --out or stdout. Chatter never comes here."""
     if out:
@@ -510,6 +518,296 @@ def cast_cmd(
             raise typer.Exit(code=code) from exc
 
 
+# --------------------------------------------------------------------------
+# git necromancy: chronicle, souls, haunt, autopsy, graveyard, resurrect,
+# ghosts, rot, tombstone. History needs a full clone, so remote sources are
+# fetched deep (depth=None), not shallow.
+# --------------------------------------------------------------------------
+
+
+def _resolve_history(source: str, ref: str | None) -> ResolvedSource:
+    return _resolve(source, ref=ref, depth=None)
+
+
+def _history_die(exc: GitError) -> typer.Exit:
+    return _die(str(exc), "`reaper pulse` checks git; history needs a real repo")
+
+
+@app.command("chronicle")
+def chronicle_cmd(
+    source: str = typer.Argument(".", help="Local path or repo URL."),
+    changelog: bool = typer.Option(False, "--changelog", help="Group commits by tag."),
+    max_count: int | None = typer.Option(
+        None, "--max-count", "-n", help="Only the newest N commits."
+    ),
+    fmt: str = typer.Option("md", "--format", "-f", help="md, json, or csv."),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Output file (default stdout)."),
+    ref: str | None = typer.Option(None, "--ref", help="Branch, tag, or sha."),
+    schema: bool = typer.Option(False, "--schema", help="Print the JSON schema and exit."),
+) -> None:
+    """Extract commit history to markdown, JSON, or CSV."""
+    if schema:
+        _print_schema("chronicle")
+        return
+    _validate_format(fmt, ("md", "json", "csv"))
+    _banner()
+    resolved = _resolve_history(source, ref)
+    try:
+        result = history_core.chronicle(
+            resolved.repo, changelog=changelog, max_count=max_count, invoked=_invocation()
+        )
+    except GitError as exc:
+        raise _history_die(exc) from exc
+    _say("necro", f"transcribed {len(result.commits)} commits")
+    if fmt == "json":
+        _emit(jsonfmt.render(result), out)
+    elif fmt == "csv":
+        _emit(csvfmt.render_chronicle(result), out)
+    else:
+        _emit(markdown.render_chronicle(result), out)
+
+
+@app.command("souls")
+def souls_cmd(
+    source: str = typer.Argument(".", help="Local path or repo URL."),
+    heatmap: bool = typer.Option(False, "--heatmap", help="Add the activity heatmap."),
+    fmt: str = typer.Option("md", "--format", "-f", help="md, json, or csv."),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Output file (default stdout)."),
+    ref: str | None = typer.Option(None, "--ref", help="Branch, tag, or sha."),
+    schema: bool = typer.Option(False, "--schema", help="Print the JSON schema and exit."),
+) -> None:
+    """Contributor stats, bus factor, and the witching hour."""
+    if schema:
+        _print_schema("souls")
+        return
+    _validate_format(fmt, ("md", "json", "csv"))
+    _banner()
+    resolved = _resolve_history(source, ref)
+    try:
+        result = history_core.souls(resolved.repo, heatmap=heatmap, invoked=_invocation())
+    except GitError as exc:
+        raise _history_die(exc) from exc
+    _say("necro", f"counted {len(result.souls)} souls, bus factor {result.bus_factor}")
+    if result.witching_hour:
+        _say("eldritch", f"the witching hour is {result.witching_hour}")
+    if fmt == "json":
+        _emit(jsonfmt.render(result), out)
+    elif fmt == "csv":
+        _emit(csvfmt.render_souls(result), out)
+    else:
+        _emit(markdown.render_souls(result), out)
+
+
+@app.command("haunt")
+def haunt_cmd(
+    source: str = typer.Argument(".", help="Local path or repo URL."),
+    limit: int | None = typer.Option(None, "--limit", "-n", help="Only the top N hotspots."),
+    fmt: str = typer.Option("md", "--format", "-f", help="md, json, or csv."),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Output file (default stdout)."),
+    ref: str | None = typer.Option(None, "--ref", help="Branch, tag, or sha."),
+    schema: bool = typer.Option(False, "--schema", help="Print the JSON schema and exit."),
+) -> None:
+    """Code churn and hotspots: the classic bug-risk proxy."""
+    if schema:
+        _print_schema("haunt")
+        return
+    _validate_format(fmt, ("md", "json", "csv"))
+    _banner()
+    resolved = _resolve_history(source, ref)
+    try:
+        result = history_core.haunt(resolved.repo, limit=limit, invoked=_invocation())
+    except GitError as exc:
+        raise _history_die(exc) from exc
+    _say("necro", f"found {len(result.hotspots)} hotspots")
+    if fmt == "json":
+        _emit(jsonfmt.render(result), out)
+    elif fmt == "csv":
+        _emit(csvfmt.render_haunt(result), out)
+    else:
+        _emit(markdown.render_haunt(result), out)
+
+
+@app.command("autopsy")
+def autopsy_cmd(
+    path: str | None = typer.Argument(None, help="File to examine (relative to the repo)."),
+    source: str = typer.Option(".", "--source", "-s", help="Local path or repo URL."),
+    no_follow: bool = typer.Option(False, "--no-follow", help="Do not follow renames."),
+    fmt: str = typer.Option("md", "--format", "-f", help="md or json."),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Output file (default stdout)."),
+    ref: str | None = typer.Option(None, "--ref", help="Branch, tag, or sha."),
+    schema: bool = typer.Option(False, "--schema", help="Print the JSON schema and exit."),
+) -> None:
+    """Deep single-file examination: birth, authors, churn, blame age."""
+    if schema:
+        _print_schema("autopsy")
+        return
+    if path is None:
+        raise _die("no file given", "pass the path of a file to examine")
+    _validate_format(fmt)
+    _banner()
+    resolved = _resolve_history(source, ref)
+    try:
+        result = history_core.autopsy(
+            resolved.repo, path, follow=not no_follow, invoked=_invocation()
+        )
+    except GitError as exc:
+        raise _history_die(exc) from exc
+    _say("necro", f"examined {result.path}: {result.commits} commits, {len(result.authors)} hands")
+    if fmt == "json":
+        _emit(jsonfmt.render(result), out)
+    else:
+        _emit(markdown.render_autopsy(result), out)
+
+
+@app.command("graveyard")
+def graveyard_cmd(
+    source: str = typer.Argument(".", help="Local path or repo URL."),
+    fmt: str = typer.Option("md", "--format", "-f", help="md, json, or csv."),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Output file (default stdout)."),
+    ref: str | None = typer.Option(None, "--ref", help="Branch, tag, or sha."),
+    schema: bool = typer.Option(False, "--schema", help="Print the JSON schema and exit."),
+) -> None:
+    """List every file that ever lived and died in the repo."""
+    if schema:
+        _print_schema("graveyard")
+        return
+    _validate_format(fmt, ("md", "json", "csv"))
+    _banner()
+    resolved = _resolve_history(source, ref)
+    try:
+        result = graveyard_core.graveyard(resolved.repo, invoked=_invocation())
+    except GitError as exc:
+        raise _history_die(exc) from exc
+    _say("necro", f"counted {len(result.dead)} dead")
+    if fmt == "json":
+        _emit(jsonfmt.render(result), out)
+    elif fmt == "csv":
+        _emit(csvfmt.render_graveyard(result), out)
+    else:
+        _emit(markdown.render_graveyard(result), out)
+
+
+@app.command("resurrect")
+def resurrect_cmd(
+    path: str | None = typer.Argument(None, help="Dead file to raise (its path in the repo)."),
+    source: str = typer.Option(".", "--source", "-s", help="Local path or repo URL."),
+    out: Path = typer.Option(
+        Path("."), "--out", "-o", help="Directory (keeps the path) or exact file target."
+    ),
+    force: bool = typer.Option(False, "--force", help="Overwrite if the target exists."),
+    ref: str | None = typer.Option(None, "--ref", help="Branch, tag, or sha."),
+    schema: bool = typer.Option(False, "--schema", help="Print the JSON schema and exit."),
+) -> None:
+    """Restore a dead file from the graveyard into the working tree."""
+    if schema:
+        _print_schema("resurrect")
+        return
+    if path is None:
+        raise _die("no file given", "pass the path of a dead file; `reaper graveyard` lists them")
+    _banner()
+    resolved = _resolve_history(source, ref)
+    try:
+        result = graveyard_core.resurrect(resolved.repo, path, out, force=force)
+    except graveyard_core.ResurrectError as exc:
+        raise _die(str(exc), "`reaper graveyard` lists what can be raised") from exc
+    except GitError as exc:
+        raise _history_die(exc) from exc
+    _say("necro", f"raised {result.path} from {result.sha[:7]} into {result.out}")
+    _say("ash", "it walks again.")
+
+
+@app.command("ghosts")
+def ghosts_cmd(
+    source: str = typer.Argument(".", help="Local path or repo URL."),
+    than: str | None = typer.Option(
+        None, "--than", help="Flag branches idle longer than this (e.g. 90d)."
+    ),
+    fmt: str = typer.Option("md", "--format", "-f", help="md, json, or csv."),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Output file (default stdout)."),
+    ref: str | None = typer.Option(None, "--ref", help="Branch, tag, or sha."),
+    schema: bool = typer.Option(False, "--schema", help="Print the JSON schema and exit."),
+) -> None:
+    """Branch hygiene: activity, merged-but-undeleted, gone remotes."""
+    if schema:
+        _print_schema("ghosts")
+        return
+    _validate_format(fmt, ("md", "json", "csv"))
+    _banner()
+    try:
+        than_days = _parse_days(than) if than else None
+    except ValueError as exc:
+        raise _die(str(exc)) from exc
+    resolved = _resolve_history(source, ref)
+    try:
+        result = hygiene_core.ghosts(resolved.repo, than_days=than_days, invoked=_invocation())
+    except GitError as exc:
+        raise _history_die(exc) from exc
+    _say("necro", f"walked {len(result.branches)} branches")
+    if fmt == "json":
+        _emit(jsonfmt.render(result), out)
+    elif fmt == "csv":
+        _emit(csvfmt.render_ghosts(result), out)
+    else:
+        _emit(markdown.render_ghosts(result), out)
+
+
+@app.command("rot")
+def rot_cmd(
+    source: str = typer.Argument(".", help="Local path or repo URL."),
+    limit: int | None = typer.Option(None, "--limit", "-n", help="Only the top N stalest."),
+    exclude: list[str] = typer.Option([], "--exclude", "-x", help="Glob(s) to skip."),
+    fmt: str = typer.Option("md", "--format", "-f", help="md, json, or csv."),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Output file (default stdout)."),
+    ref: str | None = typer.Option(None, "--ref", help="Branch, tag, or sha."),
+    schema: bool = typer.Option(False, "--schema", help="Print the JSON schema and exit."),
+) -> None:
+    """Staleness report: files untouched the longest."""
+    if schema:
+        _print_schema("rot")
+        return
+    _validate_format(fmt, ("md", "json", "csv"))
+    _banner()
+    resolved = _resolve_history(source, ref)
+    try:
+        result = hygiene_core.rot(
+            resolved.repo, limit=limit, excludes=exclude, invoked=_invocation()
+        )
+    except GitError as exc:
+        raise _history_die(exc) from exc
+    _say("necro", f"weighed {len(result.files)} files for rot")
+    if fmt == "json":
+        _emit(jsonfmt.render(result), out)
+    elif fmt == "csv":
+        _emit(csvfmt.render_rot(result), out)
+    else:
+        _emit(markdown.render_rot(result), out)
+
+
+@app.command("tombstone")
+def tombstone_cmd(
+    source: str = typer.Argument(".", help="Local path or repo URL."),
+    fmt: str = typer.Option("md", "--format", "-f", help="md or json."),
+    out: Path | None = typer.Option(None, "--out", "-o", help="Output file (default stdout)."),
+    ref: str | None = typer.Option(None, "--ref", help="Branch, tag, or sha."),
+    schema: bool = typer.Option(False, "--schema", help="Print the JSON schema and exit."),
+) -> None:
+    """A stats card for demos and READMEs, in ASCII tombstone art."""
+    if schema:
+        _print_schema("tombstone")
+        return
+    _validate_format(fmt)
+    _banner()
+    resolved = _resolve_history(source, ref)
+    try:
+        result = history_core.tombstone(resolved.repo, invoked=_invocation())
+    except GitError as exc:
+        raise _history_die(exc) from exc
+    if fmt == "json":
+        _emit(jsonfmt.render(result), out)
+    else:
+        _emit(markdown.render_tombstone(result), out)
+
+
 # --------------------------------------------------------------------------
 # pulse (doctor)
 # --------------------------------------------------------------------------

git_reaper-0.3.0/src/git_reaper/core/graveyard.py

@@ -0,0 +1,89 @@
+"""The graveyard and its resurrections.
+
+`graveyard` lists every file that lived and died; `resurrect` reads a dead
+file's last living bytes (from the parent of the commit that removed it) and
+brings it back. Restores refuse absolute and traversal paths, same as
+reanimate -- the zip-slip lesson does not care that the source is git.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from git_reaper.core.history import _require_repo
+from git_reaper.core.provenance import make_provenance
+from git_reaper.core.unpack import _unsafe
+from git_reaper.gitio import DeadFileRecord, GitBackend, GitError, default_backend
+from git_reaper.models import DeadFile, GraveyardResult, RepoRef, ResurrectResult
+from git_reaper.schemas import artifact_schema
+
+
+class ResurrectError(ValueError):
+    """A file could not be raised: absent, or an unsafe restore path."""
+
+
+def graveyard(
+    repo: RepoRef,
+    backend: GitBackend | None = None,
+    invoked: str = "reaper graveyard",
+    generated: str | None = None,
+) -> GraveyardResult:
+    """List files a commit removed that are not back in the working tree."""
+    backend = backend or default_backend()
+    root = _require_repo(repo, backend)
+    dead = [
+        DeadFile(path=rec.path, last_sha=rec.sha, died=rec.date, author=rec.author)
+        for rec in backend.deleted_files(root)
+        if not (root / rec.path).exists()
+    ]
+    result = GraveyardResult(
+        provenance=make_provenance(artifact_schema("graveyard"), repo, invoked, generated),
+        dead=dead,
+    )
+    result.provenance.files = len(dead)
+    return result
+
+
+def _find_death(backend: GitBackend, root: Path, rel_path: str) -> DeadFileRecord | None:
+    for rec in backend.deleted_files(root):
+        if rec.path == rel_path:
+            return rec
+    return None
+
+
+def resurrect(
+    repo: RepoRef,
+    rel_path: str,
+    out: Path,
+    force: bool = False,
+    backend: GitBackend | None = None,
+) -> ResurrectResult:
+    """Restore a dead file. `out` is a directory (the file keeps its path) or,
+    if it looks like a file target, the exact destination."""
+    backend = backend or default_backend()
+    root = _require_repo(repo, backend)
+
+    reason = _unsafe(rel_path)
+    if reason:
+        raise ResurrectError(f"refusing to resurrect {rel_path!r}: {reason}")
+
+    death = _find_death(backend, root, rel_path)
+    if death is None:
+        raise ResurrectError(f"{rel_path!r} is not in the graveyard (never deleted, or wrong path)")
+
+    # The fatal commit removed the file; its content still lives in the parent.
+    try:
+        content = backend.show_file(root, f"{death.sha}~1", rel_path)
+    except GitError as exc:
+        raise ResurrectError(str(exc)) from exc
+    if content is None:
+        raise ResurrectError(f"could not read {rel_path!r} at {death.sha[:7]}~1")
+
+    target = out / rel_path if out.is_dir() or not out.suffix else out
+    if target.exists() and not force:
+        raise ResurrectError(f"{target} already exists; use --force to overwrite")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(content)
+    return ResurrectResult(
+        path=rel_path, sha=f"{death.sha}~1", out=str(target), size_bytes=len(content)
+    )