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.

fix(kg): rebuild the knowledge graph when the builder changes, not just the graph (#1592)

Swati Ahuja04f33ae0b198
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index 3f9f7d912..420850f0d 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -1764,9 +1764,13 @@ def run_update(
flush_cost_tracker(cost_tracker)
# LLM re-enrichment of the refreshed KG (layer naming + summary backfill
- # from this run's regenerated pages), mirroring the init pipeline. Only
- # runs when the graph shape changed — carry-forward already preserved the
- # prior names, so an unchanged KG never pays an enrichment call.
+ # from this run's regenerated pages), mirroring the init pipeline. Runs
+ # whenever the refresh returned a result, which is the graph shape moving
+ # *or* KG_BUILDER_VERSION being bumped by a release — the second is a graph
+ # that did not change, and it still pays here. That is deliberate and it is
+ # the one cost of the version bump: a wider edge map or a new entry-point
+ # ranking changes the layers, and layer names the carry-forward restored
+ # were written against the old ones.
if knowledge_graph_result is not None:
try:
from repowise.core.generation.knowledge_graph import enrich_knowledge_graph
diff --git a/packages/core/src/repowise/core/analysis/knowledge_graph.py b/packages/core/src/repowise/core/analysis/knowledge_graph.py
index 0d3f143e0..f3cafb880 100644
--- a/packages/core/src/repowise/core/analysis/knowledge_graph.py
+++ b/packages/core/src/repowise/core/analysis/knowledge_graph.py
@@ -205,6 +205,16 @@ def _slugify(text: str) -> str:
# Edge type mapping
# ---------------------------------------------------------------------------
+# Bump when the builder or the curation pass changes what it emits from an
+# unchanged graph — a wider `_EDGE_TYPE_MAP`, a different entry-point ranking,
+# a new node field. Folded into `compute_kg_fingerprint`, which otherwise only
+# measures the input graph and would let an existing store serve the old
+# artifact indefinitely. See that function for why one bump is one rebuild.
+#
+# "2": `_EDGE_TYPE_MAP` gained six types and `_curate_entry_points` changed its
+# ranking, neither of which moves a node or edge count.
+KG_BUILDER_VERSION = "2"
+
# An unmapped type is dropped from the export entirely (see the
# `if not kg_type: continue` below), which is silent. Six real types used to be
# missing — framework, the three dynamic_* kinds, reads and method_implements —
@@ -410,10 +420,41 @@ def build_knowledge_graph_skeleton(
def compute_kg_fingerprint(graph_builder: Any) -> str:
- """Compute a fingerprint from the graph state for incremental skip logic."""
+ """Compute a fingerprint from the graph state for incremental skip logic.
+
+ The four graph measures describe the *input* graph. They cannot see a
+ change in how this module turns that graph into an export, and the export
+ is not total: :data:`_EDGE_TYPE_MAP` drops every unmapped edge type. So
+ widening that map — six types in 0.43.0 — changes what the knowledge graph
+ contains while all four measures hold still, and the stored artifact would
+ keep the narrower edge set until some unrelated commit happened to move a
+ node or edge count. Same for the ordering the curation pass applies to
+ ``project.entry_points``, which every orientation surface reads.
+
+ :data:`KG_BUILDER_VERSION` closes that: bump it in the same commit as a
+ change to what the builder or the curation pass emits, and every existing
+ store rebuilds its knowledge graph once, on its next ``repowise update``
+ that has work to do. Two limits on that sentence, both deliberate:
+
+ * An update with nothing to do returns ``NOOP`` before the refresh is
+ reached, so a repo with no new commits stays on its old artifact until
+ something changes. That is the right trade — the alternative is making
+ every quiet repo in the world re-curate on a version bump — but it does
+ mean this is not a hard guarantee of "everyone, once".
+ * The rebuild itself is deterministic and model-free (skeleton plus
+ curation over a graph the run already holds, betweenness served from its
+ disk cache). On a **docs** update the non-``None`` result then also
+ triggers one KG layer-enrichment LLM call per five layers, which is real
+ spend the caller pays for a graph whose shape did not change. Index-only
+ and keyless runs never reach it.
+
+ One rebuild and not a loop: the new value is stored as the artifact's
+ fingerprint, so the next run matches and skips.
+ """
g = graph_builder.graph()
cd = graph_builder.community_detection()
parts = [
+ KG_BUILDER_VERSION,
str(g.number_of_nodes()),
str(g.number_of_edges()),
str(len(set(cd.values()))),
diff --git a/tests/unit/analysis/test_kg_skip_logic.py b/tests/unit/analysis/test_kg_skip_logic.py
index d440c6fb9..42d4affb9 100644
--- a/tests/unit/analysis/test_kg_skip_logic.py
+++ b/tests/unit/analysis/test_kg_skip_logic.py
@@ -7,6 +7,7 @@ import logging
import pytest
+from repowise.core.analysis import knowledge_graph
from repowise.core.analysis.knowledge_graph import (
_KG_SCHEMA_VERSION,
KnowledgeGraphResult,
@@ -181,6 +182,36 @@ class TestFingerprintDeterminism:
)
assert compute_kg_fingerprint(gb1) != compute_kg_fingerprint(gb2)
+ def test_builder_version_changes_the_fingerprint(self, monkeypatch):
+ """The one input that is not a measurement of the graph.
+
+ Every other test here varies the graph and expects the fingerprint to
+ follow. This is the opposite case, and the one the skip logic could not
+ express before: the graph is identical and the *builder* changed, which
+ is what a release does when it widens ``_EDGE_TYPE_MAP`` or re-ranks
+ entry points. Without this fold an existing store keeps the artifact a
+ narrower builder wrote, for as long as its node and edge counts happen
+ to hold still.
+ """
+ gb = self._make_graph_builder(["a.py", "b.py"], [("a.py", "b.py")], {"a.py": 0, "b.py": 0})
+ before = compute_kg_fingerprint(gb)
+
+ monkeypatch.setattr(knowledge_graph, "KG_BUILDER_VERSION", "test-next")
+ assert compute_kg_fingerprint(gb) != before
+
+ def test_builder_version_is_a_hand_edited_literal(self):
+ """The bump is a decision, so it has to be visible in a diff.
+
+ Deliberately asserts the literal. The first cut of this test asserted
+ only ``isinstance(..., str)`` and non-emptiness, which a value derived
+ from the module's own bytes — the exact failure it claimed to guard —
+ would have passed unchanged. There is no way to check "somebody chose
+ this" other than to pin what they chose, and the cost is the honest
+ one: whoever bumps the constant updates this line and sees, in the
+ diff, that they are asking every existing store to re-curate.
+ """
+ assert knowledge_graph.KG_BUILDER_VERSION == "2"
+
# ---------------------------------------------------------------------------
# Skip logic integration (unit-level)