rein-engine 0.1.1__py3-none-any.whl

rein/__init__.py

@@ -0,0 +1,3 @@
+"""rein: agent-agnostic guardrails that keep AI-written code clean and safe."""
+
+__version__ = "0.1.1"

rein/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line adapter around rein.core."""

rein/cli/__main__.py

@@ -0,0 +1,108 @@
+"""`rein` command line.
+
+This is a thin adapter: it gathers input (files, git state), calls the pure
+checks in :mod:`rein.core`, renders the resulting findings, and chooses an
+exit code. All real logic lives in core so the MCP server and git hook can
+reuse it unchanged.
+
+Subcommands:
+    rein scan [PATH ...]        Scan files/dirs for leaked secrets.
+    rein commit-check [-m MSG]  Check a commit message + staged files.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from .. import __version__
+from .commands import (
+    cmd_baseline,
+    cmd_commit_check,
+    cmd_drift,
+    cmd_learn,
+    cmd_lint,
+    cmd_scan,
+    cmd_review,
+    cmd_security,
+)
+
+
+def _format_parent() -> argparse.ArgumentParser:
+    parent = argparse.ArgumentParser(add_help=False)
+    parent.add_argument(
+        "--format", choices=["text", "json", "sarif"], default="text",
+        help="Output format (default: text).",
+    )
+    return parent
+
+
+def _add_basic_parsers(sub: Any, fmt_parent: argparse.ArgumentParser) -> None:
+    p_scan = sub.add_parser("scan", help="Scan files/dirs for leaked secrets.", parents=[fmt_parent])
+    p_scan.add_argument("paths", nargs="*", help="Files or directories (default: .).")
+    p_scan.add_argument("--diff", action="store_true", help="Read a unified diff from stdin and scan only added lines.")
+    p_scan.set_defaults(func=cmd_scan)
+
+    p_commit = sub.add_parser("commit-check", help="Check a commit message + staged files.", parents=[fmt_parent])
+    p_commit.add_argument("-m", "--message", help="Commit message text.")
+    p_commit.add_argument("-F", "--message-file", help="Read the message from a file.")
+    p_commit.set_defaults(func=cmd_commit_check)
+
+    p_lint = sub.add_parser("lint", help="Lint Python files.", parents=[fmt_parent])
+    p_lint.add_argument("paths", nargs="*", help="Files or directories (default: .).")
+    p_lint.add_argument("--ruff", action="store_true", help="Run ruff alongside core rules.")
+    p_lint.set_defaults(func=cmd_lint)
+
+    p_sec = sub.add_parser("security", help="Scan Python files for unsafe-code patterns.", parents=[fmt_parent])
+    p_sec.add_argument("paths", nargs="*", help="Files or directories (default: .).")
+    p_sec.set_defaults(func=cmd_security)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="rein",
+        description="Guardrails that keep AI-written code clean and secure.",
+    )
+    parser.add_argument("--version", action="version", version=f"rein {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    fmt_parent = _format_parent()
+    _add_basic_parsers(sub, fmt_parent)
+
+    p_review = sub.add_parser("review", help="Run all guardrails and return a verdict.", parents=[fmt_parent])
+    p_review.add_argument("paths", nargs="*", help="Files or directories (default: .).")
+    p_review.add_argument("--diff", action="store_true", help="Read a unified diff from stdin; review only added lines (file content read from the working tree).")
+    p_review.add_argument("--explain", action="store_true", help="Show how to fix each finding.")
+    p_review.add_argument("--baseline", help="Suppress findings recorded in this baseline file.")
+    p_review.add_argument("--config", help="Path to .rein.toml configuration file.")
+    p_review.add_argument("--bandit", action="store_true", help="Run bandit alongside core rules.")
+    p_review.add_argument("--gitleaks", action="store_true", help="Run gitleaks alongside core rules.")
+    p_review.add_argument("--semgrep", action="store_true", help="Run semgrep alongside core rules.")
+    p_review.set_defaults(func=cmd_review)
+
+    p_base = sub.add_parser("baseline", help="Record current findings as an accepted baseline.")
+    p_base.add_argument("paths", nargs="*", help="Files or directories (default: .).")
+    p_base.add_argument("-o", "--output", default=None, help="Output file (default: .rein-baseline.json).")
+    p_base.set_defaults(func=cmd_baseline)
+
+    p_learn = sub.add_parser("learn", help="Measure conventions and draft a profile.")
+    p_learn.add_argument("paths", nargs="*", help="Files or directories (default: .).")
+    p_learn.add_argument("-o", "--output", help="Output file to write draft (default: stdout).")
+    p_learn.set_defaults(func=cmd_learn)
+
+    p_drift = sub.add_parser("drift", help="Check convention profile drift.")
+    p_drift.add_argument("paths", nargs="*", help="Files or directories (default: .).")
+    p_drift.set_defaults(func=cmd_drift)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rein/cli/_helpers.py

@@ -0,0 +1,169 @@
+"""CLI helpers for `rein`.
+
+Purely utility functions and detector wrappers for the thin CLI adapter.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import tomllib
+from collections.abc import Iterable
+from typing import Any
+
+from ..core import bandit, custom, gitleaks, lint, ruff, secrets, semgrep
+from ..core.code import code_domain
+from ..core.conventions import scan_profile
+from ..core.diffs import parse_added_lines
+from ..core.findings import Finding
+from ..core.profile import Profile, ProfileError, parse_profile, profile_invalid_finding
+from ..core.review import review_diff_findings
+
+_SKIP_DIRS = {
+    ".git", "node_modules", "__pycache__", ".venv", "venv", "dist", "build",
+    ".pytest_cache", ".mypy_cache", ".ruff_cache",
+}
+
+
+def _iter_files(paths: Iterable[str]) -> Iterable[str]:
+    for path in paths:
+        if os.path.isfile(path):
+            yield path
+        elif os.path.isdir(path):
+            for root, dirs, files in os.walk(path):
+                dirs[:] = [d for d in dirs if d not in _SKIP_DIRS]
+                for name in files:
+                    yield os.path.join(root, name)
+
+
+def _git(*args: str) -> str:
+    try:
+        return subprocess.check_output(["git", *args], text=True, stderr=subprocess.DEVNULL)
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return ""
+
+
+_DETECTOR_TIMEOUT = 60  # seconds; a detector must not hang the review
+
+
+def _run_stdout_detector(cmd: list[str]) -> str:
+    """Run a detector that writes JSON to stdout; fail open on any failure."""
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=_DETECTOR_TIMEOUT)
+        return proc.stdout
+    except FileNotFoundError:
+        print(f"rein: {cmd[0]} not found; skipping.", file=sys.stderr)
+        return ""
+    except subprocess.TimeoutExpired:
+        print(f"rein: {cmd[0]} timed out after {_DETECTOR_TIMEOUT}s; skipping.", file=sys.stderr)
+        return ""
+    except OSError as exc:
+        print(f"rein: {cmd[0]} failed ({exc}); skipping.", file=sys.stderr)
+        return ""
+
+
+def _run_ruff(targets: list[str]) -> str:
+    return _run_stdout_detector(["ruff", "check", "--output-format=json", *targets])
+
+
+def _run_bandit(targets: list[str]) -> str:
+    return _run_stdout_detector(["bandit", "-r", "-f", "json", "-q", *targets])
+
+
+def _run_gitleaks(targets: list[str]) -> str:
+    report = ""
+    try:
+        fd, report = tempfile.mkstemp(suffix=".json")
+        os.close(fd)
+        subprocess.run(
+            ["gitleaks", "dir", *targets, "--report-format", "json", "--report-path", report, "--no-banner"],
+            capture_output=True,
+            timeout=_DETECTOR_TIMEOUT,
+        )
+        with open(report, encoding="utf-8") as fh:
+            return fh.read()
+    except FileNotFoundError:
+        print("rein: gitleaks not found; skipping gitleaks checks.", file=sys.stderr)
+        return ""
+    except subprocess.TimeoutExpired:
+        print(f"rein: gitleaks timed out after {_DETECTOR_TIMEOUT}s; skipping.", file=sys.stderr)
+        return ""
+    except OSError as exc:
+        print(f"rein: gitleaks failed ({exc}); skipping.", file=sys.stderr)
+        return ""
+    finally:
+        if report and os.path.exists(report):
+            try:
+                os.unlink(report)
+            except OSError:
+                pass
+
+
+def _run_semgrep(targets: list[str]) -> str:
+    return _run_stdout_detector(["semgrep", "--json", "--quiet", "--config", "auto", *targets])
+
+
+_DETECTORS = {
+    "ruff": (lambda t: _run_ruff(t), ruff.parse_ruff_output),
+    "bandit": (lambda t: _run_bandit(t), bandit.parse_bandit_output),
+    "gitleaks": (lambda t: _run_gitleaks(t), gitleaks.parse_gitleaks_output),
+    "semgrep": (lambda t: _run_semgrep(t), semgrep.parse_semgrep_output),
+}
+
+
+def _collect_review_findings(targets: list[str], custom_rules: tuple[custom.CustomRule, ...] = (), profile: Profile | None = None) -> list[Finding]:
+    findings: list[Finding] = []
+    for p in _iter_files(targets):
+        if p.endswith(".py"):
+            try:
+                with open(p, encoding="utf-8") as fh:
+                    text = fh.read()
+            except (OSError, UnicodeDecodeError):
+                continue
+            findings.extend(code_domain(text, p))
+            findings.extend(custom.scan_custom(text, p, custom_rules))
+            if profile is not None:
+                findings.extend(scan_profile(text, p, profile))
+    return findings
+
+
+def _collect_diff_findings(diff_text: str, custom_rules: tuple[custom.CustomRule, ...] = ()) -> list[Finding]:
+    findings: list[Finding] = []
+    for p in sorted({al.path for al in parse_added_lines(diff_text) if al.path}):
+        try:
+            with open(p, encoding="utf-8") as fh:
+                content = fh.read()
+        except (OSError, UnicodeDecodeError):
+            continue
+
+        def custom_domain(t: str, p_: str | None) -> list[Finding]:
+            return code_domain(t, p_) + custom.scan_custom(t, p_, custom_rules)
+
+        findings.extend(review_diff_findings(content, diff_text, p, domain=custom_domain))
+    return findings
+
+
+def _load_baseline(path: str) -> set[str]:
+    """Fingerprints from a baseline file. Fail open: warn and return empty on
+    any read/parse error, so a bad baseline never crashes or hides findings."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+        return {entry["fingerprint"] for entry in data.get("findings", [])}
+    except (OSError, UnicodeDecodeError, ValueError, KeyError, TypeError):
+        print(f"rein: could not read baseline '{path}'; ignoring it.", file=sys.stderr)
+        return set()
+
+
+def _load_profile(path: str = ".rein-profile.toml") -> tuple[Profile | None, list[Finding]]:
+    if not os.path.exists(path):
+        return None, []                      # missing -> silent, opt-in
+    try:
+        with open(path, "rb") as fh:
+            data = tomllib.load(fh)
+        return parse_profile(data), []
+    except (OSError, tomllib.TOMLDecodeError, ProfileError) as exc:
+        return None, [profile_invalid_finding(str(exc), path=path)]

rein/cli/commands.py

@@ -0,0 +1,194 @@
+"""CLI commands for `rein`.
+
+Provides individual command implementations called by the parser.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import os
+import sys
+import tomllib
+
+from ..core import baseline, lint, ruff, secrets, security
+from ..core.commits import check_commit
+from ..core.config import DEFAULT_CONFIG, apply_disabled, config_from_dict
+from ..core.drift import measure_drift
+from ..core.findings import Finding
+from ..core.learn import filter_net_new, measure_naming, measure_test_layout, render_profile_draft
+from ..core.profile import parse_profile, ProfileError
+from ..core.review import ReviewResult
+from ..report import emit, emit_report, report_exit_code, worst_exit_code
+from . import _helpers
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    if args.diff:
+        findings = secrets.scan_diff(sys.stdin.read())
+    else:
+        targets = args.paths or ["."]
+        findings: list[Finding] = []
+        for filepath in _helpers._iter_files(targets):
+            findings.extend(secrets.scan_file(filepath))
+    emit(findings, args.format)
+    return worst_exit_code(findings)
+
+
+def cmd_commit_check(args: argparse.Namespace) -> int:
+    if args.message is not None:
+        message = args.message
+    elif args.message_file is not None:
+        with open(args.message_file, encoding="utf-8") as fh:
+            message = fh.read()
+    else:
+        message = _helpers._git("log", "-1", "--pretty=%B") or ""
+
+    staged = [p for p in _helpers._git("diff", "--cached", "--name-only").splitlines() if p]
+    findings = check_commit(message, staged)
+    emit(findings, args.format)
+    return worst_exit_code(findings)
+
+
+def cmd_lint(args: argparse.Namespace) -> int:
+    targets = args.paths or ["."]
+    findings = [f for p in _helpers._iter_files(targets) if p.endswith(".py") for f in lint.lint_file(p)]
+    if args.ruff:
+        findings.extend(ruff.parse_ruff_output(_helpers._run_ruff(targets)))
+    emit(findings, args.format)
+    return worst_exit_code(findings)
+
+
+def cmd_security(args: argparse.Namespace) -> int:
+    targets = args.paths or ["."]
+    findings = [f for p in _helpers._iter_files(targets) if p.endswith(".py") for f in security.scan_security_file(p)]
+    emit(findings, args.format)
+    return worst_exit_code(findings)
+
+
+def cmd_review(args: argparse.Namespace) -> int:
+    config = DEFAULT_CONFIG
+    config_path = args.config or ".rein.toml"
+    if os.path.exists(config_path):
+        try:
+            with open(config_path, "rb") as fh:
+                data = tomllib.load(fh)
+            config = config_from_dict(data)
+        except (OSError, tomllib.TOMLDecodeError, ValueError) as exc:
+            print(f"rein: config error in '{config_path}': {exc}", file=sys.stderr)
+            return 1
+    elif args.config:
+        print(f"rein: could not find config '{args.config}'", file=sys.stderr)
+        return 1
+
+    profile, profile_findings = _helpers._load_profile()
+
+    if args.diff:
+        findings = _helpers._collect_diff_findings(sys.stdin.read(), config.custom_rules)
+    else:
+        findings = _helpers._collect_review_findings(args.paths or ["."], config.custom_rules, profile)
+
+        enabled = set(config.detectors)
+        if args.bandit:
+            enabled.add("bandit")
+        if args.gitleaks:
+            enabled.add("gitleaks")
+        if args.semgrep:
+            enabled.add("semgrep")
+
+        for name in sorted(enabled):
+            if name in _helpers._DETECTORS:
+                runner, parser = _helpers._DETECTORS[name]
+                findings.extend(parser(runner(args.paths or ["."])))
+    if args.baseline:
+        findings = baseline.apply_baseline(findings, _helpers._load_baseline(args.baseline))
+
+    findings = apply_disabled(findings, config.disabled)
+    findings = profile_findings + findings
+    result = ReviewResult.from_findings(findings, config.policy)
+    emit_report(result, args.format, args.explain)
+    return report_exit_code(result)
+
+
+def cmd_baseline(args: argparse.Namespace) -> int:
+    findings = _helpers._collect_review_findings(args.paths or ["."])
+    data = {"version": 1, "findings": baseline.make_baseline(findings)}
+    out = args.output or ".rein-baseline.json"
+    with open(out, "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2)
+        fh.write("\n")
+    print(f"rein: wrote baseline with {len(data['findings'])} finding(s) to {out}")
+    return 0
+
+
+def cmd_learn(args: argparse.Namespace) -> int:
+    targets = args.paths or ["."]
+    files = []
+    for p in _helpers._iter_files(targets):
+        if p.endswith(".py"):
+            try:
+                with open(p, encoding="utf-8") as fh:
+                    files.append((p, fh.read()))
+            except (OSError, UnicodeDecodeError):
+                continue
+
+    measured = measure_naming([text for _, text in files])
+    measured.extend(measure_test_layout(files))
+
+    existing = None
+    if os.path.exists(".rein-profile.toml"):
+        try:
+            with open(".rein-profile.toml", "rb") as fh:
+                data = tomllib.load(fh)
+            existing = parse_profile(data)
+        except (OSError, tomllib.TOMLDecodeError, ProfileError) as exc:
+            print(f"rein: could not parse existing profile: {exc}", file=sys.stderr)
+            existing = None
+
+    filtered = filter_net_new(measured, existing)
+    draft = render_profile_draft(filtered, datetime.date.today().isoformat())
+
+    if args.output:
+        if os.path.exists(args.output):
+            print(f"rein: error: output file '{args.output}' already exists. Refusing to overwrite.", file=sys.stderr)
+            return 1
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(draft)
+        print(f"rein: wrote draft profile to {args.output}", file=sys.stderr)
+    else:
+        print(draft, end="")
+    return 0
+
+
+def cmd_drift(args: argparse.Namespace) -> int:
+    profile, profile_findings = _helpers._load_profile()
+    if profile is None:
+        if not os.path.exists(".rein-profile.toml"):
+            print("rein: no profile found; skipping drift check.", file=sys.stderr)
+            return 0
+        else:
+            for f in profile_findings:
+                print(f"rein: error: {f.message}", file=sys.stderr)
+            return 1
+
+    targets = args.paths or ["."]
+    files = []
+    for p in _helpers._iter_files(targets):
+        if p.endswith(".py"):
+            try:
+                with open(p, encoding="utf-8") as fh:
+                    files.append((p, fh.read()))
+            except (OSError, UnicodeDecodeError):
+                continue
+
+    reports = measure_drift(profile, files)
+
+    has_drift = False
+    for r in reports:
+        status = "DRIFT" if r.drifted else "OK"
+        print(f"[{status}] {r.convention_id}: {r.summary} (conformance: {r.current_conformance:.2f}, ratified: {r.ratified_agreement:.2f}, sample: {r.sample_size})")
+        if r.drifted:
+            has_drift = True
+
+    return 1 if has_drift else 0

rein/core/__init__.py

@@ -0,0 +1,5 @@
+"""Pure checking logic shared by every adapter (CLI, MCP, git hook)."""
+
+from .findings import Finding, Severity, max_severity
+
+__all__ = ["Finding", "Severity", "max_severity"]

rein/core/bandit.py

@@ -0,0 +1,66 @@
+"""Parse output from the bandit security scanner.
+
+This is a pure parsing adapter. It takes bandit's JSON output and turns it
+into rein Findings. It does no I/O.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .findings import Finding, Severity
+
+_SEVERITY_MAP = {
+    "high": Severity.HIGH,
+    "medium": Severity.MEDIUM,
+    "low": Severity.LOW,
+}
+
+
+def parse_bandit_output(json_text: str) -> list[Finding]:
+    """Parse bandit -f json output into a list of Findings.
+
+    Tolerates bad JSON or empty input by returning an empty list.
+    """
+    if not json_text or not json_text.strip():
+        return []
+
+    try:
+        data = json.loads(json_text)
+    except json.JSONDecodeError:
+        return []
+
+    if not isinstance(data, dict):
+        return []
+
+    results = data.get("results")
+    if not isinstance(results, list):
+        return []
+
+    findings = []
+    for item in results:
+        if not isinstance(item, dict):
+            continue
+        test_id = item.get("test_id")
+        filename = item.get("filename")
+        line_number = item.get("line_number")
+
+        if not test_id or not filename or line_number is None:
+            continue
+
+        issue_text = item.get("issue_text", "")
+        sev_str = str(item.get("issue_severity", "")).lower()
+        severity = _SEVERITY_MAP.get(sev_str, Severity.LOW)
+
+        findings.append(
+            Finding(
+                rule_id=f"bandit.{test_id}",
+                severity=severity,
+                message=issue_text,
+                path=filename,
+                line=line_number,
+                snippet=None,
+                tags=("security", "bandit"),
+            )
+        )
+    return findings

rein/core/baseline.py

@@ -0,0 +1,45 @@
+"""Baseline fingerprinting: accept current findings, block only new ones.
+
+The fingerprint excludes line numbers so a finding survives code moving around;
+it keys on the rule, the file, and the finding's content (redacted snippet, or
+message when there is no snippet). Stored as a hash so the file leaks nothing.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from .findings import Finding
+
+
+def fingerprint(finding: Finding) -> str:
+    """Stable id for a finding, independent of its line number.
+
+    Uses the redacted snippet when present (distinguishes e.g. two different
+    secrets in one file), else the message (carries the function/var name for
+    snippet-less findings). Line is deliberately excluded so the fingerprint
+    survives code shifting up or down.
+    """
+    content = finding.snippet if finding.snippet is not None else finding.message
+    raw = f"{finding.rule_id}\0{finding.path or ''}\0{content}"
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def make_baseline(findings: list[Finding]) -> list[dict]:
+    """Build de-duplicated, serializable baseline entries from current findings.
+
+    Each entry carries rule_id and path for human auditing plus the fingerprint
+    used for matching. No raw secret values are stored.
+    """
+    entries: dict[str, dict] = {}
+    for f in findings:
+        fp = fingerprint(f)
+        entries[fp] = {"rule_id": f.rule_id, "path": f.path, "fingerprint": fp}
+    return list(entries.values())
+
+
+def apply_baseline(
+    findings: list[Finding], fingerprints: set[str],
+) -> list[Finding]:
+    """Drop findings whose fingerprint is in the baseline; keep the rest."""
+    return [f for f in findings if fingerprint(f) not in fingerprints]

rein/core/code.py

@@ -0,0 +1,41 @@
+"""The code domain: runs code guardrails (secrets, lint, security) over source.
+
+This encapsulates the code-specific logic so the review engine can run it
+as a generic Domain.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from .findings import Finding
+from .lint import lint_text
+from .secrets import scan_text
+from .security import scan_security
+
+
+def _safe_parse(text: str) -> ast.Module | None:
+    try:
+        return ast.parse(text)
+    except (SyntaxError, ValueError, RecursionError):
+        return None
+
+
+def _python_findings(text: str, path: str | None) -> list[Finding]:
+    """Lint + security over text, parsing the AST exactly once on the happy path."""
+    tree = _safe_parse(text)
+    if tree is None:
+        return lint_text(text, path)  # rare error path: lint reports it; security no-ops
+    return lint_text(text, path, tree=tree) + scan_security(text, path, tree=tree)
+
+
+def code_domain(text: str, path: str | None = None) -> list[Finding]:
+    """Run all code guardrails over text.
+
+    Always runs the secret scanner. If the path implies Python (or is None),
+    also runs lint and security checks, parsing the AST at most once.
+    """
+    findings = list(scan_text(text, path))
+    if path is None or path.endswith(".py"):
+        findings.extend(_python_findings(text, path))
+    return findings