polycodegraph 0.1.0__py3-none-any.whl

codegraph/__init__.py

@@ -0,0 +1,10 @@
+"""codegraph — language-agnostic code graph for analysis, PR review, and AI assistants."""
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("polycodegraph")
+except _PackageNotFoundError:
+    # Source checkout without install (rare — `pip install -e .` registers
+    # the package and avoids this branch in normal dev setups).
+    __version__ = "0.0.0+local"

codegraph/analysis/__init__.py

@@ -0,0 +1,30 @@
+"""Whole-project analyses operating on the codegraph store."""
+from codegraph.analysis.blast_radius import BlastRadiusResult, blast_radius
+from codegraph.analysis.cycles import Cycle, CycleReport, find_cycles
+from codegraph.analysis.dataflow import DataFlow, FlowHop, match_route, trace
+from codegraph.analysis.dead_code import DeadNode, find_dead_code
+from codegraph.analysis.hotspots import Hotspot, find_hotspots
+from codegraph.analysis.metrics import GraphMetrics, compute_metrics
+from codegraph.analysis.roles import classify_roles
+from codegraph.analysis.untested import UntestedNode, find_untested
+
+__all__ = [
+    "BlastRadiusResult",
+    "Cycle",
+    "CycleReport",
+    "DataFlow",
+    "DeadNode",
+    "FlowHop",
+    "GraphMetrics",
+    "Hotspot",
+    "UntestedNode",
+    "blast_radius",
+    "classify_roles",
+    "compute_metrics",
+    "find_cycles",
+    "find_dead_code",
+    "find_hotspots",
+    "find_untested",
+    "match_route",
+    "trace",
+]

codegraph/analysis/_common.py

@@ -0,0 +1,125 @@
+"""Shared helpers for analysis modules."""
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import networkx as nx
+
+from codegraph.graph.schema import EdgeKind
+
+
+def _kind_str(value: object) -> str:
+    """Return the canonical string form of a NodeKind/EdgeKind/str."""
+    return str(getattr(value, "value", value) or "")
+
+
+REFERENCE_EDGE_KINDS: frozenset[str] = frozenset(
+    {
+        EdgeKind.CALLS.value,
+        EdgeKind.IMPORTS.value,
+        EdgeKind.INHERITS.value,
+        EdgeKind.IMPLEMENTS.value,
+    }
+)
+
+
+EXCLUDED_PATH_FRAGMENTS: tuple[str, ...] = (
+    "tests/fixtures/",
+    "tests\\fixtures\\",
+    "/static/",
+    "\\static\\",
+    # Demo / example repos are documentation, not call-graph-traceable code.
+    # Their entry points are framework-driven (FastAPI decorators, React JSX
+    # mount points) so the call-graph analyser would otherwise flag every
+    # showcase symbol as "dead" or "untested".
+    "examples/",
+    "examples\\",
+)
+
+
+def is_excluded_path(file_path: str) -> bool:
+    """True iff the file path is under a directory excluded from analysis.
+
+    Test fixtures and static frontend assets don't have traceable call graphs
+    and should not be analysed for dead-code or untested-symbol detection.
+    """
+    if not file_path:
+        return False
+    return any(fragment in file_path for fragment in EXCLUDED_PATH_FRAGMENTS)
+
+
+def is_protocol_class(graph: nx.MultiDiGraph, class_id: str) -> bool:
+    """True iff the class inherits from ``typing.Protocol``.
+
+    Walks INHERITS out-edges and matches any parent whose target name ends in
+    ``Protocol``. This covers ``Protocol``, ``typing.Protocol``, and the
+    parser's ``unresolved::Protocol`` / ``unresolved::typing.Protocol`` forms.
+    """
+    for _src, dst, key, data in graph.out_edges(class_id, keys=True, data=True):
+        if key != EdgeKind.INHERITS.value:
+            continue
+        target_name = ""
+        meta = data.get("metadata") or {}
+        if isinstance(meta, dict):
+            target_name = str(meta.get("target_name") or "")
+        if not target_name:
+            attrs = graph.nodes.get(dst) or {}
+            target_name = str(attrs.get("name") or attrs.get("qualname") or dst)
+        # Strip an unresolved:: prefix if the dst ID was used as fallback.
+        if target_name.startswith("unresolved::"):
+            target_name = target_name.split("::", 1)[1]
+        # Match bare "Protocol" or any dotted form ending with ".Protocol".
+        if target_name == "Protocol" or target_name.endswith(".Protocol"):
+            return True
+    return False
+
+
+def in_protocol_class(graph: nx.MultiDiGraph, method_id: str) -> bool:
+    """True iff this method's owning class is a typing.Protocol."""
+    for _src, dst, key in graph.out_edges(method_id, keys=True):
+        if key != EdgeKind.DEFINED_IN.value:
+            continue
+        attrs = graph.nodes.get(dst) or {}
+        if _kind_str(attrs.get("kind")) != "CLASS":
+            continue
+        if is_protocol_class(graph, dst):
+            return True
+    return False
+
+
+def in_test_module(graph: nx.MultiDiGraph, node_id: str) -> bool:
+    """True iff the node is in a file whose MODULE node is marked is_test."""
+    attrs = graph.nodes.get(node_id) or {}
+    metadata = attrs.get("metadata") or {}
+    if metadata.get("is_test"):
+        return True
+    file_path = attrs.get("file")
+    if not file_path:
+        return False
+    # Path-based fallback for non-Python test files (e.g. node --test JS files
+    # under tests/) which don't carry the is_test module metadata.
+    normalised = str(file_path).replace("\\", "/")
+    if "/tests/" in normalised or normalised.startswith("tests/"):
+        return True
+    for _, other_attrs in graph.nodes(data=True):
+        if (
+            other_attrs.get("file") == file_path
+            and _kind_str(other_attrs.get("kind")) == "MODULE"
+            and (other_attrs.get("metadata") or {}).get("is_test")
+        ):
+            return True
+    return False
+
+
+def filter_kinds(
+    graph: nx.MultiDiGraph, allowed: Iterable[str]
+) -> nx.MultiDiGraph:
+    """Return a subgraph view containing only edges with kinds in ``allowed``."""
+    allowed_set = set(allowed)
+    out: nx.MultiDiGraph = nx.MultiDiGraph()
+    for nid, attrs in graph.nodes(data=True):
+        out.add_node(nid, **attrs)
+    for src, dst, key, data in graph.edges(keys=True, data=True):
+        if data.get("kind") in allowed_set:
+            out.add_edge(src, dst, key=key, **data)
+    return out

