review-gate

review-gate

中文说明

A DeepSeek Harness (dsh) bundle that turns code review into a hard gate.
Unlike read-only review/diff viewers, review-gate closes the loop: it produces
graded findings, blocks or passes merges deterministically, requires a team
approval quorum, and keeps a durable compliance audit trail — all wired to
ctx.tools and a standalone CLI for CI/hooks.

The gap it fills: in the ecosystem, review plugins observe a diff and add
annotations, but none of them gate the merge. review-gate makes review a
checkpoint that must pass before a PR/merge proceeds.

  git diff ──► run ──► findings
                        │  deterministic rules (severe/warning/suggestion)
                        ▼
                     gate ──► blocked / passed
                        │
                        ▼
                 team approval quorum ──► approved ⇢ merge unlocked
                        │
                        ▼
                 audit trail (time / person / conclusion / rules version)

---

Features

1. Review sessions — review the working tree, staged changes, a single
   commit, or any base..head range. Findings are graded
   severe / warning / suggestion, produced per file/hunk by:
   • deterministic static rules (regex over added lines, never a model), and
   • LLM-assisted findings (optional). The model only ever adds findings;
     it can never bypass a threshold.
2. Gate rules — configurable thresholds (severe = 0, warning ≤ N,
   suggestions unlimited, manual-confirmation checklist). The pass/fail
   decision is computed by deterministic rules from the persisted round
   (findings + acknowledgements + votes) — fully reproducible, never a model
   judgment. If the auto-gate fails, no approval can unlock the merge.
3. Team approval flow — approve / request_changes / reject with a
   configurable quorum (N distinct approvals). Last-writer-wins per reviewer;
   a re-review (new round) invalidates stale approvals and stale
   acknowledgements.
4. Compliance trail — every run, vote, acknowledgement and export is
   appended to an immutable audit log (time, actor, conclusion, rules
   version), and can be exported as a JSON or Markdown report.
5. CI collaboration — every tool and CLI command emits machine-readable
   JSON and correct exit codes (gate-check exits non-zero until passable),
   ready for a GitHub Action / hook / branch protection.
6. Lessons library — optional: failed findings can be turned into reusable
   static rules by adding them to the rule set (see Config).
7. Toolchain — dsh tools review_run, review_status, review_approve,
   review_request_changes, review_reject, review_acknowledge,
   gate_check, review_export, plus a standalone review-gate CLI.

---

How it works (short)

• A session is keyed by (stable repository identity, diff scope), so a
  committed trail keeps the same identity on any checkout or CI machine. A
  deterministic fingerprint of the diff + rules + policy identifies the
  reviewed content; running on unchanged content reuses the round (idempotent)
  and never duplicates audit entries.

• Findings have stable ids derived from their content, so acknowledgements
  and manual-confirmation lists survive identical re-runs. A new round
  (content or policy changed) requires fresh acknowledgements.

• The gate combines the auto-rules and the approval state into one status:

  status	meaning
  open	created, not yet reviewed (no round)
  blocked	auto-gate failed, or a request_changes/reject is active
  passed	auto-gate passed, approvals pending
  approved	auto-gate passed and quorum met, no blockers — merge unlocked

• Persistence is a JSON file store with per-session atomic
  read-modify-write (in-process mutex + temp-write/fsync/rename), a
  cross-process lock file, and an append-only audit.jsonl.

---

Project layout

review-gate/
├── package.json            # dsh.bundle.patch → cordis.patch.yml
├── cordis.patch.yml        # mounts the plugin row
├── tsconfig[.test].json
├── src/
│   ├── types.ts            # core domain types
│   ├── config.ts           # configuration, defaults, validation, rules
│   ├── git/diff.ts         # unified-diff parser (pure)
│   ├── git/runner.ts       # `git` interactions (injectable executor)
│   ├── analyzers/static.ts # deterministic regex analyzer
│   ├── analyzers/llm.ts    # optional LLM reviewer (lazy ctx.llm)
│   ├── gate/engine.ts      # deterministic auto-gate
│   ├── approval/flow.ts    # votes, quorum, last-writer-wins
│   ├── service/evaluate.ts # combined gate+approval verdict
│   ├── service/reviewGate.ts # the facade / public API
│   ├── store/              # durable + in-memory stores, file lock
│   ├── audit/report.ts     # compliance report rendering
│   ├── dsh/                # dsh adapter (tools, llm gateway, entry)
│   ├── cli.ts              # standalone CLI
│   └── index.ts            # programmatic API exports
├── test/                   # node:test suites (61 tests)
├── examples/
│   ├── review-gate.config.json   # full annotated config
│   └── github-action.yml         # CI gate workflow
├── README.md / README.zh.md
└── LICENSE

