slopgate-cli 0.1.0__py3-none-any.whl

slopgate/phantom.py

@@ -0,0 +1,388 @@
+"""
+Phantom Symbol & Hallucinated Import Detector.
+Catches packages, modules, and API calls invented by LLMs that do not exist
+in Python standard library, project manifests, or local repository files.
+"""
+
+import ast
+import re
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import List, Optional, Set
+
+from slopgate.diff_parser import FileDiff
+from slopgate.fragment import Fragment
+
+
+class PhantomKind(str, Enum):
+    HALLUCINATED_IMPORT = "HALLUCINATED_IMPORT"
+    HALLUCINATED_STDLIB_METHOD = "HALLUCINATED_STDLIB_METHOD"
+
+
+@dataclass
+class PhantomIncident:
+    kind: PhantomKind
+    file_path: str
+    line_number: int
+    symbol: str
+    message: str
+
+
+def _normalize(name: str) -> str:
+    """Normalizes a distribution or module name for comparison (PEP 503-ish)."""
+    name = name.split("[")[0]
+    name = re.split(r"[<>=~!;\s]", name)[0]
+    return name.strip().replace("-", "_").replace(".", "_").lower()
+
+
+class PhantomDetector:
+    """Detects phantom imports and hallucinated APIs added in diffs."""
+
+    # Python stdlib modules set (built-in in Python 3.10+)
+    STDLIB_MODULES: Set[str] = (
+        set(sys.stdlib_module_names)
+        if hasattr(sys, "stdlib_module_names")
+        else {
+            "os",
+            "sys",
+            "re",
+            "json",
+            "ast",
+            "math",
+            "time",
+            "datetime",
+            "typing",
+            "pathlib",
+            "collections",
+            "itertools",
+            "functools",
+            "unittest",
+            "logging",
+            "urllib",
+            "http",
+            "hashlib",
+            "subprocess",
+            "shutil",
+            "tempfile",
+            "io",
+            "string",
+            "copy",
+            "socket",
+        }
+    )
+
+    # Import name != distribution name for these packages.
+    # shortcut: fixed alias table covers the common offenders, extend it when a
+    # false positive is reported.
+    IMPORT_ALIASES = {
+        "yaml": "pyyaml",
+        "cv2": "opencv_python",
+        "pil": "pillow",
+        "bs4": "beautifulsoup4",
+        "skimage": "scikit_image",
+        "sklearn": "scikit_learn",
+        "dateutil": "python_dateutil",
+        "dotenv": "python_dotenv",
+        "jwt": "pyjwt",
+        "serial": "pyserial",
+        "openssl": "pyopenssl",
+        "crypto": "pycryptodome",
+        "usb": "pyusb",
+        "attr": "attrs",
+        "gi": "pygobject",
+    }
+
+    # Common hallucinated methods on standard library objects
+    KNOWN_STDLIB_HALLUCINATIONS = {
+        ("json", "loads_async"): "json has no async loads method.",
+        ("json", "parse"): "json uses .loads(), not .parse().",
+        ("os", "mkdir_p"): "os uses os.makedirs(..., exist_ok=True).",
+        ("re", "match_all"): "re uses .findall() or .finditer(), not .match_all().",
+        ("time", "sleep_async"): "time has no sleep_async; use asyncio.sleep().",
+        (
+            "sys",
+            "print",
+        ): "sys has no print method; use builtin print() or sys.stdout.write().",
+    }
+
+    @classmethod
+    def get_declared_dependencies(cls, repo_root: Optional[Path] = None) -> Set[str]:
+        """Scans dependency manifests and local modules to extract valid import names."""
+        deps: Set[str] = set()
+        repo_root = repo_root or Path.cwd()
+
+        # 1. requirements.txt, requirements/*.txt, requirements-*.txt
+        req_files = list(repo_root.glob("*requirement*.txt")) + list(
+            repo_root.glob("requirements/*.txt")
+        )
+        for req_file in sorted(set(req_files)):
+            cls._read_requirements_file(req_file, deps)
+
+        # 2. setup.py install_requires=[...]
+        setup_py = repo_root / "setup.py"
+        if setup_py.exists():
+            try:
+                content = setup_py.read_text(encoding="utf-8", errors="ignore")
+                block = re.search(r"install_requires\s*=\s*\[(.*?)\]", content, re.S)
+                if block:
+                    for match in re.finditer(r'["\']([^"\']+)["\']', block.group(1)):
+                        deps.add(_normalize(match.group(1)))
+            except Exception:
+                pass
+
+        # 3. setup.cfg [options] install_requires
+        setup_cfg = repo_root / "setup.cfg"
+        if setup_cfg.exists():
+            try:
+                content = setup_cfg.read_text(encoding="utf-8", errors="ignore")
+                block = re.search(
+                    r"(?ms)^install_requires\s*=\s*\n(.*?)(?=^\S|\Z)", content
+                )
+                if block:
+                    cls._read_requirement_lines(block.group(1), deps)
+            except Exception:
+                pass
+
+        # 4. environment.yml (conda)
+        for env_file in (repo_root / "environment.yml", repo_root / "environment.yaml"):
+            if not env_file.exists():
+                continue
+            try:
+                content = env_file.read_text(encoding="utf-8", errors="ignore")
+                for line in content.splitlines():
+                    stripped = line.strip()
+                    if stripped.startswith("- ") and "::" not in stripped:
+                        deps.add(_normalize(stripped[2:]))
+            except Exception:
+                pass
+
+        # 5. Pipfile [packages] / [dev-packages]
+        pipfile = repo_root / "Pipfile"
+        if pipfile.exists():
+            try:
+                content = pipfile.read_text(encoding="utf-8", errors="ignore")
+                section = ""
+                for line in content.splitlines():
+                    stripped = line.strip()
+                    if stripped.startswith("["):
+                        section = stripped.strip("[]").lower()
+                    elif section in ("packages", "dev-packages") and "=" in stripped:
+                        deps.add(_normalize(stripped.split("=")[0].strip(' "')))
+            except Exception:
+                pass
+
+        # 6. pyproject.toml: only dependency sections, not every quoted string
+        pyproject = repo_root / "pyproject.toml"
+        if pyproject.exists():
+            try:
+                cls._read_pyproject(
+                    pyproject.read_text(encoding="utf-8", errors="ignore"), deps
+                )
+            except Exception:
+                pass
+
+        # 7. Local repo top-level packages & modules
+        for p in repo_root.glob("*.py"):
+            deps.add(p.stem.lower())
+        for pattern in ("*/__init__.py", "src/*.py", "src/*/__init__.py"):
+            for p in repo_root.glob(pattern):
+                deps.add(
+                    p.stem.lower() if p.name != "__init__.py" else p.parent.name.lower()
+                )
+
+        return deps
+
+    @classmethod
+    def _read_requirements_file(cls, path: Path, deps: Set[str], depth: int = 0):
+        """Reads a requirements file, following `-r` includes one level deep."""
+        if depth > 5:
+            return
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+        except Exception:
+            return
+        for line in text.splitlines():
+            stripped = line.strip().split("#")[0].strip()
+            if not stripped:
+                continue
+            if stripped.startswith(("-r ", "--requirement ")):
+                included = stripped.split(None, 1)[1].strip().strip("'\"")
+                cls._read_requirements_file(path.parent / included, deps, depth + 1)
+                continue
+            if stripped.startswith("-") or "://" in stripped:
+                continue
+            deps.add(_normalize(stripped))
+
+    @classmethod
+    def _read_requirement_lines(cls, text: str, deps: Set[str]):
+        for line in text.splitlines():
+            line = line.strip().split("#")[0]
+            if not line or line.startswith(("-", "http", "git+", "--")):
+                continue
+            pkg = _normalize(line)
+            if pkg:
+                deps.add(pkg)
+
+    @classmethod
+    def _read_pyproject(cls, content: str, deps: Set[str]):
+        section = ""
+        in_deps = False
+        for line in content.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("[") and stripped.endswith("]"):
+                section = stripped.strip("[]").strip()
+                in_deps = False
+                continue
+
+            poetry_deps = section.startswith(
+                (
+                    "tool.poetry.dependencies",
+                    "tool.poetry.dev-dependencies",
+                    "tool.poetry.group",
+                )
+            )
+            dependency_section = (
+                section
+                in (
+                    "project.optional-dependencies",
+                    "dependency-groups",
+                    "build-system",
+                )
+                or poetry_deps
+            )
+            if re.match(r"^dependencies\s*=\s*\[", stripped):
+                in_deps = True
+
+            # Poetry declares packages as bare keys: requests = "^2.31"
+            if poetry_deps and "=" in stripped and not stripped.startswith("#"):
+                key = stripped.split("=")[0].strip().strip("\"'")
+                if key and key != "python":
+                    deps.add(_normalize(key))
+
+            if in_deps or dependency_section:
+                for match in re.finditer(r'["\']([A-Za-z0-9_.\-]+)', stripped):
+                    deps.add(_normalize(match.group(1)))
+
+            if in_deps and "]" in stripped:
+                in_deps = False
+
+    @classmethod
+    def analyze_file(
+        cls, file_diff: FileDiff, declared_deps: Set[str]
+    ) -> List[PhantomIncident]:
+        incidents: List[PhantomIncident] = []
+        if not file_diff.is_python or file_diff.is_deleted:
+            return incidents
+
+        fragment = Fragment(file_diff)
+        if not fragment.text.strip():
+            return incidents
+
+        tree, offset = fragment.parse()
+        if tree is not None:
+            return cls._scan_tree(
+                tree,
+                file_diff,
+                lambda lineno: fragment.real_line(lineno, offset),
+                declared_deps,
+            )
+
+        # Unparseable fragment (a hunk can start mid-expression): scan each added
+        # line on its own. Single-line strings parse as expressions, not calls.
+        # shortcut: statement-shaped prose inside a docstring of an unparseable
+        # hunk can still be flagged; upgrade to tokenize-based skipping if reported.
+        covered = fragment.string_lines()
+        for idx, (ln, line) in enumerate(file_diff.added_lines, start=1):
+            if idx in covered:
+                continue
+            try:
+                line_tree = ast.parse(line.strip())
+            except SyntaxError:
+                continue
+            incidents.extend(
+                cls._scan_tree(
+                    line_tree, file_diff, lambda _lineno, ln=ln: ln, declared_deps
+                )
+            )
+        return incidents
+
+    @classmethod
+    def _scan_tree(cls, tree, file_diff, line_of, declared_deps: Set[str]):
+        incidents: List[PhantomIncident] = []
+        for node in ast.walk(tree):
+            # Check `import x`
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    top_pkg = alias.name.split(".")[0]
+                    if not cls._is_known_package(top_pkg, declared_deps):
+                        incidents.append(
+                            PhantomIncident(
+                                kind=PhantomKind.HALLUCINATED_IMPORT,
+                                file_path=file_diff.target_path,
+                                line_number=line_of(getattr(node, "lineno", 1)),
+                                symbol=alias.name,
+                                message=f"Package '{alias.name}' is not in stdlib, project dependencies, or local modules.",
+                            )
+                        )
+
+            # Check `from x import y`
+            elif isinstance(node, ast.ImportFrom):
+                # Relative imports (from . import x) always resolve inside the package
+                if node.module and not node.level:
+                    top_pkg = node.module.split(".")[0]
+                    if not cls._is_known_package(top_pkg, declared_deps):
+                        incidents.append(
+                            PhantomIncident(
+                                kind=PhantomKind.HALLUCINATED_IMPORT,
+                                file_path=file_diff.target_path,
+                                line_number=line_of(getattr(node, "lineno", 1)),
+                                symbol=node.module,
+                                message=f"Module '{node.module}' is not in stdlib, project dependencies, or local modules.",
+                            )
+                        )
+
+            # Check hallucinated stdlib method calls (e.g. json.loads_async)
+            elif isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
+                if isinstance(node.func.value, ast.Name):
+                    mod_name = node.func.value.id
+                    attr_name = node.func.attr
+                    key = (mod_name, attr_name)
+                    if key in cls.KNOWN_STDLIB_HALLUCINATIONS:
+                        incidents.append(
+                            PhantomIncident(
+                                kind=PhantomKind.HALLUCINATED_STDLIB_METHOD,
+                                file_path=file_diff.target_path,
+                                line_number=line_of(getattr(node, "lineno", 1)),
+                                symbol=f"{mod_name}.{attr_name}",
+                                message=cls.KNOWN_STDLIB_HALLUCINATIONS[key],
+                            )
+                        )
+
+        return incidents
+
+    @classmethod
+    def _is_known_package(cls, pkg_name: str, declared_deps: Set[str]) -> bool:
+        pkg_clean = _normalize(pkg_name)
+        if pkg_clean in cls.STDLIB_MODULES:
+            return True
+        if pkg_clean in declared_deps:
+            return True
+        alias = cls.IMPORT_ALIASES.get(pkg_clean)
+        if alias and alias in declared_deps:
+            return True
+        # Namespaced distributions: import `google.cloud.x` is served by
+        # `google-cloud-storage` (normalized prefix match).
+        if any(dep.startswith(pkg_clean + "_") for dep in declared_deps):
+            return True
+        # Common build / test tooling usually injected by CI
+        if pkg_clean in {
+            "pytest",
+            "unittest",
+            "setuptools",
+            "wheel",
+            "typing_extensions",
+        }:
+            return True
+        return False

