adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/cli/commands.py

@@ -0,0 +1,993 @@
+"""Command implementations.
+
+Business logic backing the CLI commands.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import List, Dict, Set, Tuple, Any, Optional
+
+from adl_drift.detectors.base import DetectorRegistry
+from adl_drift.lang.registry import backend_for_file, detect_backends, get_backend
+from adl_drift.cortex.memory import CortexMemory, GRAPH_CACHE_RACY_WINDOW_SECONDS
+from adl_drift.cortex.patterns import PatternManager
+from adl_drift.cortex.telemetry import TelemetryRecorder
+from adl_drift.graph.builder import CallGraphBuilder
+from adl_drift.scanner.incremental import (
+    IncrementalScanner,
+    java_declaration_fingerprint,
+    java_incremental_scope,
+)
+from adl_drift.scanner.parallel import parallel_analyze, should_parallelize
+from adl_drift.scanner.discovery import discover_file_groups, discover_files, select_backend
+
+
+from adl_drift.utils.types import (
+    LOCALS_MARKER, SCAN_FILE_ERRORS, Pattern, PatternCategory, ProjectContext, SourcePosition,
+)
+from typing import Callable
+
+
+class DriftCommands:
+    """Implements all CLI commands."""
+
+    def __init__(self, project_path: Path):
+        self.project_path = project_path
+        # P2.5: per-file errors from the most recent scan() call —
+        # [{"file": str, "error": str}]. Read by the CLI for the summary line.
+        self.last_scan_errors: List[Dict[str, str]] = []
+        # Baseline context from the most recent scan() call (files, LOC, symbols, ...).
+        self.last_scan_context: Optional[ProjectContext] = None
+        # Explains whether the latest graph update was dependency-scoped or
+        # deliberately fell back to a full rebuild. Consumed by P6 metrics and
+        # useful to callers that must not mistake a safe fallback for a fast
+        # incremental update.
+        self.last_graph_update: Dict[str, Any] = {}
+        self.project_root = CallGraphBuilder.find_project_root(project_path) or project_path
+        self.memory = CortexMemory.for_project(self.project_root)
+        self.pattern_manager = PatternManager(self.memory)
+        # PM.2: CLI queries record the same telemetry the MCP path does, tagged
+        # source="cli" so the monitor can tell agent calls from shell calls.
+        self._telemetry = TelemetryRecorder(self.memory, self.project_root)
+
+        self.backend = None
+        # Language detection and the build-file config for a root are reused
+        # by `_file_groups` for that same root: a CLI invocation otherwise
+        # walked the whole tree and parsed every build file twice per query.
+        self._detected_root: Optional[Path] = None
+        self._detected_backends: Optional[List[Any]] = None
+        self._config_root: Optional[Path] = None
+        self._configure_backend(project_path)
+
+    def _configure_backend(self, path: Path, backend_name: Optional[str] = None) -> None:
+        if backend_name:
+            backend = get_backend(backend_name)
+        else:
+            self._detected_backends = detect_backends(path)
+            self._detected_root = path
+            backend = select_backend(path, candidates=self._detected_backends)
+        if self.backend is not None and self.backend.name == backend.name:
+            return
+        self.backend = backend
+        self.config = backend.project_config(path)
+        self._config_root = path
+        self.parser = backend.parser()
+        self.extractor = backend.extractor()
+        self.registry = DetectorRegistry(backend.detectors())
+        security = self.registry.get_for_category(PatternCategory.SECURITY)
+        self._security_detector = security[0] if security else None
+
+    def _resolver_config(self):
+        return self.backend.resolver_config()
+
+    def _route_patterns(self, parse_result: Any, file_path: Path) -> List[Pattern]:
+        """ROUTES-only detection for the structural-only graph-build path.
+
+        `build_graph()` (unlike `scan()`) never runs the full detector set,
+        but callers (impact/caller/callee/path queries) still need route
+        handlers marked as entry points (`graph/builder.py` reads
+        `result.patterns` for this). Mirrors
+        `MCPHandlers._route_patterns` (server/handlers.py).
+        """
+        patterns: List[Pattern] = []
+        for detector in self.registry.get_for_category(PatternCategory.ROUTES):
+            try:
+                patterns.extend(detector.detect(parse_result.tree, parse_result.source_bytes, file_path))
+            except Exception:
+                continue
+        return patterns
+
+    @staticmethod
+    def _backend_name(file_path: Path) -> str:
+        backend = backend_for_file(file_path)
+        return backend.name if backend else "python"
+
+    def _file_groups(self, path: Path, language: Optional[str] = None) -> Dict[str, List[Path]]:
+        configs = (
+            {self.backend.name: self.config}
+            if self.backend is not None and path == self._config_root else {}
+        )
+        if language:
+            files = discover_files(path, get_backend(language), config=configs.get(language))
+            return {language: files} if files else {}
+        return discover_file_groups(
+            path,
+            backends=self._detected_backends if path == self._detected_root else None,
+            configs=configs,
+        )
+
+    @classmethod
+    def _group_paths(cls, paths: List[Path]) -> Dict[str, List[Path]]:
+        groups: Dict[str, List[Path]] = {}
+        for path in paths:
+            groups.setdefault(cls._backend_name(path), []).append(path)
+        return groups
+
+    def _parse_file(self, file_path: Path):
+        self._configure_backend(file_path, self._backend_name(file_path))
+        return self.parser.parse_file(file_path)
+
+    def _resolve_graph(
+        self,
+        builder: "CallGraphBuilder",
+        parses: Dict[Path, Any],
+        results: Dict[Path, Any],
+    ) -> None:
+        if not parses:
+            return
+        builder.resolve_relationships(results)
+        for backend_name in sorted({self._backend_name(path) for path in parses}):
+            self._configure_backend(self.project_path, backend_name)
+            builder.resolver_config = self._resolver_config()
+            builder._resolver = None
+            group = {
+                path: parse for path, parse in parses.items()
+                if self._backend_name(path) == backend_name
+            }
+            builder.resolve_decorator_types(group, results)
+            builder.resolve_calls(group, results)
+            builder.harvest_literal_candidates(group, results)
+
+    @staticmethod
+    def _java_declaration_fingerprint(result: Any) -> Tuple[Any, ...]:
+        """Thin wrapper: the logic lives in ``scanner.incremental`` so the MCP
+        graph-build path uses the identical definition (MCP_INCREMENTAL_REBUILD_PLAN.md)."""
+        return java_declaration_fingerprint(result)
+
+    def _java_incremental_scope(
+        self,
+        root: Path,
+        scanner: IncrementalScanner,
+        changed: List[Path],
+        deleted: List[Path],
+    ) -> Tuple[Optional[Set[Path]], str]:
+        """Thin wrapper over ``scanner.incremental.java_incremental_scope``."""
+        return java_incremental_scope(root, scanner, changed, deleted)
+
+    def scan(
+        self,
+        path: Path,
+        category: Optional[str] = None,
+        incremental: bool = False,
+        progress_callback: Optional[Callable[[int, int, str], None]] = None,
+        language: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """Scan path and return patterns.
+
+        When *incremental* is ``True``, only files whose content hash has
+        changed since the last scan are re-parsed.  Patterns for unchanged
+        files are loaded from the cache.
+
+        *progress_callback(done, total, detail)* is called after each file is
+        processed.  ``detail`` is either the file path string or a phase
+        marker of the form ``"PHASE: <name>"``.  Pass ``None`` (default) to
+        suppress all progress reporting (MCP, tests).
+        """
+        t0 = time.perf_counter()
+        if language:
+            self._configure_backend(path, language)
+        groups = self._file_groups(path, language)
+        scope_extensions = set(get_backend(language).file_extensions) if language else None
+        files = sorted((file for group in groups.values() for file in group), key=str)
+        total = len(files)
+        total_loc, non_blank_loc = self._count_lines(files)
+        done_count = 0
+        scanner = IncrementalScanner(self.memory, self.parser, self.extractor, self.registry)
+        self.last_scan_errors = []
+
+        def _cb(detail: str, *, advance: bool = True) -> None:
+            nonlocal done_count
+            if progress_callback is None:
+                return
+            if advance:
+                done_count += 1
+            progress_callback(done_count, total, detail)
+
+        if incremental:
+            changed, unchanged, deleted = scanner.classify_files(
+                path, files, scope_extensions
+            )
+            if not changed and not deleted:
+                # Fast path – nothing changed, serve from cache
+                return self._patterns_from_cached_results(path, unchanged, category)
+        else:
+            changed = files
+            unchanged = []
+            deleted = []
+
+        results: List[Dict[str, Any]] = []
+        all_patterns: List[Pattern] = []
+        parses: Dict[Path, Any] = {}
+        analysis_results: Dict[Path, Any] = {}
+        pending_metadata: List[Any] = []
+
+        def _append_patterns(patterns: List[Pattern]) -> None:
+            """Store all patterns for indexing, but only emit filtered ones
+            to the CLI/MCP result list when a category filter is active."""
+            display = patterns
+            if category:
+                display = [p for p in patterns if p.category.name.lower() == category.lower()]
+            self.memory.store_patterns(display)
+            for p in display:
+                results.append({
+                    "name": p.name,
+                    "category": p.category.name,
+                    "description": p.description,
+                    "file": str(p.file_path),
+                    "line": p.position.line,
+                    "confidence": p.confidence,
+                    "metadata": p.metadata,
+                })
+
+        need_graph = path.is_dir()
+        use_parallel = should_parallelize(len(changed))
+
+        if use_parallel:
+            # Pass category=None so we can build the full baseline category
+            # breakdown and cache all patterns; filtering happens in _append_patterns.
+            for backend_name, backend_files in self._group_paths(changed).items():
+                self._configure_backend(path, backend_name)
+                for fp, ar, patterns, err in parallel_analyze(
+                    backend_files, backend_name=backend_name, category_filter=None
+                ):
+                    if err is not None or ar is None:
+                        self.last_scan_errors.append({
+                            "file": str(fp), "error": err or "unknown",
+                        })
+                        _cb(str(fp))
+                        continue
+                    all_patterns.extend(patterns)
+                    _append_patterns(patterns)
+                    ar.patterns = patterns
+                    analysis_results[fp] = ar
+                    pending_metadata.append((fp, ar))
+                    _cb(str(fp))
+            scanner.store_results(path, pending_metadata)
+            pending_metadata = []
+            if need_graph:
+                _cb("PHASE: re-parsing for graph", advance=False)
+                for fp in list(analysis_results):
+                    try:
+                        parses[fp] = self._parse_file(fp)
+                    except SCAN_FILE_ERRORS as e:
+                        analysis_results.pop(fp, None)
+                        self.last_scan_errors.append({
+                            "file": str(fp), "error": f"{type(e).__name__}: {e}",
+                        })
+        else:
+            for backend_name, backend_files in self._group_paths(changed).items():
+                self._configure_backend(path, backend_name)
+                for file_path in backend_files:
+                    try:
+                        parse_result = self.parser.parse_file(file_path)
+                        # P2.18: pre-compute def-use facts for Python security checks.
+                        if backend_name == "python":
+                            self._inject_def_use_facts(parse_result, file_path)
+                        patterns = self.registry.run_all(parse_result.tree, parse_result.source_bytes, file_path)
+                        if self._security_detector is not None and hasattr(self._security_detector, "def_use_facts"):
+                            self._security_detector.def_use_facts = {}
+                        ar = self.extractor._build(parse_result, file_path)
+
+                        all_patterns.extend(patterns)
+                        _append_patterns(patterns)
+
+                        # P1.11: carry patterns on the result (see parallel branch).
+                        ar.patterns = patterns
+                        parses[file_path] = parse_result
+                        analysis_results[file_path] = ar
+                        pending_metadata.append((file_path, ar))
+                    except SCAN_FILE_ERRORS as e:
+                        self.last_scan_errors.append({
+                            "file": str(file_path),
+                            "error": f"{type(e).__name__}: {e}",
+                        })
+                    _cb(str(file_path))
+            scanner.store_results(path, pending_metadata)
+
+        # Load unchanged results so the graph stays complete
+        for file_path in unchanged:
+            ar = scanner.load_cached_result(path, file_path)
+            if ar is not None:
+                analysis_results[file_path] = ar
+                if not incremental:
+                    # Full scan mode: also emit patterns from cache
+                    patterns = ar.patterns or []
+                    all_patterns.extend(patterns)
+                    _append_patterns(patterns)
+
+        graph_unchanged = list(unchanged)
+        if scope_extensions is not None:
+            for row in self.memory.get_all_file_metadata(path):
+                file_path = Path(row["file_path"])
+                if file_path.suffix in scope_extensions:
+                    continue
+                ar = scanner.load_cached_result(path, file_path)
+                if ar is not None:
+                    analysis_results[file_path] = ar
+                    graph_unchanged.append(file_path)
+
+        # P2.18: CFG + reaching-definitions pass on changed files
+        python_parses = {
+            file_path: parse for file_path, parse in parses.items()
+            if self._backend_name(file_path) == "python"
+        }
+        if python_parses:
+            _cb("PHASE: def-use analysis", advance=False)
+            self._run_def_use_pass(path, python_parses, analysis_results)
+
+        # Build / update graph
+        builder = None
+        if path.is_dir() and analysis_results:
+            _cb("PHASE: building graph", advance=False)
+            builder = self._update_graph_incrementally(
+                path, scanner, changed, graph_unchanged, deleted, parses,
+                analysis_results, scope_extensions,
+            )
+            _cb("PHASE: saving index", advance=False)
+            # P2.19: taint analysis (source→sink) over the freshly built graph.
+            _cb("PHASE: taint analysis", advance=False)
+            self._run_taint_pass(path, builder, python_parses, results, category)
+
+        duration_ms = (time.perf_counter() - t0) * 1000.0
+        context = self._build_project_context(
+            path, files, total_loc, non_blank_loc,
+            analysis_results, all_patterns, builder,
+        )
+        self.last_scan_context = context
+        try:
+            self.memory.store_scan(context, duration_ms, json.dumps({
+                "categories": context.patterns_by_category,
+                "errors": len(self.last_scan_errors),
+            }))
+        except Exception:
+            pass
+
+        return results
+
+    @staticmethod
+    def _count_lines(files: List[Path]) -> Tuple[int, int]:
+        """Return (total_lines, non_blank_lines) for a list of files."""
+        total_lines = 0
+        non_blank = 0
+        for fp in files:
+            try:
+                text = fp.read_text(encoding="utf-8", errors="ignore")
+                lines = text.splitlines()
+                total_lines += len(lines)
+                non_blank += sum(1 for ln in lines if ln.strip())
+            except OSError:
+                pass
+        return total_lines, non_blank
+
+    def _build_project_context(
+        self,
+        path: Path,
+        files: List[Path],
+        total_loc: int,
+        non_blank_loc: int,
+        analysis_results: Dict[Path, Any],
+        all_patterns: List[Pattern],
+        builder: Optional["CallGraphBuilder"],
+    ) -> ProjectContext:
+        """Aggregate project-size baseline metrics from a completed scan."""
+        total_symbols = 0
+        total_functions = 0
+        total_classes = 0
+        total_variables = 0
+        for ar in analysis_results.values():
+            total_symbols += len(ar.symbols)
+            for sym in ar.symbols:
+                if sym.kind == "function":
+                    total_functions += 1
+                elif sym.kind == "class":
+                    total_classes += 1
+                elif sym.kind in ("variable", "attribute"):
+                    total_variables += 1
+
+        entry_points = 0
+        calls_edges = 0
+        if builder is not None:
+            stats = builder.stats()
+            entry_points = stats.get("entry_points", 0)
+            calls_edges = stats.get("edge_types", {}).get("CALLS", 0)
+
+        patterns_by_category: Dict[str, int] = {}
+        for p in all_patterns:
+            cat = p.category.name
+            patterns_by_category[cat] = patterns_by_category.get(cat, 0) + 1
+
+        return ProjectContext(
+            root_path=path if path.is_dir() else path.parent,
+            files_analyzed=len(files),
+            total_symbols=total_symbols,
+            total_patterns=len(all_patterns),
+            frameworks=self.config.frameworks,
+            lines_of_code=total_loc,
+            non_blank_lines=non_blank_loc,
+            total_functions=total_functions,
+            total_classes=total_classes,
+            total_variables=total_variables,
+            total_modules=len(analysis_results),
+            entry_points=entry_points,
+            calls_edges=calls_edges,
+            patterns_by_category=patterns_by_category,
+            excluded_files=self._excluded_source_files(),
+        )
+
+    def _excluded_source_files(self) -> List[Dict[str, Any]]:
+        """P1 diagnostics: files on disk that ``self.config`` correctly
+        left out of scope, with a reason. Duck-typed (not a Java import
+        here) since `self.config` is whichever backend's ProjectConfig was
+        last configured; only `JavaProjectConfig` currently implements it."""
+        method = getattr(self.config, "excluded_source_files", None)
+        if method is None:
+            return []
+        try:
+            return method()
+        except OSError:
+            return []
+
+    def _inject_def_use_facts(self, parse_result: Any, file_path: Path) -> None:
+        """P2.18: run CFG analysis on one file and load facts into SecurityDetector."""
+        try:
+            from adl_drift.graph.cfg import analyze_file
+            from adl_drift.graph.builder import CallGraphBuilder
+            tmp = CallGraphBuilder(project_root=self.project_root)
+            module_name = tmp._path_to_module(file_path)
+            facts = analyze_file(
+                parse_result.tree.root_node,
+                parse_result.source_bytes,
+                module_name,
+                {},
+            )
+            # Build function_id → {binding_name → [facts]} index
+            index: Dict[str, Dict[str, List[Any]]] = {}
+            for f in facts:
+                fmap = index.setdefault(f.function_id, {})
+                fmap.setdefault(f.binding_name, []).append(f)
+            # Also index by bare function name (last segment) for robustness
+            short_index: Dict[str, Dict[str, List[Any]]] = {}
+            for fid, fmap in index.items():
+                short = fid.split(".")[-1]
+                for bname, bfacts in fmap.items():
+                    short_index.setdefault(short, {}).setdefault(bname, []).extend(bfacts)
+            merged = {**index, **short_index}
+            self._security_detector.def_use_facts = merged
+        except Exception:
+            self._security_detector.def_use_facts = {}
+
+    def _run_def_use_pass(
+        self,
+        project_path: Path,
+        parses: Dict[Path, Any],
+        analysis_results: Dict[Path, Any],
+    ) -> None:
+        """P2.18: run CFG + reaching-definitions on every function in *parses*.
+
+        Stores DefUseFact rows in SQLite for later query by SecurityDetector
+        and DynamicPatternDetector.  Per-file failures are silently skipped
+        (the pass is best-effort; security findings remain even without facts).
+        """
+        from adl_drift.graph.cfg import analyze_file
+        from adl_drift.graph.builder import CallGraphBuilder
+
+        _tmp_builder = CallGraphBuilder(project_root=self.project_root)
+
+        for file_path, parse_result in parses.items():
+            try:
+                ar = analysis_results.get(file_path)
+                module_name = _tmp_builder._path_to_module(file_path)
+                # Build a name→id map so facts carry the correct graph node id
+                # cfg's _walk_for_functions keys facts by module + the chain
+                # of enclosing *function* names (no classes, no <locals>
+                # markers) — map that key to the real graph node id so facts
+                # carry ids that match the graph (P1.10).
+                node_id_map: Dict[str, str] = {}
+                if ar:
+                    for sym in ar.symbols:
+                        if sym.kind in ("function", "method"):
+                            fn_chain = [
+                                seg for i, seg in enumerate(sym.scope_chain)
+                                if i + 1 < len(sym.scope_chain)
+                                and sym.scope_chain[i + 1] == LOCALS_MARKER
+                            ]
+                            cfg_key = ".".join([module_name] + fn_chain + [sym.name])
+                            graph_id = CallGraphBuilder._symbol_to_id(sym, module_name)
+                            node_id_map[cfg_key] = graph_id
+
+                facts = analyze_file(
+                    parse_result.tree.root_node,
+                    parse_result.source_bytes,
+                    module_name,
+                    node_id_map,
+                )
+                if facts:
+                    self.memory.store_def_use_facts(project_path, facts)
+            except Exception:
+                pass  # best-effort
+
+    def _run_taint_pass(
+        self,
+        project_path: Path,
+        builder: "CallGraphBuilder",
+        parses: Dict[Path, Any],
+        results: List[Dict[str, Any]],
+        category: Optional[str],
+    ) -> None:
+        """P2.19: run intra + cross-function taint analysis, persist the paths,
+        and surface each confirmed source→sink path as a CRITICAL TAINT pattern.
+
+        Best-effort: per-pass failures never abort a scan. Cross-function taint
+        only follows calls between functions whose CSTs are in *parses* (every
+        file on a full scan; the changed set on an incremental scan)."""
+        if not parses:
+            return
+        try:
+            from adl_drift.detectors.taint import TaintAnalyzer
+        except Exception:
+            return
+        try:
+            paths = TaintAnalyzer().analyze(builder, parses)
+        except Exception:
+            return
+
+        # Persist: replace paths only for the functions we just re-analyzed so a
+        # partial (incremental) scan doesn't wipe paths in untouched functions.
+        analyzed_fids = list({nid for _, nid in self._iter_parsed_func_ids(builder, parses)})
+        try:
+            self.memory.store_taint_paths(project_path, paths, replace_function_ids=analyzed_fids)
+        except Exception:
+            pass
+
+        if category and category.lower() != "taint":
+            return  # filtered scan that doesn't ask for taint — don't inject rows
+
+        for p in paths:
+            sev = "CRITICAL"
+            chain_str = " → ".join(p.chain)
+            pat = Pattern(
+                category=PatternCategory.TAINT,
+                name=f"taint_{p.sink_category}",
+                description=f"{p.sink_category}: {chain_str}",
+                position=SourcePosition(
+                    line=p.sink_site.line, column=p.sink_site.column,
+                    end_line=p.sink_site.end_line, end_column=p.sink_site.end_column,
+                ),
+                file_path=Path(p.file_path),
+                confidence=p.confidence,
+                metadata={
+                    "severity": sev,
+                    "sink": p.sink,
+                    "sink_category": p.sink_category,
+                    "source": p.source_label,
+                    "binding": p.binding_name or "",
+                    "chain": chain_str,
+                    "cross_function": p.cross_function,
+                    "function": p.function_id,
+                },
+            )
+            try:
+                self.memory.store_pattern(pat)
+            except Exception:
+                pass
+            results.append({
+                "name": pat.name,
+                "category": pat.category.name,
+                "description": pat.description,
+                "file": str(pat.file_path),
+                "line": pat.position.line,
+                "confidence": pat.confidence,
+                "metadata": pat.metadata,
+            })
+
+    @staticmethod
+    def _iter_parsed_func_ids(builder: "CallGraphBuilder", parses: Dict[Path, Any]):
+        """Yield (file_path, function_node_id) for every function in *parses*."""
+        for file_path, parse_result in parses.items():
+            try:
+                module = builder._path_to_module(file_path)
+                for _, nid in builder._iter_func_cst(
+                    parse_result.tree.root_node, parse_result.source_bytes, module
+                ):
+                    yield file_path, nid
+            except Exception:
+                continue
+
+    def _patterns_from_cached_results(
+        self,
+        project_path: Path,
+        files: List[Path],
+        category: Optional[str],
+    ) -> List[Dict[str, Any]]:
+        """Return patterns from cached AnalysisResults without re-parsing."""
+        scanner = IncrementalScanner(self.memory, self.parser, self.extractor, self.registry)
+        results: List[Dict[str, Any]] = []
+        for file_path in files:
+            ar = scanner.load_cached_result(project_path, file_path)
+            if ar is None:
+                continue
+            patterns = ar.patterns
+            if category:
+                patterns = [p for p in patterns if p.category.name.lower() == category.lower()]
+            for p in patterns:
+                results.append({
+                    "name": p.name,
+                    "category": p.category.name,
+                    "description": p.description,
+                    "file": str(p.file_path),
+                    "line": p.position.line,
+                    "confidence": p.confidence,
+                    "metadata": p.metadata,
+                })
+        return results
+
+    def _update_graph_incrementally(
+        self,
+        path: Path,
+        scanner: IncrementalScanner,
+        changed: List[Path],
+        unchanged: List[Path],
+        deleted: List[Path],
+        parses: Dict[Path, Any],
+        analysis_results: Dict[Path, Any],
+        scope_extensions: Optional[Set[str]] = None,
+    ) -> "CallGraphBuilder":
+        """Update the persisted graph using cached + fresh results."""
+        builder = self.memory.load_graph(path)
+        if builder is None:
+            # No prior graph – do a full build.  ``parses`` only covers changed
+            # files in incremental mode; reparse the rest so CALLS edges from
+            # unchanged callers into changed-file symbols still resolve.
+            builder = CallGraphBuilder(project_root=self.project_root)
+            for ar in analysis_results.values():
+                builder.add_file_result(ar)
+            for fp in analysis_results.keys():
+                if fp not in parses:
+                    try:
+                        parses[fp] = self._parse_file(fp)
+                    except Exception:
+                        continue
+            self._resolve_graph(builder, parses, analysis_results)
+        else:
+            # Remove stale nodes
+            for fp in deleted + changed:
+                builder.remove_file(str(fp))
+            # Add fresh results for changed files
+            for fp in changed:
+                if fp in analysis_results:
+                    builder.add_file_result(analysis_results[fp])
+            # Resolve calls originating from changed files
+            if parses:
+                self._resolve_graph(builder, parses, analysis_results)
+            # Drop stale cross-file edges (target deleted/renamed) and re-sync
+            # the NetworkX graph with surviving inbound edges.
+            builder.reconcile_edges()
+
+        scanner.prune_deleted_files(
+            path,
+            {str(f.resolve()) for f in (changed + unchanged)},
+            scope_extensions,
+        )
+        self.memory.save_graph(path, builder)
+        return builder
+
+    def approve(self, pattern_id: str) -> None:
+        """Approve a pattern."""
+        self.pattern_manager.approve(pattern_id)
+
+
+    def list_patterns(self) -> List[Dict[str, Any]]:
+        """List all patterns from memory."""
+        return self.memory.get_patterns()
+
+    def prune(
+        self,
+        *,
+        aggressive: bool = False,
+        include_approved: bool = False,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        """P2.20: reclaim space from the project's cortex.db.
+
+        Always reaps dead projects (root gone) and dead files (file gone).
+        With *aggressive*, first runs a full (non-incremental) scan of this
+        project so every still-detected pattern's ``updated_at`` is refreshed,
+        then sweeps `patterns` rows for live files that the scan did not
+        re-emit (the detector no longer fires there).
+        """
+        stale_before: Optional[str] = None
+        if aggressive:
+            from datetime import datetime as _dt
+            stale_before = _dt.now().isoformat()
+            # Full scan refreshes updated_at on every currently-detected pattern
+            # for this project's files; un-refreshed live-file rows are stale.
+            self.scan(self.project_path, incremental=False)
+        return self.memory.prune_database(
+            stale_before=stale_before,
+            include_approved=include_approved,
+            dry_run=dry_run,
+        )
+
+    def add_knowledge(self, topic: str, content: str) -> str:
+        """Add tribal knowledge."""
+        return self.memory.add_tribal_knowledge(topic, content)
+
+    def get_knowledge(self, topic: str) -> List[Dict[str, Any]]:
+        """Get tribal knowledge."""
+        return self.memory.get_tribal_knowledge(topic=topic)
+
+    def build_graph(self, path: Optional[Path] = None, incremental: bool = True) -> CallGraphBuilder:
+        """Parse every file under `path`, build full call graph (CONTAINS + CALLS).
+
+        When *incremental* is ``True`` (the default), only changed files are
+        re-parsed.  The existing graph is loaded from SQLite, stale nodes are
+        removed, and call edges for changed files are re-resolved.
+        """
+        root = path or self.project_path
+        files = self._find_files(root)
+        scanner = IncrementalScanner(self.memory, self.parser, self.extractor, self.registry)
+
+        if incremental:
+            cached_update = {
+                "mode": "cached", "invalidated_files": [],
+                "reason": "no source changes",
+            }
+            # MCP_GRAPH_CACHE_PLAN.md Lớp 1's stat-based fast path, for the
+            # CLI: when the sources' size/mtime fingerprint still matches the
+            # persisted graph's — and the newest mtime is outside the racy
+            # window, where a same-size rewrite could hide — load it without
+            # hashing every file. Otherwise classify by content hash as before.
+            max_mtime, fingerprint = CortexMemory._source_state(root, files)
+            if (
+                fingerprint == self.memory.get_source_fingerprint(root)
+                and max_mtime < time.time() - GRAPH_CACHE_RACY_WINDOW_SECONDS
+            ):
+                cached = self.memory.load_graph(root, files=files, fingerprint=fingerprint)
+                if cached is not None:
+                    self.last_graph_update = cached_update
+                    return cached
+            changed, unchanged, deleted = scanner.classify_files(root, files)
+            if not changed and not deleted:
+                cached = self.memory.load_graph(root, files=files, fingerprint=fingerprint)
+                if cached is not None:
+                    self.last_graph_update = cached_update
+                    return cached
+            if any(fp.suffix == ".java" for fp in (*changed, *deleted)):
+                scope, reason = self._java_incremental_scope(root, scanner, changed, deleted)
+                if scope is None:
+                    fallback = {
+                        "mode": "full_rebuild", "invalidated_files": [str(fp) for fp in changed + deleted],
+                        "reason": reason,
+                    }
+                    graph = self.build_graph(root, incremental=False)
+                    self.last_graph_update = fallback
+                    return graph
+                # Only body-only Java units are in scope. Keep the complete
+                # cached graph and re-resolve their outgoing relationships.
+                changed = [fp for fp in changed if fp.suffix != ".java" or fp in scope]
+                self.last_graph_update = {
+                    "mode": "dependency_scoped", "invalidated_files": [str(fp) for fp in sorted(scope)],
+                    "reason": reason,
+                }
+        else:
+            changed = files
+            unchanged = []
+            deleted = []
+            self.last_graph_update = {"mode": "full_rebuild", "invalidated_files": [str(fp) for fp in files], "reason": "requested full build"}
+
+        # A requested full rebuild must start with no persisted graph state.
+        # Reusing the deserialized builder retained backend/module identity
+        # caches, so an alleged full rebuild could disagree with a fresh
+        # incremental graph even when their source was identical (P3.2).
+        # Changes are classified above, so preserve the pre-edit snapshot for
+        # dependency-scoped removal/re-resolution instead of having the
+        # storage layer discard it solely because its source fingerprint moved.
+        builder = None if not incremental else self.memory.load_graph(root, allow_stale=True)
+        if builder is not None:
+            # The persisted graph is keyed by the scan root, while this
+            # command may have found a broader project root (for example a
+            # fixture without a Maven marker inside a Git worktree). Reapply
+            # that root before adding changed Java symbols so their module
+            # namespace matches a full rebuild.
+            builder.project_root = self.project_root.resolve()
+            builder._project_languages = None
+            builder._java_build_module_roots = None
+            builder._java_namespace_visibility = None
+        full_rebuild = builder is None
+        if full_rebuild:
+            builder = CallGraphBuilder(project_root=self.project_root)
+            # Cached file analyses without their matching graph snapshot are
+            # insufficient for a scoped update: inbound edges would be absent.
+            # Start fresh and expose that fact to telemetry/callers.
+            if incremental:
+                self.last_graph_update = {
+                    "mode": "full_rebuild",
+                    "invalidated_files": [str(fp) for fp in changed + deleted],
+                    "reason": "persisted graph unavailable",
+                }
+
+        # Remove stale nodes
+        for fp in deleted + changed:
+            builder.remove_file(str(fp))
+
+        parses: Dict[Path, Any] = {}
+        results: Dict[Path, Any] = {}
+
+        # Re-parse changed files
+        for fp in changed:
+            try:
+                self._configure_backend(root, self._backend_name(fp))
+                pr = self.parser.parse_file(fp)
+                ar = self.extractor._build(pr, fp)
+                # P1: this path skips the full detector set, but the graph
+                # still needs ROUTES patterns to mark route handlers as entry
+                # points (see `_route_patterns`).
+                ar.patterns = self._route_patterns(pr, fp)
+                parses[fp] = pr
+                results[fp] = ar
+            except Exception:
+                continue
+        scanner.store_results(root, list(results.items()))
+
+        # Add all results to graph (changed + unchanged cached)
+        results.update(scanner.load_cached_results(root, unchanged))
+
+        # A persisted builder already owns every unchanged node/edge. Adding
+        # those results again repopulates pending indexes and defeats the
+        # dependency-scoped update. Full builds still add the complete set.
+        cached_incremental_builder = incremental and not full_rebuild
+        for fp, ar in results.items():
+            if not cached_incremental_builder or fp in changed:
+                builder.add_file_result(ar)
+
+        # Full rebuild (no prior graph / cache invalidated): ``parses`` only
+        # covers changed files, but CALLS edges originating from *unchanged*
+        # files exist nowhere else — re-parse them so resolve_calls() walks
+        # every body. Same fix as _update_graph_incrementally (P0.5).
+        if full_rebuild:
+            for fp in results.keys():
+                if fp not in parses:
+                    try:
+                        parses[fp] = self._parse_file(fp)
+                    except Exception:
+                        continue
+
+        if parses:
+            self._resolve_graph(builder, parses, results)
+        # Drop edges whose endpoints vanished and re-sync surviving inbound
+        # edges into the NetworkX graph (remove_file keeps them in _edges
+        # but remove_node drops them from the graph).
+        builder.reconcile_edges()
+
+        scanner.prune_deleted_files(root, {str(f.resolve()) for f in files})
+        self.memory.save_graph(root, builder, files=files)
+        return builder
+
+    def graph_stats(self, path: Optional[Path] = None) -> Dict[str, Any]:
+        t0 = time.perf_counter()
+        result = self.build_graph(path).stats()
+        self._telemetry.record(
+            "drift_graph", {}, result,
+            duration_ms=(time.perf_counter() - t0) * 1000.0, source="cli",
+        )
+        return result
+
+    def god_nodes(self, top_n: int = 10, path: Optional[Path] = None) -> List[Dict]:
+        return self.build_graph(path).god_nodes(top_n)
+
+    def surprising_connections(self, path: Optional[Path] = None) -> List[Dict]:
+        return self.build_graph(path).surprising_connections()
+
+    def impact(
+        self,
+        symbol: str,
+        path: Optional[Path] = None,
+        *,
+        include_initializers: bool = False,
+    ) -> Dict[str, Any]:
+        t0 = time.perf_counter()
+        result = self.build_graph(path).get_impact_analysis(
+            symbol, include_initializers=include_initializers,
+        )
+        self._telemetry.record(
+            "drift_impact", {
+                "symbol": symbol,
+                "include_initializers": include_initializers,
+            }, result,
+            is_error=bool(result.get("error")),
+            duration_ms=(time.perf_counter() - t0) * 1000.0, source="cli",
+        )
+        return result
+
+    def check_gate(self) -> List[Dict[str, Any]]:
+        """Check for unapproved patterns (CI gate)."""
+        # Scan entire project
+        all_patterns = []
+        for backend_name, files in self._file_groups(self.project_path).items():
+            self._configure_backend(self.project_path, backend_name)
+            for file_path in files:
+                try:
+                    parse_result = self.parser.parse_file(file_path)
+                    patterns = self.registry.run_all(parse_result.tree, parse_result.source_bytes, file_path)
+                    all_patterns.extend(patterns)
+                except Exception:
+                    continue
+
+        return self.pattern_manager.check_conformance(all_patterns)
+
+    def gate_report(self) -> Dict[str, Any]:
+        """`adl-drift gate --json` contract (HARNESS.md Part 4):
+        {violations, new_patterns, scan_errors, high_security, failed}.
+
+        ``failed`` (→ CLI exit 1) means HIGH-severity security findings or
+        scan errors — conformance violations are reported but advisory.
+        Unlike check_gate(), per-file failures are surfaced, not swallowed.
+        """
+        all_patterns = []
+        scan_errors: List[Dict[str, str]] = []
+        for backend_name, files in self._file_groups(self.project_path).items():
+            self._configure_backend(self.project_path, backend_name)
+            for file_path in files:
+                try:
+                    parse_result = self.parser.parse_file(file_path)
+                    patterns = self.registry.run_all(parse_result.tree, parse_result.source_bytes, file_path)
+                    all_patterns.extend(patterns)
+                except SCAN_FILE_ERRORS as e:
+                    scan_errors.append({"file": str(file_path), "error": f"{type(e).__name__}: {e}"})
+
+        known_ids = {p["id"] for p in self.memory.get_patterns()}
+        new_patterns = [
+            {"name": p.name, "category": p.category.name,
+             "file": str(p.file_path), "line": p.position.line}
+            for p in all_patterns if p.compute_hash() not in known_ids
+        ]
+        high_security = [
+            {"name": p.name, "description": p.description,
+             "file": str(p.file_path), "line": p.position.line}
+            for p in all_patterns
+            if p.category.name == "SECURITY"
+            and str((p.metadata or {}).get("severity", "")).upper() == "HIGH"
+        ]
+        return {
+            "violations": self.pattern_manager.check_conformance(all_patterns),
+            "new_patterns": new_patterns,
+            "scan_errors": scan_errors,
+            "high_security": high_security,
+            "failed": bool(high_security or scan_errors),
+        }
+
+    def _find_files(self, path: Path, language: Optional[str] = None) -> List[Path]:
+        return sorted(
+            (file for files in self._file_groups(path, language).values() for file in files),
+            key=str,
+        )
+
+    @classmethod
+    def _find_python_files(cls, path: Path) -> List[Path]:
+        """Compatibility wrapper for downstream Python-only callers."""
+        from adl_drift.lang.registry import get_backend
+
+        return discover_files(path, get_backend("python"))