---

Getting started

Node.js ≥ 18 is enough for the standalone CLI and programmatic API. When
running as a dsh bundle, the harness itself requires ^22.19.0 || >=24.0.0
(check the harness install docs). git must be on PATH and the target
directory must be a git working tree.

Install

npm install -g review-gate   # standalone CLI for any git repo

or install it as a dsh bundle (see below).

Run the CLI

# from a git repo
review-gate run --json                 # review working tree vs HEAD
review-gate status --json
review-gate gate-check --mode merge    # exit 0 only when mergeable

Build & test locally:

npm install
npm run build          # → dist/
npm test               # → builds dist-test/ and runs node --test
node dist/cli.js run   # or: npm run cli -- run

Install as a dsh bundle

review-gate follows the dsh bundle spec:

// package.json
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }

cordis.patch.yml inserts a review-gate row into the profile layer; override
its config per deployment (a patch replaces the whole row config; restate
every key). Install like any bundle:

dsh plugin --profile <name> add ./review-gate
dsh --profile <name> --patch ./review-gate/cordis.patch.yml

The plugin exports name / inject / apply(ctx, config) and registers the
tools on ctx.tools (see dsh tools below). LLM-assisted review is enabled
through config.llm.enabled and resolves ctx.llm lazily at call time, so a
later-mounted model layer is picked up automatically; when no model layer is
available the plugin records a llm.warn audit event and continues — findings
from the static rules still rule the gate.

Configure

Place <repo>/.review-gate.config.json (used by the CLI) and/or the same
object in the plugin row's config:

{
  "cwd": "/absolute/path/to/repo",
  "store": { "root": ".review-gate", "repoId": "github.com/acme/repo" },
  "gate": {
    "severe": 0,
    "warning": 0,
    "suggestion": -1,
    "requiredAcknowledge": []
  },
  "approvals": { "required": 2 },
  "llm": { "enabled": false },
  "onEmptyDiff": "pass",
  "maxFindings": 500,
  "rules": { /* custom static rules, merged over built-ins */ }
}

Run review-gate init to write an example file. See examples/review-gate.config.json.

store.repoId pins the stable identity used to key sessions so a committed
trail is readable from every checkout and CI. When unset it is derived from
remote.origin.url, then the git toplevel, then the working directory — see
CI collaboration.

LLM-assisted review is off by default. To enable it set llm.enabled and,
where your deployment does not route a default provider/model, llm.provider
and llm.model. LLM findings are counted by the same deterministic
thresholds; if the model is unavailable the run still completes.

Gate thresholds (-1 = unlimited):

field	default	meaning
gate.severe	0	max unacknowledged severe findings allowed
gate.warning	0	max unacknowledged warnings allowed
gate.suggestion	-1	suggestions never block by default
gate.requiredAcknowledge	[]	finding ids that must be explicitly acknowledged; the token "severe" means every severe finding must be acknowledged

Acknowledging findings moves them out of the failure set and is always
audited: review-gate acknowledge <id> --reason "charted in CR-77".

Built-in rules (src/config.ts::defaultRules): todo, debugger,
console-log, hardcoded-secret, long-line, merge-markers. Each has a
pattern, severity, message, optional files path regex and suggestion.
Add or override entries under rules to encode lessons from past failures —
hundreds of matches are capped by maxFindings.

Empty diff — "empty" means git reported no changes at all. A binary-only,
pure-rename or mode-only change is a real diff: it produces no line-level
findings but still requires the approval quorum. onEmptyDiff: "pass"
(default) lets a genuinely empty diff through; "fail" requires an explicit
review: it inserts a severe finding that must be acknowledged, which is how
a "nothing changed but this still needs sign-off" policy is expressed.

---

dsh tools

