diff-contract 0.1.1__py3-none-any.whl

diff_contract/__init__.py

@@ -0,0 +1,7 @@
+"""diff-contract — deterministic guardrails for ai-generated diffs."""
+
+from diff_contract.engine import GitDiffError
+
+__version__ = "0.1.1"
+
+__all__ = ["__version__", "GitDiffError"]

diff_contract/cli.py

@@ -0,0 +1,436 @@
+"""CLI entry point for diff-contract."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from diff_contract import __version__
+from diff_contract.contract import load_contract
+from diff_contract.engine import (
+    DiffCalculator,
+    GitDiffError,
+    RulesEngine,
+    ViolationSeverity,
+)
+from diff_contract.sarif import violations_to_sarif
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="diff-contract",
+        description="Deterministic guardrails for AI-generated diffs",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # `check` command
+    check_parser = subparsers.add_parser("check", help="Check diff against contract")
+    check_parser.add_argument(
+        "--contract",
+        type=Path,
+        default=Path(".diffcontract.yml"),
+        help="Path to .diffcontract.yml (default: .diffcontract.yml)",
+    )
+    check_parser.add_argument(
+        "--base",
+        default="main",
+        help="Base branch to diff against (default: main)",
+    )
+    check_parser.add_argument(
+        "--output",
+        choices=["json", "text"],
+        default="text",
+        help="Output format (default: text)",
+    )
+    check_parser.add_argument(
+        "--sarif",
+        action="store_true",
+        help="Output SARIF 2.1.0 format for GitHub Code Scanning",
+    )
+    check_parser.add_argument(
+        "--files",
+        nargs="*",
+        help="Specific files to check (instead of git diff)",
+    )
+
+    # `validate` command (no git dependency)
+    validate_parser = subparsers.add_parser(
+        "validate", help="Validate files against contract (no git required)"
+    )
+    validate_parser.add_argument(
+        "--contract",
+        type=Path,
+        default=Path(".diffcontract.yml"),
+        help="Path to .diffcontract.yml (default: .diffcontract.yml)",
+    )
+    validate_parser.add_argument(
+        "--files",
+        nargs="*",
+        help="Files to validate",
+    )
+    validate_parser.add_argument(
+        "--from-stdin",
+        action="store_true",
+        help="Read file list from stdin (one per line)",
+    )
+    validate_parser.add_argument(
+        "--output",
+        choices=["json", "text"],
+        default="text",
+        help="Output format (default: text)",
+    )
+    validate_parser.add_argument(
+        "--sarif",
+        action="store_true",
+        help="Output SARIF 2.1.0 format for GitHub Code Scanning",
+    )
+
+    # `init` command
+    init_parser = subparsers.add_parser("init", help="Create a sample .diffcontract.yml")
+    init_parser.add_argument(
+        "--template",
+        choices=["python", "react", "django", "rust", "docs"],
+        default="python",
+        help="Template type (default: python)",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "check":
+        return _cmd_check(args)
+    elif args.command == "validate":
+        return _cmd_validate(args)
+    elif args.command == "init":
+        return _cmd_init(args.template)
+    else:
+        parser.print_help()
+        return 1
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    """Execute the check command."""
+    # Load contract
+    contract_path: Path = args.contract
+    if not contract_path.exists():
+        print(f"ERROR: Contract not found: {contract_path}", file=sys.stderr)
+        return 1
+
+    contract = load_contract(contract_path)
+
+    # Get changed files
+    if args.files:
+        changed_files: list = list(args.files)
+    else:
+        calc = DiffCalculator(base_branch=args.base)
+        try:
+            changed_files = calc.get_changed_files()
+        except GitDiffError as e:
+            print(f"ERROR: {e}", file=sys.stderr)
+            return 1
+
+    # Validate
+    engine = RulesEngine(contract.rules)
+    violations = engine.check(changed_files)
+
+    # Output
+    if args.sarif:
+        sarif_doc = violations_to_sarif(violations)
+        print(json.dumps(sarif_doc, indent=2))
+    elif args.output == "json":
+        result = {
+            "clean": len(violations) == 0,
+            "block_count": sum(1 for v in violations if v.severity == ViolationSeverity.BLOCK),
+            "warn_count": sum(1 for v in violations if v.severity == ViolationSeverity.WARN),
+            "violations": [
+                {
+                    "file": v.file,
+                    "severity": v.severity.value,
+                    "rule": v.rule,
+                    "message": v.message,
+                }
+                for v in violations
+            ],
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        if not violations:
+            print("✓ Diff is clean — no contract violations")
+        else:
+            print(f"✗ {len(violations)} violation(s):")
+            for v in violations:
+                icon = "🔴" if v.severity == ViolationSeverity.BLOCK else "🟡"
+                print(f"  {icon} [{v.severity.value.upper()}] {v.message}")
+
+    # Exit code
+    has_block = any(v.severity == ViolationSeverity.BLOCK for v in violations)
+    has_warn = any(v.severity == ViolationSeverity.WARN for v in violations)
+    if has_block:
+        return 1
+    elif has_warn:
+        return 2
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    """Execute the validate command (no git dependency)."""
+    contract_path: Path = args.contract
+    if not contract_path.exists():
+        print(f"ERROR: Contract not found: {contract_path}", file=sys.stderr)
+        return 1
+
+    contract = load_contract(contract_path)
+
+    # Get changed files
+    if args.from_stdin:
+        changed_files = [line.strip() for line in sys.stdin if line.strip()]
+    elif args.files:
+        changed_files = list(args.files)
+    else:
+        print("ERROR: Provide --files or --from-stdin", file=sys.stderr)
+        return 1
+
+    # Validate
+    engine = RulesEngine(contract.rules)
+    violations = engine.check(changed_files)
+
+    # Output
+    if args.sarif:
+        sarif_doc = violations_to_sarif(violations)
+        print(json.dumps(sarif_doc, indent=2))
+    elif args.output == "json":
+        result = {
+            "clean": len(violations) == 0,
+            "block_count": sum(1 for v in violations if v.severity == ViolationSeverity.BLOCK),
+            "warn_count": sum(1 for v in violations if v.severity == ViolationSeverity.WARN),
+            "violations": [
+                {
+                    "file": v.file,
+                    "severity": v.severity.value,
+                    "rule": v.rule,
+                    "message": v.message,
+                }
+                for v in violations
+            ],
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        if not violations:
+            print("✓ Diff is clean — no contract violations")
+        else:
+            print(f"✗ {len(violations)} violation(s):")
+            for v in violations:
+                icon = "🔴" if v.severity == ViolationSeverity.BLOCK else "🟡"
+                print(f"  {icon} [{v.severity.value.upper()}] {v.message}")
+
+    # Exit codes: 0 clean, 1 block, 2 warn
+    has_block = any(v.severity == ViolationSeverity.BLOCK for v in violations)
+    has_warn = any(v.severity == ViolationSeverity.WARN for v in violations)
+    if has_block:
+        return 1
+    elif has_warn:
+        return 2
+    return 0
+
+
+def _cmd_init(template_type: str = "python") -> int:
+    """Create a sample .diffcontract.yml from a template."""
+    template = _TEMPLATES.get(template_type, _TEMPLATES["python"])
+    path = Path(".diffcontract.yml")
+    if path.exists():
+        print(f"WARNING: {path} already exists — not overwriting", file=sys.stderr)
+        return 1
+    path.write_text(template)
+    print(f"✓ Created {path} (template: {template_type})")
+    return 0
+
+
+_TEMPLATES = {
+    "python": """# .diffcontract.yml — Python project contract
+version: 1
+
+rules:
+  # Block changes to critical infrastructure
+  - name: "Protect CI/CD configs"
+    deny:
+      - ".github/workflows/*.yml"
+      - "Dockerfile"
+      - "docker-compose.yml"
+    on_violation: block
+
+  # Allow feature work with limits
+  - name: "Feature development"
+    allow:
+      - "src/features/**"
+      - "tests/features/**"
+    max_files: 15
+    max_lines: 400
+    on_violation: block
+
+  # Warn on large diffs
+  - name: "Large diff warning"
+    max_files: 20
+    max_lines: 500
+    on_violation: warn
+""",
+    "react": """# React/Next.js project contract
+version: 1
+
+rules:
+  - name: "Protect CI/CD configs"
+    deny:
+      - ".github/workflows/*.yml"
+      - "Dockerfile"
+      - "docker-compose.yml"
+    on_violation: block
+
+  - name: "Protect root config"
+    deny:
+      - "package.json"
+      - "package-lock.json"
+      - "tsconfig.json"
+      - "next.config.*"
+      - ".env*"
+    on_violation: block
+
+  - name: "Feature development"
+    allow:
+      - "app/**"
+      - "components/**"
+      - "lib/**"
+      - "pages/**"
+      - "src/**"
+      - "styles/**"
+      - "public/**"
+    max_files: 20
+    max_lines: 600
+    on_violation: block
+
+  - name: "Test updates"
+    allow:
+      - "tests/**"
+      - "__tests__/**"
+      - "*.test.*"
+      - "*.spec.*"
+    max_files: 10
+    max_lines: 300
+    on_violation: warn
+""",
+    "django": """# Django project contract
+version: 1
+
+rules:
+  - name: "Protect deployment configs"
+    deny:
+      - "Dockerfile"
+      - "docker-compose.yml"
+      - ".github/workflows/*.yml"
+      - "requirements/base.txt"
+    on_violation: block
+
+  - name: "Protect root config"
+    deny:
+      - "manage.py"
+      - "project/settings/*.py"
+      - "pyproject.toml"
+      - "requirements/*.txt"
+    on_violation: block
+
+  - name: "Feature development"
+    allow:
+      - "apps/**"
+      - "templates/**"
+      - "static/**"
+      - "media/**"
+    max_files: 15
+    max_lines: 500
+    on_violation: block
+
+  - name: "Test updates"
+    allow:
+      - "tests/**"
+      - "**/tests.py"
+      - "**/test_*.py"
+    max_files: 10
+    max_lines: 200
+    on_violation: warn
+""",
+    "rust": """# Rust workspace contract
+version: 1
+
+rules:
+  - name: "Protect CI/CD configs"
+    deny:
+      - ".github/workflows/*.yml"
+      - "Dockerfile"
+      - "docker-compose.yml"
+      - "rust-toolchain.toml"
+    on_violation: block
+
+  - name: "Protect workspace config"
+    deny:
+      - "Cargo.toml"
+      - "Cargo.lock"
+      - "deny.toml"
+      - "clippy.toml"
+      - "rustfmt.toml"
+    on_violation: block
+
+  - name: "Feature development"
+    allow:
+      - "crates/**"
+      - "src/**"
+      - "tests/**"
+      - "benches/**"
+      - "examples/**"
+    max_files: 15
+    max_lines: 500
+    on_violation: block
+
+  - name: "Test updates"
+    allow:
+      - "tests/**"
+      - "**/tests/*.rs"
+      - "**/tests/**/*.rs"
+      - "benches/**"
+    max_files: 10
+    max_lines: 200
+    on_violation: warn
+""",
+    "docs": """# Documentation-only project contract
+version: 1
+
+rules:
+  - name: "Block source code changes"
+    deny:
+      - "src/**"
+      - "lib/**"
+      - "app/**"
+      - "packages/**"
+      - "*.py"
+      - "*.js"
+      - "*.ts"
+      - "*.rs"
+      - "*.go"
+    on_violation: block
+
+  - name: "Documentation updates"
+    allow:
+      - "docs/**"
+      - "*.md"
+      - "*.rst"
+      - "CHANGELOG*"
+      - "LICENSE*"
+      - "README*"
+    max_files: 30
+    max_lines: 1000
+    on_violation: block
+""",
+}
+
+
+if __name__ == "__main__":
+    sys.exit(main())

diff_contract/contract.py

@@ -0,0 +1,95 @@
+"""Contract parser — reads and validates .diffcontract.yml files."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class ViolationSeverity(enum.Enum):
+    BLOCK = "block"
+    WARN = "warn"
+    INFO = "info"
+
+
+@dataclass(frozen=True)
+class ContractRule:
+    name: str
+    allow: tuple[str, ...] = ()
+    deny: tuple[str, ...] = ()
+    on_violation: ViolationSeverity = ViolationSeverity.BLOCK
+    max_files: int | None = None
+    max_lines: int | None = None
+
+    def matches_allow(self, file_path: str) -> bool:
+        """Return True if file matches any allow glob."""
+        import fnmatch
+
+        return any(fnmatch.fnmatch(file_path, pattern) for pattern in self.allow)
+
+    def matches_deny(self, file_path: str) -> bool:
+        """Return True if file matches any deny glob."""
+        import fnmatch
+
+        return any(fnmatch.fnmatch(file_path, pattern) for pattern in self.deny)
+
+
+@dataclass(frozen=True)
+class Contract:
+    version: int
+    rules: tuple[ContractRule, ...] = ()
+
+
+class ContractParser:
+    """Parse contract from YAML dict."""
+
+    def parse(self, data: dict[str, Any]) -> Contract:
+        version = data.get("version", 1)
+        raw_rules = data.get("rules", [])
+        rules: list[ContractRule] = []
+        for i, raw_rule in enumerate(raw_rules):
+            rule = self._parse_rule(raw_rule, index=i)
+            rules.append(rule)
+        return Contract(version=version, rules=tuple(rules))
+
+    def _parse_rule(self, raw: dict[str, Any], index: int) -> ContractRule:
+        name = raw.get("name", f"rule-{index}")
+        severity_str = raw.get("on_violation", "block")
+        try:
+            severity = ViolationSeverity(severity_str)
+        except ValueError:
+            valid = [s.value for s in ViolationSeverity]
+            raise ValueError(
+                f"Invalid on_violation value '{severity_str}' at rule {index}. "
+                f"Valid values: {valid}"
+            )
+
+        allow = tuple(raw.get("allow", []))
+        deny = tuple(raw.get("deny", []))
+        max_files = raw.get("max_files")
+        max_lines = raw.get("max_lines")
+
+        return ContractRule(
+            name=name,
+            allow=allow,
+            deny=deny,
+            on_violation=severity,
+            max_files=max_files,
+            max_lines=max_lines,
+        )
+
+    def parse_file(self, path: Path) -> Contract:
+        """Parse contract from YAML file."""
+        text = path.read_text()
+        data = yaml.safe_load(text) or {}
+        return self.parse(data)
+
+
+def load_contract(path: Path) -> Contract:
+    """Convenience: load contract from path."""
+    parser = ContractParser()
+    return parser.parse_file(path)

