prism-code-review 2.0.0__py3-none-any.whl

prism/__init__.py

@@ -0,0 +1,87 @@
+"""
+Prism - Local Pre-Commit Code Review System
+
+A multi-agent code review pipeline that runs on the developer's machine
+before code is pushed to GitHub. Each agent checks a specific concern.
+"""
+
+import os
+from pathlib import Path
+
+__version__ = "2.0.0"
+
+_ENV_LOADED = False
+
+
+def _parse_env_file(path):
+    """Parse a .env file using only the standard library.
+
+    ``python-dotenv`` is an optional extra, so a plain ``pip install`` must not
+    depend on it: without this fallback a .env written by ``prism key set`` is
+    ignored and the AI agents report "no API key configured" with no clue why.
+    """
+    values = {}
+    try:
+        text = path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return values
+
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):].lstrip()
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if not key:
+            continue
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+            value = value[1:-1]
+        values[key] = value
+    return values
+
+
+def load_env():
+    """Load the nearest .env file into os.environ (idempotent).
+
+    Runs at package import so every entry point (CLI, LSP, library use) sees
+    the same provider keys. Previously only `prism.cli` loaded .env, so
+    `prism.lsp` or a direct `review_with_agent` call silently ran without a
+    key and reported "no API key configured".
+    """
+    global _ENV_LOADED
+    if _ENV_LOADED:
+        return
+    _ENV_LOADED = True
+
+    here = Path(__file__).resolve().parent
+    # Project-local .env wins over the tool's own config, so a developer can
+    # point PRISM at a different key without editing the install.
+    candidates = (
+        Path.cwd() / ".env",
+        Path.cwd() / ".config" / ".env",
+        here.parent / ".env",
+        here / ".env",
+        here.parent / ".config" / ".env",
+        here / ".config" / ".env",
+        here.parent.parent / ".env",
+    )
+    for candidate in candidates:
+        if not candidate.exists():
+            continue
+        try:
+            from dotenv import load_dotenv
+        except ImportError:
+            # Mirror python-dotenv's default: existing environment wins.
+            for key, value in _parse_env_file(candidate).items():
+                os.environ.setdefault(key, value)
+        else:
+            load_dotenv(candidate)
+        return
+
+
+load_env()

prism/__main__.py

@@ -0,0 +1,13 @@
+"""Allow ``py -m prism`` and ``python -m prism`` to run the CLI.
+
+The console script (``prism = prism.cli:main`` in pyproject) covers installs
+made by pip; this module covers the case where a developer unzips the source
+folder and runs the tool directly with the interpreter they already have, with
+no install step of their own. Importing ``prism.cli`` runs the agent
+registration decorators, same as the console entry point.
+"""
+
+from prism.cli import main
+
+if __name__ == "__main__":
+    main()

prism/agents.py

