Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

perf(graph): reuse betweenness inside a churn budget instead of rescoring (#2066)

Raghav Chamadiya349a7938fa66
diff --git a/packages/api-client/src/types/intelligence.ts b/packages/api-client/src/types/intelligence.ts
index 509481b8d..8fbcfb2cb 100644
--- a/packages/api-client/src/types/intelligence.ts
+++ b/packages/api-client/src/types/intelligence.ts
@@ -80,6 +80,8 @@ export interface GraphMetricsResponse {
pagerank_percentile: number;
betweenness: number;
betweenness_percentile: number;
+ /** False when the node appeared after the last exact centrality scoring. */
+ betweenness_scored?: boolean;
community_id: number;
community_label: string | null;
is_entry_point: boolean;
diff --git a/packages/core/alembic/versions/0061_graph_node_betweenness_commit.py b/packages/core/alembic/versions/0061_graph_node_betweenness_commit.py
new file mode 100644
index 000000000..884693eec
--- /dev/null
+++ b/packages/core/alembic/versions/0061_graph_node_betweenness_commit.py
@@ -0,0 +1,45 @@
+"""Add betweenness_commit to graph_nodes.
+
+Exact betweenness is now reused across small structural changes rather than
+recomputed on every symbol-set change, so a node added since the last scoring
+carries the column's 0.0 default without ever having been measured. Reporting
+that as a centrality reads as "on no shortest path", which is the opposite
+claim for a symbol just spliced into a hot call chain. NULL records "not
+scored", the same omitted-reads-as-not-recorded contract as ``analyzed_commit``
+on the health rows. The other metrics on this row are recomputed every run and
+need no stamp.
+
+Existing rows back-fill as NULL, which is correct: their stamp is genuinely
+unknown until the next run scores them.
+
+Local SQLite stores get the column from the model via ``init_db``'s additive
+schema reconciler; this migration covers the managed Postgres ones.
+
+Revision ID: 0061
+Revises: 0060
+Create Date: 2026-09-01
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0061"
+down_revision: str | None = "0060"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.add_column(
+ "graph_nodes",
+ sa.Column("betweenness_commit", sa.String(length=40), nullable=True),
+ )
+
+
+def downgrade() -> None:
+ op.drop_column("graph_nodes", "betweenness_commit")
diff --git a/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py b/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py
index 2edf1d7b0..aca79d883 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py
@@ -6,10 +6,22 @@ graph even when the docstring-only edit it processed didn't change a single
edge. Betweenness is a pure function of the *structure* of the (unweighted)
subgraph it runs on, so values cache safely keyed by a signature over the
sorted node and edge sets: content edits that don't move call/heritage/import
-edges hit; any structural change misses and recomputes.
-
-One entry per kind (``file`` / ``symbol``) — the cache answers "is the graph
-still the one I last scored?", not a history. Thread-safe because the init
+edges hit exactly.
+
+A structural change used to mean a full recompute, which made "add one
+function" the most expensive shape of edit there is — an order of magnitude
+dearer than a body-only one. It barely moves the answer: on a 13k-symbol graph
+one added function left every surviving rank within four places. So
+:meth:`CentralityCache.lookup` serves the last exact scoring while the graph
+has drifted no further from it than ``max_churn`` nodes-plus-edges, and reports
+how far that is.
+
+The reference set stays pinned to the last *exact* scoring rather than
+advancing on each reuse, so churn accumulates monotonically and the staleness
+window cannot be walked past one edit at a time.
+
+One entry per kind (``file`` / ``symbol``) — the cache answers "how far is the
+graph from the one I last scored?", not a history. Thread-safe because the init
pipeline computes both kinds concurrently. Best-effort by design: any
load/save error degrades to a fresh computation.
@@ -23,6 +35,7 @@ from __future__ import annotations
import hashlib
import threading
+from dataclasses import dataclass
from pathlib import Path
import structlog
@@ -31,14 +44,15 @@ from repowise.core.cache_seal import dump_sealed_pickle, load_sealed_pickle
log = structlog.get_logger(__name__)
-# Bumped to 2 when betweenness was made order-independent: the signature keys
-# on graph structure only, so a warm cache would keep serving the old,
-# insertion-order-dependent values and two installs at the same commit would
-# still disagree.
-_CACHE_VERSION = 2
+# 2 when betweenness was made order-independent: the signature keys on graph
+# structure only, so a warm cache would keep serving the old, insertion-order-
+# dependent values and two installs at the same commit would still disagree.
+# 3 when entries gained the scored edge set and commit, needed to answer "how
+# far has the graph drifted, and which nodes were never in this scoring".
+_CACHE_VERSION = 3
_CACHE_FILENAME = "centrality_cache.pkl"
-__all__ = ["CentralityCache", "subgraph_signature"]
+__all__ = ["BetweennessScoring", "CentralityCache", "subgraph_signature"]
def subgraph_signature(graph) -> str:
@@ -60,12 +74,53 @@ def subgraph_signature(graph) -> str:
return h.hexdigest()
+def _edge_fingerprints(graph) -> frozenset[int]:
+ """Fingerprint each edge, so churn can be *counted* and not just detected.
+
+ The signature answers "identical?"; measuring drift needs a set difference.
+ Fingerprints rather than the ``(u, v)`` pairs because this is persisted per
+ repository and each pair is two full symbol paths.
+ """
+ return frozenset(
+ int.from_bytes(
+ hashlib.blake2b(f"{u}\x00{v}".encode(errors="replace"), digest_size=8).digest(),
+ "big",
+ )
+ for u, v in graph.edges()
+ )
+
+
+@dataclass(frozen=True)
+class _Entry:
+ """One kind's last exact scoring, and the structure it was scored on."""
+
+ signature: str
+ values: dict[str, float]
+ edges: frozenset[int]
+ scored_commit: str | None
+
+
+@dataclass(frozen=True)
+class BetweennessScoring:
+ """Cached values, plus what a caller needs to judge their age.
+
+ ``churn`` is how many nodes and edges the graph now differs by from the one
+ these were computed on — 0 for an exact hit. Nodes absent from ``values``
+ appeared since and have never been scored; callers must say so rather than
+ let them read as a legitimate 0.0.
+ """
+
+ values: dict[str, float]
+ scored_commit: str | None
+ churn: int
+
+
class CentralityCache:
- """Pickle-backed ``kind -> (signature, values)`` store."""
+ """Pickle-backed ``kind -> last exact scoring`` store."""
def __init__(self, cache_dir: Path | str) -> None:
self._path = Path(cache_dir) / _CACHE_FILENAME
- self._entries: dict[str, tuple[str, dict[str, float]]] = {}
+ self._entries: dict[str, _Entry] = {}
self._lock = threading.Lock()
self._loaded = False
@@ -97,19 +152,47 @@ class CentralityCache:
except Exception as exc: # corrupt / unsigned / unreadable -> recompute
log.debug("centrality_cache_load_failed", error=str(exc))
- def get(self, kind: str, signature: str) -> dict[str, float] | None:
+ def lookup(
+ self, kind: str, graph, *, signature: str, max_churn: int
+ ) -> BetweennessScoring | None:
+ """Return the last exact scoring for *kind* if *graph* is close enough.
+
+ ``None`` when there is no entry, or when the graph has drifted further
+ than *max_churn* nodes-plus-edges from the one that was scored; both
+ mean the caller must recompute.
+ """
with self._lock:
self._ensure_loaded()
entry = self._entries.get(kind)
- if entry is None or entry[0] != signature:
+ if entry is None:
return None
- return dict(entry[1])
-
- def put(self, kind: str, signature: str, values: dict[str, float]) -> None:
- """Store *values* for *kind* and persist atomically."""
+ if entry.signature == signature:
+ return BetweennessScoring(dict(entry.values), entry.scored_commit, 0)
+ # Both compute paths return one entry per node, so the scored node set
+ # is the values' keys.
+ nodes = set(graph.nodes())
+ scored = entry.values.keys()
+ churn = len(nodes - scored) + len(scored - nodes)
+ churn += len(_edge_fingerprints(graph) ^ entry.edges)
+ if churn > max_churn:
+ return None
+ return BetweennessScoring(dict(entry.values), entry.scored_commit, churn)
+
+ def put(
+ self,
+ kind: str,
+ signature: str,
+ values: dict[str, float],
+ *,
+ graph,
+ scored_commit: str | None,
+ ) -> None:
+ """Record an exact scoring for *kind* and persist atomically."""
with self._lock:
self._ensure_loaded()
- self._entries[kind] = (signature, dict(values))
+ self._entries[kind] = _Entry(
+ signature, dict(values), _edge_fingerprints(graph), scored_commit
+ )
try:
payload = {"version": _CACHE_VERSION, "entries": self._entries}
dump_sealed_pickle(self._path, payload, domain=_CACHE_FILENAME)
diff --git a/packages/core/src/repowise/core/ingestion/graph/_metrics.py b/packages/core/src/repowise/core/ingestion/graph/_metrics.py
index c5c1dd96d..ca33c2e39 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_metrics.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_metrics.py
@@ -26,6 +26,17 @@ log = structlog.get_logger(__name__)
_LARGE_REPO_THRESHOLD = 30_000 # nodes — above this, algorithms are expensive
+# How far the graph may drift from the last exact betweenness scoring before it
+# is rescored, as a fraction of nodes-plus-edges. Set at the knee of a sweep
+# that deleted symbols and rescored: rankings held to ~55 churn on a 27k-element
+# graph and broke well before 190.
+#
+# Not a worst case. Betweenness is not Lipschitz in edge count, so removing a
+# single bridge between two subsystems reroutes every path that crossed it
+# while scoring as churn 1. Tolerable only because the values carry the commit
+# they were scored at.
+_CHURN_BUDGET_FRACTION = 0.002
+
class MetricsMixin:
"""Centrality + community + degree metrics for :class:`GraphBuilder`."""
@@ -324,15 +335,42 @@ class MetricsMixin:
self._symbol_betweenness_cache = self._betweenness_with_disk_cache("symbol", sub)
return self._symbol_betweenness_cache
+ def betweenness_scoring(self, kind: str) -> Any | None:
+ """Return the provenance of *kind*'s betweenness, or ``None`` if unscored.
+
+ A :class:`~._centrality_cache.BetweennessScoring`. Persistence stamps
+ each node from it, so a symbol that appeared after the last exact
+ scoring is recorded as never scored rather than as a legitimate zero.
+ """
+ return self._betweenness_scoring.get(kind)
+
+ def _churn_budget(self, g: nx.DiGraph) -> int:
+ """How far *g* may drift from its last exact scoring before rescoring.
+
+ Zero below the cost threshold that already decides whether exact
+ Brandes is worth parallelising: under it the recompute is fast enough
+ that trading accuracy for it buys nothing, so those graphs keep the
+ exact-signature-only behaviour they had before. Above it, proportional
+ to the graph, because the same absolute delta perturbs a large ranking
+ far less than a small one.
+ """
+ from . import _betweenness
+
+ n, e = g.number_of_nodes(), g.number_of_edges()
+ # Read through the module so the tests that lower the threshold reach
+ # this decision too.
+ if n * e < _betweenness._PARALLEL_COST_THRESHOLD:
+ return 0
+ return int((n + e) * _CHURN_BUDGET_FRACTION)
+
def _betweenness_with_disk_cache(self, kind: str, g: nx.DiGraph) -> dict[str, float]:
"""Compute betweenness for *g*, consulting the structure-keyed disk cache.
With a cache attached (see ``GraphBuilder(centrality_cache_dir=...)``)
- and an unchanged subgraph structure, the previous run's values are
- returned without re-running Brandes — the dominant metric cost of an
- incremental update whose change didn't move any edges. Structural
- changes, cache errors, or no cache all fall through to the exact
- computation used before.
+ the previous exact scoring is reused both when the structure is
+ unchanged and when it has drifted no further than the churn budget.
+ Drifting past the budget, cache errors, or no cache all fall through to
+ the exact computation used before.
"""
cache = getattr(self, "_centrality_cache", None)
signature: str | None = None
@@ -341,10 +379,19 @@ class MetricsMixin:
from ._centrality_cache import subgraph_signature
signature = subgraph_signature(g)
- hit = cache.get(kind, signature)
+ hit = cache.lookup(
+ kind, g, signature=signature, max_churn=self._churn_budget(g)
+ )
if hit is not None:
- log.info("betweenness_reused_from_cache", kind=kind, nodes=len(hit))
- return hit
+ log.info(
+ "betweenness_reused_from_cache",
+ kind=kind,
+ nodes=len(hit.values),
+ churn=hit.churn,
+ scored_commit=hit.scored_commit,
+ )
+ self._betweenness_scoring[kind] = hit
+ return hit.values
except Exception as exc:
log.debug("centrality_cache_lookup_failed", kind=kind, error=str(exc))
signature = None
@@ -372,9 +419,12 @@ class MetricsMixin:
from ._betweenness import betweenness_centrality_fast
values = betweenness_centrality_fast(g, normalized=True)
+ from ._centrality_cache import BetweennessScoring
+
+ self._betweenness_scoring[kind] = BetweennessScoring(values, self._head_commit, 0)
if cache is not None and signature is not None:
try:
- cache.put(kind, signature, values)
+ cache.put(kind, signature, values, graph=g, scored_commit=self._head_commit)
except Exception as exc:
log.debug("centrality_cache_store_failed", kind=kind, error=str(exc))
return values
diff --git a/packages/core/src/repowise/core/ingestion/graph/builder.py b/packages/core/src/repowise/core/ingestion/graph/builder.py
index a8b8e55dd..0cd321150 100644
--- a/packages/core/src/repowise/core/ingestion/graph/builder.py
+++ b/packages/core/src/repowise/core/ingestion/graph/builder.py
@@ -47,6 +47,7 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
*,
exclude_patterns: list[str] | None = None,
centrality_cache_dir: Path | str | None = None,
+ head_commit: str | None = None,
include_submodules: bool = False,
include_nested_repos: bool = False,
) -> None:
@@ -87,6 +88,12 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
self._centrality_cache = CentralityCache(centrality_cache_dir)
except Exception:
self._centrality_cache = None
+ # Stamped onto an exact betweenness scoring so a later reuse can say
+ # which commit the values are from. Passed in rather than read here:
+ # reaching for HEAD from ``ingestion`` would invert the package order.
+ self._head_commit: str | None = head_commit
+ # kind -> BetweennessScoring, read by persistence to stamp each node.
+ self._betweenness_scoring: dict[str, Any] = {}
import pathspec
diff --git a/packages/core/src/repowise/core/persistence/crud/graph.py b/packages/core/src/repowise/core/persistence/crud/graph.py
index 6246d79fb..e45b2bf4c 100644
--- a/packages/core/src/repowise/core/persistence/crud/graph.py
+++ b/packages/core/src/repowise/core/persistence/crud/graph.py
@@ -61,6 +61,7 @@ _NODE_FIELDS = (
"is_entry_point",
"pagerank",
"betweenness",
+ "betweenness_commit",
"community_id",
"community_meta_json",
"kind",
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 33003b4bb..6866f5843 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -226,6 +226,13 @@ class GraphNode(Base):
is_entry_point: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
pagerank: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)
betweenness: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)
+ # The commit ``betweenness`` was last actually computed at. Betweenness is
+ # reused across small structural changes, so a node that appeared since the
+ # last scoring holds the ``0.0`` default unmeasured; NULL keeps that apart
+ # from a symbol genuinely on no shortest path. Same "omitted reads as not
+ # recorded" contract as ``analyzed_commit``. The other metrics on this row
+ # are recomputed every run and need no stamp.
+ betweenness_commit: Mapped[str | None] = mapped_column(String(40), nullable=True)
community_id: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
community_meta_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")
# Symbol-level fields (null for file nodes)
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index b52e8d52a..be66f52d5 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -110,6 +110,7 @@ def build_repo_graph(
_read_sources,
_split_cached,
)
+ from repowise.core.workspace.update import get_head_commit
fi_and_bytes = _read_sources(file_infos, None)
parse_cache, cached_hits, to_parse = _split_cached(Path(repo_path), fi_and_bytes, None)
@@ -121,6 +122,7 @@ def build_repo_graph(
repo_path,
exclude_patterns=exclude_patterns,
centrality_cache_dir=Path(repo_path) / ".repowise",
+ head_commit=get_head_commit(Path(repo_path)),
include_submodules=include_submodules,
include_nested_repos=include_nested_repos,
)
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index c87cf538f..4cfcb552e 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -282,6 +282,23 @@ def _derive_entry_point_scores(graph_builder: Any) -> dict[str, float]:
}
+def _betweenness_commits(graph_builder: Any) -> dict[str, str | None]:
+ """Per kind, the commit its betweenness was last exactly computed at.
+
+ ``None`` means the builder cannot say, which is not "never scored" and must
+ not be written as one: a builder rehydrated from SQL serves real values it
+ did not compute, and stamping those NULL would report an entire indexed
+ repository as unscored.
+ """
+ scoring = getattr(graph_builder, "betweenness_scoring", None)
+ if scoring is None:
+ return {"file": None, "symbol": None}
+ try:
+ return {k: getattr(scoring(k), "scored_commit", None) for k in ("file", "symbol")}
+ except Exception: # pragma: no cover - a builder without the accessor
+ return {"file": None, "symbol": None}
+
+
async def persist_graph_nodes(
session: Any,
repo_id: str,
@@ -316,6 +333,8 @@ async def persist_graph_nodes(
if ep_scores is None:
ep_scores = _derive_entry_point_scores(graph_builder)
+ bt_commits = _betweenness_commits(graph_builder)
+
nodes = []
for node_id in graph.nodes:
data = graph.nodes[node_id]
@@ -337,6 +356,17 @@ async def persist_graph_nodes(
"community_id": cd.get(node_id, 0),
}
+ # Scored → its commit; in no scoring → NULL, the unscored marker;
+ # provenance unknown → key omitted, so the stored stamp survives.
+ if node_id in bc:
+ kind, scored = "file", True
+ elif node_id in sym_bc:
+ kind, scored = "symbol", True
+ else:
+ kind, scored = ("file" if node_type == "file" else "symbol"), False
+ if bt_commits[kind] is not None:
+ node_dict["betweenness_commit"] = bt_commits[kind] if scored else None
+
community_meta: dict[str, Any] = {}
if node_type == "file":
cid = cd.get(node_id, 0)
diff --git a/packages/core/src/repowise/core/pipeline/phases/ingestion.py b/packages/core/src/repowise/core/pipeline/phases/ingestion.py
index 6edb93dd9..2e825c6c6 100644
--- a/packages/core/src/repowise/core/pipeline/phases/ingestion.py
+++ b/packages/core/src/repowise/core/pipeline/phases/ingestion.py
@@ -478,10 +478,13 @@ async def _run_ingestion(
parsed_files: list[Any] = []
source_map: dict[str, bytes] = {}
+ from repowise.core.workspace.update import get_head_commit
+
graph_builder = GraphBuilder(
repo_path=repo_path,
exclude_patterns=exclude_patterns,
centrality_cache_dir=repo_path / ".repowise",
+ head_commit=get_head_commit(repo_path),
include_submodules=include_submodules,
include_nested_repos=include_nested_repos,
)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
index d568eaffe..37522c9d7 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
@@ -517,16 +517,25 @@ async def _resolve_metrics(
return 0
return round(100 * sum(1 for v in all_vals if v < value) / len(all_vals))
- result_data["metrics"] = {
+ metrics: dict[str, Any] = {
"pagerank": round(node.pagerank or 0.0, 6),
"pagerank_percentile": _pct(node.pagerank or 0.0, pr_values),
- "betweenness": round(node.betweenness or 0.0, 6),
- "betweenness_percentile": _pct(node.betweenness or 0.0, bt_values),
"in_degree": degrees["in_degree"],
"out_degree": degrees["out_degree"],
"community_id": node.community_id,
"community_label": meta.get("label") or None,
}
+ # A node added since the last scoring holds the column default and has
+ # never been measured. Reporting that 0.0 would read as "on no shortest
+ # path" — the opposite claim for a symbol just spliced into a hot call
+ # chain.
+ if node.betweenness_commit is None:
+ metrics["betweenness"] = None
+ metrics["betweenness_note"] = "not scored yet: added since the last centrality run"
+ else:
+ metrics["betweenness"] = round(node.betweenness or 0.0, 6)
+ metrics["betweenness_percentile"] = _pct(node.betweenness or 0.0, bt_values)
+ result_data["metrics"] = metrics
async def _resolve_community(
diff --git a/packages/server/src/repowise/server/routers/graph/intelligence.py b/packages/server/src/repowise/server/routers/graph/intelligence.py
index 41de6233f..874f7712b 100644
--- a/packages/server/src/repowise/server/routers/graph/intelligence.py
+++ b/packages/server/src/repowise/server/routers/graph/intelligence.py
@@ -78,6 +78,7 @@ async def get_graph_metrics(
pagerank_percentile=percentile_rank(node.pagerank or 0.0, all_pr),
betweenness=round(node.betweenness or 0.0, 6),
betweenness_percentile=percentile_rank(node.betweenness or 0.0, all_bw),
+ betweenness_scored=node.betweenness_commit is not None,
community_id=node.community_id or 0,
community_label=meta.get("label") or None,
is_entry_point=node.is_entry_point,
diff --git a/packages/server/src/repowise/server/schemas/intelligence.py b/packages/server/src/repowise/server/schemas/intelligence.py
index aa9825d42..7d36afef5 100644
--- a/packages/server/src/repowise/server/schemas/intelligence.py
+++ b/packages/server/src/repowise/server/schemas/intelligence.py
@@ -171,6 +171,10 @@ class GraphMetricsResponse(BaseModel):
pagerank_percentile: int
betweenness: float
betweenness_percentile: int
+ # False when this node appeared after the last exact centrality scoring, so
+ # the two fields above are the column default rather than a measurement.
+ # Additive and defaulted so existing clients keep their shape.
+ betweenness_scored: bool = True
community_id: int
community_label: str | None
is_entry_point: bool
diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.ts
index be1c432da..210639a21 100644
--- a/packages/types/src/generated/http.ts
+++ b/packages/types/src/generated/http.ts
@@ -1331,6 +1331,7 @@ export interface GraphMetricsResponse {
pagerank_percentile: number;
betweenness: number;
betweenness_percentile: number;
+ betweenness_scored?: boolean;
community_id: number;
community_label: string | null;
is_entry_point: boolean;
diff --git a/packages/types/src/graph.ts b/packages/types/src/graph.ts
index e70ebdfd6..45365fb12 100644
--- a/packages/types/src/graph.ts
+++ b/packages/types/src/graph.ts
@@ -376,6 +376,8 @@ export interface GraphMetrics {
pagerank_percentile: number;
betweenness: number;
betweenness_percentile: number;
+ /** False when the node appeared after the last exact centrality scoring. */
+ betweenness_scored?: boolean;
community_id: number;
community_label: string | null;
is_entry_point: boolean;
diff --git a/packages/types/src/symbols.ts b/packages/types/src/symbols.ts
index a33beb72e..5803718db 100644
--- a/packages/types/src/symbols.ts
+++ b/packages/types/src/symbols.ts
@@ -181,6 +181,8 @@ export interface SymbolBodyGraph {
relations?: SymbolRelationGroup<SymbolBodyCall>[];
pagerank_percentile?: number | null;
betweenness_percentile?: number | null;
+ /** False when the symbol appeared after the last exact centrality scoring. */
+ betweenness_scored?: boolean;
community_label?: string | null;
entry_point_score?: number | null;
}
diff --git a/packages/ui/src/symbols/symbol-detail-body.tsx b/packages/ui/src/symbols/symbol-detail-body.tsx
index c2318c291..1b6aa4774 100644
--- a/packages/ui/src/symbols/symbol-detail-body.tsx
+++ b/packages/ui/src/symbols/symbol-detail-body.tsx
@@ -154,9 +154,15 @@ export function SymbolDetailBody({
{graph.pagerank_percentile != null && (
<Metric label="PageRank" value={`Top ${100 - graph.pagerank_percentile}%`} />
)}
- {graph.betweenness_percentile != null && (
- <Metric label="Betweenness" value={`Top ${100 - graph.betweenness_percentile}%`} />
- )}
+ {graph.betweenness_percentile != null &&
+ (graph.betweenness_scored === false ? (
+ // Added since the last exact centrality run, so the stored
+ // value is the column default. "Top 100%" would read as
+ // genuinely peripheral.
+ <Metric label="Betweenness" value="Not scored yet" />
+ ) : (
+ <Metric label="Betweenness" value={`Top ${100 - graph.betweenness_percentile}%`} />
+ ))}
<Metric label="Degree" value={`${graph.in_degree} in · ${graph.out_degree} out`} />
{graph.community_label && (
<Metric label="Community" value={graph.community_label} />
diff --git a/packages/web/src/components/docs/docs-viewer.tsx b/packages/web/src/components/docs/docs-viewer.tsx
index 2c788f787..1c7982636 100644
--- a/packages/web/src/components/docs/docs-viewer.tsx
+++ b/packages/web/src/components/docs/docs-viewer.tsx
@@ -73,7 +73,15 @@ function DocsSidebar({ repoId, targetPath }: { repoId: string; targetPath: strin
<div>
<div className="space-y-2">
<PercentileBar value={metrics.pagerank_percentile} label="PageRank" />
- <PercentileBar value={metrics.betweenness_percentile} label="Centrality" />
+ {metrics.betweenness_scored === false ? (
+ // Never measured, so a percentile bar would draw a rank it does not have.
+ <div className="flex items-center justify-between">
+ <span className="text-xs text-[var(--color-text-tertiary)]">Centrality</span>
+ <span className="text-xs text-[var(--color-text-tertiary)]">Not scored yet</span>
+ </div>
+ ) : (
+ <PercentileBar value={metrics.betweenness_percentile} label="Centrality" />
+ )}
<div className="flex items-center justify-between">
<span className="text-xs text-[var(--color-text-tertiary)]">Degree</span>
<span className="text-xs font-mono text-[var(--color-text-secondary)]">
diff --git a/packages/web/src/components/symbols/symbol-drawer-wrapper.tsx b/packages/web/src/components/symbols/symbol-drawer-wrapper.tsx
index dcdcd95da..268e4f5de 100644
--- a/packages/web/src/components/symbols/symbol-drawer-wrapper.tsx
+++ b/packages/web/src/components/symbols/symbol-drawer-wrapper.tsx
@@ -127,6 +127,7 @@ export function SymbolDrawerWrapper({ symbol, repoId, onClose }: Props) {
...calls,
pagerank_percentile: metrics?.pagerank_percentile ?? null,
betweenness_percentile: metrics?.betweenness_percentile ?? null,
+ betweenness_scored: metrics?.betweenness_scored ?? true,
community_label: metrics?.community_label ?? null,
entry_point_score: metrics?.entry_point_score ?? null,
},
diff --git a/tests/unit/ingestion/test_centrality_cache.py b/tests/unit/ingestion/test_centrality_cache.py
index 27b73b15e..1b0025b5a 100644
--- a/tests/unit/ingestion/test_centrality_cache.py
+++ b/tests/unit/ingestion/test_centrality_cache.py
@@ -1,8 +1,9 @@
-"""Structure-keyed betweenness cache: reuse iff the subgraph is unchanged.
+"""Structure-keyed betweenness cache: reuse while the subgraph is close enough.
A content edit that doesn't move call/heritage/import edges must reuse the
-previous run's betweenness values exactly; any structural change must
-recompute. No cache dir -> behavior (and filesystem) unchanged.
+previous run's betweenness values exactly. A structural change reuses only
+while the graph has drifted no further than the churn budget, and recomputes
+past it. No cache dir -> behavior (and filesystem) unchanged.
"""
from __future__ import annotations
@@ -47,6 +48,18 @@ def _build(cache_dir, files):
_FILES = [("main.py", _MAIN), ("util.py", _UTIL)]
+def _graph(edges):
+ import networkx as nx
+
+ g = nx.DiGraph()
+ g.add_edges_from(edges)
+ return g
+
+
+def _lookup(cache, kind, graph, signature, max_churn=0):
+ return cache.lookup(kind, graph, signature=signature, max_churn=max_churn)
+
+
def test_unchanged_structure_reuses_values(tmp_path, monkeypatch):
gb1 = _build(tmp_path, _FILES)
file_bc = gb1.betweenness_centrality()
@@ -109,16 +122,71 @@ def test_signature_is_structure_only():
assert subgraph_signature(g1) != subgraph_signature(g2)
-def test_signature_mismatch_returns_none(tmp_path):
+def test_signature_mismatch_outside_budget_returns_none(tmp_path):
+ g = _graph([("a", "b")])
+ cache = CentralityCache(tmp_path)
+ cache.put("symbol", "sig-1", {"a": 0.5}, graph=g, scored_commit="c0ffee")
+
+ assert _lookup(cache, "symbol", g, "sig-1").values == {"a": 0.5}
+ # A different signature on a graph nothing else matches is out of budget.
+ assert _lookup(cache, "symbol", _graph([("x", "y")]), "sig-2", max_churn=0) is None
+ assert _lookup(cache, "file", g, "sig-1") is None
+
+ # A fresh instance reads back from disk, commit included.
+ hit = _lookup(CentralityCache(tmp_path), "symbol", g, "sig-1")
+ assert hit.values == {"a": 0.5}
+ assert hit.scored_commit == "c0ffee"
+ assert hit.churn == 0
+
+
+def test_lookup_reuses_within_churn_budget_and_reports_drift(tmp_path):
+ """One added node plus its edge is 2 churn: served, and said to be stale."""
+ scored = _graph([("a", "b")])
+ cache = CentralityCache(tmp_path)
+ cache.put("symbol", "sig-1", {"a": 0.5, "b": 0.0}, graph=scored, scored_commit="c0ffee")
+
+ drifted = _graph([("a", "b"), ("b", "c")])
+ hit = _lookup(cache, "symbol", drifted, "sig-2", max_churn=4)
+ assert hit is not None
+ assert hit.values == {"a": 0.5, "b": 0.0} # values are the scoring's, unchanged
+ assert hit.churn == 2
+ assert hit.scored_commit == "c0ffee"
+ # "c" is absent, which is how the caller knows it was never scored.
+ assert "c" not in hit.values
+
+
+def test_lookup_past_churn_budget_forces_recompute(tmp_path):
+ scored = _graph([("a", "b")])
+ cache = CentralityCache(tmp_path)
+ cache.put("symbol", "sig-1", {"a": 0.5, "b": 0.0}, graph=scored, scored_commit=None)
+
+ drifted = _graph([("a", "b"), ("b", "c")])
+ assert _lookup(cache, "symbol", drifted, "sig-2", max_churn=1) is None
+
+
+def test_churn_counts_a_rewire_that_preserves_node_and_edge_counts(tmp_path):
+ """Same node count, same edge count, different edges: still churn."""
+ scored = _graph([("a", "b"), ("c", "d")])
cache = CentralityCache(tmp_path)
- cache.put("symbol", "sig-1", {"n": 0.5})
- assert cache.get("symbol", "sig-1") == {"n": 0.5}
- assert cache.get("symbol", "sig-2") is None
- assert cache.get("file", "sig-1") is None
+ cache.put("symbol", "sig-1", dict.fromkeys("abcd", 0.0), graph=scored, scored_commit=None)
+
+ rewired = _graph([("a", "d"), ("c", "b")])
+ assert _lookup(cache, "symbol", rewired, "sig-2", max_churn=0) is None
+ assert _lookup(cache, "symbol", rewired, "sig-2", max_churn=4).churn == 4
- # A fresh instance reads back from disk.
- cache2 = CentralityCache(tmp_path)
- assert cache2.get("symbol", "sig-1") == {"n": 0.5}
+
+def test_stale_cache_version_degrades_to_recompute(tmp_path):
+ """A v2 payload (entries were plain tuples) must miss, not raise."""
+ from repowise.core.cache_seal import dump_sealed_pickle
+ from repowise.core.ingestion.graph import _centrality_cache as cc
+
+ dump_sealed_pickle(
+ tmp_path / "centrality_cache.pkl",
+ {"version": 2, "entries": {"symbol": ("sig-1", {"a": 0.5})}},
+ domain="centrality_cache.pkl",
+ )
+ assert _lookup(CentralityCache(tmp_path), "symbol", _graph([("a", "b")]), "sig-1") is None
+ assert cc._CACHE_VERSION == 3
async def test_compute_metrics_parallel_with_cache(tmp_path):
@@ -127,10 +195,11 @@ async def test_compute_metrics_parallel_with_cache(tmp_path):
await gb.compute_metrics_parallel()
cache = CentralityCache(tmp_path)
- file_sig = subgraph_signature(gb.file_subgraph())
- sym_sig = subgraph_signature(gb.symbol_subgraph())
- assert cache.get("file", file_sig) == gb.betweenness_centrality()
- assert cache.get("symbol", sym_sig) == gb.symbol_betweenness_centrality()
+ files, symbols = gb.file_subgraph(), gb.symbol_subgraph()
+ file_hit = _lookup(cache, "file", files, subgraph_signature(files))
+ sym_hit = _lookup(cache, "symbol", symbols, subgraph_signature(symbols))
+ assert file_hit.values == gb.betweenness_centrality()
+ assert sym_hit.values == gb.symbol_betweenness_centrality()
def test_centrality_cache_is_picklable(tmp_path):
@@ -138,13 +207,14 @@ def test_centrality_cache_is_picklable(tmp_path):
and recreated), and entries survive the round trip."""
import pickle
+ g = _graph([("n", "m")])
cache = CentralityCache(tmp_path)
- cache.put("file", "sig-1", {"n": 0.25})
+ cache.put("file", "sig-1", {"n": 0.25}, graph=g, scored_commit="c0ffee")
restored = pickle.loads(pickle.dumps(cache))
- assert restored.get("file", "sig-1") == {"n": 0.25}
+ assert _lookup(restored, "file", g, "sig-1").values == {"n": 0.25}
# The lock is recreated (not None) so the restored cache is usable.
- assert restored.get("file", "sig-2") is None
+ assert _lookup(restored, "file", _graph([("q", "r")]), "sig-2", max_churn=0) is None
def test_graph_builder_round_trips_through_pickle(tmp_path):
@@ -165,3 +235,49 @@ def test_graph_builder_round_trips_through_pickle(tmp_path):
assert reloaded.pagerank() == pr
# The lock-guarded subgraph path must work after restore (lock recreated).
assert reloaded.betweenness_centrality() == file_bc
+
+
+def test_churn_budget_is_zero_where_recompute_is_already_cheap(tmp_path):
+ """Below the parallel-cost threshold, trading accuracy for speed buys
+ nothing, so those graphs keep exact-signature-only reuse."""
+ gb = _build(tmp_path, _FILES)
+ assert gb._churn_budget(gb.symbol_subgraph()) == 0
+ assert gb._churn_budget(gb.file_subgraph()) == 0
+
+
+def test_churn_budget_scales_with_the_graph_above_the_threshold(monkeypatch):
+ from repowise.core.ingestion.graph import _betweenness
+
+ monkeypatch.setattr(_betweenness, "_PARALLEL_COST_THRESHOLD", 0)
+ gb = GraphBuilder("C:/fake")
+ g = _graph([(f"n{i}", f"n{i + 1}") for i in range(999)]) # 1000 nodes, 999 edges
+ assert gb._churn_budget(g) == int(1999 * 0.002)
+
+
+def test_structural_change_within_budget_skips_brandes(tmp_path, monkeypatch):
+ """The phase's whole point: one added symbol must not rerun Brandes."""
+ from repowise.core.ingestion.graph import _betweenness
+
+ monkeypatch.setattr(_betweenness, "_PARALLEL_COST_THRESHOLD", 0)
+ gb = GraphBuilder("C:/fake", centrality_cache_dir=tmp_path, head_commit="c0ffee")
+ big = _graph([(f"n{i}", f"n{i + 1}") for i in range(999)])
+ monkeypatch.setattr(gb, "symbol_subgraph", lambda: big)
+ scored = gb.symbol_betweenness_centrality()
+ assert gb.betweenness_scoring("symbol").scored_commit == "c0ffee"
+ assert gb.betweenness_scoring("symbol").churn == 0
+
+ def _boom(*args, **kwargs):
+ raise AssertionError("betweenness must not recompute inside the churn budget")
+
+ monkeypatch.setattr(_betweenness, "betweenness_centrality_fast", _boom)
+ gb2 = GraphBuilder("C:/fake", centrality_cache_dir=tmp_path, head_commit="deadbee")
+ drifted = big.copy()
+ drifted.add_edge("n999", "n1000")
+ monkeypatch.setattr(gb2, "symbol_subgraph", lambda: drifted)
+
+ assert gb2.symbol_betweenness_centrality() == scored
+ reuse = gb2.betweenness_scoring("symbol")
+ # Reported as the older commit's scoring, not the commit being indexed.
+ assert reuse.scored_commit == "c0ffee"
+ assert reuse.churn == 2
+ assert "n1000" not in reuse.values
diff --git a/tests/unit/persistence/test_betweenness_commit_stamp.py b/tests/unit/persistence/test_betweenness_commit_stamp.py
new file mode 100644
index 000000000..ee07b9853
--- /dev/null
+++ b/tests/unit/persistence/test_betweenness_commit_stamp.py
@@ -0,0 +1,122 @@
+"""``graph_nodes.betweenness_commit``: scored, unscored, and unknown.
+
+Exact betweenness is reused across small structural changes, so a node added
+since the last scoring holds the column's 0.0 default without having been
+measured. The stamp is what tells those apart, and it has three states, not
+two: a commit, NULL for "this scoring did not contain the node", and — the one
+that is easy to get wrong — *absent from the payload* when the builder cannot
+say, so a row that already carries a good stamp keeps it.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+import pytest
+from sqlalchemy import select
+
+from repowise.core.ingestion.graph._centrality_cache import BetweennessScoring
+from repowise.core.persistence.models import GraphNode
+from repowise.core.pipeline.persist import persist_graph_nodes
+from tests.unit.persistence.helpers import insert_repo
+
+
+class _Builder:
+ """Minimal stand-in for the parts of GraphBuilder persist_graph_nodes reads."""
+
+ def __init__(self, graph, sym_bc, scoring):
+ self._graph = graph
+ self._sym_bc = sym_bc
+ self._scoring = scoring
+
+ def graph(self):
+ return self._graph
+
+ def pagerank(self):
+ return {}
+
+ def betweenness_centrality(self):
+ return {}
+
+ def symbol_pagerank(self):
+ return {}
+
+ def symbol_betweenness_centrality(self):
+ return self._sym_bc
+
+ def community_detection(self):
+ return {}
+
+ def symbol_communities(self):
+ return {}
+
+ def community_info(self):
+ return {}
+
+ def betweenness_scoring(self, kind):
+ return self._scoring.get(kind)
+
+
+def _graph(*symbol_ids):
+ g = nx.DiGraph()
+ for sid in symbol_ids:
+ g.add_node(sid, node_type="symbol", language="python")
+ return g
+
+
+async def _stamps(session, repo_id):
+ rows = (await session.execute(select(GraphNode).where(GraphNode.repository_id == repo_id))).scalars()
+ return {r.node_id: r.betweenness_commit for r in rows}
+
+
+async def repo_id(async_session):
+ return (await insert_repo(async_session)).id
+
+
+async def test_scored_nodes_stamped_and_new_node_marked_unscored(async_session, repo_id):
+ """A reused scoring stamps its own commit, and the symbol it never saw NULL."""
+ graph = _graph("a.py::A", "a.py::B", "a.py::New")
+ sym_bc = {"a.py::A": 0.5, "a.py::B": 0.0} # "New" appeared after the scoring
+ scoring = {"symbol": BetweennessScoring(sym_bc, "c0ffee", churn=2)}
+
+ await persist_graph_nodes(async_session, repo_id, _Builder(graph, sym_bc, scoring))
+ await async_session.commit()
+
+ stamps = await _stamps(async_session, repo_id)
+ assert stamps["a.py::A"] == "c0ffee"
+ # Genuinely scored at 0.0 is not the same as never scored.
+ assert stamps["a.py::B"] == "c0ffee"
+ assert stamps["a.py::New"] is None
+
+
+async def test_unknown_provenance_preserves_the_existing_stamp(async_session, repo_id):
+ """A builder rehydrated from SQL serves real values it did not compute.
+
+ Stamping those NULL would report an entire indexed repository as unscored,
+ so the field must be omitted and the stored stamp left standing.
+ """
+ graph = _graph("a.py::A")
+ sym_bc = {"a.py::A": 0.5}
+ await persist_graph_nodes(
+ async_session, repo_id, _Builder(graph, sym_bc, {"symbol": BetweennessScoring(sym_bc, "c0ffee", 0)})
+ )
+ await async_session.commit()
+ assert (await _stamps(async_session, repo_id))["a.py::A"] == "c0ffee"
+
+ # Same values, no provenance — the rehydrated case.
+ await persist_graph_nodes(async_session, repo_id, _Builder(graph, sym_bc, {}))
+ await async_session.commit()
+ assert (await _stamps(async_session, repo_id))["a.py::A"] == "c0ffee"
+
+
+async def test_builder_without_the_accessor_is_tolerated(async_session, repo_id):
+ """Duck-typed stand-ins predate ``betweenness_scoring`` and must not break."""
+ graph = _graph("a.py::A")
+ builder = _Builder(graph, {"a.py::A": 0.5}, {})
+ del builder.__class__.betweenness_scoring # simulate an older stand-in
+ try:
+ await persist_graph_nodes(async_session, repo_id, builder)
+ await async_session.commit()
+ assert (await _stamps(async_session, repo_id))["a.py::A"] is None
+ finally:
+ _Builder.betweenness_scoring = lambda self, kind: self._scoring.get(kind)