diff_contract/engine.py

@@ -0,0 +1,199 @@
+"""Rules engine — validates diffs against contracts."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence, Union
+
+from diff_contract.contract import Contract, ContractRule, ViolationSeverity
+
+
+@dataclass(frozen=True)
+class Violation:
+    file: str
+    severity: ViolationSeverity
+    rule: str
+    message: str
+
+
+# A file entry can be a raw path (from --files CLI arg) or a change dict
+FileEntry = Union[str, dict]
+
+
+def _extract_path(entry: FileEntry) -> str:
+    """Extract file path from a FileEntry (str or dict)."""
+    if isinstance(entry, dict):
+        return entry.get("path", "")
+    return entry
+
+
+def _extract_lines(entry: FileEntry) -> int:
+    """Extract changed line count from a FileEntry."""
+    if isinstance(entry, dict):
+        return entry.get("lines", 0)
+    return 0
+
+
+class RulesEngine:
+    """Validate a list of changed files against contract rules."""
+
+    def __init__(self, rules: Sequence[ContractRule]) -> None:
+        self.rules = list(rules)
+
+    def check(self, changed_files: Sequence[FileEntry]) -> list[Violation]:
+        """Check changed files against all rules.
+
+        All rules are evaluated for each file. Deny rules take precedence
+        over allow rules — if any deny rule matches, the file is blocked.
+        """
+        violations: list[Violation] = []
+        for file in changed_files:
+            path = _extract_path(file)
+            file_violations: list[Violation] = []
+            has_deny = False
+            for rule in self.rules:
+                v = self._check_file(path, rule)
+                if v is not None:
+                    file_violations.append(v)
+                    if v.severity == ViolationSeverity.BLOCK:
+                        has_deny = True
+            # Deny rules take precedence — if any deny matched, report only denies
+            if has_deny:
+                violations.extend(v for v in file_violations if v.severity == ViolationSeverity.BLOCK)
+            else:
+                violations.extend(file_violations)
+        # Check aggregate rules (max_files, max_lines)
+        violations.extend(self._check_aggregate_rules(changed_files))
+        return violations
+
+    def _check_aggregate_rules(self, changed_files: Sequence[FileEntry]) -> list[Violation]:
+        """Check aggregate rules like max_files and max_lines."""
+        violations: list[Violation] = []
+        total_files = len(changed_files)
+        total_lines = sum(_extract_lines(f) for f in changed_files)
+        for rule in self.rules:
+            if rule.max_files is not None and total_files > rule.max_files:
+                violations.append(
+                    Violation(
+                        file="<aggregate>",
+                        severity=rule.on_violation,
+                        rule=rule.name,
+                        message=f"Too many files changed ({total_files} > {rule.max_files})",
+                    )
+                )
+            if rule.max_lines is not None and total_lines > rule.max_lines:
+                violations.append(
+                    Violation(
+                        file="<aggregate>",
+                        severity=rule.on_violation,
+                        rule=rule.name,
+                        message=f"Too many lines changed ({total_lines} > {rule.max_lines})",
+                    )
+                )
+        return violations
+
+    def _check_file(self, file: str, rule: ContractRule) -> Violation | None:
+        """Check a single file against a single rule."""
+        # Deny takes priority — if file matches deny, it's a violation
+        if rule.matches_deny(file):
+            return Violation(
+                file=file,
+                severity=rule.on_violation,
+                rule=rule.name,
+                message=f"File '{file}' is denied by rule '{rule.name}'",
+            )
+
+        # If allow patterns are defined and file doesn't match, it's a violation
+        if rule.allow and not rule.matches_allow(file):
+            return Violation(
+                file=file,
+                severity=rule.on_violation,
+                rule=rule.name,
+                message=f"File '{file}' not allowed by rule '{rule.name}'",
+            )
+
+        return None
+
+
+class GitDiffError(Exception):
+    """Raised when git diff command fails."""
+
+    def __init__(self, message: str, returncode: int = 1, stderr: str = "") -> None:
+        super().__init__(message)
+        self.returncode = returncode
+        self.stderr = stderr
+
+
+class DiffCalculator:
+    """Calculate diff between current branch and base."""
+
+    def __init__(self, base_branch: str = "main", cwd: Path | None = None) -> None:
+        self.base_branch = base_branch
+        self.cwd = cwd
+
+    def get_changed_files(self) -> list[dict]:
+        """Run git diff and return list of file change dicts with line counts.
+
+        Raises:
+            GitDiffError: If git diff fails or git executable is not found.
+        """
+        try:
+            result = subprocess.run(
+                ["git", "--no-pager", "diff", "--numstat", f"{self.base_branch}...HEAD"],
+                capture_output=True,
+                text=True,
+                check=True,
+                cwd=self.cwd,
+            )
+        except subprocess.CalledProcessError as e:
+            err_msg = (
+                e.stderr.strip()
+                if e.stderr
+                else f"git command failed with exit code {e.returncode}"
+            )
+            raise GitDiffError(
+                f"git diff failed: {err_msg}",
+                returncode=e.returncode,
+                stderr=e.stderr or "",
+            ) from e
+        except FileNotFoundError as e:
+            raise GitDiffError("git executable not found", returncode=127) from e
+        return self._parse_numstat(result.stdout)
+
+    def _parse_numstat(self, raw: str) -> list[dict]:
+        """Parse git diff --numstat output into list of change dicts."""
+        if not raw.strip():
+            return []
+        changes = []
+        for line in raw.splitlines():
+            parts = line.split("\t")
+            if len(parts) >= 3:
+                try:
+                    added = int(parts[0])
+                except ValueError:
+                    added = 0  # binary files show "-"
+                try:
+                    deleted = int(parts[1])
+                except ValueError:
+                    deleted = 0
+                path = parts[2]
+                changes.append(
+                    {
+                        "path": path,
+                        "added": added,
+                        "deleted": deleted,
+                        "lines": added + deleted,
+                    }
+                )
+        return changes
+
+
+def validate_diff(
+    contract: Contract,
+    changed_files: Sequence[FileEntry],
+) -> list[Violation]:
+    """Convenience: validate changed files against a contract."""
+    engine = RulesEngine(contract.rules)
+    return engine.check(changed_files)

diff_contract/sarif.py

@@ -0,0 +1,92 @@
+"""SARIF 2.1.0 output for diff-contract."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from diff_contract.engine import Violation
+
+
+def violations_to_sarif(
+    violations: list[Violation],
+    tool_name: str = "diff-contract",
+    tool_version: str = "0.1.0",
+) -> dict[str, Any]:
+    """Convert violations to SARIF 2.1.0 format.
+
+    Args:
+        violations: List of Violation objects from RulesEngine
+        tool_name: Tool name for SARIF runner
+        tool_version: Tool version for SARIF runner
+
+    Returns:
+        SARIF 2.1.0 document as dict
+    """
+    rules = []
+    results = []
+
+    # Build rules from unique violation types
+    rule_ids = set()
+    for v in violations:
+        rule_id = f"diff-contract/{v.rule}"
+        if rule_id not in rule_ids:
+            rule_ids.add(rule_id)
+            rules.append(
+                {
+                    "id": rule_id,
+                    "name": v.rule,
+                    "shortDescription": {
+                        "text": f"Contract rule: {v.rule}",
+                    },
+                    "fullDescription": {
+                        "text": f"Violates diff-contract rule '{v.rule}'. File: {v.file}",
+                    },
+                    "defaultConfiguration": {
+                        "level": "error" if v.severity.value == "block" else "warning",
+                    },
+                }
+            )
+
+    # Build results
+    for v in violations:
+        level = "error" if v.severity.value == "block" else "warning"
+        results.append(
+            {
+                "ruleId": f"diff-contract/{v.rule}",
+                "level": level,
+                "message": {"text": v.message},
+                "locations": [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {
+                                "uri": v.file,
+                            },
+                        },
+                    }
+                ],
+            }
+        )
+
+    return {
+        "version": "2.1.0",
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": tool_name,
+                        "version": tool_version,
+                        "informationUri": "https://github.com/yunaremaia/diff-contract",
+                        "rules": rules,
+                    },
+                },
+                "results": results,
+            }
+        ],
+    }
+
+
+def sarif_to_string(sarif_doc: dict[str, Any]) -> str:
+    """Serialize SARIF document to JSON string."""
+    return json.dumps(sarif_doc, indent=2)

