graphite-code 0.3.0__py3-none-any.whl

graphite/cluster.py

@@ -0,0 +1,111 @@
+"""Community detection using Louvain (and optional Leiden)."""
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+from typing import Any
+
+import community as community_louvain
+import networkx as nx
+from pathlib import Path
+
+
+def detect_communities(g: nx.DiGraph, seed: int = 42, weight: str = "weight") -> dict[str, Any]:
+    """Run Louvain on an undirected projection of the graph."""
+    # Build deterministic undirected projection manually.
+    ug = nx.Graph()
+    for n in sorted(g.nodes()):
+        ug.add_node(n)
+    # Aggregate weights for both directions deterministically.
+    edge_weights: dict[tuple[str, str], float] = {}
+    for u, v, d in sorted(g.edges(data=True), key=lambda e: (e[0], e[1], e[2].get("relation", ""))):
+        key = tuple(sorted((u, v)))
+        edge_weights[key] = edge_weights.get(key, 0.0) + d.get("weight", 1.0)
+    for (u, v), w in sorted(edge_weights.items()):
+        ug.add_edge(u, v, weight=w)
+
+    partition = community_louvain.best_partition(ug, random_state=seed, weight=weight)
+
+    communities: dict[int, set[str]] = defaultdict(set)
+    for node, comm in partition.items():
+        communities[comm].add(node)
+
+    # Build cluster metadata.
+    clusters = []
+    for cid, members in sorted(communities.items()):
+        file_nodes = [n for n in members if g.nodes[n].get("kind") == "file"]
+        func_nodes = [n for n in members if g.nodes[n].get("kind") in ("function", "method")]
+        class_nodes = [n for n in members if g.nodes[n].get("kind") == "class"]
+        labels = _label_cluster(g, members)
+        clusters.append({
+            "id": cid,
+            "members": sorted(members),
+            "size": len(members),
+            "file_count": len(file_nodes),
+            "function_count": len(func_nodes),
+            "class_count": len(class_nodes),
+            "labels": labels,
+        })
+
+    return {
+        "node_to_community": {k: partition[k] for k in sorted(partition)},
+        "clusters": sorted(clusters, key=lambda c: c["size"], reverse=True),
+        "count": len(clusters),
+    }
+
+
+def _label_cluster(g: nx.DiGraph, members: Iterable[str]) -> list[str]:
+    """Generate zero-LLM cluster labels from shared directory and common node kinds.
+
+    Iterates in sorted order because the caller passes a `set`, whose order
+    `PYTHONHASHSEED` randomizes per process. That reached the artifact: `max()`
+    returns the FIRST maximum, so a tie between two kinds resolved to whichever
+    the set happened to yield first. Measured -- one cluster's labels were
+    `['src/graphite']` in one build of a commit and `['src/graphite',
+    'functions']` in the next, because `unknown` and `function` tied and
+    `unknown` suppresses the label entirely.
+    """
+    labels: list[str] = []
+    ordered = sorted(members)
+
+    # Shared parent directory from file nodes.
+    dirs: list[str] = []
+    for n in ordered:
+        sf = g.nodes[n].get("source_file")
+        if sf:
+            dirs.append(Path(sf).parent.as_posix())
+    if dirs:
+        common = _common_prefix(dirs)
+        if common and common != ".":
+            labels.append(common)
+
+    # Most common kind, ties broken by name so the winner is a property of the
+    # cluster rather than of this process's hash seed.
+    kinds: dict[str, int] = defaultdict(int)
+    for n in ordered:
+        kinds[g.nodes[n].get("kind", "unknown")] += 1
+    top_kind = min(kinds.items(), key=lambda kv: (-kv[1], kv[0]))[0]
+    if top_kind != "unknown":
+        labels.append(f"{top_kind}s")
+
+    # Dedupe while preserving order.
+    seen = set()
+    out = []
+    for label in labels:
+        if label not in seen:
+            out.append(label)
+            seen.add(label)
+    return out
+
+
+def _common_prefix(paths: list[str]) -> str:
+    if not paths:
+        return ""
+    parts = [p.split("/") for p in paths]
+    prefix = []
+    for segments in zip(*parts):
+        if len(set(segments)) == 1:
+            prefix.append(segments[0])
+        else:
+            break
+    return "/".join(prefix)

graphite/config.py

