polycodegraph 0.1.0__py3-none-any.whl

codegraph/review/differ.py

@@ -0,0 +1,211 @@
+"""Graph diffing: compare two graphs by (qualname, kind) identity."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import networkx as nx
+
+
+@dataclass
+class NodeChange:
+    qualname: str
+    kind: str
+    file: str
+    line_start: int
+    signature: str
+    change_kind: str  # "added" | "removed" | "modified"
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EdgeChange:
+    src_qualname: str
+    dst_qualname: str
+    kind: str
+    change_kind: str  # "added" | "removed"
+
+
+@dataclass
+class GraphDiff:
+    added_nodes: list[NodeChange] = field(default_factory=list)
+    removed_nodes: list[NodeChange] = field(default_factory=list)
+    modified_nodes: list[NodeChange] = field(default_factory=list)
+    added_edges: list[EdgeChange] = field(default_factory=list)
+    removed_edges: list[EdgeChange] = field(default_factory=list)
+
+    @property
+    def total(self) -> int:
+        return (
+            len(self.added_nodes)
+            + len(self.removed_nodes)
+            + len(self.modified_nodes)
+            + len(self.added_edges)
+            + len(self.removed_edges)
+        )
+
+
+_NodeKey = tuple[str, str]
+
+
+def _kind_str(value: object) -> str:
+    return str(getattr(value, "value", value) or "")
+
+
+def _node_key(attrs: dict[str, Any]) -> _NodeKey | None:
+    qualname = str(attrs.get("qualname") or "")
+    kind = _kind_str(attrs.get("kind"))
+    if not qualname or not kind:
+        return None
+    return (qualname, kind)
+
+
+def _node_payload(attrs: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "qualname": str(attrs.get("qualname") or ""),
+        "kind": _kind_str(attrs.get("kind")),
+        "file": str(attrs.get("file") or ""),
+        "line_start": int(attrs.get("line_start") or 0),
+        "signature": str(attrs.get("signature") or ""),
+    }
+
+
+def _build_node_index(graph: nx.MultiDiGraph) -> dict[_NodeKey, dict[str, Any]]:
+    index: dict[_NodeKey, dict[str, Any]] = {}
+    for nid, attrs in graph.nodes(data=True):
+        key = _node_key(attrs)
+        if key is None:
+            continue
+        # Last write wins - duplicates are exceedingly rare given (qualname, kind, file)
+        # identity; we keep the first to be deterministic.
+        if key in index:
+            continue
+        payload = _node_payload(attrs)
+        payload["_id"] = nid
+        index[key] = payload
+    return index
+
+
+def _id_to_qualname(graph: nx.MultiDiGraph) -> dict[str, str]:
+    return {
+        nid: str(attrs.get("qualname") or nid)
+        for nid, attrs in graph.nodes(data=True)
+    }
+
+
+def _edge_keys(
+    graph: nx.MultiDiGraph, id_map: dict[str, str]
+) -> set[tuple[str, str, str]]:
+    keys: set[tuple[str, str, str]] = set()
+    for src, dst, data in graph.edges(data=True):
+        kind = _kind_str(data.get("kind"))
+        src_qn = id_map.get(src, src)
+        dst_qn = id_map.get(dst, dst)
+        keys.add((src_qn, dst_qn, kind))
+    return keys
+
+
+def diff_graphs(old: nx.MultiDiGraph, new: nx.MultiDiGraph) -> GraphDiff:
+    """Diff two graphs by ``(qualname, kind)`` node identity.
+
+    A node is *modified* when the same identity exists in both graphs but
+    its ``file`` or ``signature`` changed.
+
+    ``line_start`` is intentionally NOT a modification trigger: when a PR
+    edits the top of a file, every symbol below the edit shifts down by N
+    lines and would otherwise show up as "modified" even though their
+    actual signatures are identical. Pure line-shift noise was producing
+    50+ false-positive ``modified-signature`` findings on PRs that touched
+    high-traffic files (``app.js``, ``typescript.py``).
+
+    The ``line_start`` value is still captured on each ``NodeChange`` for
+    rendering — it just no longer triggers the change.
+    """
+    diff = GraphDiff()
+
+    old_idx = _build_node_index(old)
+    new_idx = _build_node_index(new)
+
+    for key, new_payload in new_idx.items():
+        if key not in old_idx:
+            diff.added_nodes.append(
+                NodeChange(
+                    qualname=new_payload["qualname"],
+                    kind=new_payload["kind"],
+                    file=new_payload["file"],
+                    line_start=new_payload["line_start"],
+                    signature=new_payload["signature"],
+                    change_kind="added",
+                )
+            )
+            continue
+        old_payload = old_idx[key]
+        details: dict[str, Any] = {}
+        for field_name in ("file", "signature"):
+            if old_payload[field_name] != new_payload[field_name]:
+                details[field_name] = {
+                    "old": old_payload[field_name],
+                    "new": new_payload[field_name],
+                }
+        # Record line drift in details for diagnostic output, but DON'T let
+        # it alone trigger "modified".
+        if (
+            old_payload["line_start"] != new_payload["line_start"]
+            and details
+        ):
+            details["line_start"] = {
+                "old": old_payload["line_start"],
+                "new": new_payload["line_start"],
+            }
+        if details:
+            diff.modified_nodes.append(
+                NodeChange(
+                    qualname=new_payload["qualname"],
+                    kind=new_payload["kind"],
+                    file=new_payload["file"],
+                    line_start=new_payload["line_start"],
+                    signature=new_payload["signature"],
+                    change_kind="modified",
+                    details=details,
+                )
+            )
+
+    for key, old_payload in old_idx.items():
+        if key in new_idx:
+            continue
+        diff.removed_nodes.append(
+            NodeChange(
+                qualname=old_payload["qualname"],
+                kind=old_payload["kind"],
+                file=old_payload["file"],
+                line_start=old_payload["line_start"],
+                signature=old_payload["signature"],
+                change_kind="removed",
+            )
+        )
+
+    old_id_map = _id_to_qualname(old)
+    new_id_map = _id_to_qualname(new)
+    old_edges = _edge_keys(old, old_id_map)
+    new_edges = _edge_keys(new, new_id_map)
+
+    for src_qn, dst_qn, kind in sorted(new_edges - old_edges):
+        diff.added_edges.append(
+            EdgeChange(
+                src_qualname=src_qn,
+                dst_qualname=dst_qn,
+                kind=kind,
+                change_kind="added",
+            )
+        )
+    for src_qn, dst_qn, kind in sorted(old_edges - new_edges):
+        diff.removed_edges.append(
+            EdgeChange(
+                src_qualname=src_qn,
+                dst_qualname=dst_qn,
+                kind=kind,
+                change_kind="removed",
+            )
+        )
+
+    return diff

codegraph/review/hook.py

@@ -0,0 +1,70 @@
+"""Git hook installation for ``codegraph review`` integration."""
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+
+HOOK_MARKER = "# codegraph-managed-hook"
+
+DEFAULT_HOOK_NAME = "pre-push"
+
+
+def _hook_script(target: str = "main") -> str:
+    return f"""#!/usr/bin/env bash
+{HOOK_MARKER}
+# Runs codegraph review against the configured baseline.
+set -e
+if ! command -v codegraph >/dev/null 2>&1; then
+    echo "codegraph: skipping (CLI not on PATH)"
+    exit 0
+fi
+codegraph review --target {target} --fail-on high || exit $?
+"""
+
+
+def _hooks_dir(repo_root: Path) -> Path:
+    return repo_root / ".git" / "hooks"
+
+
+def install_hook(
+    repo_root: Path,
+    hook: str = DEFAULT_HOOK_NAME,
+    target: str = "main",
+    force: bool = False,
+) -> Path:
+    """Install a codegraph-managed git hook in ``repo_root``.
+
+    Returns the path of the installed hook. Raises ``FileExistsError`` if a
+    foreign (non-codegraph) hook is already present and ``force`` is False.
+    """
+    hooks_dir = _hooks_dir(repo_root)
+    if not hooks_dir.parent.exists():
+        raise FileNotFoundError(f"not a git repository: {repo_root}")
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook_path = hooks_dir / hook
+    if hook_path.exists() and not force:
+        existing = hook_path.read_text()
+        if HOOK_MARKER not in existing:
+            raise FileExistsError(
+                f"refusing to overwrite existing {hook} hook (use --force)"
+            )
+    hook_path.write_text(_hook_script(target=target))
+    mode = hook_path.stat().st_mode
+    hook_path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return hook_path
+
+
+def uninstall_hook(
+    repo_root: Path, hook: str = DEFAULT_HOOK_NAME
+) -> bool:
+    """Remove a codegraph-managed git hook. Returns True if removed."""
+    hook_path = _hooks_dir(repo_root) / hook
+    if not hook_path.exists():
+        return False
+    text = hook_path.read_text()
+    if HOOK_MARKER not in text:
+        return False
+    hook_path.unlink()
+    return True
+
+

codegraph/review/risk.py

@@ -0,0 +1,219 @@
+"""Risk scoring for diff entries."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import networkx as nx
+
+from codegraph.analysis.cycles import find_cycles
+from codegraph.analysis.hotspots import find_hotspots
+from codegraph.graph.schema import EdgeKind
+from codegraph.review.differ import EdgeChange, NodeChange
+
+
+@dataclass
+class Risk:
+    score: int  # 0-100
+    level: str  # low | med | high | critical
+    reasons: list[str] = field(default_factory=list)
+
+
+def _level(score: int) -> str:
+    if score >= 81:
+        return "critical"
+    if score >= 51:
+        return "high"
+    if score >= 21:
+        return "med"
+    return "low"
+
+
+def _kind_str(value: object) -> str:
+    return str(getattr(value, "value", value) or "")
+
+
+def _find_node_id(
+    qualname: str, kind: str, graph: nx.MultiDiGraph
+) -> str | None:
+    for nid, attrs in graph.nodes(data=True):
+        if (
+            str(attrs.get("qualname") or "") == qualname
+            and _kind_str(attrs.get("kind")) == kind
+        ):
+            return str(nid)
+    return None
+
+
+def _count_callers(node_id: str, graph: nx.MultiDiGraph) -> int:
+    count = 0
+    for _src, _dst, key in graph.in_edges(node_id, keys=True):
+        if key == EdgeKind.CALLS.value:
+            count += 1
+    return count
+
+
+def _has_callers_in_new(
+    old_node_id: str, old_graph: nx.MultiDiGraph, new_graph: nx.MultiDiGraph
+) -> bool:
+    """Return True if any caller of ``old_node_id`` (in old) still exists in new."""
+    new_ids = set(new_graph.nodes())
+    return any(
+        src in new_ids
+        for src, _dst, _data in old_graph.in_edges(old_node_id, data=True)
+    )
+
+
+def _hotspot_files(graph: nx.MultiDiGraph) -> frozenset[str]:
+    return frozenset(h.file for h in find_hotspots(graph, limit=10) if h.file)
+
+
+def _is_hotspot_file(
+    file: str,
+    graph: nx.MultiDiGraph,
+    cache: dict[str, frozenset[str]] | None = None,
+) -> bool:
+    if not file:
+        return False
+    if cache is not None and "files" in cache:
+        return file in cache["files"]
+    return file in _hotspot_files(graph)
+
+
+def _is_public_api(qualname: str) -> bool:
+    if not qualname:
+        return False
+    parts = qualname.rsplit(".", 1)
+    name = parts[-1]
+    return not name.startswith("_")
+
+
+_SIG_PARAM_RE = re.compile(r"\(([^)]*)\)")
+
+
+def _param_count(signature: str) -> int:
+    if not signature:
+        return -1
+    m = _SIG_PARAM_RE.search(signature)
+    if not m:
+        return -1
+    inside = m.group(1).strip()
+    if not inside:
+        return 0
+    # Naive split on commas at depth 0 - good enough for python signatures.
+    depth = 0
+    parts: list[str] = []
+    buf: list[str] = []
+    for ch in inside:
+        if ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        if ch == "," and depth == 0:
+            parts.append("".join(buf).strip())
+            buf = []
+        else:
+            buf.append(ch)
+    if buf:
+        parts.append("".join(buf).strip())
+    return len([p for p in parts if p])
+
+
+def _param_count_changed(old_sig: str, new_sig: str) -> bool:
+    old = _param_count(old_sig)
+    new = _param_count(new_sig)
+    if old < 0 or new < 0:
+        return old_sig != new_sig
+    return old != new
+
+
+def _cycle_total(
+    graph: nx.MultiDiGraph,
+    cache: dict[str, int] | None = None,
+    label: str = "",
+) -> int:
+    if cache is not None and label in cache:
+        return cache[label]
+    return find_cycles(graph).total
+
+
+def _introduces_cycle(
+    new_graph: nx.MultiDiGraph,
+    old_graph: nx.MultiDiGraph,
+    cache: dict[str, int] | None = None,
+) -> bool:
+    new_total = _cycle_total(new_graph, cache, "new")
+    old_total = _cycle_total(old_graph, cache, "old")
+    return new_total > old_total
+
+
+# pragma: codegraph-public-api
+def score_change(
+    change: NodeChange | EdgeChange,
+    *,
+    new_graph: nx.MultiDiGraph,
+    old_graph: nx.MultiDiGraph,
+    extra: dict[str, Any] | None = None,
+) -> Risk:
+    """Score a single diff entry against the new + old graphs."""
+    score = 0
+    reasons: list[str] = []
+    extra = extra or {}
+    raw_hotspot = extra.get("hotspot_cache")
+    hotspot_cache: dict[str, frozenset[str]] | None = (
+        raw_hotspot if isinstance(raw_hotspot, dict) else None
+    )
+    raw_cycle = extra.get("cycle_cache")
+    cycle_cache: dict[str, int] | None = (
+        raw_cycle if isinstance(raw_cycle, dict) else None
+    )
+
+    if isinstance(change, NodeChange):
+        new_id = _find_node_id(change.qualname, change.kind, new_graph)
+        old_id = _find_node_id(change.qualname, change.kind, old_graph)
+
+        if new_id is not None:
+            fan_in = _count_callers(new_id, new_graph)
+            if fan_in >= 10:
+                score += 40
+                reasons.append(f"high blast radius ({fan_in} callers)")
+
+        if (
+            change.change_kind == "removed"
+            and new_id is None
+            and old_id is not None
+            and _has_callers_in_new(old_id, old_graph, new_graph)
+        ):
+            score += 50
+            reasons.append("removed symbol still referenced")
+
+        hotspot_graph = (
+            old_graph if change.change_kind == "removed" else new_graph
+        )
+        if _is_hotspot_file(change.file, hotspot_graph, hotspot_cache):
+            score += 20
+            reasons.append("in hotspot file")
+
+        if change.change_kind == "added" and new_id is not None:
+            fan_in = _count_callers(new_id, new_graph)
+            if fan_in == 0 and not _is_public_api(change.qualname):
+                score += 10
+                reasons.append("potentially unreachable")
+
+        if change.change_kind == "modified":
+            sig_details = change.details.get("signature") or {}
+            old_sig = str(sig_details.get("old") or "")
+            new_sig = str(sig_details.get("new") or "")
+            if old_sig and new_sig and _param_count_changed(old_sig, new_sig):
+                score += 20
+                reasons.append("signature change")
+
+    if extra.get("introduces_cycle") or _introduces_cycle(
+        new_graph, old_graph, cycle_cache
+    ):
+        score += 30
+        reasons.append("introduces import/call cycle")
+
+    score = min(100, score)
+    return Risk(score=score, level=_level(score), reasons=reasons)