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
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.pyindex 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.pyindex 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 astimport jsonfrom dataclasses import dataclassfrom pathlib import Path+from repowise.core.generation import onboardingfrom 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 == 0def 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."+ )