codegraph-brain 0.6.0__py3-none-any.whl

cgis/guardian/skeptic.py

@@ -0,0 +1,208 @@
+"""Skeptic pass: one judgement per finding on two axes (spec §5, amended by #246).
+
+Each finding gets its own LLM call carrying only its file's hunks, and comes
+back with a ``verdict`` (is the claim true) and an ``impact_score`` 0-10 (does
+it matter). The batch call this replaced put every finding in one window and
+addressed verdicts by list index; it could neither rank nor survive a partial
+failure.
+"""
+
+import asyncio
+from collections.abc import Iterable
+from typing import Literal
+
+import structlog
+from pydantic import BaseModel, Field
+
+from cgis.guardian.diff_index import split_diff_by_file
+from cgis.guardian.findings import Finding, extract_json
+from cgis.guardian.providers.base import BaseProvider
+
+log = structlog.getLogger(__name__)
+
+_UNCERTAIN_MULTIPLIER = 0.9  # an 'uncertain' verdict discounts confidence as a
+# ranking signal only — it NEVER refutes. The recall-lean finder emits genuine
+# low-confidence findings on purpose; only an explicit 'refuted' verdict drops one.
+
+
+class FindingJudgement(BaseModel, frozen=True):
+    """One skeptic ruling on one finding, on two orthogonal axes (#246 spec §3.1).
+
+    ``verdict`` answers "is this claim true" and only an explicit 'refuted'
+    drops the finding. ``impact_score`` answers "does it matter" and only hides
+    below a threshold. There is no index: a judgement belongs to the call that
+    produced it, which is why the batch API's index-mapping failure modes
+    (out-of-range, duplicate) cannot occur here.
+    """
+
+    verdict: Literal["confirmed", "refuted", "uncertain"]
+    impact_score: int = Field(ge=0, le=10)
+    rationale: str
+
+
+# Confirm-by-default stance. The original refute-by-default wording over-killed
+# in benchmarks: a gemini-3.5-flash skeptic refuted 7/7 finder findings,
+# including 2 ground-truth matches on PR 122 (gate allows at most 1 lost match).
+# The finder is now recall-lean (no confidence gate, no cap), so it surfaces
+# genuine low-confidence findings BY DESIGN and leans on this pass for precision —
+# the skeptic must cut hallucinations without re-introducing the gate it removed.
+SKEPTIC_SYSTEM_PROMPT = (
+    "You are a skeptical senior reviewer double-checking another reviewer's findings. "
+    "That reviewer optimises for RECALL: it deliberately surfaces plausible, sometimes "
+    "low-confidence candidates and relies on you to remove only the ones that are wrong. "
+    "For each finding, verify the quoted evidence against the diff and judge whether the "
+    "claimed defect is real. Refute a finding ONLY when you can point to concrete evidence "
+    "that it is wrong: the quoted code does not appear in the diff, the case is already "
+    "handled, or the claim misreads what the code does. Do NOT refute a finding merely for "
+    "being low-confidence, speculative, or a judgement call — if it is plausible and you "
+    "cannot disprove it, mark it 'confirmed' or 'uncertain' (both are kept), never 'refuted'."
+)
+
+
+IMPACT_RUBRIC = """
+Also rate how much this finding MATTERS, independent of whether it is true,
+as impact_score 0-10:
+
+- 0-2  true but not actionable: style, taste, "consider X for explicitness",
+       or restating something the project's tooling already enforces.
+       If `ruff`, `ruff format` or `mypy --strict` would catch it, score <= 2:
+       those run as mandatory gates in this repo, so such issues are already
+       covered.
+- 3-5  a minor real issue: local clarity or robustness, no behaviour change.
+- 6-8  a real defect with a concrete failure path in this diff.
+- 9-10 a broken contract, a security hole, or data loss.
+
+A true finding can score 0. Scoring is NOT a second chance to refute: judge
+truth and importance independently."""
+
+
+def build_judgement_prompt(finding: Finding, hunks: str) -> str:
+    """Assemble the user prompt judging ONE finding against its own file's hunks.
+
+    The finder's ``confidence`` and ``severity`` are deliberately omitted: both
+    are its own guess at what this pass re-derives independently, and showing
+    them anchors the judge on the claim it is meant to check (#246 §3.3).
+    """
+    location = f"{finding.file}:{finding.line}" if finding.line is not None else finding.file
+    return f"""Another reviewer claims this diff contains a defect.
+
+### THE CLAIM
+Location: {location}
+Title: {finding.title}
+Quoted code: {finding.evidence}
+Problem: {finding.problem}
+Proposed fix: {finding.fix}
+
+### THE DIFF HUNKS FOR THAT FILE
+{hunks or "(no hunks available for this file)"}
+
+### HOW TO JUDGE
+Verify the quoted code against the hunks above. If the claim depends on code
+that is NOT in these hunks, you cannot check it: that is grounds for
+'uncertain', never for 'refuted'.
+{IMPACT_RUBRIC}
+
+### OUTPUT FORMAT
+Return ONLY a JSON object:
+{{"verdict": "confirmed|refuted|uncertain", "impact_score": 0, "rationale": "one sentence"}}"""
+
+
+DEFAULT_SKEPTIC_CONCURRENCY = 3
+# Bounded because provider rate limits are the binding constraint, not local CPU:
+# mistral's free tier caps tokens per MINUTE, and a local ollama skeptic
+# serialises on one model instance anyway.
+
+
+async def judge_finding(
+    provider: BaseProvider, finding: Finding, hunks: str
+) -> FindingJudgement | None:
+    """Judge one finding; None means this call failed (#246 §3.2).
+
+    Every failure mode — transport error, rate limit, unparseable output —
+    collapses to None so the caller keeps the finding unruled and visible. A
+    skeptic that cannot answer must never be able to silence a finding.
+    """
+    try:
+        raw = await provider.generate_structured(
+            SKEPTIC_SYSTEM_PROMPT, build_judgement_prompt(finding, hunks), FindingJudgement
+        )
+        return FindingJudgement.model_validate_json(extract_json(raw))
+    except Exception:
+        log.warning("Skeptic judgement failed; finding stays unruled.", file=finding.file)
+        return None
+
+
+def skeptic_status_for(judged: int, total: int) -> Literal["ok", "partial", "failed"]:
+    """Map judged/total onto the reported skeptic status (#246 §3.4).
+
+    Public and shared: the chunked orchestrator reports the same statuses, and
+    two copies of this mapping would be free to drift apart.
+    """
+    if judged == 0:
+        return "failed"
+    return "ok" if judged == total else "partial"
+
+
+async def judge_all(
+    provider: BaseProvider,
+    findings: list[Finding],
+    diff: str,
+    concurrency: int = DEFAULT_SKEPTIC_CONCURRENCY,
+) -> list[FindingJudgement | None]:
+    """Judge every finding concurrently, each against its own file's hunks.
+
+    Returns one entry per finding, positionally aligned, with None where that
+    finding's call failed — so a single failure costs one verdict instead of the
+    whole pass, which is what the batch call it replaces did.
+    """
+    blocks = split_diff_by_file(diff)
+    semaphore = asyncio.Semaphore(max(1, concurrency))
+
+    async def _one(finding: Finding) -> FindingJudgement | None:
+        async with semaphore:
+            return await judge_finding(provider, finding, blocks.get(finding.file, ""))
+
+    return list(await asyncio.gather(*(_one(f) for f in findings)))
+
+
+def apply_judgements(
+    findings: list[Finding], judgements: list[FindingJudgement | None]
+) -> list[Finding]:
+    """Merge per-finding judgements into new frozen copies, positionally (#246 §3.2).
+
+    ``judgements[i]`` rules on ``findings[i]``; a ``None`` means that call failed
+    and the finding stays unruled — absence of a judgement is not a refutation.
+    'uncertain' discounts confidence x0.9 as a ranking signal only, identical to
+    the batch merge it replaces.
+    """
+    merged: list[Finding] = []
+    for finding, judgement in zip(findings, judgements, strict=True):
+        if judgement is None:
+            merged.append(finding)
+            continue
+        update: dict[str, object] = {
+            "verdict": judgement.verdict,
+            "skeptic_note": judgement.rationale,
+            "impact_score": judgement.impact_score,
+        }
+        if judgement.verdict == "uncertain":
+            update["confidence"] = round(finding.confidence * _UNCERTAIN_MULTIPLIER)
+        merged.append(finding.model_copy(update=update))
+    return merged
+
+
+def visible_findings(findings: Iterable[Finding], threshold: int = 0) -> list[Finding]:
+    """Findings that appear in the rendered report (#246 §3.2).
+
+    Hidden: anything refuted, and anything the skeptic scored below
+    ``threshold``. An unjudged finding (``impact_score is None``) has no score to
+    compare and is always shown — a failed judgement call must never silence a
+    finding. Hidden findings stay in ``ReviewResult.findings`` so metrics and the
+    benchmark still see what was cut.
+    """
+    return [
+        f
+        for f in findings
+        if f.verdict != "refuted"
+        and not (f.impact_score is not None and f.impact_score < threshold)
+    ]

