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): overview drops undefined capabilities; UI layer needs UI files (#2709)

Swati Ahuja5258af1fc737
diff --git a/packages/core/src/repowise/core/generation/layers.py b/packages/core/src/repowise/core/generation/layers.py
index 5563df713..ac11dc75c 100644
--- a/packages/core/src/repowise/core/generation/layers.py
+++ b/packages/core/src/repowise/core/generation/layers.py
@@ -49,6 +49,13 @@ _LAYER_HINTS: tuple[tuple[str, frozenset[str]], ...] = (
("Types", frozenset({"types", "interfaces", "schemas", "contracts", "dtos", "typings"})),
)
+# The UI hint names a UI layer only for files that render one: a CLI's `ui/`
+# helpers or a Django `views/` package are not a frontend.
+_UI_LAYER = "UI"
+_UI_EXTENSIONS = frozenset(
+ {".tsx", ".jsx", ".vue", ".svelte", ".html", ".htm", ".css", ".scss", ".sass", ".less"}
+)
+
# Layers that observe or support the runtime stack rather than participate in
# it. Tests import production code and are never imported back, so letting
# them compete on import direction would crown them the top "consumer" in
@@ -234,12 +241,13 @@ def infer_layer(path: str, language: str | None = None) -> str:
suffix_hints = _LANG_SUFFIX_HINTS.get(lang)
root_hints = _LANG_ROOT_HINTS.get(lang)
original_segments = original_parts[:-1]
+ renders_ui = PurePosixPath(path).suffix.lower() in _UI_EXTENSIONS
# Deepest directory first — the closest folder describes the file best.
for i in range(len(segments) - 1, -1, -1):
seg = segments[i]
for layer_name, tokens in _LAYER_HINTS:
- if seg in tokens:
+ if seg in tokens and (renders_ui or layer_name != _UI_LAYER):
return layer_name
if token_hints and seg in token_hints:
return token_hints[seg]
diff --git a/packages/core/src/repowise/core/generation/overview_tables.py b/packages/core/src/repowise/core/generation/overview_tables.py
index af90fa880..51ba9b4bb 100644
--- a/packages/core/src/repowise/core/generation/overview_tables.py
+++ b/packages/core/src/repowise/core/generation/overview_tables.py
@@ -122,29 +122,35 @@ def select_capabilities(
more of the same list, so the ranking, the corroboration and the definition
test are shared rather than derived twice — the front page is the top of
the glossary by construction, which is also what a reader expects of it.
+
+ Only defined terms: a front-page row reading "—" says nothing, while the
+ glossary still lists them. Filtered before the cap so defined terms fill it.
"""
- return select_terms(house_terms, module_names, limit=limit)
+ defined = [t for t in select_terms(house_terms, module_names) if t.definition]
+ return defined[:limit]
def build_capability_table(capabilities: Sequence[Capability]) -> str | None:
"""Render ``Capability | What it is | Where it is written`` as markdown.
- Returns ``None`` when nothing was selected. A repository whose documents
+ Returns ``None`` when no selected row carries a definition. A repository whose documents
name nothing its code also spells is a supported and common outcome, and a
header over an empty table says less than no section at all.
"""
- if not capabilities:
- log.info("overview_capability_table_empty")
+ # An undefined row renders as "—" and says nothing; no rows means no table.
+ rows = [cap for cap in capabilities if cap.definition]
+ if not rows:
+ log.info("overview_capability_table_empty", undefined=len(capabilities))
return None
lines = [
"| Capability | What it is | Where it is written |",
"|---|---|---|",
]
- for cap in capabilities:
- definition = clamp(cap.definition, _MAX_CAPABILITY_DEFINITION) if cap.definition else "—"
+ for cap in rows:
+ definition = clamp(cap.definition, _MAX_CAPABILITY_DEFINITION)
lines.append(f"| {cell(cap.term)} | {definition} | `{cell(cap.source_path)}` |")
- log.debug("overview_capability_table_built", rows=len(capabilities))
+ log.debug("overview_capability_table_built", rows=len(rows))
return "\n".join(lines)
diff --git a/tests/unit/generation/test_layers.py b/tests/unit/generation/test_layers.py
index ae9e4fa1a..e2b7ad7f2 100644
--- a/tests/unit/generation/test_layers.py
+++ b/tests/unit/generation/test_layers.py
@@ -28,6 +28,17 @@ def test_infer_layer_matches_directory_hints():
assert infer_layer("src/types/dtos.ts") == "Types"
+def test_ui_layer_requires_ui_language():
+ # A UI-named directory only means UI for files that render one.
+ assert infer_layer("web/ui/Button.tsx") == "UI"
+ assert infer_layer("app/views/home.html") == "UI"
+ assert infer_layer("src/components/Card.vue") == "UI"
+ # A CLI's ui/ helpers keep scanning outward and land on the CLI.
+ assert infer_layer("src/tool/cli/ui/render.py") == "CLI"
+ assert infer_layer("src/tool/ui/progress.py") == DEFAULT_LAYER
+ assert infer_layer("myapp/views/users.py") == DEFAULT_LAYER
+
+
def test_infer_layer_recognizes_cli_command_surface():
# Edge case A: a CLI command surface must not fall through to Application.
assert infer_layer("packages/cli/src/repowise/cli/commands/init_cmd.py") == "CLI"
diff --git a/tests/unit/generation/test_overview_capability_table.py b/tests/unit/generation/test_overview_capability_table.py
index 6e4744c87..f94e46f01 100644
--- a/tests/unit/generation/test_overview_capability_table.py
+++ b/tests/unit/generation/test_overview_capability_table.py
@@ -22,6 +22,7 @@ from structlog.testing import capture_logs
from repowise.core.generation.concept_tree.vocabulary import HouseTerm
from repowise.core.generation.context_assembler import ContextAssembler
+from repowise.core.generation.house_vocabulary import select_terms
from repowise.core.generation.overview_tables import (
CAPABILITY_TABLE_HEADING,
build_capability_table,
@@ -32,16 +33,20 @@ from repowise.core.ingestion.models import PackageInfo, RepoStructure
from .conftest import _make_file_info
+_DEFINED = object()
+
def _term(
term: str,
*,
- definition: str | None = None,
+ definition: str | None | object = _DEFINED,
definition_source: str | None = None,
source_paths: tuple[str, ...] = ("README.md",),
doc_frequency: int = 1,
code_frequency: int = 5,
) -> HouseTerm:
+ if definition is _DEFINED:
+ definition = f"{term} is a capability the documents describe."
return HouseTerm(
term=term,
definition=definition,
@@ -177,7 +182,7 @@ def test_prose_that_is_not_a_statement_is_not_offered_as_a_definition(text):
term in a README that is often a command line or a lead-in. An em dash is
a better answer: the reader learns the capability exists and is not
misinformed about what it does."""
- picked = select_capabilities([_term("Dead code", definition=text)], MODULES)
+ picked = select_terms([_term("Dead code", definition=text)], MODULES)
assert picked[0].definition is None
@@ -210,7 +215,7 @@ def test_a_real_sentence_survives(term, text):
def test_a_rejected_definition_does_not_leave_its_source_behind():
"""Citing where prose the table declined to quote lives would point the
reader at a line that is not on the page."""
- picked = select_capabilities(
+ picked = select_terms(
[
_term(
"Dead code",
@@ -231,11 +236,18 @@ def test_a_rejected_definition_is_logged():
assert any(e["event"] == "house_vocabulary.definition_rejected" for e in logs)
-def test_a_term_the_repository_never_defined_still_gets_a_row():
- """Naming a capability and never writing a sentence about it is common,
- and inventing the sentence is the one thing the miner refuses to do."""
- table = build_capability_table(select_capabilities([_term("Dead code")], MODULES))
- assert "| Dead code | — | `README.md` |" in table
+def test_capability_table_omits_undefined():
+ """A row reading "—" tells the reader nothing, so undefined terms stay off
+ the front page and defined ones take their slots; none defined, no table."""
+ terms = [_term("Blast radius", definition=None), _term("Dead code")]
+ picked = select_capabilities(terms, MODULES, limit=1)
+ assert [c.term for c in picked] == ["Dead code"]
+ table = build_capability_table(picked)
+ assert "—" not in table
+ assert "Blast radius" not in table
+ undefined = select_terms([_term("Dead code", definition=None)], MODULES)
+ assert build_capability_table(undefined) is None
+ assert select_capabilities([_term("Dead code", definition=None)], MODULES) == []
def test_the_source_falls_back_to_the_document_that_named_the_term():
@@ -251,7 +263,7 @@ def test_a_pipe_in_mined_prose_does_not_break_the_table():
column to its right."""
table = build_capability_table(
select_capabilities(
- [_term("Dead code", definition="Run `repowise dead-code | less` to read it all.")],
+ [_term("Dead code", definition="Dead code is what a `grep|sort` pass over the tree never finds.")],
MODULES,
)
)