code-review-forge 2.1.0__tar.gz → 2.4.0__tar.gz

{code_review_forge-2.1.0 → code_review_forge-2.4.0}/PKG-INFO

@@ -1,9 +1,17 @@
 Metadata-Version: 2.4
 Name: code-review-forge
-Version: 2.1.0
+Version: 2.4.0
 Summary: 3-state quality gate for code review
 Author-email: Minxi Hou <houminxi@gmail.com>
 License-Expression: Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -12,6 +20,10 @@ Requires-Dist: unidiff<0.8.0,>=0.7.5
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: mutmut<4.0,>=3.3; extra == "dev"
+Requires-Dist: semgrep<1.100,>=1.0; extra == "dev"
+Provides-Extra: vertex
+Requires-Dist: google-auth>=2.35.0; extra == "vertex"
+Requires-Dist: requests>=2.20.0; extra == "vertex"
 Dynamic: license-file
 
 # code-forge
@@ -76,6 +88,61 @@ code-forge install-skill --skill code-forge   # one skill only
 code-forge install-skill --force              # overwrite existing
 ```
 
+## Backend configuration
+
+By default, code-forge uses the `claude` CLI in your PATH with the session
+model (no model pin). Three environment variables control the backend:
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `FORGE_BACKEND` | Select a named backend from `backends.yaml` | session-default |
+| `FORGE_OUTLET` | Force outlet: `cli` or `inline` | auto-detected |
+| `FORGE_LLM_MODEL` | Override model for CLI backends | `claude-sonnet-4-6` |
+
+**Quick examples:**
+
+```bash
+# Use the default (claude CLI, session model)
+code-forge review
+
+# Pin a specific model for this run
+FORGE_LLM_MODEL=claude-opus-4-5 code-forge review
+
+# Use a named API backend from backends.yaml
+FORGE_BACKEND=claude-api code-forge review
+
+# Force inline outlet (no CLI subprocess)
+FORGE_OUTLET=inline code-forge review
+```
+
+**Named backends** (optional) are defined in `~/.config/code-forge/backends.yaml`:
+
+```yaml
+backends:
+  - name: claude-api
+    type: api
+    format: anthropic
+    base_url: https://api.anthropic.com
+    api_key_env: ANTHROPIC_API_KEY
+    default: true
+  - name: openai
+    type: api
+    format: openai
+    base_url: https://api.openai.com/v1
+    api_key_env: OPENAI_API_KEY
+  - name: local-claude
+    type: cli
+    model: claude-opus-4-5
+    command: claude
+```
+
+Full reference: [docs/configuration.md](docs/configuration.md)
+
+Editor setup guides:
+- VS Code: [docs/setup-vscode.md](docs/setup-vscode.md)
+- Cursor: [docs/setup-cursor.md](docs/setup-cursor.md)
+- PyCharm: [docs/setup-pycharm.md](docs/setup-pycharm.md)
+
 ## The pipeline
 
 ```
@@ -187,6 +254,51 @@ Symlinks each of the 6 skills from `~/.claude/skills/<name>` to this
 repo's `skills/<name>`. Hook installation is manual -- see
 `hooks/README.md` and `hooks/settings-snippet.json`.
 
+## Enabling the commit gate (R1)
+
+`install-skill` and `./install.sh` install the review **skills** only -- they
+do not set up enforcement. The R1 pre-commit gate -- the un-fakeable layer that
+runs the test suite on every commit and blocks on new failures, regardless of
+what the in-editor review claims -- is a separate, manual step:
+
+1. Add a `test:` section to `.code-forge/gate.yaml`. Without it, `gate-check`
+   exits with `gate.yaml must have a 'test' section`:
+
+   ```yaml
+   test:
+     command: [pytest, -q]
+     timeout_seconds: 900
+   ```
+
+   `command[0]` must be a known runner (`python3`, `python`, `pytest`, `cargo`,
+   `go`, `make`, `npm`, `npx`, `node`); no shell metacharacters are allowed.
+
+2. Install the hook:
+
+   ```bash
+   code-forge install-hooks
+   ```
+
+   This writes `.git/hooks/pre-commit` that runs `code-forge verify` (a receipt
+   tamper check) and then `code-forge gate-check` (the test gate).
+
+3. If `git config core.hooksPath` is set, `install-hooks` refuses to write to a
+   custom hooks path and prints a manual fallback. Add these two lines to your
+   existing pre-commit hook by hand:
+
+   ```sh
+   code-forge verify --quiet 2>/dev/null || exit 1
+   exec code-forge gate-check
+   ```
+
+The skills give you the review passes; this gate is what makes a green verdict
+mean the tests actually pass. Without it, an in-editor review that never ran can
+still reach a commit. Commits that stage only non-code files (docs, config,
+metadata such as `.md`, `.yaml`, `.toml`, `LICENSE`, `README`) are detected by
+the hook and skip the gate automatically -- no receipts and no `--no-verify`
+needed. Any staged file outside that set, including unknown extensions, re-arms
+the gate for the whole commit.
+
 ## Hooks (reference implementations)
 
 | Hook                          | Trigger               | Purpose                       |

