DiffCarve

---

[!WARNING] Early CLI and Action. diffcarve analyze <branch> prints dependency-ordered layers with a reviewability score on each, and --dry-run prints the same thing as a PR comment. The GitHub Action posts that comment on PRs over 400 changed lines. Thresholds and score budgets come from an optional diffcarve.yml. On ten real oversized PRs the layers came out sensible on 6 (results), signed off as enough to keep building. See the roadmap.

💡 What it's for

Coding agents write a whole feature in one go, so the PRs they open are big and reviewers haven't sped up to match. GitHub now has stacked pull requests, but somebody still has to decide where to cut. DiffCarve makes that call from the code itself: it builds an import graph over the changed files and splits the diff into layers where nothing depends on a later layer. Each layer gets a reviewability score, so you know which ones to skim.

It runs as a CLI on your machine or as a GitHub Action in your own CI. There's no DiffCarve server, and your source code never leaves the runner.

📊 Features

Feature	Status
diffcarve analyze <branch>	✅ Built. Dependency-ordered layers from a ts-morph import graph (relative imports, tsconfig paths and package.json imports aliases)
Reviewability score	✅ Built. 0 to 100 per layer, pass at 50 by default, with the lines, files, complexity delta and reverse dependencies behind it
--dry-run	✅ Built. Prints the proposed stack as PR-comment markdown
diffcarve.yml	✅ Built. Trigger threshold, pass line, line/file/complexity/reverse-dep budgets, and per-language exclude globs, read from the branch the PR targets
GitHub Action	✅ Built, dry run only. Silent under the threshold (400 changed lines by default), otherwise posts or updates one comment. Needs only GITHUB_TOKEN
Live demo	✅ Built. Pick a sample PR and see it carved into scored layers in the browser. The samples are synthetic and carved by the real CLI when the page builds
Stacked PR chains, merge gate, Python	After public release

🚀 Quick start

# 1. Install dependencies (Node 22.18 or newer)
npm install

# 2. Build the CLI into dist/
npm run build

# 3. Carve a branch. Run it from the branch the PR targets:
#    it diffs <branch> against its merge base with HEAD.
node dist/cli.js analyze my-feature-branch

# 4. The same stack as the markdown a PR comment would carry
node dist/cli.js analyze my-feature-branch --dry-run

# 5. Tests and lint
npm test && npm run lint

# 6. Build the demo page into _site/ (open _site/index.html)
npm run demo

As a GitHub Action

# .github/workflows/diffcarve.yml
on:
  pull_request:
    types: [opened, synchronize]
permissions:
  contents: read
  pull-requests: write
jobs:
  carve:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # the merge base has to be in the clone
      - uses: ai-automation-tools/diff-carve@main
        with:
          threshold: 400 # optional: overrides diffcarve.yml's threshold

It never blocks or approves anything. On a fork's PR the token can't comment, so the step logs a warning and passes. It runs actions/setup-node with Node 22 first, so later steps in the job see that Node.

Configuration: diffcarve.yml

Optional, at the repo root. The CLI reads it from HEAD and the Action from the PR's base branch, so a PR can't loosen its own budgets. Every key is optional; these are the defaults. An unknown key or a wrong type stops the run and names the key.

threshold: 400       # lines changed (added plus deleted) before the Action comments
pass: 50             # a layer scoring this or more passes (0 to 100)
budgets:             # a layer exactly on every budget scores 50
  lines: 200         # lines changed
  files: 10          # files touched
  complexity: 20     # cyclomatic complexity added: the complexity threshold
  reverseDeps: 5     # changed files outside the layer that import it
languages:
  typescript:        # TS and JS
    exclude: []      # globs kept outside the import graph, e.g. ["**/*.generated.ts"]

🗂️ What's in here

Folder	What's inside
📚 docs/	The roadmap, the changelog, and the product spec and build plan.
🧰 src/	The CLI and Action source.
⚙️ action.yml	The GitHub Action. .github/workflows/diffcarve.yml runs it on this repo's own PRs; ci.yml builds, tests and lints every push and PR.
🎬 demo/	The live demo: sample PRs, the page template, and build.ts, which carves the samples with the real CLI. pages.yml builds it on every PR and deploys it to GitHub Pages from main.
🧪 tests/	Tests for node --test, run straight from TypeScript.
🔒 SECURITY.md	How to report a vulnerability privately.

---