slopgate/reporter.py

@@ -0,0 +1,205 @@
+"""
+Multi-Channel Output Formatter.
+Outputs human-friendly ANSI terminal displays, GitHub Step Summaries,
+PR review comments, and structured JSON.
+"""
+
+import json
+import os
+import sys
+
+from slopgate.engine import AuditReport, Severity
+
+
+def _color(code: str) -> str:
+    """Disables ANSI when piping output or when NO_COLOR is set."""
+    if os.environ.get("NO_COLOR"):
+        return ""
+    stream = sys.stdout
+    return code if stream is not None and stream.isatty() else ""
+
+
+class AnsiColor:
+    RESET = _color("\033[0m")
+    BOLD = _color("\033[1m")
+    RED = _color("\033[31m")
+    GREEN = _color("\033[32m")
+    YELLOW = _color("\033[33m")
+    CYAN = _color("\033[36m")
+    GRAY = _color("\033[90m")
+
+
+def _escape_data(value: str) -> str:
+    return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def _escape_property(value: str) -> str:
+    return _escape_data(value).replace(":", "%3A").replace(",", "%2C")
+
+
+class Reporter:
+    """Formats AuditReport for CLI, GitHub Actions, and JSON pipelines."""
+
+    @classmethod
+    def render_terminal(cls, report: AuditReport) -> str:
+        lines = []
+        # Header Box
+        lines.append(
+            f"{AnsiColor.CYAN}======================================================={AnsiColor.RESET}"
+        )
+        lines.append(
+            f"{AnsiColor.BOLD}{AnsiColor.CYAN} 🛡️  SLOPGATE — Code & PR Integrity Shield {AnsiColor.RESET}"
+        )
+        lines.append(
+            f"{AnsiColor.CYAN}======================================================={AnsiColor.RESET}"
+        )
+
+        # Metrics
+        m = report.metrics
+        lines.append(
+            f" {AnsiColor.GRAY}Diff:{AnsiColor.RESET} {m.files_changed} files | "
+            f"{AnsiColor.GREEN}+{m.total_added}{AnsiColor.RESET} / "
+            f"{AnsiColor.RED}-{m.total_removed}{AnsiColor.RESET} | "
+            f"Code: +{m.code_added} | Tests: +{m.test_added} | Docs: +{m.doc_added}"
+        )
+
+        # Status
+        if report.status == Severity.BLOCKED:
+            status_badge = f"{AnsiColor.BOLD}{AnsiColor.RED}[BLOCKED]{AnsiColor.RESET}"
+        elif report.status == Severity.WARNING:
+            status_badge = (
+                f"{AnsiColor.BOLD}{AnsiColor.YELLOW}[WARNING]{AnsiColor.RESET}"
+            )
+        else:
+            status_badge = f"{AnsiColor.BOLD}{AnsiColor.GREEN}[PASSED]{AnsiColor.RESET}"
+
+        lines.append(f" Status: {status_badge} {report.summary}")
+        lines.append("")
+
+        # Violations Table
+        if report.violations:
+            lines.append(f"{AnsiColor.BOLD}Violations Detected:{AnsiColor.RESET}")
+            for v in report.violations:
+                color = (
+                    AnsiColor.RED
+                    if v.severity == Severity.BLOCKED
+                    else AnsiColor.YELLOW
+                )
+                lines.append(
+                    f"  • {color}[{v.rule_id}]{AnsiColor.RESET} {AnsiColor.BOLD}{v.title}{AnsiColor.RESET}"
+                )
+                lines.append(f"    Location: {v.file_path}:{v.line_number}")
+                lines.append(f"    Details:  {v.message}")
+                if v.snippet:
+                    lines.append(
+                        f"    Snippet:  {AnsiColor.GRAY}{v.snippet}{AnsiColor.RESET}"
+                    )
+                lines.append("")
+        else:
+            lines.append(
+                f"  {AnsiColor.GREEN}✨ Zero integrity violations found. Clean PR!{AnsiColor.RESET}\n"
+            )
+
+        lines.append(
+            f"{AnsiColor.CYAN}-------------------------------------------------------{AnsiColor.RESET}"
+        )
+        return "\n".join(lines)
+
+    @classmethod
+    def render_github_markdown(cls, report: AuditReport) -> str:
+        """Formats markdown for GitHub Step Summary and PR comments."""
+        if report.status == Severity.BLOCKED:
+            badge = "![SlopGate Status](https://img.shields.io/badge/SlopGate-BLOCKED-red?style=for-the-badge)"
+            callout = "> [!CAUTION]\n> **PR Blocked by SlopGate**: Critical code/test integrity violations detected."
+        elif report.status == Severity.WARNING:
+            badge = "![SlopGate Status](https://img.shields.io/badge/SlopGate-WARNING-yellow?style=for-the-badge)"
+            callout = "> [!WARNING]\n> **SlopGate Warning**: Non-critical suggestions detected."
+        else:
+            badge = "![SlopGate Status](https://img.shields.io/badge/SlopGate-PASSED-brightgreen?style=for-the-badge)"
+            callout = "> [!NOTE]\n> **SlopGate Audit Passed**: All test assertions intact and symbols verified."
+
+        lines = [
+            f"# {badge}",
+            "",
+            callout,
+            "",
+            "### 📊 Diff Metrics",
+            "| Metric | Value |",
+            "| --- | --- |",
+            f"| **Files Changed** | `{report.metrics.files_changed}` |",
+            f"| **Logic Added** | `+{report.metrics.code_added}` lines |",
+            f"| **Tests Added** | `+{report.metrics.test_added}` lines |",
+            f"| **Docs / Comments** | `+{report.metrics.doc_added}` lines |",
+            f"| **Repro Test Verified** | `{'✅ Yes' if report.repro_verified else '⚠️ No'}` |",
+            "",
+        ]
+
+        if report.violations:
+            lines.extend(
+                [
+                    "### 🔍 Integrity Findings",
+                    "| Severity | Rule | File & Line | Message |",
+                    "| :---: | :---: | :--- | :--- |",
+                ]
+            )
+            for v in report.violations:
+                sev_icon = (
+                    "⛔ `BLOCKED`" if v.severity == Severity.BLOCKED else "⚠️ `WARNING`"
+                )
+                lines.append(
+                    f"| {sev_icon} | `{v.rule_id}` | `{v.file_path}:{v.line_number}` | {v.message} |"
+                )
+
+        lines.append("")
+        lines.append("---")
+        lines.append(
+            "*Protected by [SlopGate](https://github.com/Shinraya-Tech-Labs/slopgate) — The AST Code Integrity Shield for Open Source.*"
+        )
+
+        return "\n".join(lines)
+
+    @classmethod
+    def render_github_annotations(cls, report: AuditReport) -> str:
+        """Formats GitHub Actions workflow command annotations (::error:: and ::warning::)."""
+        lines = []
+        for v in report.violations:
+            cmd = "error" if v.severity == Severity.BLOCKED else "warning"
+            props = (
+                f"file={_escape_property(v.file_path)},"
+                f"line={v.line_number},"
+                f"title={_escape_property(v.title)}"
+            )
+            lines.append(f"::{cmd} {props}::{_escape_data(v.message)}")
+        return "\n".join(lines)
+
+    @classmethod
+    def render_json(cls, report: AuditReport) -> str:
+        data = {
+            "status": report.status.value,
+            "is_clean": report.is_clean,
+            "not_blocked": report.not_blocked,
+            "summary": report.summary,
+            "repro_verified": report.repro_verified,
+            "metrics": {
+                "files_changed": report.metrics.files_changed,
+                "total_added": report.metrics.total_added,
+                "total_removed": report.metrics.total_removed,
+                "code_added": report.metrics.code_added,
+                "test_added": report.metrics.test_added,
+                "doc_added": report.metrics.doc_added,
+                "slop_ratio": round(report.metrics.slop_ratio, 2),
+            },
+            "violations": [
+                {
+                    "rule_id": v.rule_id,
+                    "severity": v.severity.value,
+                    "file_path": v.file_path,
+                    "line_number": v.line_number,
+                    "title": v.title,
+                    "message": v.message,
+                    "snippet": v.snippet,
+                }
+                for v in report.violations
+            ],
+        }
+        return json.dumps(data, indent=2)