codrspot-processor-mcp 0.1.0__py3-none-any.whl

codepreproc_client/layer2_tooling/coupling/layer2_gate.py

@@ -0,0 +1,189 @@
+"""Layer 2: disambiguation + lazy revalidation gate for resolved coupling facts.
+
+Consumes the candidate-level superset from CouplingGraph and produces only
+resolved, current edges.  Two distinct passes, both over the affected subset only:
+
+(a) DISAMBIGUATE — ambiguous edges (resolution_status="ambiguous") carry
+    competing_targets.  We check which (project_id, chunk_id) pairs still exist
+    in their respective symbol tables.  If exactly one survives, the edge is
+    promoted to resolved.  If still multiple, it remains ambiguous (excluded
+    from the resolved output).
+
+(b) REVALIDATE — edges whose dst_export_surface_epoch differs from the
+    destination's current export_surface_hash are stale.  We re-look up
+    dst_symbol in the foreign table and, if found, emit a resolved edge with the
+    updated epoch and chunk_id.  If the symbol is gone, the edge is dropped from
+    the resolved output.
+
+Resolved edges are written back through upsert_edges so the store stays warm
+for subsequent Layer 1 reads.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from pathlib import Path
+
+from codepreproc_client.layer2_tooling.coupling.domain import ResolutionEdge
+from codepreproc_client.layer2_tooling.coupling.graph import CouplingGraph
+
+_log = logging.getLogger("codepreproc.coupling")
+
+
+def _get_export_surface_hash(db_path: Path) -> str | None:
+    """Read export_surface_hash (or last_indexed_sha fallback) from a project DB."""
+    if not db_path.exists():
+        return None
+    try:
+        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=2)
+        row = conn.execute(
+            "SELECT value FROM meta WHERE key = 'export_surface_hash'"
+        ).fetchone()
+        if not row:
+            row = conn.execute(
+                "SELECT value FROM meta WHERE key = 'last_indexed_sha'"
+            ).fetchone()
+        conn.close()
+        return row[0] if row else None
+    except Exception:
+        return None
+
+
+def _load_chunk_ids(db_path: Path) -> set[str]:
+    """Return the live set of chunk_ids in a project's symbol table."""
+    if not db_path.exists():
+        return set()
+    try:
+        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=2)
+        rows = conn.execute("SELECT chunk_id FROM symbols").fetchall()
+        conn.close()
+        return {row[0] for row in rows}
+    except Exception:
+        return set()
+
+
+def _load_symbol_to_chunk(db_path: Path) -> dict[str, str]:
+    """Return {symbol: chunk_id} for a project's current symbol table."""
+    if not db_path.exists():
+        return {}
+    try:
+        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=2)
+        rows = conn.execute("SELECT symbol, chunk_id FROM symbols").fetchall()
+        conn.close()
+        return {row[0]: row[1] for row in rows}
+    except Exception:
+        return {}
+
+
+def apply_layer2_gate(
+    edges: list[ResolutionEdge],
+    indexes_dir: Path,
+    coupling_graph: CouplingGraph,
+) -> tuple[list[ResolutionEdge], int]:
+    """Disambiguate ambiguous edges and revalidate stale edges.
+
+    Processes only the affected subset (ambiguous or stale edges).
+    Resolved edges are written back through upsert_edges.
+
+    Returns (resolved_edges, revalidated_count) where resolved_edges contains
+    all clean edges plus the successfully disambiguated/revalidated ones.
+    """
+    if not edges:
+        return [], 0
+
+    # Collect current export_surface_hash per project and cache symbol tables lazily.
+    current_epochs: dict[str, str] = {}
+    _chunk_id_cache: dict[str, set[str]] = {}
+    _sym_to_chunk_cache: dict[str, dict[str, str]] = {}
+
+    for project_dir in indexes_dir.iterdir():
+        if not project_dir.is_dir():
+            continue
+        h = _get_export_surface_hash(project_dir / "ast_graph.sqlite")
+        if h:
+            current_epochs[project_dir.name] = h
+
+    def _chunk_ids(project_id: str) -> set[str]:
+        if project_id not in _chunk_id_cache:
+            _chunk_id_cache[project_id] = _load_chunk_ids(
+                indexes_dir / project_id / "ast_graph.sqlite"
+            )
+        return _chunk_id_cache[project_id]
+
+    def _sym_to_chunk(project_id: str) -> dict[str, str]:
+        if project_id not in _sym_to_chunk_cache:
+            _sym_to_chunk_cache[project_id] = _load_symbol_to_chunk(
+                indexes_dir / project_id / "ast_graph.sqlite"
+            )
+        return _sym_to_chunk_cache[project_id]
+
+    # Group ambiguous edges by (src_chunk_id, dst_symbol) so we process each
+    # competing set once rather than once per match.
+    ambiguous_groups: dict[tuple[str, str], list[ResolutionEdge]] = {}
+    passthrough: list[ResolutionEdge] = []
+    stale_resolved: list[ResolutionEdge] = []
+
+    for edge in edges:
+        current_epoch = current_epochs.get(edge.dst_project_id)
+        is_stale = current_epoch is not None and edge.dst_export_surface_epoch != current_epoch
+        is_ambiguous = edge.resolution_status == "ambiguous"
+
+        if is_ambiguous:
+            key = (edge.src_chunk_id, edge.dst_symbol)
+            ambiguous_groups.setdefault(key, []).append(edge)
+        elif is_stale:
+            # Revalidate: look up the symbol in the current dst symbol table.
+            sym_map = _sym_to_chunk(edge.dst_project_id)
+            new_chunk_id = sym_map.get(edge.dst_symbol)
+            if new_chunk_id is not None:
+                new_edge = edge.model_copy(update={
+                    "dst_chunk_id": new_chunk_id,
+                    "dst_export_surface_epoch": current_epoch,
+                    "resolution_status": "resolved",
+                })
+                stale_resolved.append(new_edge)
+            # Symbol gone from dst → drop edge from resolved output (do not add to passthrough)
+        else:
+            passthrough.append(edge)
+
+    # Disambiguate each group.
+    disambiguated: list[ResolutionEdge] = []
+    for (src_chunk_id, dst_symbol), group in ambiguous_groups.items():
+        # competing_targets is the same on all edges in the group.
+        competing = group[0].competing_targets
+        survivors = [
+            (pid, cid)
+            for pid, cid in competing
+            if cid in _chunk_ids(pid)
+        ]
+        if len(survivors) == 1:
+            pid, cid = survivors[0]
+            new_epoch = current_epochs.get(pid, group[0].dst_export_surface_epoch)
+            # Find the original edge that pointed to this dst project to preserve edge_id
+            ref_edge = next(
+                (e for e in group if e.dst_project_id == pid and e.dst_chunk_id == cid),
+                group[0],
+            )
+            new_edge = ref_edge.model_copy(update={
+                "dst_project_id": pid,
+                "dst_chunk_id": cid,
+                "dst_export_surface_epoch": new_epoch,
+                "resolution_status": "resolved",
+                "competing_targets": [],
+            })
+            disambiguated.append(new_edge)
+        # else: still ambiguous or all gone → excluded from resolved output
+
+    to_write = stale_resolved + disambiguated
+    if to_write:
+        coupling_graph.upsert_edges(to_write)
+        _log.info(
+            "layer2_gate: %d edges revalidated/disambiguated (%d stale, %d ambiguous→resolved)",
+            len(to_write),
+            len(stale_resolved),
+            len(disambiguated),
+        )
+
+    resolved = passthrough + stale_resolved + disambiguated
+    return resolved, len(to_write)