cgis/pipeline.py

@@ -0,0 +1,252 @@
+"""Implements Pipeline to orcestrate code traversal."""
+
+import hashlib
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import structlog
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from cgis.core.models import Edge, Node
+from cgis.extractors.base import BaseExtractor
+from cgis.resolver.engine import ResolverEngine
+from cgis.resolver.uplift import SemanticUpliftEngine
+
+if TYPE_CHECKING:
+    from cgis.storage.sqlite_store import SQLiteStore
+
+logger = structlog.getLogger(__name__)
+
+
+class IngestionPipeline:
+    """Orchestrates the full Extract → Resolve → Store pipeline over a source tree."""
+
+    _extractors: Mapping[str, BaseExtractor]
+    _domains_config: str | None
+
+    def __init__(
+        self,
+        extractors: Mapping[str, BaseExtractor],
+        domains_config: str | None = None,
+    ) -> None:
+        """
+        Args:
+            extractors: Map of file extensions to their respective extractors.
+                        e.g., {".py": PythonExtractor()}
+            domains_config: Optional path to a domains.yaml file. When provided,
+                            the SemanticUpliftEngine runs after resolution.
+        """
+        self._extractors = extractors
+        self._domains_config = domains_config
+        self._excluded = {"venv", ".venv", "__pycache__", "node_modules", "build", "dist"}
+
+    @staticmethod
+    def _compute_hash(content: str) -> str:
+        """Return the MD5 hex digest of the given source content string."""
+        return hashlib.md5(content.encode("utf-8"), usedforsecurity=False).hexdigest()
+
+    def run(
+        self,
+        repo_path: str,
+        store: "SQLiteStore | None" = None,
+    ) -> tuple[list[Node], list[Edge], list[Edge]]:
+        """
+        The main pipeline execution: Walk -> Extract -> Resolve.
+
+        When `store` is provided the pipeline runs in incremental mode:
+        unchanged files (same MD5) are skipped and their nodes are loaded
+        from the store for the resolver. Only changed/new files are
+        re-extracted and persisted. Stale files (removed from disk) are
+        cleaned up automatically.
+        """
+        all_nodes: list[Node] = []
+        all_edges: list[Edge] = []
+        # file_path -> new hash, only for files that were re-extracted
+        changed_files: dict[str, str] = {}
+        found_file_paths: set[str] = set()
+
+        path = Path(repo_path)
+        if not path.exists():
+            msg = f"Path not found: {repo_path}"
+            raise FileNotFoundError(msg)
+        if not path.is_dir():
+            msg = f"Path is not a directory: {repo_path}"
+            raise NotADirectoryError(msg)
+
+        # Canonical workspace root: resolve symlinks + relative dots so that
+        # both `cgis ingest ./src` and `cgis ingest /abs/path/src` produce
+        # identical file_paths and FQNs in the database.
+        workspace_root = path.resolve()
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            transient=True,
+            console=Console(stderr=True),
+        ) as progress:
+            # Task 1: Extraction
+            extract_task = progress.add_task(description="Extracting code entities...", total=None)
+
+            for root, dirs, files in workspace_root.walk():
+                dirs[:] = [d for d in dirs if not d.startswith(".") and d not in self._excluded]
+                for file in files:
+                    extractor = self._get_extractor(file)
+                    if not extractor:
+                        continue
+
+                    full_path = root / file
+                    try:
+                        # Resolve symlinks before relativising so that a link
+                        # pointing outside the workspace is caught and skipped.
+                        rel_path_str = full_path.resolve().relative_to(workspace_root).as_posix()
+                    except ValueError:
+                        logger.warning("File outside workspace root, skipping", file=str(full_path))
+                        continue
+                    found_file_paths.add(rel_path_str)
+
+                    self._process_file(
+                        full_path,
+                        rel_path_str,
+                        extractor,
+                        store,
+                        all_nodes,
+                        all_edges,
+                        changed_files,
+                    )
+
+                    progress.update(extract_task, advance=1)
+
+            # Incremental no-op short-circuit (#185): when nothing changed and
+            # nothing went stale, the persisted graph is already correct.
+            # Re-running the resolver + persistence + uplift would rebuild the
+            # whole graph from the DB for zero benefit, so skip them entirely.
+            if store is not None and self._is_noop_incremental(
+                store, changed_files, found_file_paths
+            ):
+                logger.info("No changes detected — skipping resolution and persistence.")
+                return all_nodes, all_edges, []
+
+            # Task 2: Resolution
+            resolve_task = progress.add_task(description="Resolving semantic links...", total=None)
+            logger.info("Starting resolution phase...")
+            resolver = ResolverEngine(all_nodes, all_edges)
+            resolved_edges, virtual_nodes = resolver.resolve()
+            all_nodes.extend(virtual_nodes)
+            progress.update(resolve_task, advance=1)
+            logger.info(
+                "Resolution complete.",
+                edges=len(resolved_edges),
+                virtual_nodes=len(virtual_nodes),
+            )
+
+        if store is not None:
+            self._persist_incremental(
+                store, all_nodes, resolved_edges, changed_files, found_file_paths, virtual_nodes
+            )
+            logger.info("Running semantic uplift...")
+            SemanticUpliftEngine(store, self._domains_config).execute_uplift()
+            logger.info("Semantic uplift complete.")
+
+        return all_nodes, all_edges, resolved_edges
+
+    def _process_file(
+        self,
+        full_path: Path,
+        full_path_str: str,
+        extractor: BaseExtractor,
+        store: "SQLiteStore | None",
+        all_nodes: list[Node],
+        all_edges: list[Edge],
+        changed_files: dict[str, str],
+    ) -> None:
+        """Extract nodes/edges from one file, applying hash-based skip when store is provided."""
+        try:
+            with full_path.open(encoding="utf-8") as f:
+                code = f.read()
+
+            if store is not None:
+                file_hash = self._compute_hash(code)
+                if store.get_file_hash(full_path_str) == file_hash:
+                    all_nodes.extend(store.get_nodes_by_file(full_path_str))
+                    return
+                changed_files[full_path_str] = file_hash
+
+            nodes, edges = extractor.parse(code, full_path_str)
+            if nodes:
+                logger.info("Parsed nodes from file", nodes=len(nodes), full_path=full_path_str)
+            all_nodes.extend(nodes)
+            all_edges.extend(edges)
+        except Exception as e:
+            logger.exception("Failed to parse file", full_path=full_path, error=str(e))
+
+    def _is_noop_incremental(
+        self, store: "SQLiteStore", changed_files: dict[str, str], found_file_paths: set[str]
+    ) -> bool:
+        """True when an incremental run can be skipped entirely.
+
+        Requires no re-extracted files and no stale files. A configured domains
+        ontology also disables the skip: ``domains.yaml`` can change independently
+        of the source tree, and the semantic uplift that applies it must re-run
+        to pick those changes up (it is not tracked in ``changed_files``).
+
+        ``changed_files`` / ``domains_config`` are checked before the
+        ``get_all_tracked_files`` DB query so it is only issued when it can
+        actually change the outcome.
+        """
+        if changed_files or self._domains_config is not None:
+            return False
+        stale_files = store.get_all_tracked_files() - found_file_paths
+        return not stale_files
+
+    def _persist_incremental(
+        self,
+        store: "SQLiteStore",
+        all_nodes: list[Node],
+        resolved_edges: list[Edge],
+        changed_files: dict[str, str],
+        found_file_paths: set[str],
+        virtual_nodes: list[Node] | None = None,
+    ) -> None:
+        """Persist only changed files and clean up stale ones in one transaction."""
+        nodes_by_file: dict[str, list[Node]] = {}
+        for node in all_nodes:
+            if node.file_path in changed_files:
+                nodes_by_file.setdefault(node.file_path, []).append(node)
+
+        # Map source node → file so structural edges (file_path=None) can be assigned
+        source_to_file: dict[str, str] = {
+            node.id: node.file_path for node in all_nodes if node.file_path in changed_files
+        }
+        edges_by_file: dict[str, list[Edge]] = {}
+        for edge in resolved_edges:
+            file_path = edge.file_path or source_to_file.get(edge.source)
+            if file_path and file_path in changed_files:
+                edges_by_file.setdefault(file_path, []).append(edge)
+
+        stale_files = store.get_all_tracked_files() - found_file_paths
+        store.save_incremental_batch(nodes_by_file, edges_by_file, changed_files, stale_files)
+
+        # Virtual nodes are upserted separately — never deleted — because in incremental
+        # mode only changed files' edges are re-resolved, so virtual_nodes is incomplete.
+        # Orphaned virtual nodes (no incoming edges) are harmless phantom data.
+        if virtual_nodes:
+            store.upsert_nodes(virtual_nodes)
+
+        for file_path in changed_files:
+            logger.info("Re-ingested changed file", file_path=file_path)
+        for stale_path in stale_files:
+            logger.info("Removed stale file from graph", file_path=stale_path)
+
+    _TEST_FILE_PATTERN = re.compile(r"\.(test|spec)\.(py|ts|tsx|js|jsx)$", re.IGNORECASE)
+
+    def _get_extractor(self, filename: str) -> BaseExtractor | None:
+        """Return the registered extractor for the given filename, or None."""
+        if self._TEST_FILE_PATTERN.search(filename):
+            return None
+        for ext, extractor in self._extractors.items():
+            if filename.endswith(ext):
+                return extractor
+        return None