codegraph/analysis/blast_radius.py

@@ -0,0 +1,63 @@
+"""Blast radius: reverse-reachable set of a node via reference edges."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import networkx as nx
+
+from codegraph.analysis._common import REFERENCE_EDGE_KINDS, in_test_module
+
+
+@dataclass
+class BlastRadiusResult:
+    target: str
+    nodes: list[str] = field(default_factory=list)
+    files: set[str] = field(default_factory=set)
+    test_nodes: list[str] = field(default_factory=list)
+    depth: int | None = None
+
+    @property
+    def size(self) -> int:
+        return len(self.nodes)
+
+
+def blast_radius(
+    graph: nx.MultiDiGraph,
+    node_id: str,
+    depth: int | None = None,
+) -> BlastRadiusResult:
+    """Return the set of nodes that transitively reference ``node_id``.
+
+    A node ``B`` is in the blast radius of ``A`` iff there is a path from
+    ``B`` to ``A`` along CALLS / IMPORTS / INHERITS / IMPLEMENTS edges. The
+    target itself is excluded from ``nodes``.
+    """
+    result = BlastRadiusResult(target=node_id, depth=depth)
+    if node_id not in graph:
+        return result
+
+    visited: set[str] = {node_id}
+    frontier: set[str] = {node_id}
+    hops = 0
+    while frontier and (depth is None or hops < depth):
+        next_frontier: set[str] = set()
+        for current in frontier:
+            for src, _dst, key in graph.in_edges(current, keys=True):
+                if key not in REFERENCE_EDGE_KINDS:
+                    continue
+                if src in visited:
+                    continue
+                next_frontier.add(src)
+        visited |= next_frontier
+        frontier = next_frontier
+        hops += 1
+
+    visited.discard(node_id)
+    result.nodes = sorted(visited)
+    for nid in visited:
+        attrs = graph.nodes.get(nid) or {}
+        if attrs.get("file"):
+            result.files.add(str(attrs["file"]))
+        if in_test_module(graph, nid):
+            result.test_nodes.append(nid)
+    return result

codegraph/analysis/cycles.py

@@ -0,0 +1,79 @@
+"""Cycle detection over import + call subgraphs."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import networkx as nx
+
+from codegraph.analysis._common import filter_kinds
+from codegraph.graph.schema import EdgeKind
+
+
+@dataclass(frozen=True)
+class Cycle:
+    """A single cycle: parallel lists of node IDs and their qualnames.
+
+    `node_ids` is the canonical machine identifier; `qualnames` is the
+    human-readable rendering used in reports. Lists are the same length
+    and in the same order.
+    """
+
+    node_ids: list[str]
+    qualnames: list[str]
+
+
+@dataclass
+class CycleReport:
+    import_cycles: list[Cycle] = field(default_factory=list)
+    call_cycles: list[Cycle] = field(default_factory=list)
+
+    @property
+    def total(self) -> int:
+        return len(self.import_cycles) + len(self.call_cycles)
+
+
+def _qualname_for(graph: nx.MultiDiGraph, node_id: str) -> str:
+    attrs = graph.nodes.get(node_id, {})
+    qn = attrs.get("qualname")
+    if isinstance(qn, str) and qn:
+        return qn
+    name = attrs.get("name")
+    if isinstance(name, str) and name:
+        return name
+    return node_id
+
+
+def _scc_cycles(graph: nx.MultiDiGraph) -> list[Cycle]:
+    digraph = nx.DiGraph(graph)
+    cycles: list[Cycle] = []
+    for component in nx.strongly_connected_components(digraph):
+        if len(component) > 1:
+            node_ids = sorted(component)
+            cycles.append(
+                Cycle(
+                    node_ids=node_ids,
+                    qualnames=[_qualname_for(graph, n) for n in node_ids],
+                )
+            )
+            continue
+        # length-1 SCC: only a cycle if there's a self-loop.
+        node = next(iter(component))
+        if digraph.has_edge(node, node):
+            cycles.append(
+                Cycle(
+                    node_ids=[node],
+                    qualnames=[_qualname_for(graph, node)],
+                )
+            )
+    cycles.sort(key=lambda c: (-len(c.node_ids), c.node_ids))
+    return cycles
+
+
+def find_cycles(graph: nx.MultiDiGraph) -> CycleReport:
+    """Detect strongly-connected components in import and call subgraphs."""
+    import_only = filter_kinds(graph, {EdgeKind.IMPORTS.value})
+    call_only = filter_kinds(graph, {EdgeKind.CALLS.value})
+    return CycleReport(
+        import_cycles=_scc_cycles(import_only),
+        call_cycles=_scc_cycles(call_only),
+    )