codepreproc_client/layer2_tooling/coupling/projector.py

@@ -0,0 +1,139 @@
+"""Coupling projection engine: Ca/Ce metrics and SCC detection via Tarjan.
+
+Given a set of ResolutionEdges (already hydrated from CouplingGraph), this
+module computes the read-model projection entirely server-side — no LLM
+involvement, deterministic.
+
+Tarjan runs on the repo-level directed graph (nodes = project_ids), not on
+individual symbols, so the graph is always small (N registered projects).
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from codepreproc_client.layer2_tooling.coupling.domain import (
+    CouplingMetricRow,
+    CouplingProjectSummary,
+    ResolutionEdge,
+    SCC,
+)
+
+
+# ---------------------------------------------------------------------------
+# Tarjan SCC (iterative to avoid Python recursion limit on large graphs)
+# ---------------------------------------------------------------------------
+
+
+def _tarjan_sccs(nodes: list[str], adj: dict[str, list[str]]) -> list[list[str]]:
+    """Return list of SCCs (as node lists) for a directed graph, largest first."""
+    index_counter = [0]
+    stack: list[str] = []
+    lowlinks: dict[str, int] = {}
+    index: dict[str, int] = {}
+    on_stack: dict[str, bool] = {}
+    sccs: list[list[str]] = []
+
+    def strongconnect(v: str) -> None:
+        index[v] = index_counter[0]
+        lowlinks[v] = index_counter[0]
+        index_counter[0] += 1
+        stack.append(v)
+        on_stack[v] = True
+
+        for w in adj.get(v, []):
+            if w not in index:
+                strongconnect(w)
+                lowlinks[v] = min(lowlinks[v], lowlinks[w])
+            elif on_stack.get(w):
+                lowlinks[v] = min(lowlinks[v], index[w])
+
+        if lowlinks[v] == index[v]:
+            scc: list[str] = []
+            while True:
+                w = stack.pop()
+                on_stack[w] = False
+                scc.append(w)
+                if w == v:
+                    break
+            sccs.append(scc)
+
+    for node in nodes:
+        if node not in index:
+            strongconnect(node)
+
+    return sccs
+
+
+# ---------------------------------------------------------------------------
+# Main projector
+# ---------------------------------------------------------------------------
+
+
+class CouplingProjector:
+    """Project a set of ResolutionEdges into CouplingProjectSummary."""
+
+    def project(
+        self,
+        anchors: list[str],
+        edges: list[ResolutionEdge],
+        stale_count: int = 0,
+    ) -> CouplingProjectSummary:
+        """Compute metrics and SCCs from the given edge set.
+
+        anchors: the project_ids in the working set (symbol table keys).
+        edges:   ResolutionEdges filtered to the working set.
+        stale_count: number of edges re-resolved during hydration (for info).
+        """
+        # Symbol table: short name = project_id (already short enough)
+        projects = {pid: pid for pid in anchors}
+
+        # Count edges per (src, dst) pair
+        pair_counts: dict[tuple[str, str], int] = defaultdict(int)
+        for edge in edges:
+            pair_counts[(edge.src_project_id, edge.dst_project_id)] += 1
+
+        # Build compact edge list: (src_id, dst_id, count)
+        compact_edges = [
+            (src, dst, count)
+            for (src, dst), count in sorted(pair_counts.items())
+        ]
+
+        # Ca/Ce per pair: from src's perspective
+        # Ce(src→dst): efferent — src depends on dst
+        # Ca(src→dst): afferent — edges going dst→src (i.e., dst depends on src)
+        ce_map: dict[tuple[str, str], int] = defaultdict(int)
+        ca_map: dict[tuple[str, str], int] = defaultdict(int)
+        for (src, dst), count in pair_counts.items():
+            ce_map[(src, dst)] += count
+            ca_map[(src, dst)] += pair_counts.get((dst, src), 0)
+
+        all_pairs = set(ce_map.keys()) | {(dst, src) for src, dst in ce_map}
+        metrics: list[CouplingMetricRow] = []
+        seen_pairs: set[tuple[str, str]] = set()
+        for src, dst in sorted(all_pairs):
+            if (src, dst) in seen_pairs:
+                continue
+            seen_pairs.add((src, dst))
+            ce = ce_map.get((src, dst), 0)
+            ca = pair_counts.get((dst, src), 0)
+            if ce > 0 or ca > 0:
+                metrics.append(CouplingMetricRow.compute(src, dst, ce, ca))
+
+        # Build adjacency for Tarjan (repo-level, directed)
+        adj: dict[str, list[str]] = defaultdict(list)
+        for src, dst in pair_counts:
+            if src != dst:
+                adj[src].append(dst)
+
+        raw_sccs = _tarjan_sccs(list(anchors), adj)
+        non_trivial = [SCC(members=scc) for scc in raw_sccs if len(scc) > 1]
+
+        return CouplingProjectSummary(
+            projects=projects,
+            edges=compact_edges,
+            metrics=metrics,
+            sccs=non_trivial,
+            total_edges=len(edges),
+            stale_edges_revalidated=stale_count,
+        )

codepreproc_client/layer2_tooling/coupling/resolver.py

@@ -0,0 +1,150 @@
+"""Cross-repo symbol resolution: called at index-time to emit ResolutionEdges.
+
+Resolution strategy: load all other projects' symbol tables from their
+AstGraph SQLite files (read-only) and perform a global namespace lookup.
+On symbol name collision across projects, we take all matches and emit one
+edge per match (conservative; duplicates are deduped by edge_id in the DB).
+
+This is called from ProjectIndexer after the local AST graph is built,
+with the full chunk set available. It is synchronous and CPU-bound; the
+caller runs it with asyncio.to_thread().
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from pathlib import Path
+
+from codepreproc_client.layer2_tooling.coupling.domain import ResolutionEdge
+from codepreproc_client.layer2_tooling.coupling.graph import CouplingGraph
+from contracts.dtos import CodeChunk
+
+_log = logging.getLogger("codepreproc.coupling")
+
+
+def _load_foreign_symbols(indexes_dir: Path, exclude_project_id: str) -> dict[str, list[tuple[str, str, str]]]:
+    """Return {symbol: [(project_id, chunk_id, file_path)]} for all other projects.
+
+    Opens each project's ast_graph.sqlite read-only; skips missing or locked DBs.
+    """
+    foreign: dict[str, list[tuple[str, str, str]]] = {}
+    for project_dir in indexes_dir.iterdir():
+        if not project_dir.is_dir():
+            continue
+        project_id = project_dir.name
+        if project_id == exclude_project_id:
+            continue
+        db_path = project_dir / "ast_graph.sqlite"
+        if not db_path.exists():
+            continue
+        try:
+            conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=2)
+            rows = conn.execute("SELECT chunk_id, symbol, file_path FROM symbols").fetchall()
+            conn.close()
+        except Exception as exc:
+            _log.debug("coupling_resolver: skipping %s — %s", project_id, exc)
+            continue
+        for chunk_id, symbol, file_path in rows:
+            foreign.setdefault(symbol, []).append((project_id, chunk_id, file_path))
+    return foreign
+
+
+def emit_cross_repo_edges(
+    *,
+    src_project_id: str,
+    src_epoch: str,
+    chunks: list[CodeChunk],
+    indexes_dir: Path,
+    coupling_graph: CouplingGraph,
+    dst_epochs: dict[str, str],
+) -> int:
+    """Resolve cross-repo deps for all chunks and persist as ResolutionEdges.
+
+    Returns the number of new edges emitted.
+    """
+    if not chunks:
+        return 0
+
+    foreign = _load_foreign_symbols(indexes_dir, src_project_id)
+    if not foreign:
+        return 0
+
+    # Wipe old src edges before re-emitting (idempotent full-refresh)
+    coupling_graph.delete_edges_for_project(src_project_id)
+
+    edges: list[ResolutionEdge] = []
+    seen: set[tuple[str, str, str]] = set()
+
+    for chunk in chunks:
+        for dep_symbol in chunk.deps:
+            matches = foreign.get(dep_symbol)
+            if not matches:
+                continue
+            is_ambiguous = len(matches) > 1
+            # competing_targets lists all (project_id, chunk_id) matches so Layer 2
+            # can disambiguate without re-running the join.
+            competing: list[tuple[str, str]] = (
+                [(pid, cid) for pid, cid, _ in matches] if is_ambiguous else []
+            )
+            for dst_project_id, dst_chunk_id, _dst_file in matches:
+                key = (chunk.chunk_id, dst_project_id, dst_chunk_id)
+                if key in seen:
+                    continue
+                seen.add(key)
+                dst_epoch = dst_epochs.get(dst_project_id, "unknown")
+                edges.append(
+                    ResolutionEdge(
+                        src_project_id=src_project_id,
+                        src_chunk_id=chunk.chunk_id,
+                        src_symbol=chunk.symbol,
+                        dst_project_id=dst_project_id,
+                        dst_chunk_id=dst_chunk_id,
+                        dst_symbol=dep_symbol,
+                        dst_export_surface_epoch=dst_epoch,
+                        resolution_status="ambiguous" if is_ambiguous else "resolved",
+                        competing_targets=competing,
+                    )
+                )
+
+    if edges:
+        coupling_graph.upsert_edges(edges)
+        _log.info(
+            "coupling_resolver: %d cross-repo edges emitted for project=%s",
+            len(edges),
+            src_project_id,
+        )
+    return len(edges)
+
+
+def collect_dst_epochs(indexes_dir: Path, exclude_project_id: str) -> dict[str, str]:
+    """Return {project_id: export_surface_hash} for all other indexed projects.
+
+    Falls back to last_indexed_sha for projects not yet reindexed after the
+    export-surface-hash migration, so stale detection remains functional.
+    """
+    epochs: dict[str, str] = {}
+    for project_dir in indexes_dir.iterdir():
+        if not project_dir.is_dir():
+            continue
+        project_id = project_dir.name
+        if project_id == exclude_project_id:
+            continue
+        db_path = project_dir / "ast_graph.sqlite"
+        if not db_path.exists():
+            continue
+        try:
+            conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=2)
+            row = conn.execute(
+                "SELECT value FROM meta WHERE key = 'export_surface_hash'"
+            ).fetchone()
+            if not row:
+                row = conn.execute(
+                    "SELECT value FROM meta WHERE key = 'last_indexed_sha'"
+                ).fetchone()
+            conn.close()
+            if row:
+                epochs[project_id] = row[0]
+        except Exception:
+            continue
+    return epochs