diff_contract-0.1.1.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: diff-contract
+Version: 0.1.1
+Summary: Deterministic guardrails for AI-generated diffs — define what files can change, block violations.
+Author-email: Yunare Maia <yunare@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yunaremaia/diff-contract
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Dynamic: license-file
+
+# diff-contract
+
+**Deterministic guardrails for AI-generated diffs — define what files can change, block violations.**
+
+```bash
+pip install diff-contract
+diff-contract check --contract .diffcontract.yml
+```
+
+## The Problem
+
+AI coding tools (Cursor, Claude Code, Codex) sometimes modify unrelated files, introduce changes outside the intended scope, or drift from the original structure. `diff-contract` sits between AI-generated code and your repo, enforcing **deterministic** constraints — not relying on another AI pass to review.
+
+> "Most tools either help generate code or review it after the fact, but there's no real control layer in between." — HN discussion, 2026
+
+## Quick Start
+
+### 1. Install
+```bash
+pip install diff-contract
+```
+
+### 2. Define your contract
+```yaml
+# .diffcontract.yml
+version: 1
+rules:
+  - name: "Block core changes"
+    deny:
+      - "src/core/**"
+      - "*.env"
+    on_violation: block
+
+  - name: "Allow feature X"
+    allow:
+      - "src/features/X/**"
+      - "tests/features/X/**"
+    on_violation: block
+```
+
+### 3. Check your diff
+```bash
+# Check current branch vs main
+diff-contract check
+
+# Check specific files
+diff-contract check --files src/app.py src/utils.py
+
+# JSON output (for CI)
+diff-contract check --output json
+```
+
+### 4. GitHub Action
+```yaml
+# .github/workflows/diff-contract.yml
+name: diff-contract
+on: pull_request
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: yunaremaia/diff-contract@main
+```
+
+## Validate files (no git required)
+
+Validate specific files against your contract without a git diff — ideal for pre-commit hooks:
+
+```bash
+diff-contract validate --files src/app.py tests/test_app.py
+echo "src/foo.py" | diff-contract validate --from-stdin
+```
+
+## Initialize a contract
+
+Create a starter `.diffcontract.yml`:
+
+```bash
+diff-contract init                    # default Python project contract
+diff-contract init --template react   # React/Next.js
+diff-contract init --template django  # Django
+diff-contract init --template rust    # Rust workspace
+diff-contract init --template docs    # documentation-only
+```
+
+Ready-to-use templates for React, Django, Rust, and documentation-only projects are available in the [`examples/`](examples/) directory.
+
+## Pre-commit hook
+
+diff-contract ships a pre-commit hook. Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/yunaremaia/diff-contract
+    rev: v0.1.0
+    hooks:
+      - id: diff-contract
+        args: ["--contract", ".diffcontract.yml"]
+```
+
+## SARIF Output (GitHub Code Scanning)
+
+Generate SARIF 2.1.0 output for GitHub Code Scanning integration:
+
+```bash
+diff-contract check --sarif > diff-contract.sarif
+diff-contract validate --files src/foo.py --sarif
+```
+
+GitHub Actions workflow:
+
+```yaml
+- uses: yunaremaia/diff-contract@main
+  with:
+    format: sarif
+    sarif-output: diff-contract.sarif
+
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: diff-contract.sarif
+```
+
+SARIF output includes one rule per violation type. Block violations emit at `error` level, warnings at `warning`.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Clean — no violations |
+| 1 | Block violation — file denied, outside allowed scope, or an aggregate limit exceeded with `on_violation: block` |
+| 2 | Warning — non-blocking violation (e.g., large diff with `on_violation: warn`) |
+
+## Rules
+
+- **allow**: File globs that are permitted (all others blocked)
+- **deny**: File globs that are denied (takes priority)
+- **on_violation**: `block` (exit 1) or `warn` (exit 2)
+- **max_files** / **max_lines**: optional aggregate size limits (see below)
+
+## Aggregate Limits
+
+Path allow/deny rules constrain *which* files may change. `max_files` and `max_lines` constrain *how large* a change set may be. They are evaluated against the whole diff after per-file rules run.
+
+| Field | Meaning |
+|-------|---------|
+| `max_files` | Maximum number of changed files in the diff |
+| `max_lines` | Maximum total changed lines (`added + deleted` from `git diff --numstat`) |
+
+A rule may set either field, both, or neither. Limits are omitted by default (no size budget). When a limit is exceeded, the engine records an aggregate violation on the synthetic path `<aggregate>` and applies that rule's `on_violation`:
+
+- `on_violation: block` — fail the check (exit code **1**). Use this to stop AI agents or CI from landing oversized diffs.
+- `on_violation: warn` — report the overshoot but continue (exit code **2** if there are no block violations). Use this as a PR-size nudge.
+
+Typical uses:
+
+- Cap feature work so an agent cannot rewrite half the tree while implementing one ticket.
+- Keep documentation or bugfix rules tight even when the path globs are broad.
+- Warn on large diffs without blocking hotfixes.
+
+Limits are compared against the **entire** change list, not only files that match that rule's `allow`/`deny` globs. A rule that only sets `max_files` / `max_lines` (no path patterns) is a global size guard.
+
+### Example
+
+```yaml
+# .diffcontract.yml
+version: 1
+rules:
+  - name: "Block core changes"
+    deny:
+      - "src/core/**"
+      - "*.env"
+    on_violation: block
+
+  - name: "Feature development"
+    allow:
+      - "src/features/**"
+      - "tests/features/**"
+    max_files: 15
+    max_lines: 400
+    on_violation: block
+
+  - name: "Large diff warning"
+    max_files: 20
+    max_lines: 600
+    on_violation: warn
+```
+
+In this contract:
+
+- Changes under `src/core/**` or `*.env` are blocked.
+- Feature-area diffs may proceed only if they stay within 15 files and 400 lines; exceeding either budget is a **block** (exit 1).
+- Any diff larger than 20 files or 600 lines also produces a **warning** (exit 2 when nothing is blocked).
+
+See [`examples/strict.yml`](examples/strict.yml) for a fuller contract that combines deny rules with per-rule size budgets.
+
+## License
+
+MIT
+
+# diff-contract
+
+![CI](https://github.com/yunaremaia/diff-contract/actions/workflows/ci.yml/badge.svg)

diff_contract-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+diff_contract/__init__.py,sha256=qvLKBGfNLz4dZEpO6Os_4Y73IigYeAe5eSKZ2MBdaMc,186
+diff_contract/cli.py,sha256=qUKRBxzxMTPVNeZS7EKtnjIwqJyNj6hDhRW9ct4kTNQ,11485
+diff_contract/contract.py,sha256=lX2S2QBQeW-wN4fAU11gfSZF8kb591CO2RBc_Rh0nKo,2772
+diff_contract/engine.py,sha256=MjHsSgkN3caFiX92SBJuPG8DETVWL3UygfBl9FB1rIo,7035
+diff_contract/sarif.py,sha256=hsJSf9f75hzV2YKgEbXLiComOdLHViPUCm2g9dxmi64,2702
+diff_contract-0.1.1.dist-info/licenses/LICENSE,sha256=jaJ4N5zOiHxuIAaPgohynRXOjhcZsCwBBU6lpDNG-IE,1068
+diff_contract-0.1.1.dist-info/METADATA,sha256=caDuy8PdoXq4KsPWgWQ6mPxohhp0rDs1j06s5iu7grs,6782
+diff_contract-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+diff_contract-0.1.1.dist-info/entry_points.txt,sha256=3scYACMiJxCLhgtlKNLzsUOz3jRiKP2SjSRQUDR32-g,57
+diff_contract-0.1.1.dist-info/top_level.txt,sha256=jpfrzUOpWQPxkMXo0tMp6CBqYGJw85m4ZdXPxQzAWzo,14
+diff_contract-0.1.1.dist-info/RECORD,,

diff_contract-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

diff_contract-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+diff-contract = diff_contract.cli:main

diff_contract-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yunare Maia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diff_contract-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+diff_contract