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(wiki): retire a symbol spotlight when its symbol leaves a live file (#3892)

Raghav Chamadiyaa183b075c1cf
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
index 8555f0297..232e4f894 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py
@@ -974,6 +974,7 @@ async def _persist_full_update_async(
try:
from repowise.core.pipeline.persist import (
sweep_absent_cycle_pages,
+ sweep_absent_symbol_spotlights,
sweep_retired_pages,
)
@@ -982,10 +983,14 @@ async def _persist_full_update_async(
# Cycle pages are never regenerated on this path (the
# ladder stops at file pages), so a cycle that no longer
# exists can only be retired by asking the rebuilt graph
- # directly.
+ # directly. A spotlight whose symbol left its file is the
+ # same case.
swept_page_ids += await sweep_absent_cycle_pages(
session, repo_id, graph_builder
)
+ swept_page_ids += await sweep_absent_symbol_spotlights(
+ session, repo_id, graph_builder
+ )
# Drop the embeddings before the SQL session commits, the same
# ordering ``init`` uses: the vector store is a separate engine,
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index 55b5bdb6c..3db852344 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -2106,6 +2106,7 @@ async def persist_incremental_index(
try:
from repowise.core.pipeline.persist import (
sweep_absent_cycle_pages,
+ sweep_absent_symbol_spotlights,
sweep_retired_pages,
)
@@ -2115,10 +2116,13 @@ async def persist_incremental_index(
# never regenerates a cycle page, so asking the rebuilt
# graph whether the cycle still exists is the only way a
# fixed cycle's page can ever be retired for a user who
- # only runs `update`.
+ # only runs `update`. Spotlights of removed symbols too.
swept_page_ids += await sweep_absent_cycle_pages(
session, repo_id, graph_builder
)
+ swept_page_ids += await sweep_absent_symbol_spotlights(
+ session, repo_id, graph_builder
+ )
except Exception as exc:
_skip("Retired page sweep", exc)
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index d9947417f..91a7ecef9 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -1594,6 +1594,79 @@ async def sweep_absent_cycle_pages(session: Any, repo_id: str, graph_builder: An
return stale
+def _symbol_names_by_file(graph_builder: Any) -> dict[str, set[str]]:
+ """``file path -> names of the symbols it defines`` in the rebuilt graph.
+
+ Empty when there is no graph to ask. The synthetic ``__module__`` symbol is
+ left out, so a file that failed to parse has no entry at all.
+ """
+ if graph_builder is None:
+ return {}
+ try:
+ graph = graph_builder.graph()
+ except Exception: # a released graph cannot speak for any symbol
+ return {}
+ names_by_file: dict[str, set[str]] = {}
+ for _node, data in graph.nodes(data=True):
+ if data.get("node_type") != "symbol" or data.get("kind") == "module":
+ continue
+ path, name = data.get("file_path"), data.get("name")
+ if path and name:
+ names_by_file.setdefault(path, set()).add(name)
+ return names_by_file
+
+
+async def sweep_absent_symbol_spotlights(
+ session: Any, repo_id: str, graph_builder: Any
+) -> list[str]:
+ """Delete ``symbol_spotlight`` rows whose symbol left a file that still exists.
+
+ A spotlight targets ``<path>::<name>``. Deleting the file tombstones it
+ (:func:`mark_tombstone_pages`), but moving or removing the symbol while the
+ file stays left the row ``fresh``: nothing regenerates a page for a symbol
+ the parser no longer emits, so it kept serving the old body and the old
+ importer list.
+
+ Same question as :func:`sweep_absent_cycle_pages`, asked of the rebuilt
+ graph: does this file still define a symbol of that name? Only files the
+ graph holds with at least one named symbol are judged, so a file outside
+ the traversal or one that failed to parse keeps its pages.
+
+ Returns the deleted page ids so the caller can drop them from FTS and the
+ vector store after the session closes.
+ """
+ from sqlalchemy import delete, select
+
+ from repowise.core.persistence.models import Page, PageVersion
+
+ names_by_file = _symbol_names_by_file(graph_builder)
+ if not names_by_file:
+ return []
+
+ rows = (
+ await session.execute(
+ select(Page.id, Page.target_path).where(
+ Page.repository_id == repo_id,
+ Page.page_type == "symbol_spotlight",
+ Page.freshness_status != "tombstone",
+ )
+ )
+ ).all()
+ stale: list[str] = []
+ for page_id, target in rows:
+ path, sep, name = (target or "").partition("::")
+ names = names_by_file.get(path)
+ if sep and names is not None and name not in names:
+ stale.append(page_id)
+ for i in range(0, len(stale), _PRUNE_CHUNK):
+ batch = stale[i : i + _PRUNE_CHUNK]
+ await session.execute(delete(PageVersion).where(PageVersion.page_id.in_(batch)))
+ await session.execute(delete(Page).where(Page.repository_id == repo_id, Page.id.in_(batch)))
+ if stale:
+ logger.info("absent_symbol_spotlights_swept", repo_id=repo_id, count=len(stale))
+ return stale
+
+
async def sweep_superseded_generated_pages(
session: Any,
repo_id: str,
diff --git a/tests/unit/persistence/test_spotlight_symbol_sweep.py b/tests/unit/persistence/test_spotlight_symbol_sweep.py
new file mode 100644
index 000000000..29a8a71cd
--- /dev/null
+++ b/tests/unit/persistence/test_spotlight_symbol_sweep.py
@@ -0,0 +1,114 @@
+"""`repowise update` retires the spotlight of a symbol that left a live file.
+
+Deleting a file tombstones its spotlights. Moving a function to another module
+while the old file stays did not: the old ``<path>::<name>`` row stayed fresh
+and kept serving the old body and importer list.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+import pytest
+
+from repowise.core.generation.models import compute_page_id
+from repowise.core.persistence.models import Page
+from repowise.core.pipeline.persist import sweep_absent_symbol_spotlights
+from tests.unit.persistence.helpers import insert_repo, make_page_kwargs
+
+
+class _FakeBuilder:
+ def __init__(self, graph: nx.DiGraph) -> None:
+ self._graph = graph
+
+ def graph(self):
+ return self._graph
+
+
+def _graph(symbols: dict[str, list[str]]) -> nx.DiGraph:
+ g = nx.DiGraph()
+ for path, names in symbols.items():
+ g.add_node(path, node_type="file")
+ g.add_node(
+ f"{path}::__module__",
+ node_type="symbol",
+ kind="module",
+ name="__module__",
+ file_path=path,
+ )
+ for name in names:
+ g.add_node(
+ f"{path}::{name}",
+ node_type="symbol",
+ kind="function",
+ name=name,
+ file_path=path,
+ )
+ return g
+
+
+async def repo_id(async_session) -> str:
+ repo = await insert_repo(async_session)
+ return repo.id
+
+
+async def _add_spotlight(async_session, repo_id: str, target: str) -> str:
+ from repowise.core.persistence.crud import upsert_page
+
+ page_id = compute_page_id("symbol_spotlight", target)
+ await upsert_page(
+ async_session,
+ **make_page_kwargs(
+ repo_id,
+ page_id=page_id,
+ page_type="symbol_spotlight",
+ target_path=target,
+ title=target.split("::")[-1],
+ ),
+ )
+ await async_session.flush()
+ return page_id
+
+
+async def _spotlight_ids(async_session) -> set[str]:
+ rows = (await async_session.execute(Page.__table__.select())).fetchall()
+ return {r.id for r in rows if r.page_type == "symbol_spotlight"}
+
+
+class TestAbsentSymbolSpotlightSweep:
+ async def test_moved_symbol_page_is_deleted(self, async_session, repo_id) -> None:
+ moved = await _add_spotlight(async_session, repo_id, "pkg/contracts.py::match")
+ kept = await _add_spotlight(async_session, repo_id, "pkg/contracts.py::load")
+ builder = _FakeBuilder(_graph({"pkg/contracts.py": ["load"], "pkg/matching.py": ["match"]}))
+
+ swept = await sweep_absent_symbol_spotlights(async_session, repo_id, builder)
+
+ assert swept == [moved]
+ assert await _spotlight_ids(async_session) == {kept}
+
+ async def test_file_outside_graph_keeps_its_pages(self, async_session, repo_id) -> None:
+ # Deleted or excluded files belong to the tombstone sweeps, not this one.
+ page = await _add_spotlight(async_session, repo_id, "gone.py::f")
+ swept = await sweep_absent_symbol_spotlights(
+ async_session, repo_id, _FakeBuilder(_graph({"other.py": ["g"]}))
+ )
+ assert swept == []
+ assert await _spotlight_ids(async_session) == {page}
+
+ async def test_file_with_no_parsed_symbols_keeps_its_pages(
+ self, async_session, repo_id
+ ) -> None:
+ # A parse failure leaves only the synthetic module symbol; that is not
+ # evidence the symbol is gone.
+ page = await _add_spotlight(async_session, repo_id, "broken.py::f")
+ swept = await sweep_absent_symbol_spotlights(
+ async_session, repo_id, _FakeBuilder(_graph({"broken.py": []}))
+ )
+ assert swept == []
+ assert await _spotlight_ids(async_session) == {page}
+
+ async def test_missing_builder_is_a_no_op(self, async_session, repo_id) -> None:
+ page = await _add_spotlight(async_session, repo_id, "a.py::f")
+ assert await sweep_absent_symbol_spotlights(async_session, repo_id, None) == []
+ assert await _spotlight_ids(async_session) == {page}