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.

refactor(generation): drop the onboarding prerequisite table nothing reads (#1179)

Swati Ahuja27eb3c9fb5fc
diff --git a/packages/core/src/repowise/core/generation/onboarding/slots.py b/packages/core/src/repowise/core/generation/onboarding/slots.py
index b97dffcda..8611c7bd6 100644
--- a/packages/core/src/repowise/core/generation/onboarding/slots.py
+++ b/packages/core/src/repowise/core/generation/onboarding/slots.py
@@ -70,18 +70,6 @@ SLOT_TITLES: dict[str, str] = {
}
-SLOT_PREREQUISITES: dict[str, tuple[str, ...]] = {
- SLOT_PROJECT_OVERVIEW: (),
- SLOT_GUIDED_TOUR: (SLOT_PROJECT_OVERVIEW,),
- SLOT_GETTING_STARTED: (),
- SLOT_CODEBASE_MAP: (SLOT_PROJECT_OVERVIEW,),
- SLOT_KEY_CONCEPTS: (SLOT_PROJECT_OVERVIEW,),
- SLOT_HOW_IT_WORKS: (SLOT_KEY_CONCEPTS,),
- SLOT_DEVELOPMENT_GUIDE: (SLOT_GETTING_STARTED, SLOT_HOW_IT_WORKS),
- SLOT_ACTIVE_LANDSCAPE: (SLOT_CODEBASE_MAP,),
-}
-
-
def target_path(slot: str) -> str:
"""Canonical wiki ``target_path`` for an onboarding slot."""
return f"onboarding/{slot}"
diff --git a/tests/unit/generation/test_kg_enrichment.py b/tests/unit/generation/test_kg_enrichment.py
index 50177933f..2866c3e78 100644
--- a/tests/unit/generation/test_kg_enrichment.py
+++ b/tests/unit/generation/test_kg_enrichment.py
@@ -2,20 +2,19 @@
from __future__ import annotations
+import ast
import json
from dataclasses import dataclass
from pathlib import Path
+from repowise.core.generation import onboarding
from repowise.core.generation.kg_enrichment import enrich_tour_with_wiki_links
-from repowise.core.generation.onboarding.slots import (
- ONBOARDING_ORDER,
- SLOT_ACTIVE_LANDSCAPE,
- SLOT_CODEBASE_MAP,
- SLOT_HOW_IT_WORKS,
- SLOT_KEY_CONCEPTS,
- SLOT_PREREQUISITES,
- SLOT_PROJECT_OVERVIEW,
-)
+from repowise.core.generation.onboarding import slots as slots_module
+
+SLOTS_PATH = Path(slots_module.__file__).resolve()
+# The installed product tree, so "is anything reading this?" is asked of the
+# packages rather than of the tests that assert on them.
+PACKAGES_ROOT = Path(onboarding.__file__).resolve().parents[4]
# ---------------------------------------------------------------------------
# Helpers
@@ -43,10 +42,17 @@ def _write_kg(tmp_path: Path, tour: list[dict], **extra: object) -> Path:
class TestEnrichTourWithWikiLinks:
def test_adds_wiki_page_ids(self, tmp_path):
- kg_path = _write_kg(tmp_path, tour=[
- {"order": 1, "title": "Entry", "nodeIds": ["file:src/main.py", "file:src/utils.py"]},
- {"order": 2, "title": "Core", "nodeIds": ["file:src/core.py"]},
- ])
+ kg_path = _write_kg(
+ tmp_path,
+ tour=[
+ {
+ "order": 1,
+ "title": "Entry",
+ "nodeIds": ["file:src/main.py", "file:src/utils.py"],
+ },
+ {"order": 2, "title": "Core", "nodeIds": ["file:src/core.py"]},
+ ],
+ )
pages = [
FakePage(page_id="file_page:src/main.py", target_path="src/main.py"),
FakePage(page_id="file_page:src/core.py", target_path="src/core.py"),
@@ -59,9 +65,12 @@ class TestEnrichTourWithWikiLinks:
assert kg["tour"][1]["wikiPageIds"] == ["file_page:src/core.py"]
def test_missing_pages_get_empty_list(self, tmp_path):
- kg_path = _write_kg(tmp_path, tour=[
- {"order": 1, "title": "Entry", "nodeIds": ["file:src/missing.py"]},
- ])
+ kg_path = _write_kg(
+ tmp_path,
+ tour=[
+ {"order": 1, "title": "Entry", "nodeIds": ["file:src/missing.py"]},
+ ],
+ )
count = enrich_tour_with_wiki_links(kg_path, [])
assert count == 0
@@ -69,9 +78,14 @@ class TestEnrichTourWithWikiLinks:
assert kg["tour"][0]["wikiPageIds"] == []
def test_preserves_existing_kg_data(self, tmp_path):
- kg_path = _write_kg(tmp_path, tour=[
- {"order": 1, "title": "Entry", "nodeIds": ["file:a.py"]},
- ], version="1.0.0", project={"name": "test"})
+ kg_path = _write_kg(
+ tmp_path,
+ tour=[
+ {"order": 1, "title": "Entry", "nodeIds": ["file:a.py"]},
+ ],
+ version="1.0.0",
+ project={"name": "test"},
+ )
pages = [FakePage(page_id="file_page:a.py", target_path="a.py")]
enrich_tour_with_wiki_links(kg_path, pages)
@@ -81,11 +95,20 @@ class TestEnrichTourWithWikiLinks:
assert kg["tour"][0]["wikiPageIds"] == ["file_page:a.py"]
def test_multiple_files_in_step(self, tmp_path):
- kg_path = _write_kg(tmp_path, tour=[
- {"order": 1, "title": "Step", "nodeIds": [
- "file:a.py", "file:b.py", "file:c.py",
- ]},
- ])
+ kg_path = _write_kg(
+ tmp_path,
+ tour=[
+ {
+ "order": 1,
+ "title": "Step",
+ "nodeIds": [
+ "file:a.py",
+ "file:b.py",
+ "file:c.py",
+ ],
+ },
+ ],
+ )
pages = [
FakePage(page_id="file_page:a.py", target_path="a.py"),
FakePage(page_id="file_page:c.py", target_path="c.py"),
@@ -97,11 +120,19 @@ class TestEnrichTourWithWikiLinks:
assert kg["tour"][0]["wikiPageIds"] == ["file_page:a.py", "file_page:c.py"]
def test_non_file_node_ids_skipped(self, tmp_path):
- kg_path = _write_kg(tmp_path, tour=[
- {"order": 1, "title": "Step", "nodeIds": [
- "class:src/models.py:User", "file:src/models.py",
- ]},
- ])
+ kg_path = _write_kg(
+ tmp_path,
+ tour=[
+ {
+ "order": 1,
+ "title": "Step",
+ "nodeIds": [
+ "class:src/models.py:User",
+ "file:src/models.py",
+ ],
+ },
+ ],
+ )
pages = [
FakePage(page_id="file_page:src/models.py", target_path="src/models.py"),
]
@@ -127,9 +158,12 @@ class TestEnrichTourWithWikiLinks:
assert count == 0
def test_idempotent(self, tmp_path):
- kg_path = _write_kg(tmp_path, tour=[
- {"order": 1, "title": "Entry", "nodeIds": ["file:a.py"]},
- ])
+ kg_path = _write_kg(
+ tmp_path,
+ tour=[
+ {"order": 1, "title": "Entry", "nodeIds": ["file:a.py"]},
+ ],
+ )
pages = [FakePage(page_id="file_page:a.py", target_path="a.py")]
enrich_tour_with_wiki_links(kg_path, pages)
enrich_tour_with_wiki_links(kg_path, pages)
@@ -139,49 +173,55 @@ class TestEnrichTourWithWikiLinks:
# ---------------------------------------------------------------------------
-# Onboarding prerequisites
+# Onboarding slot tables
# ---------------------------------------------------------------------------
-class TestOnboardingPrerequisites:
- def test_all_slots_have_prerequisites(self):
- for slot in ONBOARDING_ORDER:
- assert slot in SLOT_PREREQUISITES, f"Missing prerequisites for {slot}"
-
- def test_root_slots_have_no_prerequisites(self):
- assert SLOT_PREREQUISITES[SLOT_PROJECT_OVERVIEW] == ()
-
- def test_downstream_slots_reference_valid_slots(self):
- all_slots = set(ONBOARDING_ORDER)
- for slot, prereqs in SLOT_PREREQUISITES.items():
- for prereq in prereqs:
- assert prereq in all_slots, f"{slot} prereq {prereq} not in ONBOARDING_ORDER"
-
- def test_no_circular_prerequisites(self):
- visited: set[str] = set()
-
- def _walk(slot: str, path: frozenset[str]) -> None:
- assert slot not in path, f"Circular prerequisite: {slot} in {path}"
- if slot in visited:
- return
- visited.add(slot)
- for prereq in SLOT_PREREQUISITES.get(slot, ()):
- _walk(prereq, path | {slot})
-
- for slot in ONBOARDING_ORDER:
- _walk(slot, frozenset())
-
- def test_prerequisites_respect_ordering(self):
- order_index = {s: i for i, s in enumerate(ONBOARDING_ORDER)}
- for slot, prereqs in SLOT_PREREQUISITES.items():
- for prereq in prereqs:
- assert order_index[prereq] < order_index[slot], (
- f"{slot} (index {order_index[slot]}) has prereq {prereq} "
- f"(index {order_index[prereq]}) which comes later"
- )
-
- def test_active_landscape_depends_on_codebase_map(self):
- assert SLOT_CODEBASE_MAP in SLOT_PREREQUISITES[SLOT_ACTIVE_LANDSCAPE]
-
- def test_how_it_works_depends_on_key_concepts(self):
- assert SLOT_KEY_CONCEPTS in SLOT_PREREQUISITES[SLOT_HOW_IT_WORKS]
+class TestOnboardingTablesAreRead:
+ """Every lookup table in ``slots.py`` must have a reader in the product.
+
+ A table that declares behaviour nothing implements is worse than no table:
+ it reads as a live feature to anyone deciding what onboarding already does.
+ This is derived from the source rather than a fixed list, so a new unread
+ table fails here instead of quietly joining the file.
+
+ Tests asserting a table's shape cannot catch this — they pass whether or
+ not anything consults it, which is how one such table survived for months.
+ """
+
+ def _tables(self) -> dict[str, ast.AST]:
+ """Module-level collection constants — the shape a lookup table takes."""
+ tree = ast.parse(SLOTS_PATH.read_text())
+ found: dict[str, ast.AST] = {}
+ for node in tree.body:
+ if not isinstance(node, ast.Assign | ast.AnnAssign):
+ continue
+ targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+ value = node.value
+ if not isinstance(value, ast.Dict | ast.Tuple | ast.List):
+ continue
+ for target in targets:
+ if isinstance(target, ast.Name) and target.id.isupper():
+ found[target.id] = value
+ return found
+
+ def _readers(self, name: str) -> list[Path]:
+ return [
+ path
+ for path in PACKAGES_ROOT.rglob("*.py")
+ if path != SLOTS_PATH and name in path.read_text()
+ ]
+
+ def test_every_table_has_a_reader(self):
+ tables = self._tables()
+
+ # Anti-vacuous: a parse that found nothing would pass the loop below
+ # without checking anything at all.
+ assert len(tables) >= 3, f"Parsed too few tables from {SLOTS_PATH.name}: {sorted(tables)}"
+ assert "ONBOARDING_ORDER" in tables
+
+ unread = [name for name in tables if not self._readers(name)]
+ assert not unread, (
+ f"Declared in {SLOTS_PATH.name} and read by nothing in the product: "
+ f"{sorted(unread)}. Wire it up or delete it."
+ )