difftriage 0.1.0__tar.gz

difftriage-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

difftriage-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/

difftriage-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: difftriage
+Version: 0.1.0
+Summary: PR risk gate for AI-generated code: diff scoring, test impact checks, and merge policy enforcement.
+Author: DiffTriage Contributors
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# DiffTriage - Pro PR Risk Gating for AI-Generated Code
+
+**difftriage** is an open-source Python library for production-grade pull request risk analysis.
+
+It scores change risk across blast radius, behavior change, test impact, schema/security sensitivity, AI uncertainty, and observability gaps. It then enforces configurable merge policy decisions: `pass`, `review_required`, `block`, and `override_required_review`.
+
+[![PyPI version](https://img.shields.io/pypi/v/difftriage.svg)](https://pypi.org/project/difftriage/)
+[![Python](https://img.shields.io/pypi/pyversions/difftriage.svg)](https://pypi.org/project/difftriage/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Why DiffTriage
+
+Teams shipping more AI-assisted code often face:
+- more regressions in core paths,
+- slower reviews,
+- weak signal-to-noise in large diffs.
+
+DiffTriage provides a deterministic, explainable risk gate with rule-level scoring so teams can move fast without blind merges.
+
+---
+
+## Key Features
+
+- Multi-factor risk model (9 weighted dimensions)
+- Explainable scoring with per-rule contributions
+- Policy decisions: `pass` / `review_required` / `block` / `override_required_review`
+- Confidence bands near threshold boundaries
+- False-positive controls for docs/tests-only changes
+- Override governance with audit-friendly policy flags
+- CI-friendly CLI with multiple output modes
+- GitHub + PyPI release workflows (trusted publishing ready)
+
+---
+
+## Installation
+
+```bash
+pip install difftriage
+```
+
+Requires Python 3.10+.
+
+---
+
+## Quick Start
+
+```bash
+difftriage score \
+  --files-changed 12 \
+  --lines-added 420 \
+  --lines-deleted 130 \
+  --changed-path src/auth/service.py \
+  --changed-path db/migrations/001.sql \
+  --dependencies-changed \
+  --output text
+```
+
+Example result:
+- risk score + level
+- decision + confidence
+- top risk drivers
+- rule scores
+
+---
+
+## CLI Usage
+
+Output formats:
+- `--output text` (default)
+- `--output json`
+- `--output markdown`
+
+Exit semantics:
+- `--exit-mode threshold`:
+  - `0` pass
+  - `2` fail
+- `--exit-mode decision`:
+  - `0` pass
+  - `3` review required
+  - `2` block
+
+Examples:
+
+```bash
+# JSON for automation
+difftriage score --files-changed 8 --lines-added 140 --lines-deleted 35 --changed-path src/payments.py --output json
+
+# Markdown for PR comments
+difftriage score --files-changed 8 --lines-added 140 --lines-deleted 35 --changed-path src/payments.py --output markdown --exit-mode decision
+```
+
+---
+
+## Risk Model
+
+Default weighted dimensions:
+
+- `blast_radius` (0.20)
+- `behavior_change` (0.18)
+- `test_impact` (0.16)
+- `complexity` (0.12)
+- `dependency_config` (0.10)
+- `data_schema` (0.08)
+- `security_privacy` (0.08)
+- `ai_uncertainty` (0.05)
+- `observability_gap` (0.03)
+
+Scoring levels:
+- `0-24`: low
+- `25-49`: medium
+- `50-74`: high
+- `75-100`: critical
+
+---
+
+## Configuration
+
+Create `.difftriage.yml` in repo root:
+
+```yaml
+threshold: 50
+review_threshold: 50
+block_threshold: 75
+enable_confidence_bands: true
+
+weights:
+  blast_radius: 0.20
+  behavior_change: 0.18
+  test_impact: 0.16
+  complexity: 0.12
+  dependency_config: 0.10
+  data_schema: 0.08
+  security_privacy: 0.08
+  ai_uncertainty: 0.05
+  observability_gap: 0.03
+
+rules:
+  risky_path_patterns: ["auth", "billing", "migrations", ".github/workflows", "infra", "config", "permissions", "token"]
+  schema_patterns: ["migrations", "schema", "models", "ddl"]
+  security_patterns: ["auth", "token", "permission", "secret", "privacy"]
+  observability_patterns: ["log", "metrics", "trace"]
+  safe_path_patterns: ["docs/", ".md", "tests/"]
+
+policy:
+  docs_tests_only_max_score: 18
+  safe_change_max_score: 30
+  security_block_score: 70
+  schema_block_score: 78
+  schema_review_score: 45
+  dependency_review_score: 55
+  missing_tests_review_score: 45
+
+override:
+  require_reason_min_length: 12
+  allow_score_override: true
+  allow_schema_override: true
+  allow_dependency_override: true
+  allow_security_override: true
+```
+
+---
+
+## CI Integration
+
+DiffTriage is designed for CI gates:
+
+```bash
+difftriage score ... --output json --exit-mode decision
+```
+
+Recommended policy:
+- treat `review_required` as protected-branch reviewer gate,
+- treat `block` as merge stop,
+- allow audited overrides only for approved emergency paths.
+
+---
+
+## Release and Publishing
+
+This repo includes:
+- `.github/workflows/ci.yml` for tests + build checks
+- `.github/workflows/release.yml` for tag-based PyPI publishing
+
+Publish flow:
+1. Push tag `vX.Y.Z`
+2. Build artifacts
+3. Publish with `pypa/gh-action-pypi-publish` via GitHub OIDC
+
+---
+
+## Local Validation
+
+```bash
+pip install -e . pytest build twine
+pytest -q
+python -m build
+twine check dist/*
+```
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+---
+
+## License
+
+MIT - see `LICENSE`.

difftriage-0.1.0/README.md

@@ -0,0 +1,212 @@
+# DiffTriage - Pro PR Risk Gating for AI-Generated Code
+
+**difftriage** is an open-source Python library for production-grade pull request risk analysis.
+
+It scores change risk across blast radius, behavior change, test impact, schema/security sensitivity, AI uncertainty, and observability gaps. It then enforces configurable merge policy decisions: `pass`, `review_required`, `block`, and `override_required_review`.
+
+[![PyPI version](https://img.shields.io/pypi/v/difftriage.svg)](https://pypi.org/project/difftriage/)
+[![Python](https://img.shields.io/pypi/pyversions/difftriage.svg)](https://pypi.org/project/difftriage/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Why DiffTriage
+
+Teams shipping more AI-assisted code often face:
+- more regressions in core paths,
+- slower reviews,
+- weak signal-to-noise in large diffs.
+
+DiffTriage provides a deterministic, explainable risk gate with rule-level scoring so teams can move fast without blind merges.
+
+---
+
+## Key Features
+
+- Multi-factor risk model (9 weighted dimensions)
+- Explainable scoring with per-rule contributions
+- Policy decisions: `pass` / `review_required` / `block` / `override_required_review`
+- Confidence bands near threshold boundaries
+- False-positive controls for docs/tests-only changes
+- Override governance with audit-friendly policy flags
+- CI-friendly CLI with multiple output modes
+- GitHub + PyPI release workflows (trusted publishing ready)
+
+---
+
+## Installation
+
+```bash
+pip install difftriage
+```
+
+Requires Python 3.10+.
+
+---
+
+## Quick Start
+
+```bash
+difftriage score \
+  --files-changed 12 \
+  --lines-added 420 \
+  --lines-deleted 130 \
+  --changed-path src/auth/service.py \
+  --changed-path db/migrations/001.sql \
+  --dependencies-changed \
+  --output text
+```
+
+Example result:
+- risk score + level
+- decision + confidence
+- top risk drivers
+- rule scores
+
+---
+
+## CLI Usage
+
+Output formats:
+- `--output text` (default)
+- `--output json`
+- `--output markdown`
+
+Exit semantics:
+- `--exit-mode threshold`:
+  - `0` pass
+  - `2` fail
+- `--exit-mode decision`:
+  - `0` pass
+  - `3` review required
+  - `2` block
+
+Examples:
+
+```bash
+# JSON for automation
+difftriage score --files-changed 8 --lines-added 140 --lines-deleted 35 --changed-path src/payments.py --output json
+
+# Markdown for PR comments
+difftriage score --files-changed 8 --lines-added 140 --lines-deleted 35 --changed-path src/payments.py --output markdown --exit-mode decision
+```
+
+---
+
+## Risk Model
+
+Default weighted dimensions:
+
+- `blast_radius` (0.20)
+- `behavior_change` (0.18)
+- `test_impact` (0.16)
+- `complexity` (0.12)
+- `dependency_config` (0.10)
+- `data_schema` (0.08)
+- `security_privacy` (0.08)
+- `ai_uncertainty` (0.05)
+- `observability_gap` (0.03)
+
+Scoring levels:
+- `0-24`: low
+- `25-49`: medium
+- `50-74`: high
+- `75-100`: critical
+
+---
+
+## Configuration
+
+Create `.difftriage.yml` in repo root:
+
+```yaml
+threshold: 50
+review_threshold: 50
+block_threshold: 75
+enable_confidence_bands: true
+
+weights:
+  blast_radius: 0.20
+  behavior_change: 0.18
+  test_impact: 0.16
+  complexity: 0.12
+  dependency_config: 0.10
+  data_schema: 0.08
+  security_privacy: 0.08
+  ai_uncertainty: 0.05
+  observability_gap: 0.03
+
+rules:
+  risky_path_patterns: ["auth", "billing", "migrations", ".github/workflows", "infra", "config", "permissions", "token"]
+  schema_patterns: ["migrations", "schema", "models", "ddl"]
+  security_patterns: ["auth", "token", "permission", "secret", "privacy"]
+  observability_patterns: ["log", "metrics", "trace"]
+  safe_path_patterns: ["docs/", ".md", "tests/"]
+
+policy:
+  docs_tests_only_max_score: 18
+  safe_change_max_score: 30
+  security_block_score: 70
+  schema_block_score: 78
+  schema_review_score: 45
+  dependency_review_score: 55
+  missing_tests_review_score: 45
+
+override:
+  require_reason_min_length: 12
+  allow_score_override: true
+  allow_schema_override: true
+  allow_dependency_override: true
+  allow_security_override: true
+```
+
+---
+
+## CI Integration
+
+DiffTriage is designed for CI gates:
+
+```bash
+difftriage score ... --output json --exit-mode decision
+```
+
+Recommended policy:
+- treat `review_required` as protected-branch reviewer gate,
+- treat `block` as merge stop,
+- allow audited overrides only for approved emergency paths.
+
+---
+
+## Release and Publishing
+
+This repo includes:
+- `.github/workflows/ci.yml` for tests + build checks
+- `.github/workflows/release.yml` for tag-based PyPI publishing
+
+Publish flow:
+1. Push tag `vX.Y.Z`
+2. Build artifacts
+3. Publish with `pypa/gh-action-pypi-publish` via GitHub OIDC
+
+---
+
+## Local Validation
+
+```bash
+pip install -e . pytest build twine
+pytest -q
+python -m build
+twine check dist/*
+```
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+---
+
+## License
+
+MIT - see `LICENSE`.

difftriage-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling>=1.26.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "difftriage"
+version = "0.1.0"
+description = "PR risk gate for AI-generated code: diff scoring, test impact checks, and merge policy enforcement."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "DiffTriage Contributors" }]
+dependencies = [
+  "pyyaml>=6.0",
+  "typer>=0.12.0",
+]
+
+[project.scripts]
+difftriage = "difftriage.cli:app"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

difftriage-0.1.0/src/difftriage/__init__.py

@@ -0,0 +1,4 @@
+from .scoring import score_pr
+from .models import RiskInput, RiskReport
+
+__all__ = ["score_pr", "RiskInput", "RiskReport"]

difftriage-0.1.0/src/difftriage/cli.py

@@ -0,0 +1,103 @@
+import json
+from dataclasses import asdict
+from typing import Literal
+
+import typer
+
+from difftriage.models import RiskInput
+from difftriage.scoring import score_pr
+
+app = typer.Typer(no_args_is_help=True)
+
+OutputFormat = Literal["text", "json", "markdown"]
+ExitMode = Literal["threshold", "decision"]
+
+
+def _render_text(report: object) -> str:
+    lines = [
+        (
+            f"risk_score={report.score} level={report.level} threshold={report.threshold} "
+            f"passed={report.passed} decision={report.decision} confidence={report.confidence}"
+        ),
+        "top_drivers:",
+    ]
+    for driver in report.drivers:
+        lines.append(f"- {driver}")
+    lines.append("rule_scores:")
+    for rule, val in sorted(report.rule_scores.items(), key=lambda item: item[1], reverse=True):
+        lines.append(f"- {rule}: {val}")
+    return "\n".join(lines)
+
+
+def _render_markdown(report: object) -> str:
+    lines = [
+        "| Metric | Value |",
+        "|---|---|",
+        f"| Risk Score | {report.score} |",
+        f"| Risk Level | {report.level} |",
+        f"| Threshold | {report.threshold} |",
+        f"| Passed | {report.passed} |",
+        f"| Decision | {report.decision} |",
+        f"| Confidence | {report.confidence} |",
+        "",
+        "### Top Drivers",
+    ]
+    for driver in report.drivers:
+        lines.append(f"- {driver}")
+    lines.extend(["", "### Rule Scores", "", "| Rule | Score |", "|---|---:|"])
+    for rule, val in sorted(report.rule_scores.items(), key=lambda item: item[1], reverse=True):
+        lines.append(f"| `{rule}` | {val} |")
+    return "\n".join(lines)
+
+
+def _exit_code(report: object, exit_mode: ExitMode) -> int:
+    if exit_mode == "threshold":
+        return 0 if report.passed else 2
+
+    if report.decision == "pass":
+        return 0
+    if report.decision in {"review_required", "override_required_review"}:
+        return 3
+    return 2
+
+
+@app.command()
+def score(
+    files_changed: int = typer.Option(...),
+    lines_added: int = typer.Option(...),
+    lines_deleted: int = typer.Option(...),
+    changed_path: list[str] = typer.Option([]),
+    tests_changed: bool = typer.Option(False),
+    dependencies_changed: bool = typer.Option(False),
+    ai_uncertainty_hits: int = typer.Option(0),
+    config: str = typer.Option(".difftriage.yml"),
+    threshold: float | None = typer.Option(None),
+    output: OutputFormat = typer.Option("text"),
+    exit_mode: ExitMode = typer.Option("threshold"),
+) -> None:
+    report = score_pr(
+        RiskInput(
+            files_changed=files_changed,
+            lines_added=lines_added,
+            lines_deleted=lines_deleted,
+            changed_paths=changed_path,
+            tests_changed=tests_changed,
+            dependencies_changed=dependencies_changed,
+            ai_uncertainty_hits=ai_uncertainty_hits,
+        ),
+        config_path=config,
+        threshold_override=threshold,
+    )
+
+    if output == "json":
+        typer.echo(json.dumps(asdict(report), indent=2))
+    elif output == "markdown":
+        typer.echo(_render_markdown(report))
+    else:
+        typer.echo(_render_text(report))
+
+    raise typer.Exit(code=_exit_code(report, exit_mode))
+
+
+if __name__ == "__main__":
+    app()

difftriage-0.1.0/src/difftriage/config.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+from copy import deepcopy
+from typing import Any
+
+import yaml
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "threshold": 50,
+    "block_threshold": 75,
+    "review_threshold": 50,
+    "enable_confidence_bands": True,
+    "weights": {
+        "blast_radius": 0.20,
+        "behavior_change": 0.18,
+        "test_impact": 0.16,
+        "complexity": 0.12,
+        "dependency_config": 0.10,
+        "data_schema": 0.08,
+        "security_privacy": 0.08,
+        "ai_uncertainty": 0.05,
+        "observability_gap": 0.03,
+    },
+    "rules": {
+        "risky_path_patterns": ["auth", "billing", "migrations", ".github/workflows", "infra", "config", "permissions", "token"],
+        "schema_patterns": ["migrations", "schema", "models", "ddl"],
+        "security_patterns": ["auth", "token", "permission", "secret", "privacy"],
+        "observability_patterns": ["log", "metrics", "trace"],
+        "safe_path_patterns": ["docs/", ".md", "tests/"],
+        "docs_path_patterns": ["docs/", ".md", ".rst", ".txt", "readme", "changelog", "license"],
+        "test_path_patterns": ["tests/", "test_", "_test.", ".spec.", ".test."],
+    },
+    "policy": {
+        "docs_tests_only_max_score": 18,
+        "docs_tests_only_review_threshold": 70,
+        "safe_change_max_score": 30,
+        "security_block_score": 70,
+        "schema_block_score": 78,
+        "schema_review_score": 45,
+        "dependency_review_score": 55,
+        "missing_tests_review_score": 45,
+    },
+    "override": {
+        "require_reason_min_length": 12,
+        "allow_score_override": True,
+        "allow_schema_override": True,
+        "allow_dependency_override": True,
+        "allow_security_override": True,
+    },
+}
+
+
+def _deep_merge(base: dict[str, Any], updates: dict[str, Any]) -> dict[str, Any]:
+    merged = deepcopy(base)
+    for key, value in updates.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def load_config(path: str | None) -> dict[str, Any]:
+    if not path:
+        return deepcopy(DEFAULT_CONFIG)
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+    except FileNotFoundError:
+        return deepcopy(DEFAULT_CONFIG)
+    return _deep_merge(DEFAULT_CONFIG, data)

difftriage-0.1.0/src/difftriage/models.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class RiskInput:
+    files_changed: int
+    lines_added: int
+    lines_deleted: int
+    changed_paths: list[str] = field(default_factory=list)
+    tests_changed: bool = False
+    dependencies_changed: bool = False
+    ai_uncertainty_hits: int = 0
+    ai_generated_ratio: float = 0.0
+    override_approved: bool = False
+    override_reason: str = ""
+
+
+@dataclass
+class RiskReport:
+    score: float
+    threshold: float
+    passed: bool
+    level: str
+    drivers: list[str]
+    decision: str
+    confidence: str
+    rule_scores: dict[str, float]
+    review_threshold: float = 50.0
+    block_threshold: float = 75.0
+    rule_breakdown: list[dict[str, Any]] = field(default_factory=list)
+    policy_flags: list[str] = field(default_factory=list)
+    override_gates: dict[str, Any] = field(default_factory=dict)

difftriage-0.1.0/src/difftriage/scoring.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+from typing import Any
+
+from difftriage.config import load_config
+from difftriage.models import RiskInput, RiskReport
+
+
+def _clamp(value: float, low: float = 0.0, high: float = 100.0) -> float:
+    return max(low, min(high, value))
+
+
+def _risk_level(score: float) -> str:
+    if score >= 75:
+        return "critical"
+    if score >= 50:
+        return "high"
+    if score >= 25:
+        return "medium"
+    return "low"
+
+
+def _confidence(score: float, review_threshold: float, block_threshold: float) -> str:
+    # Scores near enforcement edges are inherently less certain.
+    band = 5.0
+    if abs(score - review_threshold) <= band or abs(score - block_threshold) <= band:
+        return "medium"
+    return "high"
+
+
+def _matches(path: str, patterns: list[str]) -> bool:
+    return any(pattern.lower() in path for pattern in patterns)
+
+
+def _path_profile(paths: list[str], rules: dict[str, Any], files_changed: int) -> dict[str, Any]:
+    lowered = [p.replace("\\", "/").lower() for p in paths]
+    file_count = max(files_changed, len(lowered), 1)
+    docs_patterns = rules["docs_path_patterns"]
+    test_patterns = rules["test_path_patterns"]
+    safe_patterns = rules["safe_path_patterns"]
+
+    docs = [p for p in lowered if _matches(p, docs_patterns)]
+    tests = [p for p in lowered if _matches(p, test_patterns)]
+    safe = [p for p in lowered if _matches(p, safe_patterns) or p in docs or p in tests]
+    risky = [p for p in lowered if _matches(p, rules["risky_path_patterns"])]
+    schema = [p for p in lowered if _matches(p, rules["schema_patterns"])]
+    security = [p for p in lowered if _matches(p, rules["security_patterns"])]
+    observability = [p for p in lowered if _matches(p, rules["observability_patterns"])]
+
+    docs_or_tests_only = bool(lowered) and len(set(docs + tests + safe)) == len(set(lowered))
+
+    return {
+        "paths": lowered,
+        "file_count": file_count,
+        "docs_count": len(set(docs)),
+        "tests_count": len(set(tests)),
+        "safe_count": len(set(safe)),
+        "non_safe_count": max(0, file_count - len(set(safe))),
+        "risky": risky,
+        "schema": schema,
+        "security": security,
+        "observability": observability,
+        "docs_or_tests_only": docs_or_tests_only,
+        "risky_ratio": len(set(risky)) / file_count,
+    }
+
+
+def _breakdown_item(
+    name: str,
+    score: float,
+    weight: float,
+    rationale: str,
+    evidence: list[str] | None = None,
+) -> dict[str, Any]:
+    return {
+        "rule": name,
+        "score": round(score, 2),
+        "weight": weight,
+        "contribution": round(score * weight, 2),
+        "rationale": rationale,
+        "evidence": evidence or [],
+    }
+
+
+def _has_valid_override(risk_input: RiskInput, override_config: dict[str, Any]) -> bool:
+    reason = risk_input.override_reason.strip()
+    min_length = int(override_config.get("require_reason_min_length", 12))
+    return risk_input.override_approved and len(reason) >= min_length
+
+
+def _override_satisfies(reason: str, risk_input: RiskInput, override_config: dict[str, Any]) -> bool:
+    if not risk_input.override_approved:
+        return False
+    if reason == "schema":
+        return bool(override_config.get("allow_schema_override", True))
+    if reason == "security":
+        return bool(override_config.get("allow_security_override", True)) and _has_valid_override(risk_input, override_config)
+    if reason == "score":
+        return bool(override_config.get("allow_score_override", True)) and _has_valid_override(risk_input, override_config)
+    if reason == "dependency":
+        return bool(override_config.get("allow_dependency_override", True)) and _has_valid_override(risk_input, override_config)
+    return False
+
+
+def score_pr(risk_input: RiskInput, config_path: str | None = None, threshold_override: float | None = None) -> RiskReport:
+    config = load_config(config_path)
+    weights = config["weights"]
+    rules = config["rules"]
+    policy = config["policy"]
+    override_config = config["override"]
+
+    profile = _path_profile(risk_input.changed_paths, rules, risk_input.files_changed)
+    file_count = profile["file_count"]
+    non_safe_files = profile["non_safe_count"]
+    churn = risk_input.lines_added + risk_input.lines_deleted
+    docs_tests_only = profile["docs_or_tests_only"]
+
+    code_file_factor = 0.15 if docs_tests_only else 1.0
+    churn_factor = 0.12 if docs_tests_only else 1.0
+
+    blast_radius = _clamp((non_safe_files * 7) + ((churn * churn_factor) / 28))
+    behavior_change = _clamp((non_safe_files * 6) + ((risk_input.lines_added * churn_factor) / 32))
+    complexity = _clamp((file_count * 3.5 * code_file_factor) + ((churn * churn_factor) / 24))
+
+    schema_hits = len(set(profile["schema"]))
+    security_hits = len(set(profile["security"]))
+    observability_hits = len(set(profile["observability"]))
+    risky_ratio = profile["risky_ratio"]
+
+    missing_tests = not risk_input.tests_changed and not docs_tests_only
+    test_impact = 0.0 if not missing_tests else _clamp(32 + (complexity * 0.45) + (risky_ratio * 22))
+    dependency_config = 65.0 if risk_input.dependencies_changed else 0.0
+    data_schema = _clamp(schema_hits * 32)
+    security_privacy = _clamp(security_hits * 28)
+    ai_uncertainty = _clamp((risk_input.ai_uncertainty_hits * 12) + (risk_input.ai_generated_ratio * 25))
+    observability_gap = 0.0 if observability_hits > 0 or docs_tests_only else _clamp((risky_ratio * 35) + (8 if non_safe_files > 4 else 0))
+
+    rule_scores = {
+        "blast_radius": round(blast_radius, 2),
+        "behavior_change": round(behavior_change, 2),
+        "test_impact": round(test_impact, 2),
+        "complexity": round(complexity, 2),
+        "dependency_config": round(dependency_config, 2),
+        "data_schema": round(data_schema, 2),
+        "security_privacy": round(security_privacy, 2),
+        "ai_uncertainty": round(ai_uncertainty, 2),
+        "observability_gap": round(observability_gap, 2),
+    }
+
+    raw_score = sum(rule_scores[name] * weights[name] for name in weights)
+    score_cap = None
+    policy_flags: list[str] = []
+    if docs_tests_only:
+        score_cap = float(policy["docs_tests_only_max_score"])
+        policy_flags.append("docs_tests_only_low_false_positive_cap")
+    elif profile["safe_count"] and profile["safe_count"] >= file_count * 0.75:
+        score_cap = float(policy["safe_change_max_score"])
+        policy_flags.append("mostly_safe_paths_score_cap")
+
+    score = min(raw_score, score_cap) if score_cap is not None else raw_score
+
+    threshold = threshold_override if threshold_override is not None else float(config["threshold"])
+    review_threshold = float(config["review_threshold"])
+    block_threshold = float(config["block_threshold"])
+
+    rule_breakdown = [
+        _breakdown_item(
+            "blast_radius",
+            blast_radius,
+            weights["blast_radius"],
+            f"{non_safe_files} non-safe file(s), {churn} total changed line(s)",
+        ),
+        _breakdown_item(
+            "behavior_change",
+            behavior_change,
+            weights["behavior_change"],
+            f"{risk_input.lines_added} added line(s) across implementation-sensitive paths",
+        ),
+        _breakdown_item(
+            "test_impact",
+            test_impact,
+            weights["test_impact"],
+            "Tests changed or docs/tests-only change" if not missing_tests else "Implementation change without test changes",
+        ),
+        _breakdown_item(
+            "complexity",
+            complexity,
+            weights["complexity"],
+            f"{file_count} file(s), churn factor adjusted for docs/tests-only safety",
+        ),
+        _breakdown_item(
+            "dependency_config",
+            dependency_config,
+            weights["dependency_config"],
+            "Dependency/config change declared" if risk_input.dependencies_changed else "No dependency change declared",
+        ),
+        _breakdown_item(
+            "data_schema",
+            data_schema,
+            weights["data_schema"],
+            f"{schema_hits} schema-sensitive path hit(s)",
+            profile["schema"][:5],
+        ),
+        _breakdown_item(
+            "security_privacy",
+            security_privacy,
+            weights["security_privacy"],
+            f"{security_hits} security/privacy path hit(s)",
+            profile["security"][:5],
+        ),
+        _breakdown_item(
+            "ai_uncertainty",
+            ai_uncertainty,
+            weights["ai_uncertainty"],
+            f"{risk_input.ai_uncertainty_hits} uncertainty hit(s), generated ratio {risk_input.ai_generated_ratio}",
+        ),
+        _breakdown_item(
+            "observability_gap",
+            observability_gap,
+            weights["observability_gap"],
+            "Risky code path has observability coverage" if observability_gap == 0 else "Risky code path without observability signal",
+        ),
+    ]
+
+    if score_cap is not None and raw_score > score:
+        policy_flags.append(f"score_capped_from_{round(raw_score, 2)}_to_{round(score, 2)}")
+
+    hard_blocks: list[str] = []
+    review_reasons: list[str] = []
+    overrideable_reasons: list[str] = []
+
+    if score >= block_threshold:
+        hard_blocks.append("score_at_or_above_block_threshold")
+        overrideable_reasons.append("score")
+    elif score >= review_threshold:
+        review_reasons.append("score_at_or_above_review_threshold")
+
+    if security_privacy >= float(policy["security_block_score"]):
+        hard_blocks.append("security_privacy_gate")
+        if bool(override_config.get("allow_security_override", False)):
+            overrideable_reasons.append("security")
+    if data_schema >= float(policy["schema_block_score"]):
+        hard_blocks.append("schema_gate")
+        if bool(override_config.get("allow_schema_override", True)):
+            overrideable_reasons.append("schema")
+    elif data_schema >= float(policy["schema_review_score"]):
+        review_reasons.append("schema_review_gate")
+    if dependency_config >= float(policy["dependency_review_score"]):
+        review_reasons.append("dependency_or_config_review_gate")
+    if test_impact >= float(policy["missing_tests_review_score"]):
+        review_reasons.append("missing_tests_review_gate")
+
+    valid_override = _has_valid_override(risk_input, override_config)
+    block_reason_map = {
+        "score_at_or_above_block_threshold": "score",
+        "schema_gate": "schema",
+        "security_privacy_gate": "security",
+    }
+    non_overrideable_blocks = [
+        reason
+        for reason in hard_blocks
+        if block_reason_map.get(reason) not in overrideable_reasons
+    ]
+    unsatisfied_override_blocks = [
+        reason
+        for reason in hard_blocks
+        if reason not in non_overrideable_blocks and not _override_satisfies(block_reason_map[reason], risk_input, override_config)
+    ]
+
+    if hard_blocks and not non_overrideable_blocks and not unsatisfied_override_blocks:
+        if hard_blocks == ["schema_gate"] and not review_reasons and score < review_threshold:
+            decision = "pass"
+            policy_flags.append("valid_schema_override_downgraded_block_to_pass")
+        else:
+            decision = "override_required_review"
+            policy_flags.append("valid_override_downgraded_block_to_review")
+    elif hard_blocks:
+        decision = "block"
+    elif review_reasons:
+        decision = "review_required"
+    else:
+        decision = "pass"
+
+    if hard_blocks:
+        policy_flags.extend(hard_blocks)
+    if review_reasons:
+        policy_flags.extend(review_reasons)
+    if risk_input.override_approved and unsatisfied_override_blocks:
+        policy_flags.append("override_missing_required_reason")
+
+    level = _risk_level(score)
+    conf = _confidence(score, review_threshold, block_threshold) if config.get("enable_confidence_bands", True) else "high"
+
+    drivers = []
+    for item in sorted(rule_breakdown, key=lambda x: x["contribution"], reverse=True)[:4]:
+        if item["score"] > 0:
+            drivers.append(f"{item['rule']}: {item['score']} ({item['rationale']})")
+    if not drivers:
+        drivers.append("No major risk driver detected")
+
+    passed = decision == "pass" and score < threshold
+
+    return RiskReport(
+        score=round(score, 2),
+        threshold=threshold,
+        passed=passed,
+        level=level,
+        drivers=drivers,
+        decision=decision,
+        confidence=conf,
+        rule_scores=rule_scores,
+        review_threshold=review_threshold,
+        block_threshold=block_threshold,
+        rule_breakdown=rule_breakdown,
+        policy_flags=policy_flags,
+        override_gates={
+            "override_requested": risk_input.override_approved,
+            "override_reason_provided": bool(risk_input.override_reason.strip()),
+            "override_valid": valid_override,
+            "overrideable_reasons": sorted(set(overrideable_reasons)),
+            "non_overrideable_blocks": non_overrideable_blocks,
+            "unsatisfied_override_blocks": unsatisfied_override_blocks,
+        },
+    )

difftriage-0.1.0/tests/test_scoring.py

@@ -0,0 +1,242 @@
+from difftriage.models import RiskInput
+from difftriage.scoring import score_pr
+
+
+def test_high_risk_without_tests_blocks() -> None:
+    report = score_pr(
+        RiskInput(
+            files_changed=20,
+            lines_added=800,
+            lines_deleted=200,
+            changed_paths=["src/auth/service.py", "src/billing/charge.py", "db/migrations/001.sql", ".github/workflows/ci.yml"],
+            tests_changed=False,
+            dependencies_changed=True,
+            ai_uncertainty_hits=2,
+            ai_generated_ratio=0.7,
+        ),
+        threshold_override=50,
+    )
+    assert report.decision == "block"
+    assert report.passed is False
+
+
+def test_low_risk_with_tests_passes() -> None:
+    report = score_pr(
+        RiskInput(
+            files_changed=2,
+            lines_added=20,
+            lines_deleted=4,
+            changed_paths=["src/utils/format.py", "tests/test_format.py"],
+            tests_changed=True,
+        ),
+        threshold_override=50,
+    )
+    assert report.decision == "pass"
+    assert report.passed is True
+
+
+def test_docs_only_reduces_false_positive() -> None:
+    report = score_pr(
+        RiskInput(
+            files_changed=3,
+            lines_added=120,
+            lines_deleted=30,
+            changed_paths=["docs/guide.md", "README.md", "docs/usage.md"],
+            tests_changed=False,
+        )
+    )
+    assert report.level in {"low", "medium"}
+
+
+def test_override_changes_block_to_review_required() -> None:
+    base = RiskInput(
+        files_changed=12,
+        lines_added=400,
+        lines_deleted=120,
+        changed_paths=["src/auth/token.py", "db/schema.sql"],
+        tests_changed=False,
+    )
+    blocked = score_pr(base)
+    assert blocked.decision in {"block", "review_required"}
+
+    override = score_pr(
+        RiskInput(**{**base.__dict__, "override_approved": True, "override_reason": "approved by code owners"})
+    )
+    assert override.decision in {"override_required_review", "review_required", "pass"}
+
+
+def test_decision_review_required_at_exact_review_threshold_and_confidence_band() -> None:
+    # Force a deterministic score of exactly 50.0 via clamping of core rule scores.
+    # With default config, review_threshold is 50.
+    report = score_pr(
+        RiskInput(
+            files_changed=1,
+            lines_added=4000,
+            lines_deleted=0,
+            changed_paths=["src/core/worker.py"],
+            tests_changed=True,  # keep test_impact at 0 for determinism
+        )
+    )
+    assert report.score == 50.0
+    assert report.decision == "review_required"
+    assert report.passed is False
+    # Confidence band is +/- 5 around the review_threshold.
+    assert report.confidence == "medium"
+
+
+def test_threshold_override_only_affects_passed_not_decision() -> None:
+    # Craft a pass decision with a stable score around ~43, then tighten only the pass threshold.
+    base = score_pr(
+        RiskInput(
+            files_changed=1,
+            lines_added=2500,
+            lines_deleted=0,
+            changed_paths=["src/core/worker.py"],
+            tests_changed=True,
+        )
+    )
+    assert base.decision == "pass"
+    assert base.passed is True
+    assert base.score > 40.0
+
+    tightened = score_pr(
+        RiskInput(
+            files_changed=1,
+            lines_added=2500,
+            lines_deleted=0,
+            changed_paths=["src/core/worker.py"],
+            tests_changed=True,
+        ),
+        threshold_override=40,
+    )
+    assert tightened.decision == "pass"
+    assert tightened.score == base.score
+    assert tightened.threshold == 40
+    assert tightened.passed is False
+
+
+def test_security_privacy_hard_block_and_override_required_review() -> None:
+    # security_privacy = 22 * security_hits; 4 "auth" paths -> 88 -> hard block.
+    blocked = score_pr(
+        RiskInput(
+            files_changed=4,
+            lines_added=0,
+            lines_deleted=0,
+            changed_paths=[
+                "src/auth/a.py",
+                "src/auth/b.py",
+                "src/auth/c.py",
+                "src/auth/d.py",
+            ],
+            tests_changed=True,
+        )
+    )
+    assert blocked.rule_scores["security_privacy"] >= 70
+    assert blocked.decision == "block"
+    assert blocked.passed is False
+
+    overridden = score_pr(
+        RiskInput(
+            files_changed=4,
+            lines_added=0,
+            lines_deleted=0,
+            changed_paths=[
+                "src/auth/a.py",
+                "src/auth/b.py",
+                "src/auth/c.py",
+                "src/auth/d.py",
+            ],
+            tests_changed=True,
+            override_approved=True,
+            override_reason="Emergency fix; follow-up review required",
+        )
+    )
+    assert overridden.rule_scores["security_privacy"] >= 70
+    assert overridden.decision == "override_required_review"
+    assert overridden.passed is False
+
+
+def test_schema_hard_block_can_be_avoided_with_override_approval() -> None:
+    # Schema hits can hard-block, but a valid schema override can downgrade a schema-only block
+    # all the way to a pass when nothing else triggers review and the score is below the review threshold.
+    no_override = score_pr(
+        RiskInput(
+            files_changed=3,
+            lines_added=0,
+            lines_deleted=0,
+            changed_paths=["migrations/001.sql", "migrations/002.sql", "migrations/003.sql"],
+            tests_changed=True,
+        )
+    )
+    assert no_override.rule_scores["data_schema"] >= 70
+    assert no_override.decision == "block"
+    assert no_override.passed is False
+
+    approved = score_pr(
+        RiskInput(
+            files_changed=3,
+            lines_added=0,
+            lines_deleted=0,
+            changed_paths=["migrations/001.sql", "migrations/002.sql", "migrations/003.sql"],
+            tests_changed=True,
+            override_approved=True,
+            override_reason="Approved for emergency rollout",
+        )
+    )
+    assert approved.rule_scores["data_schema"] >= 70
+    assert approved.decision == "pass"
+    assert approved.passed is True
+    assert "valid_schema_override_downgraded_block_to_pass" in approved.policy_flags
+
+
+def test_confidence_bands_can_be_disabled_via_config_injection(monkeypatch) -> None:
+    # load_config() does not currently merge enable_confidence_bands from file,
+    # so cover this branch by injecting a config with bands disabled.
+    import difftriage.scoring as scoring
+
+    real_load = scoring.load_config
+
+    def fake_load_config(_path):
+        cfg = real_load(None)
+        cfg["enable_confidence_bands"] = False
+        return cfg
+
+    monkeypatch.setattr(scoring, "load_config", fake_load_config)
+
+    report = scoring.score_pr(
+        RiskInput(
+            files_changed=1,
+            lines_added=4000,
+            lines_deleted=0,
+            changed_paths=["src/core/worker.py"],
+            tests_changed=True,
+        )
+    )
+    assert report.score == 50.0
+    assert report.confidence == "high"
+
+
+def test_safe_paths_reduce_false_positive_risk() -> None:
+    # Same churn and file_count, but safe paths reduce non_safe_files -> lower blast_radius/behavior_change -> lower score.
+    non_safe = score_pr(
+        RiskInput(
+            files_changed=3,
+            lines_added=300,
+            lines_deleted=0,
+            changed_paths=["src/core/a.py", "src/core/b.py", "src/core/c.py"],
+            tests_changed=False,
+        )
+    )
+    safe = score_pr(
+        RiskInput(
+            files_changed=3,
+            lines_added=300,
+            lines_deleted=0,
+            changed_paths=["DOCS/a.MD", "docs/b.md", "docs/c.md"],  # case-insensitive safe hit
+            tests_changed=False,
+        )
+    )
+
+    assert safe.rule_scores["blast_radius"] < non_safe.rule_scores["blast_radius"]
+    assert safe.rule_scores["behavior_change"] < non_safe.rule_scores["behavior_change"]
+    assert safe.score < non_safe.score