tool	purpose
review_run	run the review of the current diff / commit / range
review_status	current findings, status, approval progress
review_approve	+1 toward the quorum (blocks if auto-gate fails)
review_request_changes	block until re-reviewed
review_reject	block until re-reviewed
review_acknowledge	acknowledge a finding with a reason (audited)
gate_check	deterministic verdict, machine-readable JSON, modes gate/merge
review_export	compliance report as JSON / Markdown

Every tool returns a JSON value (CI-consumable) and renders a readable summary
for the model. You can also call the same logic programmatically:

import { ReviewGate, JsonFileStore, GitRunner, resolveConfig } from 'review-gate/core'

const config = resolveConfig({ cwd: '/path/to/repo' })
const gate = new ReviewGate({
  config,
  store: new JsonFileStore({ root: config.store.root }),
  git: new GitRunner({ cwd: config.cwd }),
})
const { verdict } = await gate.run({ scope: { kind: 'range', base: 'main', head: 'feature' } })
const check = await gate.gateCheck({ mode: 'merge' })

---

CLI reference

review-gate <command> [scope] [options]

  run | status | approve | reject | request-changes | acknowledge
  gate-check | export | audit | init | version

Scope: working | staged | commit:<ref> | range:<base>..<head>   (default working)

  --dir <path>      repository to review            --config <file>
  --force           new round even if unchanged     --mode gate|merge
  --reviewer <r>    --comment <text>                --reason <text>
  --format json|markdown (export)                   --out <file>
  --actor <label>   --json

gate-check is the CI hook: it prints JSON and exits 0 on --mode gate
(when status is passed/approved) or 0 on --mode merge (only when
approved). All other commands exit 0 on success, 1 on a refused
operation, 2 on usage/config errors.

---

CI collaboration

The gate's state + audit trail live in <repo>/.review-gate/. Because sessions
are keyed on a stable repo identity (store.repoId, or derived from the
remote URL), a trail recorded in one checkout is readable from any other
checkout of the same repository — including CI.

Two deployment models:

• Committed trail (recommended for merge blocking) — reviewers create and
  update the review state and approvals in their checkout, then commit
  .review-gate/ to the repository. CI simply checks it out and verifies:
  review-gate gate-check --mode merge exits 0 only when the automatic
  thresholds and the approval quorum are satisfied. examples/github-action.yml
  shows a branch-protection job with this shape.
• Pipeline-owned — the harness / CLI is the reviewer and records state
  directly in the environment the merge gate reads.

Important: use one consistent scope for a given gate everywhere — the same
diff scope reviewers approve on must be the one CI checks (working by
default). gate-check itself never mutates state, so it is safe to run
repeatedly from hooks.

---

Design notes / tradeoffs

• Deterministic gate: the pass/fail decision is a pure function of the
  round's persisted findings + acknowledgements + votes. Model output can only
  contribute findings — never bypass a threshold — and once a round is
  persisted any re-read yields the identical verdict.
• Idempotent: re-running review_run on unchanged content reuses the
  round; an identical vote/acknowledgement is a no-op; gate_check never
  mutates.
• Concurrency: sessions are serialized per key (in-process mutex +
  cross-process lock file with stale-breaking and owner tokens); writes are
  temp+fsync+rename so a crash never corrupts a document; the audit trail is
  append-only.
• Scope boundaries: combined (--cc) merge diffs are intentionally not
  line-reviewed (recorded as a placeholder). Empty diffs are governed by
  onEmptyDiff. Findings are capped by maxFindings.
• Lessons library is intentionally config-driven (add a rule) rather than
  an auto-mutating subsystem — deterministic and auditable.

Security

• The gate reads the repository read-only (git diff / git show); it never
  modifies working trees.
• Secrets in findings: the hardcoded-secret rule echoes matched lines into
  findings/reports — restrict who may read the trail, and consider tighter
  rules in high-security repos.
• This is a review/compliance helper, not an authorization boundary. Anyone
  who can write to the store can edit approvals; protect .review-gate/
  accordingly.

Testing

npm test runs the node:test suites: git/diff parsers, static analyzer,
gate engine, approval flow, JSON store (concurrency + durability + locks),
review runner E2E (incl. empty-diff + LLM fallback + round scoping + stable
identity), idempotency, reports, config validation, dsh tool registry, and a
full CLI round-trip against a real thrown-together git repository.

License

MIT — see LICENSE.