code_review_forge-2.1.0/src/code_review_forge.egg-info/PKG-INFO → code_review_forge-2.4.0/README.md

@@ -1,19 +1,3 @@
-Metadata-Version: 2.4
-Name: code-review-forge
-Version: 2.1.0
-Summary: 3-state quality gate for code review
-Author-email: Minxi Hou <houminxi@gmail.com>
-License-Expression: Apache-2.0
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: unidiff<0.8.0,>=0.7.5
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: mutmut<4.0,>=3.3; extra == "dev"
-Dynamic: license-file
-
 # code-forge
 
 [![PyPI version](https://img.shields.io/pypi/v/code-review-forge.svg)](https://pypi.org/project/code-review-forge/)
@@ -76,6 +60,61 @@ code-forge install-skill --skill code-forge   # one skill only
 code-forge install-skill --force              # overwrite existing
 ```
 
+## Backend configuration
+
+By default, code-forge uses the `claude` CLI in your PATH with the session
+model (no model pin). Three environment variables control the backend:
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `FORGE_BACKEND` | Select a named backend from `backends.yaml` | session-default |
+| `FORGE_OUTLET` | Force outlet: `cli` or `inline` | auto-detected |
+| `FORGE_LLM_MODEL` | Override model for CLI backends | `claude-sonnet-4-6` |
+
+**Quick examples:**
+
+```bash
+# Use the default (claude CLI, session model)
+code-forge review
+
+# Pin a specific model for this run
+FORGE_LLM_MODEL=claude-opus-4-5 code-forge review
+
+# Use a named API backend from backends.yaml
+FORGE_BACKEND=claude-api code-forge review
+
+# Force inline outlet (no CLI subprocess)
+FORGE_OUTLET=inline code-forge review
+```
+
+**Named backends** (optional) are defined in `~/.config/code-forge/backends.yaml`:
+
+```yaml
+backends:
+  - name: claude-api
+    type: api
+    format: anthropic
+    base_url: https://api.anthropic.com
+    api_key_env: ANTHROPIC_API_KEY
+    default: true
+  - name: openai
+    type: api
+    format: openai
+    base_url: https://api.openai.com/v1
+    api_key_env: OPENAI_API_KEY
+  - name: local-claude
+    type: cli
+    model: claude-opus-4-5
+    command: claude
+```
+
+Full reference: [docs/configuration.md](docs/configuration.md)
+
+Editor setup guides:
+- VS Code: [docs/setup-vscode.md](docs/setup-vscode.md)
+- Cursor: [docs/setup-cursor.md](docs/setup-cursor.md)
+- PyCharm: [docs/setup-pycharm.md](docs/setup-pycharm.md)
+
 ## The pipeline
 
 ```
@@ -187,6 +226,51 @@ Symlinks each of the 6 skills from `~/.claude/skills/<name>` to this
 repo's `skills/<name>`. Hook installation is manual -- see
 `hooks/README.md` and `hooks/settings-snippet.json`.
 
+## Enabling the commit gate (R1)
+
+`install-skill` and `./install.sh` install the review **skills** only -- they
+do not set up enforcement. The R1 pre-commit gate -- the un-fakeable layer that
+runs the test suite on every commit and blocks on new failures, regardless of
+what the in-editor review claims -- is a separate, manual step:
+
+1. Add a `test:` section to `.code-forge/gate.yaml`. Without it, `gate-check`
+   exits with `gate.yaml must have a 'test' section`:
+
+   ```yaml
+   test:
+     command: [pytest, -q]
+     timeout_seconds: 900
+   ```
+
+   `command[0]` must be a known runner (`python3`, `python`, `pytest`, `cargo`,
+   `go`, `make`, `npm`, `npx`, `node`); no shell metacharacters are allowed.
+
+2. Install the hook:
+
+   ```bash
+   code-forge install-hooks
+   ```
+
+   This writes `.git/hooks/pre-commit` that runs `code-forge verify` (a receipt
+   tamper check) and then `code-forge gate-check` (the test gate).
+
+3. If `git config core.hooksPath` is set, `install-hooks` refuses to write to a
+   custom hooks path and prints a manual fallback. Add these two lines to your
+   existing pre-commit hook by hand:
+
+   ```sh
+   code-forge verify --quiet 2>/dev/null || exit 1
+   exec code-forge gate-check
+   ```
+
+The skills give you the review passes; this gate is what makes a green verdict
+mean the tests actually pass. Without it, an in-editor review that never ran can
+still reach a commit. Commits that stage only non-code files (docs, config,
+metadata such as `.md`, `.yaml`, `.toml`, `LICENSE`, `README`) are detected by
+the hook and skip the gate automatically -- no receipts and no `--no-verify`
+needed. Any staged file outside that set, including unknown extensions, re-arms
+the gate for the whole commit.
+
 ## Hooks (reference implementations)
 
 | Hook                          | Trigger               | Purpose                       |

code_review_forge-2.4.0/pyproject.toml

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "code-review-forge"
+version = "2.4.0"
+description = "3-state quality gate for code review"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+authors = [
+    {name = "Minxi Hou", email = "houminxi@gmail.com"},
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "pyyaml>=6.0",
+    "unidiff>=0.7.5,<0.8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "mutmut>=3.3,<4.0",
+    # semgrep>=1.100 uses io_uring which fails on systems with low RLIMIT_MEMLOCK.
+    # Pin to <1.100 until the upstream io_uring memory issue is resolved.
+    "semgrep>=1.0,<1.100",
+]
+vertex = [
+    "google-auth>=2.35.0",
+    "requests>=2.20.0",
+]
+
+[project.scripts]
+code-forge = "code_forge.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+code_forge = ["skills/**/*", "skills/**/.gitkeep", "rules/**/*"]
+
+[tool.ruff]
+line-length = 105
+
+[tool.pytest.ini_options]
+markers = [
+    "real_api: opt-in tests that call real backends (skipped by default)",
+    "integration: marks tests requiring real infrastructure",
+]
+pythonpath = ["src"]
+norecursedirs = ["tests/eval/corpus/base_files"]

code_review_forge-2.4.0/src/code_forge/advisory.py

@@ -0,0 +1,78 @@
+"""Advisory finding type and AxisRunner Protocol.
+
+TWO FOUNDING PRINCIPLES:
+
+1. Advisory findings NEVER participate in convergence, NEVER block commits.
+   AdvisoryFinding is a structurally separate type from StateFinding -- no
+   shared base class, no fingerprint, no disposition, no source field.
+   machine.py maintains self.advisories: list[AdvisoryFinding] independently
+   of self.findings: list[StateFinding]. The convergence logic in
+   _fixpoint_reached() operates ONLY on the StateFinding list.
+
+2. AxisRunner.run() intentionally receives ONLY (diff_text, repo_root): no
+   prior findings, no other axes' output, no review state. This is the
+   anti-anchoring invariant underpinning D-11's multi-run majority. Each run
+   sees the diff fresh, forming independent judgments. Do not widen this
+   signature.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class AdvisoryFinding:
+    """A single advisory finding from a review axis.
+
+    Advisory findings are informational: they surface risks, concerns, and
+    observations but NEVER block the review verdict or reset the cycle
+    counter. They are a completely separate type from StateFinding.
+
+    Fields intentionally excluded (structural incompatibility):
+    - fingerprint: advisory findings are not deduplicated against blocking
+    - disposition: advisory findings have no CONFIRMED/FIXED/DISMISSED state
+    - source: advisory findings are attributed by axis, not by L0/L1/L2 tier
+    """
+
+    id: str
+    axis: str
+    file: str
+    line_range: list[int]
+    description: str
+    attribution: str
+
+
+class AxisRunner(Protocol):
+    """Protocol for review axes (blocking or advisory).
+
+    machine.py dispatches to runners implementing this protocol.
+    Each axis is a separate module providing its own runner.
+
+    The run() signature is intentionally narrow: only diff_text and
+    repo_root. No prior findings, no review state, no other axes' output.
+    This prevents anchoring bias when running majority-vote evaluations
+    (D-11).
+    """
+
+    @property
+    def is_advisory(self) -> bool:
+        """True if this axis produces advisory (non-blocking) findings."""
+        ...
+
+    def run(
+        self,
+        diff_text: str,
+        repo_root: Path,
+    ) -> list[AdvisoryFinding]:
+        """Run the axis on the given diff and return findings.
+
+        Args:
+            diff_text: unified diff of the changes under review.
+            repo_root: path to the repository root.
+
+        Returns:
+            List of findings from this axis.
+        """
+        ...