@@ -0,0 +1,209 @@
+"""Graphite configuration defaults and environment overrides."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+
+def default_projects_root() -> Path:
+    r"""Base folder for daemon/init defaults: the environment, else the cwd.
+
+    This used to probe one hardcoded absolute path and return it when that
+    directory existed, welding a single machine's drive layout into a
+    published tool. The literal is deliberately not repeated here: it would
+    ship inside the wheel, which is exactly the defect being removed. Three
+    consequences, in rising order of seriousness:
+
+    * the path reached `--help` text and every README example -- and README is
+      the packaging `readme`, so it rendered on PyPI as if it were the default;
+    * any user who happens to have that directory would silently get a folder
+      that is not theirs, with nothing said about it;
+    * `channel_root()` derives from this, so which directory the agent channel
+      lived in was decided by whether one drive letter existed.
+
+    `GRAPHITE_PROJECTS_ROOT` is now the only way to move it, which is what the
+    variable was always for. Machines that relied on the old fallback set it
+    explicitly -- an operator action, and a visible one, rather than a constant
+    in shipped source.
+    """
+    env = os.environ.get("GRAPHITE_PROJECTS_ROOT")
+    if env:
+        return Path(env)
+    return Path(".")
+
+
+@dataclass
+class Config:
+    """Immutable runtime configuration."""
+
+    output_dir: Path = Path("graph-out")
+    cache_dir: Path = Path(".cache/graphite")
+    cache_version: str = "v11"  # bump on extraction-format changes (v11: destructured hook callables bindable by name; v10: arrow/function-expression definitions bindable by name, new_expression emits calls edges; v9: EXTERNAL_CALL confidence on calls edges; v8: from-package submodule import edges; v7: python import/file-node resolution, import maps, python method dispatch; v6: per-package tsconfig path aliases; v5: resolve JS-extension + ".."-relative imports; v4: full-path node ids, workspace imports, phantom-edge drop)
+    workers: int = 4
+    max_file_size: int = 1_000_000  # bytes
+    max_files: int | None = None
+    include_dotfiles: bool = False
+    typescript_resolver: str = "auto"  # auto | compiler | heuristic | disabled
+    typescript_resolver_timeout_seconds: float = 10.0
+    typescript_symbol_references: bool = True
+    llm_mode: str = "none"  # none | auto | local | cloud
+    llm_provider: str = "ollama"
+    llm_model: str | None = None
+    llm_base_url: str | None = None
+    llm_api_key: str | None = None
+    llm_timeout_seconds: float = 30.0
+    llm_max_input_chars: int = 12000
+    llm_max_output_tokens: int = 512
+    provider_observer_enabled_providers: tuple[str, ...] = ()
+    provider_observer_interval_seconds: float = 300.0
+    provider_observer_timeout_seconds: float = 15.0
+    provider_observer_max_per_cycle: int = 4
+    provider_observer_backoff_cap_seconds: float = 3_600.0
+    provider_observer_jitter_ratio: float = 0.1
+    seed: int = 42
+    verbose: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        from dataclasses import asdict
+        return asdict(self)
+
+    def routing_settings(self, overrides: dict[str, str] | None = None):
+        """Build isolated routing settings without exporting routing secrets."""
+        from .routing.settings import RoutingSettings
+
+        return RoutingSettings.from_env(overrides)
+
+    def provider_observer_options(self):
+        """Build validated non-inference daemon observer limits."""
+        from .provider_observer import ProviderObserverOptions
+        from .routing.lifecycle import LifecycleProviderId
+
+        try:
+            providers = tuple(
+                LifecycleProviderId(value)
+                for value in self.provider_observer_enabled_providers
+            )
+        except ValueError:
+            raise ValueError("observer_enabled_providers_invalid") from None
+        options = ProviderObserverOptions(
+            enabled_providers=providers,
+            interval_seconds=self.provider_observer_interval_seconds,
+            timeout_seconds=self.provider_observer_timeout_seconds,
+            max_observations_per_cycle=self.provider_observer_max_per_cycle,
+            backoff_cap_seconds=self.provider_observer_backoff_cap_seconds,
+            jitter_ratio=self.provider_observer_jitter_ratio,
+        )
+        options.validate()
+        return options
+
+    def canonical_graph(self) -> "Config":
+        """Return configuration that cannot carry provider authority into a graph operation."""
+        return replace(
+            self,
+            llm_mode="none",
+            llm_provider="none",
+            llm_model=None,
+            llm_base_url=None,
+            llm_api_key=None,
+            llm_timeout_seconds=30.0,
+            llm_max_input_chars=12_000,
+            llm_max_output_tokens=512,
+        )
+
+    @classmethod
+    def from_env(
+        cls,
+        overrides: dict[str, str] | None = None,
+        *,
+        include_llm: bool = True,
+    ) -> "Config":
+        """Build config from environment variables and CLI overrides."""
+        if not isinstance(include_llm, bool):
+            raise ValueError("include_llm_invalid")
+        env: dict[str, str] = {}
+        for key in os.environ:
+            normalized = key.upper()
+            if not normalized.startswith("GRAPHITE_"):
+                continue
+            if not include_llm and normalized.startswith("GRAPHITE_LLM"):
+                continue
+            env[key.lower()] = os.environ[key]
+        if overrides:
+            env.update({
+                key.lower(): value
+                for key, value in overrides.items()
+                if include_llm or not key.upper().startswith("GRAPHITE_LLM")
+            })
+
+        def _path(key: str, default: Path) -> Path:
+            return Path(env[key]) if key in env else default
+
+        def _int(key: str, default: int) -> int:
+            return int(env[key]) if key in env and env[key].isdigit() else default
+
+        def _bounded_int(key: str, default: int, minimum: int, maximum: int) -> int:
+            return min(max(_int(key, default), minimum), maximum)
+
+        def _opt_int(key: str, default: int | None) -> int | None:
+            if key in env and env[key].isdigit():
+                return int(env[key])
+            return default
+
+        def _float(key: str, default: float) -> float:
+            try:
+                return float(env[key]) if key in env else default
+            except ValueError:
+                return default
+
+        def _bool(key: str, default: bool) -> bool:
+            return env.get(key, str(default).lower()).lower() in ("1", "true", "yes", "on")
+
+        def _csv(key: str) -> tuple[str, ...]:
+            raw = env.get(key, "")
+            return tuple(part.strip().casefold() for part in raw.split(",") if part.strip())
+
+        config = cls(
+            output_dir=_path("graphite_output_dir", Path("graph-out")),
+            cache_dir=_path("graphite_cache_dir", Path(".cache/graphite")),
+            cache_version=env.get("graphite_cache_version", "v11"),
+            workers=_int("graphite_workers", 4),
+            max_file_size=_int("graphite_max_file_size", 1_000_000),
+            max_files=_opt_int("graphite_max_files", None),
+            include_dotfiles=_bool("graphite_include_dotfiles", False),
+            typescript_resolver=env.get("graphite_typescript_resolver", "auto"),
+            typescript_resolver_timeout_seconds=_float("graphite_typescript_resolver_timeout", 10.0),
+            typescript_symbol_references=_bool("graphite_typescript_symbol_references", True),
+            llm_mode=env.get("graphite_llm", "none"),
+            llm_provider=env.get("graphite_llm_provider", "ollama"),
+            llm_model=env.get("graphite_llm_model"),
+            llm_base_url=env.get("graphite_llm_base_url"),
+            llm_api_key=env.get("graphite_llm_api_key"),
+            llm_timeout_seconds=_float("graphite_llm_timeout", 30.0),
+            llm_max_input_chars=_int("graphite_llm_max_input_chars", 12000),
+            llm_max_output_tokens=_bounded_int(
+                "graphite_llm_max_output_tokens", 512, 1, 4096
+            ),
+            provider_observer_enabled_providers=_csv(
+                "graphite_provider_observer_enabled_providers"
+            ),
+            provider_observer_interval_seconds=_float(
+                "graphite_provider_observer_interval", 300.0
+            ),
+            provider_observer_timeout_seconds=_float(
+                "graphite_provider_observer_timeout", 15.0
+            ),
+            provider_observer_max_per_cycle=_int(
+                "graphite_provider_observer_max_per_cycle", 4
+            ),
+            provider_observer_backoff_cap_seconds=_float(
+                "graphite_provider_observer_backoff_cap", 3_600.0
+            ),
+            provider_observer_jitter_ratio=_float(
+                "graphite_provider_observer_jitter_ratio", 0.1
+            ),
+            seed=_int("graphite_seed", 42),
+            verbose=_bool("graphite_verbose", False),
+        )
+        return config if include_llm else config.canonical_graph()

graphite/context.py

@@ -0,0 +1,355 @@
+"""Agent-focused compact graph context for selected files or nodes."""
+from __future__ import annotations
+
+from collections import deque
+from typing import Any
+
+import networkx as nx
+
+from .answer_contract import (
+    GRADE_INCONCLUSIVE,
+    build_answer_block,
+    empty_marker,
+    is_degraded,
+    is_unmeasured,
+    languages_for_nodes,
+)
+from .health import ratio_percent, resolution_health
+from .listing import listing_lines
+from .query import _find_node_detail
+
+_CONTEXT_LIST_CAP = 30
+
+_TEST_SUFFIXES = (
+    ".test.ts",
+    ".spec.ts",
+    ".test.tsx",
+    ".spec.tsx",
+    ".test.js",
+    ".spec.js",
+    ".test.py",
+    ".spec.py",
+)
+
+
+def build_context(
+    g: nx.DiGraph,
+    inputs: list[str],
+    *,
+    depth: int = 2,
+    neighbor_limit: int = 20,
+) -> dict[str, Any]:
+    """Build compact context for code agents without dumping the full graph."""
+    if depth < 0:
+        raise ValueError("context depth must be zero or greater")
+    if neighbor_limit <= 0:
+        raise ValueError("context neighbor limit must be greater than zero")
+
+    matched: list[dict[str, Any]] = []
+    missing: list[str] = []
+    start_nodes: list[str] = []
+    for item in inputs:
+        detail = _find_node_detail(g, item)
+        if detail:
+            node, match_type, alternates = detail
+            start_nodes.append(node)
+            entry: dict[str, Any] = {"input": item, "node": _node_summary(g, node), "match_type": match_type}
+            if alternates:
+                entry["alternates"] = alternates
+            matched.append(entry)
+        else:
+            missing.append(item)
+
+    impact = _reverse_impact(g, start_nodes, depth)
+    dependency_pairs = {node: _neighbors(g, node, outgoing=True, limit=neighbor_limit) for node in start_nodes}
+    dependent_pairs = {node: _neighbors(g, node, outgoing=False, limit=neighbor_limit) for node in start_nodes}
+    direct_dependencies = {node: items for node, (items, _) in dependency_pairs.items()}
+    direct_dependents = {node: items for node, (items, _) in dependent_pairs.items()}
+    neighbor_totals = {
+        "direct_dependencies": {node: total for node, (_, total) in dependency_pairs.items()},
+        "direct_dependents": {node: total for node, (_, total) in dependent_pairs.items()},
+    }
+    communities = _community_peers(g, start_nodes, limit=neighbor_limit)
+    risk = [_risk_summary(g, node) for node in start_nodes]
+
+    health = resolution_health(g)
+    total = len(impact["impacted_files"]) + len(impact["likely_tests"])
+    matched_languages = languages_for_nodes(g, start_nodes)
+    try:
+        block = build_answer_block(
+            g,
+            relations=("calls", "imports"),
+            languages=matched_languages,
+            total=total,
+            empty_meaning="no impacted files or tests reachable through bound edges",
+        )
+    except Exception:
+        block = None
+    if block is not None:
+        inconclusive = block["grade"] == GRADE_INCONCLUSIVE
+    elif start_nodes and not matched_languages:
+        # Matched real nodes, but none have an applicable code language (e.g.
+        # markdown/config) -- nothing to grade, not a resolution gap.
+        inconclusive = False
+    else:
+        inconclusive = (
+            not impact["impacted_files"]
+            and not impact["likely_tests"]
+            and not health["healthy"]
+        )
+
+    result: dict[str, Any] = {
+        "metadata": {
+            "node_count": g.number_of_nodes(),
+            "edge_count": g.number_of_edges(),
+            "density": nx.density(g),
+        },
+        "inputs": inputs,
+        "matched": matched,
+        "missing": missing,
+        "depth": depth,
+        "direct_dependencies": direct_dependencies,
+        "direct_dependents": direct_dependents,
+        "neighbor_totals": neighbor_totals,
+        "impact": impact,
+        "communities": communities,
+        "risk": risk,
+        "resolution_health": health,
+        "inconclusive": inconclusive,
+    }
+    if block is not None:
+        result["answer"] = block
+    return result
+
+
+def format_context_markdown(context: dict[str, Any]) -> str:
+    """Render compact context as Markdown for humans and agents."""
+    meta = context["metadata"]
+    lines = [
+        "# Graphite Context",
+        "",
+        f"- Nodes: {meta['node_count']}",
+        f"- Edges: {meta['edge_count']}",
+        f"- Depth: {context['depth']}",
+    ]
+    if context["missing"]:
+        lines.append(f"- Missing inputs: {', '.join(context['missing'])}")
+
+    lines.extend(["", "## Matched"])
+    for item in context["matched"]:
+        node = item["node"]
+        lines.append(
+            f"- `{item['input']}` -> `{node['id']}` "
+            f"({node['kind']}, in={node['in_degree']}, out={node['out_degree']})"
+        )
+
+    lines.extend(["", "## Impact"])
+    impact = context["impact"]
+    health = context.get("resolution_health") or {}
+    unhealthy = health.get("healthy") is False
+    answer = context.get("answer")
+    if impact["impacted_files"] or impact["likely_tests"]:
+        marker = empty_marker(answer)
+        lines.extend(
+            listing_lines(
+                impact["impacted_files"],
+                lambda path: f"`{path}`",
+                header="Impacted files:",
+                cap=_CONTEXT_LIST_CAP,
+                indent="",
+                empty=marker,
+            )
+        )
+    elif context.get("inconclusive"):
+        if answer:
+            meaning = answer.get(
+                "empty_meaning", "no impacted files or tests reachable through bound edges"
+            )
+            lines.append(
+                f"Impacted files: none found — INCONCLUSIVE: {meaning}; "
+                "treat as unverified and confirm with grep."
+            )
+        else:
+            lines.append(
+                "Impacted files: none found — INCONCLUSIVE: only "
+                f"{ratio_percent(health, 'imports')} of import edges and "
+                f"{ratio_percent(health, 'calls')} of call edges resolved in this "
+                "graph; treat as unverified and confirm with grep."
+            )
+    else:
+        answer_meaning = (answer or {}).get("empty_meaning")
+        if answer_meaning:
+            lines.append(f"Impacted files: none found — {answer_meaning}")
+        else:
+            lines.append("Impacted files: none found")
+    if impact["impacted_files"] or impact["likely_tests"]:
+        lines.extend(
+            listing_lines(
+                impact["likely_tests"],
+                lambda path: f"`{path}`",
+                header="Likely tests:",
+                cap=_CONTEXT_LIST_CAP,
+                indent="",
+                empty=empty_marker(answer),
+            )
+        )
+    if unhealthy and (impact["impacted_files"] or impact["likely_tests"]):
+        lines.append(
+            f"note: resolution health low (imports {ratio_percent(health, 'imports')}, "
+            f"calls {ratio_percent(health, 'calls')}) — this list may be incomplete."
+        )
+
+    empty = not impact["impacted_files"] and not impact["likely_tests"]
+    if answer:
+        if empty or is_degraded(answer) or is_unmeasured(answer):
+            cells = ", ".join(
+                f"{relation} ({language}) {langs[language]['ratio']:.2f}"
+                for relation, langs in sorted(answer.get("health", {}).items())
+                for language in sorted(langs)
+            )
+            grade = answer["grade"].replace("_", "-")
+            line = f"answer health: {cells} — {grade}" if cells else f"answer health: — {grade}"
+            lines.append(line)
+            if answer.get("caveats"):
+                lines.append("known limits: " + "; ".join(c["summary"] for c in answer["caveats"]))
+
+    lines.extend(["", "## Direct Dependents"])
+    # Guarded read: contexts built before neighbor_totals existed still render.
+    totals = context.get("neighbor_totals") or {}
+    dependents = context["direct_dependents"]
+    if unhealthy and all(not neighbors for neighbors in dependents.values()):
+        lines.append("no direct dependents found — inconclusive (resolution health low)")
+    else:
+        _append_neighbor_section(lines, dependents, totals.get("direct_dependents"))
+
+    lines.extend(["", "## Direct Dependencies"])
+    _append_neighbor_section(lines, context["direct_dependencies"], totals.get("direct_dependencies"))
+
+    lines.extend(["", "## Risk Signals"])
+    for item in context["risk"]:
+        flags = ", ".join(item["flags"]) if item["flags"] else "none"
+        lines.append(f"- `{item['id']}`: {flags}")
+
+    return "\n".join(lines) + "\n"
+
+
+def _append_neighbor_section(
+    lines: list[str],
+    groups: dict[str, list[dict[str, Any]]],
+    totals: dict[str, int] | None = None,
+) -> None:
+    if not groups:
+        lines.append("none")
+        return
+    for node, neighbors in groups.items():
+        lines.append(f"- `{node}`")
+        if not neighbors:
+            lines.append("  - none")
+            continue
+        # No second cap here: build_context already applied neighbor_limit. A
+        # slice at this layer silently overrode the user's explicit flag (#11).
+        for neighbor in neighbors:
+            sf = f" [{neighbor['source_file']}]" if neighbor.get("source_file") else ""
+            lines.append(f"  - `{neighbor['id']}` ({neighbor['kind']}){sf}")
+        hidden = (totals or {}).get(node, len(neighbors)) - len(neighbors)
+        if hidden > 0:
+            lines.append(f"  - ... {hidden} more")
+
+
+def _node_summary(g: nx.DiGraph, node: str) -> dict[str, Any]:
+    attrs = g.nodes[node]
+    return {
+        "id": node,
+        "name": attrs.get("name", node),
+        "kind": attrs.get("kind", "unknown"),
+        "source_file": attrs.get("source_file"),
+        "community": attrs.get("community"),
+        "in_degree": g.in_degree(node),
+        "out_degree": g.out_degree(node),
+    }
+
+
+def _neighbors(
+    g: nx.DiGraph, node: str, *, outgoing: bool, limit: int
+) -> tuple[list[dict[str, Any]], int]:
+    """Capped neighbour summaries, and the uncapped total they were taken from.
+
+    The total is what lets a consumer tell a complete list from a truncated one;
+    without it a list exactly `limit` long is ambiguous.
+    """
+    ids = sorted(g.successors(node) if outgoing else g.predecessors(node))
+    return [_node_summary(g, neighbor) for neighbor in ids[:limit]], len(ids)
+
+
+def _reverse_impact(g: nx.DiGraph, start_nodes: list[str], depth: int) -> dict[str, Any]:
+    visited: set[str] = set(start_nodes)
+    queue: deque[tuple[str, int]] = deque((node, 0) for node in start_nodes)
+    impacted_nodes: set[str] = set()
+    while queue:
+        node, dist = queue.popleft()
+        if dist >= depth:
+            continue
+        for pred in sorted(g.predecessors(node)):
+            if pred in visited:
+                continue
+            visited.add(pred)
+            impacted_nodes.add(pred)
+            queue.append((pred, dist + 1))
+
+    impacted_files: set[str] = set()
+    likely_tests: set[str] = set()
+    for node in impacted_nodes.union(start_nodes):
+        source_file = g.nodes[node].get("source_file")
+        if not source_file:
+            continue
+        if _is_test_file(source_file):
+            likely_tests.add(source_file)
+        elif node not in start_nodes:
+            impacted_files.add(source_file)
+
+    return {
+        "matched_nodes": sorted(start_nodes),
+        "impacted_files": sorted(impacted_files),
+        "likely_tests": sorted(likely_tests),
+        "impacted_node_count": len(impacted_nodes),
+    }
+
+
+def _community_peers(g: nx.DiGraph, start_nodes: list[str], *, limit: int) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for node in start_nodes:
+        community = g.nodes[node].get("community")
+        if community is None:
+            continue
+        peers = [n for n in g.nodes if n != node and g.nodes[n].get("community") == community]
+        result[node] = {
+            "community": community,
+            "peer_count": len(peers),
+            "sample": [_node_summary(g, peer) for peer in sorted(peers)[:limit]],
+        }
+    return result
+
+
+def _risk_summary(g: nx.DiGraph, node: str) -> dict[str, Any]:
+    in_degree = g.in_degree(node)
+    out_degree = g.out_degree(node)
+    flags: list[str] = []
+    if in_degree >= 10:
+        flags.append("high fan-in: many files depend on this")
+    if out_degree >= 25:
+        flags.append("high fan-out: broad dependency surface")
+    if in_degree == 0:
+        flags.append("no direct dependents found")
+    if out_degree == 0:
+        flags.append("no direct dependencies found")
+    return {
+        "id": node,
+        "in_degree": in_degree,
+        "out_degree": out_degree,
+        "flags": flags,
+    }
+
+
+def _is_test_file(path: str) -> bool:
+    normalized = path.replace("\\", "/")
+    return "/tests/" in f"/{normalized}" or normalized.endswith(_TEST_SUFFIXES)