@@ -0,0 +1,191 @@
+"""
+Agent registry, data model, config, and pipeline orchestration.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+class Blocker(str, Enum):
+    BLOCKS = "blocks"
+    WARNS = "warns"
+    ALLOWS = "allows"
+
+
+@dataclass
+class Finding:
+    agent: str
+    severity: Severity
+    category: str
+    message: str
+    file: str
+    line: Optional[int] = None
+    suggestion: Optional[str] = None
+    suggested_code: Optional[str] = None
+    blocker: Blocker = Blocker.BLOCKS
+    auto_fixable: bool = False
+    confidence: float = 1.0
+    rule_id: Optional[str] = None
+    # Other agents that raised the same issue. Populated by dedupe_results();
+    # empty for a finding nothing else corroborated.
+    corroborated_by: List[str] = field(default_factory=list)
+
+
+@dataclass
+class AgentResult:
+    agent_name: str
+    findings: List[Finding] = field(default_factory=list)
+    passed: bool = True
+    duration_ms: float = 0.0
+
+    @property
+    def blocking_findings(self) -> List[Finding]:
+        return [f for f in self.findings if f.blocker == Blocker.BLOCKS]
+
+
+class BaseAgent:
+    name: str = "base"
+    description: str = "Base agent"
+
+    def review(self, file_path: str, content: str, diff: str,
+               skeleton: str = "", line_count: int = None,
+               fast: bool = False) -> AgentResult:
+        import time
+        start = time.time()
+        findings = self._check(file_path, content, diff, skeleton, line_count, fast)
+        duration = (time.time() - start) * 1000
+        blocking = any(f.blocker == Blocker.BLOCKS for f in findings)
+        return AgentResult(
+            agent_name=self.name,
+            findings=findings,
+            passed=not blocking,
+            duration_ms=duration,
+        )
+
+    def _check(self, file_path: str, content: str, diff: str,
+               skeleton: str = "", line_count: int = None,
+               fast: bool = False) -> List[Finding]:
+        raise NotImplementedError
+
+
+AGENT_REGISTRY: Dict[str, BaseAgent] = {}
+
+
+def register_agent(cls: BaseAgent) -> BaseAgent:
+    AGENT_REGISTRY[cls.name] = cls()
+    return cls
+
+
+def get_agent(name: str) -> Optional[BaseAgent]:
+    return AGENT_REGISTRY.get(name)
+
+
+def list_agents() -> List[str]:
+    return list(AGENT_REGISTRY.keys())
+
+
+def run_pipeline(agents: List[str], file_path: str, content: str,
+                 diff: str, skeleton: str = "",
+                 line_count: int = None, fast: bool = False) -> List[AgentResult]:
+    results = []
+    for agent_name in agents:
+        agent = get_agent(agent_name)
+        if agent is None:
+            logger.warning("Agent %s not found, skipping", agent_name)
+            continue
+        result = agent.review(file_path, content, diff, skeleton, line_count, fast)
+        results.append(result)
+    return results
+
+
+def risk_score(file_path: str, content: str, diff: str, findings=None) -> float:
+    """Score 0.0 (low risk) to 1.0 (high risk) for a file.
+
+    Combines file characteristics with the severity of what was actually
+    found: a tiny file with a critical finding is high risk, so a 0.0 score
+    next to a blocking finding (which read as a contradiction to CI
+    consumers) cannot happen any more.
+    """
+    score = 0.0
+    name = file_path.lower()
+
+    if any(k in name for k in ["config", "secret", "env", "credential", "key", "auth"]):
+        score += 0.3
+
+    diff_lines = diff.count("\n")
+    if diff_lines > 200:
+        score += 0.3
+    elif diff_lines > 50:
+        score += 0.15
+
+    if any(m in content.lower() for m in ["generated by", "copilot", "chatgpt", "claude"]):
+        score += 0.2
+
+    if "test" in name or "spec" in name:
+        score -= 0.2
+
+    if file_path.endswith((".md", ".rst", ".txt", ".yaml", ".yml", ".json")):
+        score -= 0.1
+
+    weight = {Severity.CRITICAL: 0.25, Severity.HIGH: 0.1,
+              Severity.MEDIUM: 0.03, Severity.LOW: 0.0, Severity.INFO: 0.0}
+    for f in findings or []:
+        score += weight.get(f.severity, 0.0)
+
+    return round(max(0.0, min(1.0, score)), 2)
+
+
+def quality_gates_met(results: List[AgentResult], config: dict) -> bool:
+    """Check if all quality gates pass.
+
+    Only high and critical findings block the commit (the ``block_on`` set).
+    A blocking finding means the change is not safe to commit, so it fails the
+    gate as well; otherwise ``quality_gates_passed`` could be true while the
+    review is blocked, which reads as a contradiction in JSON output.
+
+    The regex quality agent reports advisory rules as LOW/MEDIUM with
+    ``Blocker.WARNS``; those never block regardless of the gate thresholds, so
+    a style preference cannot stop a commit.
+    """
+    gates = config.get("quality_gates", {})
+    blocking_sev = set(config.get("block_on", ["critical", "high"]))
+    all_findings = [f for r in results for f in r.findings]
+
+    for f in all_findings:
+        if f.blocker == Blocker.BLOCKS and f.severity.value in blocking_sev:
+            return False
+
+    max_complexity = gates.get("max_complexity")
+    if max_complexity:
+        for f in all_findings:
+            if (f.category == "Complexity"
+                    and f.severity.value in blocking_sev):
+                return False
+
+    max_file_length = gates.get("max_file_length")
+    if max_file_length:
+        for f in all_findings:
+            if (f.category == "File Length"
+                    and f.severity.value in blocking_sev):
+                return False
+
+    min_coverage = gates.get("min_coverage")
+    if min_coverage:
+        for f in all_findings:
+            if (f.category == "Missing Tests"
+                    and f.severity.value in blocking_sev):
+                return False
+
+    return True

prism/agents_policy.py

@@ -0,0 +1,277 @@
+"""
+Policy Agent - Checks compliance with project policies,
+license headers, copyright notices, and code ownership rules.
+
+Rule IDs follow SonarQube convention: POL-XXX
+
+These are style/policy preferences, not bugs, so everything here is LOW
+severity and never blocks. The rules that are pure noise on most projects
+(SPDX headers, print(), console.log, TODO(issue-ref) formatting) are off by
+default and opt-in via prism.json:
+
+  "policy": {
+    "headers": true,          # require copyright/SPDX headers
+    "banned_console": true,   # flag console.log in JS/TS
+    "check_print": true,      # flag print() outside CLI entry points
+    "check_todo_refs": true   # enforce TODO(PROJECT-123) format
+  }
+"""
+
+import re
+from typing import List
+from prism.agents import BaseAgent, Finding, Severity, Blocker, register_agent
+from prism.langs import lang_for, strip_literals
+
+# Copyright/SPDX header checks are opt-in via prism.json:
+#   "policy": {"headers": true}
+# They fired on every source file, which is pure noise for projects that do
+# not use SPDX headers.
+HEADER_CHECKS_ENABLED = False
+
+# Everything that is a preference rather than a defect is opt-in.
+BANNED_CONSOLE_ENABLED = False
+CHECK_PRINT_ENABLED = False
+CHECK_TODO_REFS_ENABLED = False
+
+
+@register_agent
+class PolicyAgent(BaseAgent):
+    name = "policy"
+    description = "Checks compliance with project policies and standards"
+
+    def __init__(self, require_header: bool = True, allowed_licenses: list = None,
+               policy: dict = None):
+        self.require_header = require_header
+        self.allowed_licenses = allowed_licenses or ["MIT", "Apache-2.0", "BSD-3-Clause", "ISC"]
+        self._policy = policy or {}
+
+    @property
+    def policy(self):
+        """Policy options, kept on the instance so tests can inject them."""
+        return self._policy
+
+    def _check(self, file_path: str, content: str, diff: str,
+               skeleton: str = "", line_count: int = None,
+               fast: bool = False) -> List[Finding]:
+        findings: List[Finding] = []
+        lines = content.split("\n")
+        policy = self._policy
+
+        headers_on = HEADER_CHECKS_ENABLED or policy.get("headers", False)
+        console_on = BANNED_CONSOLE_ENABLED or policy.get("banned_console", False)
+        print_on = CHECK_PRINT_ENABLED or policy.get("check_print", False)
+        todo_refs_on = CHECK_TODO_REFS_ENABLED or policy.get("check_todo_refs", False)
+
+        if headers_on and self.require_header and lang_for(file_path) is not None:
+            first_10 = "\n".join(lines[:10])
+            if not re.search(r"Copyright\s+\(c\)", first_10):
+                findings.append(Finding(
+                    agent=self.name,
+                    severity=Severity.LOW,
+                    category="Missing Header",
+                    message="Missing copyright notice in file header",
+                    file=file_path,
+                    line=1,
+                    suggestion="Add copyright header with year and author.",
+                    blocker=Blocker.WARNS,
+                    confidence=1.0,
+                    rule_id="POL-101",
+                ))
+
+        banned = [
+            (r"debugger;", "Remove debugger statement", "POL-203"),
+            (r"alert\(", "Remove alert() - use proper UI components", "POL-204"),
+        ]
+        if console_on:
+            banned.append(
+                (r"console\.log\(", "Use structured logging instead of console.log",
+                 "POL-201")
+            )
+        # print() is legitimate in CLI tools and entry points. Only flag it
+        # in library/module code that has no argparse or __main__ guard, and
+        # only when the developer opted in.
+        is_cli_entry = bool(
+            re.search(r'argparse|__main__|def main\b', content)
+        )
+        docstrings = _docstring_lines(content)
+        spec = lang_for(file_path)
+        for pattern, message, rule_id in banned:
+            for i, line in enumerate(lines):
+                if _matches_code(pattern, line, i + 1, docstrings, spec):
+                    findings.append(Finding(
+                        agent=self.name,
+                        severity=Severity.LOW,
+                        category="Banned Pattern",
+                        message=message,
+                        file=file_path,
+                        line=i + 1,
+                        suggestion=message,
+                        blocker=Blocker.WARNS,
+                        confidence=1.0,
+                        rule_id=rule_id,
+                    ))
+        if print_on and not is_cli_entry:
+            for i, line in enumerate(lines):
+                if _matches_code(r'print\(', line, i + 1, docstrings, spec):
+                    findings.append(Finding(
+                        agent=self.name,
+                        severity=Severity.LOW,
+                        category="Banned Pattern",
+                        message="Use logging module instead of print()",
+                        file=file_path,
+                        line=i + 1,
+                        suggestion="Use logging module instead of print()",
+                        blocker=Blocker.WARNS,
+                        confidence=1.0,
+                        rule_id="POL-202",
+                    ))
+
+        if todo_refs_on:
+            for i, line in enumerate(lines):
+                match = re.search(r'TODO\s*\((\w+)\)', strip_literals(line, spec))
+                if match:
+                    issue_ref = match.group(1)
+                    if not re.match(r'^[A-Z]+-\d+$', issue_ref):
+                        findings.append(Finding(
+                            agent=self.name,
+                            severity=Severity.LOW,
+                            category="Invalid Issue Reference",
+                            message="TODO references '{}' - use format PROJECT-123".format(issue_ref),
+                            file=file_path,
+                            line=i + 1,
+                            suggestion="Use valid issue tracker reference.",
+                            blocker=Blocker.WARNS,
+                            confidence=0.90,
+                            rule_id="POL-205",
+                        ))
+
+        if headers_on:
+            findings.extend(_check_license_header(content, file_path, self.allowed_licenses))
+        findings.extend(_check_branch_naming(file_path))
+
+        return findings
+
+
+# SPDX-style license identifiers recognized in source headers.
+SPDX_LICENSES = {
+    "MIT": r"MIT",
+    "Apache-2.0": r"Apache[\-\s]?2\.0",
+    "BSD-3-Clause": r"BSD[\-\s]?3[\-\s]?Clause",
+    "ISC": r"\bISC\b",
+    "GPL-3.0": r"GPL[\-\s]?3\.0",
+    "MPL-2.0": r"MPL[\-\s]?2\.0",
+}
+
+
+def _strip_literals(line: str, spec=None) -> str:
+    """Remove single-line string/regex literals so patterns only match code.
+
+    Which characters open a comment and a string is a property of the language:
+    a rule that only knew ``#`` read a commented-out ``debugger;`` in Go or Rust
+    as a real statement.
+    """
+    return strip_literals(line, spec)
+
+
+def _docstring_lines(content: str) -> set:
+    """Line numbers (1-based) that belong to a module/class/function docstring.
+
+    A per-line stripper cannot know it is inside a triple-quoted block, so a
+    rule word quoted in a docstring (this module's own docs mention
+    `debugger;`) was reported as a real statement.
+    """
+    import ast
+
+    try:
+        tree = ast.parse(content)
+    except (SyntaxError, ValueError):
+        return set()
+
+    lines = set()
+
+    def _mark(node):
+        body = getattr(node, "body", None)
+        if not body:
+            return
+        first = body[0]
+        if (isinstance(first, ast.Expr)
+                and isinstance(first.value, ast.Constant)
+                and isinstance(first.value.value, str)):
+            for n in range(first.lineno, (first.end_lineno or first.lineno) + 1):
+                lines.add(n)
+
+    _mark(tree)
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            _mark(node)
+    return lines
+
+
+def _matches_code(pattern, line, lineno=None, docstrings=None, spec=None):
+    """True when ``pattern`` matches the line's code, ignoring literals."""
+    if docstrings and lineno in docstrings:
+        return False
+    return re.search(pattern, strip_literals(line, spec)) is not None
+
+
+def _check_license_header(content: str, file_path: str, allowed_licenses: list) -> List[Finding]:
+    """Verify the file header declares an allowed SPDX license."""
+    if lang_for(file_path) is None:
+        return []
+    findings = []
+    first_20 = "\n".join(content.split("\n")[:20])
+    found = None
+    for lic, pattern in SPDX_LICENSES.items():
+        if re.search(pattern, first_20):
+            found = lic
+            break
+    if found is None:
+        findings.append(Finding(
+            agent="policy",
+            severity=Severity.MEDIUM,
+            category="Missing License",
+            message="No SPDX license identifier found in header",
+            file=file_path,
+            line=1,
+            suggestion="Add an SPDX license identifier (e.g. 'SPDX-License-Identifier: MIT').",
+            blocker=Blocker.WARNS,
+            confidence=0.80,
+            rule_id="POL-206",
+        ))
+    elif allowed_licenses and found not in allowed_licenses:
+        findings.append(Finding(
+            agent="policy",
+            severity=Severity.MEDIUM,
+            category="Disallowed License",
+            message="License '{}' is not in allowed list {}".format(found, allowed_licenses),
+            file=file_path,
+            line=1,
+            suggestion="Use one of: {}".format(", ".join(allowed_licenses)),
+            blocker=Blocker.WARNS,
+            confidence=0.85,
+            rule_id="POL-207",
+        ))
+    return findings
+
+
+def _check_branch_naming(file_path: str) -> List[Finding]:
+    """Flag source files whose path implies a non-standard branch name."""
+    findings = []
+    # Only applies to files that live under a branch-shaped directory.
+    m = re.search(r'(?:^|[/\\])(feature|fix|hotfix|docs|chore|refactor|test|build|ci)(?:[/\\]|$)', file_path)
+    if m:
+        prefix = m.group(1)
+        if prefix not in ("feature", "fix", "hotfix", "docs", "chore", "refactor", "test", "build", "ci"):
+            findings.append(Finding(
+                agent="policy",
+                severity=Severity.LOW,
+                category="Branch Naming",
+                message="Branch prefix '{}' not in conventional set".format(prefix),
+                file=file_path,
+                line=1,
+                suggestion="Use: feature/, fix/, hotfix/, docs/, chore/, refactor/, test/, build/, ci/.",
+                blocker=Blocker.WARNS,
+                confidence=0.60,
+                rule_id="POL-208",
+            ))
+    return findings