What It Is

adversarial-review is an adversarial multi-perspective code review plugin. It uses parallel multi-lens, attack-style review to solve the problem that single-perspective reviews can easily miss defects or mix in stylistic issues. The plugin is maintained by JohnXu22786 and supports both the dsh (DeepSeek Harness) plugin entry point and a standalone CLI.

Core Capabilities

The plugin includes the following core features:
- dsh (DeepSeek Harness) plugin entry: Registers the gavel_review tool, allowing models to call it directly within a session.
- Standalone CLI entry: Supports running locally from the command line and is compatible with any model service that supports the OpenAI Chat Completions protocol.
- Deterministic static sentinel: Runs rule-based (Regex) scans before model involvement to provide a safety-net fallback.
- Suppression rules: Prevents repeated reports of the same type of issue.
- Review history: Performs incremental comparison against known issues.
- Cross-lens merging: Clustering and deduplication, and calculates confirmation boosts.
- Severity grading: Deterministically calculates severity levels.
- Arbitration layer: Merges findings from multiple perspectives.
- Zero third-party runtime dependencies: The core engine and CLI use only built-in Node.js modules.

Installation and Configuration

Install the plugin through the DSH CLI:

dsh plugin --profile demo add github:JohnXu22786/adversarial-review

After installation, the plugin registers itself in the Cordis configuration and declares dsh.bundle.patch in package.json.

Standalone CLI Usage

The standalone CLI tool is gavel.

Environment Requirements

  • Node.js >= 20.19 (running build artifacts)
  • Node.js >= 23.6 (running source code directly)

Basic Build and Usage

  1. Install dependencies and build:
   npm install
   npm run build
  1. Review using a diff file:
   node bin/gavel.mjs review --diff examples/sample.diff --api-key $GAVEL_API_KEY --model deepseek-chat
  1. Review the most recent commit:
   node bin/gavel.mjs review --base HEAD~1
  1. Review specified files:
   node bin/gavel.mjs review --path src/order.js --path src/notify.js
  1. Deep review and generate suppression rules (CI scenario):
   node bin/gavel.mjs review --diff p.patch --deep --emit-rules --out report.md --json-out report.json --fail-on required

Common Options

Option Description
--diff Specifies the path to a unified diff file (supports - to read from stdin)
--base Generates a diff based on a Git reference (e.g., HEAD~1)
--path Reviews specified files (can be repeated)
--lens Specifies a subset of lenses (e.g., correctness,security)
--deep Enables deep review (challenges candidates one by one)
--emit-rules Generates suppression rules for “must fix” level and above
--fail-on Sets a failure threshold (CI gate)
--out / --json-out Outputs Markdown or JSON report paths
--model / --api-key Model and API key configuration (environment variable GAVEL_API_KEY or DEEPSEEK_API_KEY)

Exit Codes

  • 0: Success (including no findings).
  • 1: Argument error or runtime error (e.g., missing API Key).
  • 2: The --fail-on threshold was triggered.
  • 130: Interrupted by a signal.

DSH Integration Notes

In a DSH environment, the plugin registers capabilities through apply(ctx, config). Models can directly call the gavel_review tool within a session. The plugin runtime is a read-only process and does not modify code.

Review Process

The plugin executes a seven-step pipeline:
1. Ingest collect: Parses a unified diff or reads files and builds line mappings.
2. Static sentinel tripwire: Runs deterministic regex rule scans (e.g., hardcoded credentials, dangerous calls).
3. Lens probing probe: Runs correctness, security, and maintainability lenses in parallel (LLM calls).
4. Deep review deep (optional): Revalidates candidates based on challenges.
5. Arbitration merge: Performs cross-lens clustering, deduplication, fingerprinting, and severity grading.
6. Suppression filter suppress: Matches suppression rules and archives issues that should no longer be reported.
7. Docket record docket: Appends to the review history and marks known issues.

Notes

  • Read-only process: The plugin only reads code and does not modify files.
  • Runtime dependencies: Zero third-party runtime dependencies.
  • License: MIT License.
  • API key: An API Key must be provided (e.g., GAVEL_API_KEY or DEEPSEEK_API_KEY).
  • Version compatibility: Ensure the Node.js version meets the requirements.

Conclusion

adversarial-review provides determinism and traceability for code review through multi-lens parallel review and arbitration mechanisms. It is suitable for DSH workflows that require high-quality code delivery.