Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.tsindex 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.pynew file mode 100644index 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.pyindex 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 singleedge. Betweenness is a pure function of the *structure* of the (unweighted)subgraph it runs on, so values cache safely keyed by a signature over thesorted 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 initpipeline computes both kinds concurrently. Best-effort by design: anyload/save error degrades to a fresh computation.@@ -23,6 +35,7 @@ from __future__ import annotationsimport hashlibimport threading+from dataclasses import dataclassfrom pathlib import Pathimport structlog@@ -31,14 +44,15 @@ from repowise.core.cache_seal import dump_sealed_pickle, load_sealed_picklelog = 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 -> recomputelog.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.pyindex 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_signaturesignature = 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.valuesexcept 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_fastvalues = 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 valuesdiff --git a/packages/core/src/repowise/core/ingestion/graph/builder.py b/packages/core/src/repowise/core/ingestion/graph/builder.pyindex 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, Rehydself._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 pathspecdiff --git a/packages/core/src/repowise/core/persistence/crud/graph.py b/packages/core/src/repowise/core/persistence/crud/graph.pyindex 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.pyindex 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.pyindex 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_commitfi_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.pyindex 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.pyindex 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.pyindex 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 0return 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"] = metricsasync def _resolve_community(diff --git a/packages/server/src/repowise/server/routers/graph/intelligence.py b/packages/server/src/repowise/server/routers/graph/intelligence.pyindex 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.pyindex 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: intbetweenness: floatbetweenness_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 = Truecommunity_id: intcommunity_label: str | Noneis_entry_point: booldiff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.pyindex 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 == 3async 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 Nonedef 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.valuesdiff --git a/tests/unit/persistence/test_betweenness_commit_stamp.py b/tests/unit/persistence/test_betweenness_commit_stamp.pynew file mode 100644index 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)