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
feat(wiki): render the history the file pages already carry (#2082)
Raghav Chamadiya1dda6877999d
diff --git a/packages/core/src/repowise/core/generation/context/assembler.py b/packages/core/src/repowise/core/generation/context/assembler.pyindex 92a1a9a5d..de3db2cef 100644--- a/packages/core/src/repowise/core/generation/context/assembler.py+++ b/packages/core/src/repowise/core/generation/context/assembler.py@@ -66,6 +66,16 @@ _MAX_TOP_FILES = 20# public surface._MAX_CONCEPT_ROWS = 40+# The graph gives every file a synthetic symbol that owns its module-scope+# calls. It is not a caller anyone can look up, and the importer list already+# covers import-time use.+_MODULE_SCOPE_NODE = "__module__"++# How many co-change partners a file page names. Past a handful the list+# stops being "and this other thing moves with it" and becomes a second,+# weaker dependency table.+_MAX_CO_CHANGE_PARTNERS = 5+# The module page's "Class hierarchy" section: how many classes it shows, and# how many any one file may contribute so a single dense file cannot fill it._MAX_KEY_CLASSES = 10@@ -360,6 +370,21 @@ class ContextAssembler:# Generation depthdepth = self._select_generation_depth(path, git_meta, pagerank.get(path, 0.0))+ # Files this one changes with in history and does not import. The+ # partners the graph already explains are dropped: they are the paths+ # the page lists under "Depends on" two sections down, and a section+ # that repeats them says nothing. Decoded here rather than in the+ # template because the indexer persists them as a JSON cell.+ co_change_pages = [+ {+ "path": partner.file_path,+ "commits": partner.support,+ "last": partner.last_co_change or "",+ }+ for partner in parse_partners((git_meta or {}).get("co_change_partners_json"))+ if partner.structural == STRUCTURAL_UNEXPLAINED and partner.support > 0+ ][:_MAX_CO_CHANGE_PARTNERS]+# Graph intelligence: call graph, heritage, community metadatacall_graph_entries = extract_call_graph(path, graph, symbol_index)heritage_entries = extract_heritage(path, graph, symbol_index)@@ -388,6 +413,7 @@ class ContextAssembler:parse_errors=parsed.parse_errors,estimated_tokens=used,git_metadata=git_meta,+ co_change_pages=co_change_pages,dead_code_findings=dead_code_findings or [],depth=depth,dependency_summaries=dep_summaries,@@ -432,6 +458,8 @@ class ContextAssembler:else:callers = []+ call_sites = _resolved_call_sites(symbol, graph)+# Extract source body for the symbolsource_body = Noneif source_bytes and symbol.start_line and symbol.end_line:@@ -454,6 +482,7 @@ class ContextAssembler:complexity_estimate=symbol.complexity_estimate,callers=callers,source_body=source_body,+ call_sites=call_sites,)# ------------------------------------------------------------------@@ -1125,3 +1154,53 @@ def _symbol_to_dict(symbol: Symbol) -> dict[str, Any]:"start_line": symbol.start_line,"end_line": symbol.end_line,}+++def _resolved_call_sites(symbol: Symbol, graph: Any) -> list[dict]:+ """Calls the resolver actually resolved to *symbol*, most confident first.++ A spotlight's ``callers`` list is the files importing the defining module,+ which for a constant like ``PRUNED_DIRS`` means thirty-seven files that+ may never touch it. The call graph knows better wherever the resolver+ reached a verdict, and ``Symbol.id`` is the graph's own node key, so this+ is an in-edge scan on one node rather than a walk.++ Uncapped: the template slices what it prints and reports the true total,+ the way the importer list already does. A count that was silently the cap+ would tell a reader with nine hundred callers that it had twenty-five.++ Empty when nothing resolved, which is the common case for data and for+ dynamically dispatched languages — the template then keeps the honest+ import-level wording.+ """+ try:+ if symbol.id not in graph:+ return []+ scored: list[tuple[float, dict]] = []+ for source, _, edata in graph.in_edges(symbol.id, data=True):+ if edata.get("edge_type") != "calls":+ continue+ data = graph.nodes.get(source, {})+ if data.get("name") == _MODULE_SCOPE_NODE:+ continue+ scored.append(+ (+ float(edata.get("confidence") or 0.0),+ {+ "caller": data.get("name", source),+ "caller_file": data.get("file_path", ""),+ },+ )+ )+ except Exception:+ return []+ scored.sort(key=lambda s: (-s[0], s[1]["caller_file"], s[1]["caller"]))+ seen: set[tuple[str, str]] = set()+ unique: list[dict] = []+ for _, site in scored:+ key = (site["caller_file"], site["caller"])+ if key in seen:+ continue+ seen.add(key)+ unique.append(site)+ return uniquediff --git a/packages/core/src/repowise/core/generation/context/contexts.py b/packages/core/src/repowise/core/generation/context/contexts.pyindex fed4bc10f..438adefe5 100644--- a/packages/core/src/repowise/core/generation/context/contexts.py+++ b/packages/core/src/repowise/core/generation/context/contexts.py@@ -36,6 +36,9 @@ class FilePageContext:file_category: str = "code"rag_context: list[str] = field(default_factory=list)git_metadata: dict | None = None+ # Files that change in the same commits as this one and that the import+ # graph does not explain: [{"path", "commits", "last"}]. Coupling a reader+ # cannot see from the code, decoded from the git metadata's partner cell.co_change_pages: list[dict] = field(default_factory=list)dead_code_findings: list[dict] = field(default_factory=list)depth: str = "standard"@@ -81,8 +84,14 @@ class SymbolSpotlightContext:decorators: list[str]is_async: boolcomplexity_estimate: int+ # Files importing the module that defines the symbol. Import-level+ # references, not call sites; the template says so where it lists them.callers: list[str]source_body: str | None = None+ # Resolved calls *to* this symbol: [{"caller", "caller_file"}]. Where the+ # call resolver reached a verdict this is what "where it is used" means,+ # and ``callers`` is the fallback for the symbols it did not resolve.+ call_sites: list[dict] = field(default_factory=list)@dataclassdiff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.pyindex 251def6e2..71ae5da03 100644--- a/packages/core/src/repowise/core/generation/page_generator/core.py+++ b/packages/core/src/repowise/core/generation/page_generator/core.py@@ -49,9 +49,7 @@ from .pertype import PerTypeGenerationMixinfrom .prompts import CORRECTIVE_RETRY_DIRECTIVE, SUPPORTED_LANGUAGES, SYSTEM_PROMPTSfrom .structural import (StructuralRenderMixin,- as_markdown,- oneline,- signature,+ register_filters,)from .validation import (InvalidGeneratedContentError,@@ -206,9 +204,7 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):self._jinja_env = jinja_env# Registered on whatever env we ended up with (including one a caller# injected), since deterministic templates depend on it.- self._jinja_env.filters.setdefault("oneline", oneline)- self._jinja_env.filters.setdefault("as_markdown", as_markdown)- self._jinja_env.filters.setdefault("signature", signature)+ register_filters(self._jinja_env)# A pipe ends a table cell wherever it appears, and a deterministic# template interpolates the repository's own prose — which routinely# quotes a shell pipeline. Without this every column to the right ofdiff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.pyindex baf894b36..30a496510 100644--- a/packages/core/src/repowise/core/generation/page_generator/pertype.py+++ b/packages/core/src/repowise/core/generation/page_generator/pertype.py@@ -179,7 +179,11 @@ class PerTypeGenerationMixin:return self._structural_symbol_spotlight(ctx,target,- structural_page_title(self._language, "symbol_spotlight", symbol.qualified_name),+ # Titled by the target the page is keyed on, not by the dotted+ # path built from every directory above the file. That path is+ # synthetic; a real path beside a real name is what a reader+ # scanning the tree can place.+ structural_page_title(self._language, "symbol_spotlight", target),subject_hash=parsed.content_hash or "",)diff --git a/packages/core/src/repowise/core/generation/page_generator/structural.py b/packages/core/src/repowise/core/generation/page_generator/structural.pyindex 87bd64135..dc97ea65b 100644--- a/packages/core/src/repowise/core/generation/page_generator/structural.py+++ b/packages/core/src/repowise/core/generation/page_generator/structural.py@@ -45,7 +45,7 @@ log = structlog.get_logger(__name__)# output without changing any template's bytes: new context fields, a changed# helper, a reordered section. Template edits are picked up automatically# (their source is hashed), so this is only for the cases hashing cannot see.-STRUCTURAL_GENERATION_VERSION = "1"+STRUCTURAL_GENERATION_VERSION = "2"# Keyless stub templates live one directory down so their filenames can match# the prompt templates they stand in for.@@ -143,22 +143,380 @@ def dedent_body(text: str) -> str:def signature(value: object, limit: int = 120) -> str:- """Render a symbol signature for a table cell without cutting mid-token.-- Signatures are captured across source lines, so collapsing whitespace is- needed before anything else or the cell fills with runs of indentation.- When one is still too long we cut back to the last argument boundary, so- the reader sees a whole parameter list prefix rather than half an- identifier.+ """Format a captured signature so it reads as a declaration, not as source.++ A signature is captured verbatim across source lines, so it arrives with+ the author's line breaks and indentation in it, and sometimes without its+ tail: a constant whose value opens a bracket on the next line is stored as+ ``PRUNED_DIRS: frozenset[str] = frozenset(``.++ Three passes, cheapest first. Collapse the whitespace. Close the brackets+ an unfinished capture left open. Then, if it is still too long, shorten the+ parameter list to bare names and keep the return annotation — slicing the+ string instead cuts the annotation off, and what a function returns is the+ half a reader is looking for."""text = " ".join(str(value or "").split())+ if not text:+ return ""+ text = _tidy_punctuation(text)+ text = _normalize_params(text)+ text = _close_unfinished_capture(text)if len(text) <= limit:return text- head = text[:limit]- cut = max(head.rfind(", "), head.rfind("("))+ shortened = _names_only_params(text)+ if shortened is not None and len(shortened) <= limit:+ return shortened+ head, params, tail = _split_params(text) or (text, None, "")+ if params is not None and len(head) + len(tail) + 3 <= limit:+ return f"{head}…){tail}"+ cut = text[:limit].rfind(", ")if cut > limit // 3:- head = head[: cut + 1]- return head.rstrip().rstrip(",") + " …"+ return text[:cut] + " …"+ return text[: limit - 1].rstrip().rstrip(",") + "…"+++def _code_spans(text: str) -> list[tuple[bool, str]]:+ """*text* split into (is_code, chunk), where a string literal is not code.++ Every rewrite below reshapes source punctuation, and a signature routinely+ carries a regex or a path in a string literal: ``re.compile(r"[|&;]")``,+ ``("Cargo.toml",)``. Reshaping inside one corrupts a value the page then+ states as fact, so the passes see only what is outside the quotes.+ """+ out: list[tuple[bool, str]] = []+ buf: list[str] = []+ quote = ""+ escaped = False+ for ch in text:+ if escaped:+ escaped = False+ buf.append(ch)+ continue+ if ch == "\\":+ escaped = True+ buf.append(ch)+ elif quote:+ buf.append(ch)+ if ch == quote:+ out.append((False, "".join(buf)))+ buf = []+ quote = ""+ elif ch in _QUOTES:+ if buf:+ out.append((True, "".join(buf)))+ buf = [ch]+ quote = ch+ else:+ buf.append(ch)+ if buf:+ out.append((not quote, "".join(buf)))+ return out+++_QUOTES = "\"'"++# The spacing a multi-line declaration leaves behind once it is collapsed onto+# one line. Nothing here removes a comma: a trailing one is cosmetic in a+# parameter list and load-bearing in ``("Cargo.toml",)``, so the parameter list+# normalises its own and every other bracket group is left as written.+_SPACING_RULES = (+ (re.compile(r"\(\s+"), "("),+ (re.compile(r"\s+\)"), ")"),+ (re.compile(r"\[\s+"), "["),+ (re.compile(r"\s+\]"), "]"),+ (re.compile(r"\s+,"), ","),+)+++def _tidy_punctuation(text: str) -> str:+ """Undo the spacing a multi-line signature leaves once it is collapsed."""+ out = []+ for is_code, chunk in _code_spans(text):+ if is_code:+ for pattern, repl in _SPACING_RULES:+ chunk = pattern.sub(repl, chunk)+ out.append(chunk)+ return "".join(out)+++def _close_unfinished_capture(text: str) -> str:+ """Close the brackets a capture that stopped mid-expression left open.++ A constant whose value opens a bracket on the next source line is stored+ as ``PRUNED_DIRS: frozenset[str] = frozenset(``, which renders as a broken+ fragment. Closing it reads as a declaration and, unlike cutting the+ initializer off, keeps every token; the page is the index entry.+ """+ if text.endswith("="):+ return text[:-1].rstrip()+ unclosed = _unclosed_brackets(text)+ if not unclosed:+ return text+ return text + "\u2026" + "".join(_CLOSERS[ch] for ch in reversed(unclosed))+++_CLOSERS = {"(": ")", "[": "]", "{": "}"}+++def _unclosed_brackets(text: str) -> list[str]:+ """The still-open brackets of *text*, outermost first, quotes excluded."""+ stack: list[str] = []+ for is_code, chunk in _code_spans(text):+ if not is_code:+ continue+ for ch in chunk:+ if ch in _CLOSERS:+ stack.append(ch)+ elif ch in ")]}" and stack and _CLOSERS[stack[-1]] == ch:+ stack.pop()+ return stack+++def _split_params(text: str) -> tuple[str, str, str] | None:+ """Split ``head(``, the parameter list, and the trailing ``) -> T``."""+ depth = 0+ open_at = -1+ index = 0+ for is_code, chunk in _code_spans(text):+ if not is_code:+ index += len(chunk)+ continue+ for offset, ch in enumerate(chunk):+ if ch in "([{":+ if depth == 0 and ch == "(" and open_at < 0:+ open_at = index + offset+ depth += 1+ elif ch in ")]}":+ depth -= 1+ if depth == 0 and open_at >= 0:+ close_at = index + offset+ return (+ text[: open_at + 1],+ text[open_at + 1 : close_at],+ text[close_at + 1 :],+ )+ index += len(chunk)+ return None+++def _split_top_level(params: str) -> list[str]:+ """*params* split on the commas that separate one parameter from the next.++ Depth- and quote-aware, so neither ``dict[str, int]`` nor ``sep = ", "``+ splits. A lambda default is the one shape this cannot see through, since+ its comma really is at depth zero; :func:`_names_only_params` then refuses+ the signature rather than printing a name it cannot vouch for.+ """+ parts: list[str] = []+ depth = 0+ current: list[str] = []+ for is_code, chunk in _code_spans(params):+ if not is_code:+ current.append(chunk)+ continue+ for ch in chunk:+ if ch in "([{":+ depth += 1+ elif ch in ")]}":+ depth -= 1+ if ch == "," and depth == 0:+ parts.append("".join(current))+ current = []+ continue+ current.append(ch)+ parts.append("".join(current))+ return [p for p in (part.strip() for part in parts) if p]+++def _normalize_params(text: str) -> str:+ """Rejoin a callable's parameter list, dropping a magic trailing comma.++ Only where the bracket group is a parameter list. A group that follows an+ ``=`` is a value, and ``filenames: tuple[str, ...] = ("Cargo.toml",)`` is a+ one-tuple that becomes a plain string if that comma goes.+ """+ split = _split_params(text)+ if split is None:+ return text+ head, params, tail = split+ if "=" in "".join(c for is_code, c in _code_spans(head) if is_code):+ return text+ return f"{head}{', '.join(_split_top_level(params))}){tail}"+++def _names_only_params(text: str) -> str | None:+ """The same signature with each parameter reduced to its name.++ ``root: Path | str`` becomes ``root``, ``*, prune_dirs: frozenset[str] =+ PRUNED_DIRS`` becomes ``*, prune_dirs``. Returns None when there is no+ parameter list, or when a parameter does not reduce to something shaped+ like a name: eliding the whole list is better than printing an identifier+ the signature never declared.+ """+ split = _split_params(text)+ if split is None:+ return None+ head, params, tail = split+ names = [_param_name(part) for part in _split_top_level(params)]+ if not names or not all(_NAME_RE.fullmatch(name) for name in names):+ return None+ return f"{head}{', '.join(names)}){tail}"+++_NAME_RE = re.compile(r"[*/]{0,2}[A-Za-z_$][\w$]*|[*/]{1,2}")+++def _param_name(param: str) -> str:+ """The declared name of one parameter, without annotation or default."""+ text = param.strip()+ if text in {"*", "**", "/"}:+ return text+ consumed = 0+ for is_code, chunk in _code_spans(text):+ if not is_code:+ break+ cut = min((chunk.find(c) for c in ":=" if c in chunk), default=-1)+ if cut >= 0:+ return text[: consumed + cut].strip()+ consumed += len(chunk)+ return text.strip()+++def datestamp(value: object) -> str:+ """A date, as ``YYYY-MM-DD``, from whatever git metadata carries.++ Dates only, never "three days ago": a page's bytes are its reuse key, and+ a relative date would move every one of them every day.+ """+ if value is None:+ return ""+ text = str(value).strip()+ if not text:+ return ""+ return text[:10]+++def is_public_api(symbol: Mapping[str, Any]) -> bool:+ """Whether a public symbol is API a caller would reach for.++ Two kinds of name are public to the parser and are not an API. A dunder is+ the language talking to itself, and ``__all__`` in particular is metadata+ *about* the API rather than part of it. A module-level ``variable`` with no+ capital in its name is module state — ``log``, ``logger``, ``router``, and+ Alembic's ``revision`` / ``down_revision`` are 771 of the 878 such symbols+ in this repository, and not one of them is something another file calls.+ The type aliases that share the kind (``SourceFile``, ``ReasoningMode``)+ keep their capitals and stay.++ Demoted, not dropped: the caller still names them on the page, so the+ identifier stays in ``content`` for the index.+ """+ name = str(symbol.get("name") or "")+ if name.startswith("__") and name.endswith("__"):+ return False+ if symbol.get("kind") == "variable" and not symbol.get("parent_name"):+ return any(c.isupper() for c in name)+ return True+++def api_symbols(symbols: Iterable[Mapping[str, Any]]) -> list[Mapping[str, Any]]:+ """The public symbols that belong in the API table."""+ return [s for s in symbols if s.get("visibility") == "public" and is_public_api(s)]+++def internal_symbols(symbols: Iterable[Mapping[str, Any]]) -> list[Mapping[str, Any]]:+ """The public symbols the API table leaves out, in declaration order."""+ return [s for s in symbols if s.get("visibility") == "public" and not is_public_api(s)]+++# A prose line rather than a table cell, so it can carry a whole constructor.+# The table's 120 is what keeps a column readable; here the only reason to cut+# is a generated signature long enough to be the page.+_DECLARATION_LIMIT = 400+++def declarations(symbols: Iterable[Mapping[str, Any]]) -> list[str]:+ """How to spell symbols the API table leaves out, one string each.++ The signature rather than the name, because the name alone would take the+ rest of the declaration out of ``content``: ``log`` on its own drops+ ``structlog``, ``get_logger`` and ``__name__`` from the page, and the page+ is the index entry. Falls back to the name for a symbol the parser+ captured no signature for, and appends it where the signature somehow does+ not spell it, so no name can go missing either way.+ """+ out: list[str] = []+ for symbol in symbols:+ name = str(symbol.get("name") or "")+ declared = signature(symbol.get("signature") or "", _DECLARATION_LIMIT)+ if not declared:+ declared = name+ elif name and name not in declared:+ declared = f"{name}: {declared}"+ if declared:+ out.append(declared)+ return out+++def code_span(text: str) -> str:+ """*text* as a markdown code span, fenced long enough to contain it.++ A single backtick fence ends at the first backtick inside it, and 47 of+ this repository's own signatures carry one — a regex matching a fence, for+ instance. Markdown's own rule is a longer fence, which keeps the bytes+ exactly as captured rather than escaping them into something else.+ """+ body = str(text)+ longest = max((len(run) for run in re.findall(r"`+", body)), default=0)+ fence = "`" * (longest + 1)+ pad = " " if body.startswith("`") or body.endswith("`") else ""+ return f"{fence}{pad}{body}{pad}{fence}"+++def group_paths(paths: Iterable[str], limit: int = 25) -> list[dict[str, Any]]:+ """Group file paths under their directory, busiest directory first.++ A flat list of twenty-five import paths is the same twenty-five strings a+ reader could get from grep. Grouped, the shape of the dependency shows: of+ the thirty-seven files importing ``fs_walk``, nine are import resolvers.++ Every path is carried through whole, because the page is also the index+ entry: a directory heading with basenames under it would drop the strings+ a question matches on.+ """+ grouped: dict[str, list[str]] = {}+ for path in list(paths)[:limit]:+ directory = path.rsplit("/", 1)[0] if "/" in path else "."+ grouped.setdefault(directory, []).append(path)+ return sorted(+ ({"directory": d, "paths": p} for d, p in grouped.items()),+ key=lambda g: (-len(g["paths"]), g["directory"]),+ )+++def register_filters(env: Any) -> None:+ """Register every filter the deterministic templates use on *env*.++ One function rather than a list repeated at each call site: a template+ that reaches for a filter the caller forgot raises at render time, and the+ callers are the generator and four test fixtures.+ """+ for name, fn in (+ ("oneline", oneline),+ ("as_markdown", as_markdown),+ ("signature", signature),+ # Page shaping the templates cannot express: the split between+ # declared API and module bookkeeping, the grouping of a dependency+ # list, and a date out of a git metadata value.+ ("api_symbols", api_symbols),+ ("internal_symbols", internal_symbols),+ ("declarations", declarations),+ ("code_span", code_span),+ ("group_paths", group_paths),+ ("datestamp", datestamp),+ ):+ env.filters.setdefault(name, fn)_TEMPLATES_DIR = Path(__file__).parent.parent / "templates"diff --git a/packages/core/src/repowise/core/generation/structural_labels.py b/packages/core/src/repowise/core/generation/structural_labels.pyindex 11985a7cd..b27165978 100644--- a/packages/core/src/repowise/core/generation/structural_labels.py+++ b/packages/core/src/repowise/core/generation/structural_labels.py@@ -72,6 +72,33 @@ ENGLISH_LABELS: dict[str, str] = {"part_of_module_cluster": "Part of the **{community}** module cluster.","layer": "Layer","role": "Role",+ # The knowledge graph's three roles, spelled for a reader. The stored+ # values are enum members and one of them, ``edge_connector``, says+ # nothing at all outside the code that computes it.+ "role_entry_point": "entry point into its layer",+ "role_internal": "internal to its layer",+ "role_boundary": "boundary — imported from other layers",+ # Symbols the API table leaves out, named so the identifier stays on the+ # page even though the row does not.+ "also_defined": "Also defined: {names}.",+ # -- file page: history ------------------------------------------------+ "history": "History",+ "history_commits": "{total} {commit_word} in its history, {recent} in the last 90 days.",+ "history_last_commit": "The last landed on {date}.",+ "history_owner": "**{owner}** is its primary maintainer, at {pct}% of commits.",+ "history_fixes": "{count} of those commits fixed a bug.",+ "history_hotspot": "It is one of the repository's change hotspots.",+ "history_stable": "It has been stable: nothing has changed it lately.",+ "commit_singular": "commit",+ "commit_plural": "commits",+ "changes_with": "Changes together with",+ "changes_with_intro": (+ "Files that change in the same commits as this one without importing it "+ "or being imported by it."+ ),+ "changes_with_entry": "{count} shared {commit_word}",+ "last_together": "last together on {date}",+ "decisions_heading": "Decisions touching this file","in_the_code": "In the code","question_exports": "What does `{path}` export?","question_where_defined": "Where is `{symbol}` defined?",@@ -95,6 +122,12 @@ ENGLISH_LABELS: dict[str, str] = {),"import_verb_singular": "imports","import_verb_plural": "import",+ "call_sites_summary": "Reached by {count} resolved {call_word}.",+ "imported_by_heading": "Files importing this module",+ "call_site_singular": "call",+ "call_site_plural": "calls",+ "in_file": "in `{path}`",+ "question_what_calls": "What calls `{symbol}`?","implementation": "Implementation","question_what_is": "What is `{symbol}`?","question_which_files_import": ("Which files import the module that defines `{symbol}`?"),@@ -191,6 +224,29 @@ LOCALIZED_LABELS: dict[str, dict[str, str]] = {"part_of_module_cluster": "Teil des Modulclusters **{community}**.","layer": "Schicht","role": "Rolle",+ "role_entry_point": "Einstiegspunkt in ihre Schicht",+ "role_internal": "innerhalb ihrer Schicht",+ "role_boundary": "Randstelle — wird aus anderen Schichten importiert",+ "also_defined": "Ebenfalls definiert: {names}.",+ "history": "Historie",+ "history_commits": (+ "{total} {commit_word} in ihrer Historie, {recent} in den letzten 90 Tagen."+ ),+ "history_last_commit": "Der letzte stammt vom {date}.",+ "history_owner": "**{owner}** betreut sie hauptsächlich, mit {pct}% der Commits.",+ "history_fixes": "{count} dieser Commits haben einen Fehler behoben.",+ "history_hotspot": "Sie gehört zu den Änderungs-Hotspots des Repositorys.",+ "history_stable": "Sie ist stabil: zuletzt hat sich nichts an ihr geändert.",+ "commit_singular": "Commit",+ "commit_plural": "Commits",+ "changes_with": "Ändert sich gemeinsam mit",+ "changes_with_intro": (+ "Dateien, die in denselben Commits geändert werden wie diese, ohne sie zu "+ "importieren oder von ihr importiert zu werden."+ ),+ "changes_with_entry": "{count} gemeinsame {commit_word}",+ "last_together": "zuletzt gemeinsam am {date}",+ "decisions_heading": "Entscheidungen zu dieser Datei","in_the_code": "Im Code","question_exports": "Was exportiert `{path}`?","question_where_defined": "Wo ist `{symbol}` definiert?",@@ -213,6 +269,12 @@ LOCALIZED_LABELS: dict[str, dict[str, str]] = {),"import_verb_singular": "importiert","import_verb_plural": "importieren",+ "call_sites_summary": "Erreicht von {count} aufgelösten {call_word}.",+ "imported_by_heading": "Dateien, die dieses Modul importieren",+ "call_site_singular": "Aufrufstelle",+ "call_site_plural": "Aufrufstellen",+ "in_file": "in `{path}`",+ "question_what_calls": "Was ruft `{symbol}` auf?","implementation": "Implementierung","question_what_is": "Was ist `{symbol}`?","question_which_files_import": (diff --git a/packages/core/src/repowise/core/generation/templates/file_page.j2 b/packages/core/src/repowise/core/generation/templates/file_page.j2index 667609fea..4466e2673 100644--- a/packages/core/src/repowise/core/generation/templates/file_page.j2+++ b/packages/core/src/repowise/core/generation/templates/file_page.j2@@ -7,8 +7,11 @@Written for retrieval as much as for reading: the page names its ownsymbols, its neighbours' file paths and its layer in full, because those- are the identifiers a question embeds near. Nobody reads a file page end- to end, so where readability and retrieval disagree, retrieval wins.+ are the identifiers a question embeds near. Where readability and+ retrieval disagree, retrieval wins and the reader personas in+ ``docs/reader-persona.ts`` decide what a reader is shown — a section is+ hidden client-side rather than dropped here, since dropping it would take+ it out of the index with it.Every section below the Overview is conditional. A heading with nothingunder it costs a reader a stop and puts the same stock sentence into the@@ -18,31 +21,124 @@``_extract_summary`` reads it back as the summary shown in search resultsand the wiki list.-#}-{%- set public_syms = ctx.symbols | selectattr("visibility", "equalto", "public") | list -%}+{%- set api_syms = ctx.symbols | api_symbols -%}+{%- set other_syms = ctx.symbols | internal_symbols -%}+{%- set git = ctx.git_metadata or {} -%}# {{ ctx.file_path }}## {{ labels.overview }}-{% if ctx.docstring %}{{ ctx.docstring | as_markdown }}{% else %}`{{ ctx.file_path }}` {{ labels.is_a }} {{ ctx.language }} {% if ctx.is_entry_point %}{{ labels.entry_point }} {% endif %}{% if ctx.is_test %}{{ labels.test }} {% endif %}{{ labels.source_file }}{% if ctx.kg_layer_name %} {{ labels.in_layer.format(layer=ctx.kg_layer_name) }}{% endif %}{% if ctx.community_label %}, {{ labels.part_of_module_cluster_intro.format(community=ctx.community_label) }}{% endif %}.{% endif %}-{%- if public_syms %}-{%- set symbol_word = labels.public_symbol_plural if public_syms | length != 1 else labels.public_symbol_singular %}+{% if ctx.docstring %}{{ ctx.docstring | as_markdown }}{% else %}{% if ctx.kg_node_summary %}{{ ctx.kg_node_summary | oneline }} {% endif %}`{{ ctx.file_path }}` {{ labels.is_a }} {{ ctx.language }} {% if ctx.is_entry_point %}{{ labels.entry_point }} {% endif %}{% if ctx.is_test %}{{ labels.test }} {% endif %}{{ labels.source_file }}{% if ctx.kg_layer_name %} {{ labels.in_layer.format(layer=ctx.kg_layer_name) }}{% endif %}{% if ctx.community_label %}, {{ labels.part_of_module_cluster_intro.format(community=ctx.community_label) }}{% endif %}.{% endif %}+{%- if api_syms %}+{%- set symbol_word = labels.public_symbol_plural if api_syms | length != 1 else labels.public_symbol_singular %}-{% if ctx.dependencies %}{{ labels.exposes_symbols_and_depends.format(symbol_count=public_syms | length, symbol_word=symbol_word, file_count=ctx.dependencies | length, file_word=labels.other_file_plural if ctx.dependencies | length != 1 else labels.other_file_singular) }}{% else %}{{ labels.exposes_symbols.format(symbol_count=public_syms | length, symbol_word=symbol_word) }}{% endif %}+{% if ctx.dependencies %}{{ labels.exposes_symbols_and_depends.format(symbol_count=api_syms | length, symbol_word=symbol_word, file_count=ctx.dependencies | length, file_word=labels.other_file_plural if ctx.dependencies | length != 1 else labels.other_file_singular) }}{% else %}{{ labels.exposes_symbols.format(symbol_count=api_syms | length, symbol_word=symbol_word) }}{% endif %}+{%- endif %}+{#- What the history knows and the code cannot say.++ All of this was assembled already and thrown away at render time. That a+ file has been fixed twice and moves with ``incremental.py`` is something a+ reader acts on; twenty-five import paths are something they could have got+ from grep.++ Every clause is conditional on the number behind it, so a repository with+ no git history renders no heading rather than a row of zeroes. Dates are+ absolute, never "three days ago": the rendered bytes are this page's reuse+ key, and a relative date would restate every page in the wiki daily.+-#}+{%- set history = [] -%}+{%- set commits = git.get("commit_count_total") or 0 -%}+{%- if commits -%}+{%- set _ = history.append(labels.history_commits.format(total=commits, commit_word=labels.commit_plural if commits != 1 else labels.commit_singular, recent=git.get("commit_count_90d") or 0)) -%}+{%- if git.get("last_commit_at") -%}+{%- set _ = history.append(labels.history_last_commit.format(date=git.get("last_commit_at") | datestamp)) -%}+{%- endif -%}+{#- The column is written on either scale depending on the producer, the+ same normalisation ``health/biomarkers/developer_congestion.py`` applies.+ Unnormalised, a 0-100 source renders "at 8500% of commits". -#}+{%- if git.get("primary_owner_name") and git.get("primary_owner_commit_pct") -%}+{%- set owner_pct = git.get("primary_owner_commit_pct") -%}+{%- set _ = history.append(labels.history_owner.format(owner=git.get("primary_owner_name"), pct=(owner_pct if owner_pct > 1.0 else owner_pct * 100) | round | int)) -%}+{%- endif -%}+{#- Suppressed when it exceeds the commit total: the two are counted over+ different windows, and a file whose fix count outruns its own log is one+ that has been moved, so the fixes belong to a path this page no longer+ describes. -#}+{%- if git.get("prior_defect_count") and git.get("prior_defect_count") <= commits -%}+{%- set _ = history.append(labels.history_fixes.format(count=git.get("prior_defect_count"))) -%}+{%- endif -%}+{%- if git.get("is_hotspot") -%}+{%- set _ = history.append(labels.history_hotspot) -%}+{%- elif git.get("is_stable") -%}+{%- set _ = history.append(labels.history_stable) -%}+{%- endif -%}+{%- endif -%}+{%- if history %}++## {{ labels.history }}++{{ history | join(" ") }}+{%- endif %}+{%- if ctx.co_change_pages %}++## {{ labels.changes_with }}++{{ labels.changes_with_intro }}+{% for cc in ctx.co_change_pages %}+- `{{ cc.path }}` — {{ labels.changes_with_entry.format(count=cc.commits, commit_word=labels.commit_plural if cc.commits != 1 else labels.commit_singular) }}{% if cc.last %} ({{ labels.last_together.format(date=cc.last | datestamp) }}){% endif %}+{%- endfor %}+{%- endif %}+{%- if ctx.decision_records %}++## {{ labels.decisions_heading }}+{% for dr in ctx.decision_records[:3] %}+- **{{ dr.title | oneline(80) }}** — {{ dr.decision | oneline }}{% if dr.rationale %} *({{ dr.rationale | oneline(120) }})*{% endif %}+{%- endfor %}+{%- endif %}+{#- The declared surface, and the names that are public to the parser without+ being anything a caller reaches for.++ ``log``, ``__all__`` and ``__init__`` made the table read as a symbol dump+ rather than as an API. They are declared under it instead of dropped, with+ their signatures and not just their names: ``content`` is also the index+ entry, and ``log`` alone would take ``structlog``, ``get_logger`` and+ ``__name__`` out of it. A constructor keeps its parameter list this way+ too, which the class's own row does not carry.+-#}+{%- if api_syms or other_syms %}## {{ labels.public_api }}+{%- if api_syms %}| {{ labels.symbol }} | {{ labels.kind }} | {{ labels.signature }} || --- | --- | --- |-{%- for s in public_syms %}+{%- for s in api_syms %}| `{{ s.name }}` | {{ s.kind }} | {{ (s.signature or "") | signature | replace("|", "\\|") }} |{%- endfor %}{%- endif %}+{%- if other_syms %}++{{ labels.also_defined.format(names=other_syms | declarations | map("code_span") | join(", ")) }}+{%- endif %}+{%- endif %}+{#- Dependency lists, grouped by the directory each path sits in.++ Flat, these were twenty-five strings in graph order — the same twenty-five+ a reader could have got from grep, and nothing about their shape. Grouped,+ the shape shows: of the files importing ``fs_walk``, nine are import+ resolvers. Each path is still printed whole, because dropping a directory+ prefix from a bullet would drop it from the index.+-#}{%- if ctx.dependencies %}## {{ labels.depends_on }}-{% for dep in ctx.dependencies[:25] %}+{%- for group in ctx.dependencies | group_paths %}++**`{{ group.directory }}`**+{% for dep in group.paths %}- `{{ dep }}`{%- endfor %}+{%- endfor %}{%- if ctx.dependencies | length > 25 %}_{{ labels.and_more.format(count=ctx.dependencies | length - 25) }}_@@ -53,9 +149,13 @@ _{{ labels.and_more.format(count=ctx.dependencies | length - 25) }}_## {{ labels.used_by }}{{ labels.imported_by_files.format(count=ctx.dependents | length, file_word=labels.file_plural if ctx.dependents | length != 1 else labels.file_singular) }}-{% for dep in ctx.dependents[:25] %}+{%- for group in ctx.dependents | group_paths %}++**`{{ group.directory }}`**+{% for dep in group.paths %}- `{{ dep }}`{%- endfor %}+{%- endfor %}{%- if ctx.dependents | length > 25 %}_{{ labels.and_more.format(count=ctx.dependents | length - 25) }}_@@ -68,7 +168,7 @@ _{{ labels.and_more.format(count=ctx.dependents | length - 25) }}_{{ labels.part_of_module_cluster.format(community=ctx.community_label) }}{%- endif %}{%- if ctx.kg_layer_name %}-**{{ labels.layer }}:** {{ ctx.kg_layer_name }}{% if ctx.kg_layer_role %} | **{{ labels.role }}:** {{ ctx.kg_layer_role }}{% endif %}+**{{ labels.layer }}:** {{ ctx.kg_layer_name }}{% if ctx.kg_layer_role %} | **{{ labels.role }}:** {% if ctx.kg_layer_role == "entry_point" %}{{ labels.role_entry_point }}{% elif ctx.kg_layer_role == "edge_connector" %}{{ labels.role_boundary }}{% else %}{{ labels.role_internal }}{% endif %}{% endif %}{%- endif %}{%- endif %}{#- Question-shaped text, built from structure rather than prose.@@ -81,7 +181,7 @@ _{{ labels.and_more.format(count=ctx.dependents | length - 25) }}_A question is emitted only where the page can answer it. A question whoseanswer is not below it puts the words of a promise into the index and then- breaks it, which is the failure this block exists to avoid. Last on the+ breaks it, which is the failure this block exists to avoid. Low on thepage so it cannot become the summary ``_extract_summary`` reads back.Built as a list and capped, because a fully-connected file qualifies for@@ -89,9 +189,9 @@ _{{ labels.and_more.format(count=ctx.dependents | length - 25) }}_question-shaped text and starts being padding on every page in the corpus.-#}{%- set questions = [] -%}-{%- if public_syms -%}+{%- if api_syms -%}{%- set _ = questions.append(labels.question_exports.format(path=ctx.file_path)) -%}-{%- set _ = questions.append(labels.question_where_defined.format(symbol=public_syms[0].name)) -%}+{%- set _ = questions.append(labels.question_where_defined.format(symbol=api_syms[0].name)) -%}{%- endif -%}{%- if ctx.dependents -%}{%- set _ = questions.append(labels.question_what_imports.format(path=ctx.file_path)) -%}diff --git a/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2 b/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2index cdf21c43a..0bf7dfaf1 100644--- a/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2+++ b/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2@@ -1,9 +1,12 @@{#- Deterministic (no-LLM) symbol spotlight.- Note the wording around callers: ``ctx.callers`` holds files that import- the containing module, not verified call sites. The LLM template hedges- the same way; a template that claimed otherwise would over-state what the- graph actually knows.+ "Where it is used" has two sources and says which one it is reading.+ ``ctx.call_sites`` is what the call resolver resolved to this symbol, and+ is what the section means wherever it is non-empty. ``ctx.callers`` is the+ fallback: files importing the containing module, not verified call sites,+ which for a constant meant listing thirty-seven files that may never touch+ it. The wording changes with the source, because a page that called an+ import a call would over-state what the graph knows.The rendered list stops at 25, the same bound ``file_page.j2`` puts on its"Used by" section over the same data, while the summary line above it keeps@@ -21,7 +24,11 @@the identifiers this page exists to carry. Deleting it would blank thesummary for every undocumented symbol.-#}-# {{ ctx.qualified_name }}+{#- The symbol's own name, not the synthetic dotted path built by joining+ every directory above it. The file it lives in is on the line below, which+ is where a reader looks for it and is the form ``get_symbol`` takes.+-#}+# {{ ctx.symbol_name }}**{{ labels.kind }}:** {{ ctx.kind }}{% if ctx.is_async %} ({{ labels.async_marker }}){% endif %} | **{{ labels.defined_in }}:** `{{ ctx.file_path }}`{% if ctx.complexity_estimate %} | **{{ labels.estimated_complexity }}:** {{ ctx.complexity_estimate }}{% endif %}{%- if ctx.signature %}@@ -41,8 +48,43 @@- `{{ d }}`{%- endfor %}{%- endif %}+{%- if ctx.call_sites %}++## {{ labels.where_used }}++{{ labels.call_sites_summary.format(count=ctx.call_sites | length, call_word=labels.call_site_plural if ctx.call_sites | length != 1 else labels.call_site_singular) }}+{% for site in ctx.call_sites[:25] %}+- `{{ site.caller }}`{% if site.caller_file %} {{ labels.in_file.format(path=site.caller_file) }}{% endif %}+{%- endfor %}+{%- if ctx.call_sites | length > 25 %}++_{{ labels.and_more.format(count=ctx.call_sites | length - 25) }}_+{%- endif %}+{#- The importers, once the resolved calls have answered the question.++ Their own heading, and one the reader personas hide: for a hub symbol+ these are twenty-five files that import the module and may never touch+ the symbol, which is what "where it is used" used to mean and why it was+ worth replacing. They stay on the page because ``content`` is the index+ entry — dropping them would take fifteen thousand file paths across a+ thousand pages out of search — and out of the reader's way because the+ section above already answered honestly.+-#}{%- if ctx.callers %}+## {{ labels.imported_by_heading }}++{{ labels.importers_summary.format(count=ctx.callers | length, file_word=labels.file_plural if ctx.callers | length != 1 else labels.file_singular, import_verb=labels.import_verb_plural if ctx.callers | length != 1 else labels.import_verb_singular) }}+{% for c in ctx.callers[:25] %}+- `{{ c }}`+{%- endfor %}+{%- if ctx.callers | length > 25 %}++_{{ labels.and_more.format(count=ctx.callers | length - 25) }}_+{%- endif %}+{%- endif %}+{%- elif ctx.callers %}+## {{ labels.where_used }}{{ labels.importers_summary.format(count=ctx.callers | length, file_word=labels.file_plural if ctx.callers | length != 1 else labels.file_singular, import_verb=labels.import_verb_plural if ctx.callers | length != 1 else labels.import_verb_singular) }}@@ -77,7 +119,9 @@ _{{ labels.and_more.format(count=ctx.callers | length - 25) }}_- {{ labels.question_where_defined.format(symbol=ctx.symbol_name) }}- {{ labels.question_what_is.format(symbol=ctx.qualified_name) }}-{%- if ctx.callers %}+{%- if ctx.call_sites %}+- {{ labels.question_what_calls.format(symbol=ctx.symbol_name) }}+{%- elif ctx.callers %}- {{ labels.question_which_files_import.format(symbol=ctx.symbol_name) }}{%- endif %}diff --git a/packages/ui/__tests__/docs/reader-persona.test.ts b/packages/ui/__tests__/docs/reader-persona.test.tsnew file mode 100644index 000000000..bad8aac21--- /dev/null+++ b/packages/ui/__tests__/docs/reader-persona.test.ts@@ -0,0 +1,86 @@+import { describe, it, expect } from "vitest";+import {+ DEFAULT_PERSONA,+ filterMarkdownByPersona,+ personaFilteringApplies,+} from "../../src/docs/reader-persona.js";++/**+ * The reader lens over a deterministic page.+ *+ * A file page's `## In the code` and `## Questions this page answers` are+ * written for the index, not for a reader: one is a bag of the file's own+ * tokens, the other is question-shaped text so a query has something to match.+ * They cannot be dropped upstream — `content` is a single string that FTS+ * indexes, the vector store embeds and `get_context` returns verbatim — so the+ * lens is where they stop being a reader's problem.+ *+ * What the rendered page actually emits is pinned on the Python side, against+ * the template rather than against a string typed here.+ */++const PAGE = [+ "# src/walk.py",+ "",+ "## Overview",+ "",+ "Walks a repository tree.",+ "",+ "## Public API",+ "",+ "| Symbol | Kind |",+ "| --- | --- |",+ "| `walk` | function |",+ "",+ "## Questions this page answers",+ "",+ "- What does `src/walk.py` export?",+ "",+ "## In the code",+ "",+ "prune_dirs max_depth node_modules",+].join("\n");++describe("filterMarkdownByPersona", () => {+ it("hides the retrieval scaffolding from the default reader", () => {+ const out = filterMarkdownByPersona(PAGE, "contributor");++ expect(out).not.toContain("## Questions this page answers");+ expect(out).not.toContain("## In the code");+ expect(out).not.toContain("prune_dirs max_depth node_modules");+ });++ it("keeps the reference material the default reader came for", () => {+ const out = filterMarkdownByPersona(PAGE, "contributor");++ expect(out).toContain("## Overview");+ expect(out).toContain("Walks a repository tree.");+ expect(out).toContain("## Public API");+ expect(out).toContain("`walk`");+ });++ it("shows everything at the deep level", () => {+ expect(filterMarkdownByPersona(PAGE, "deep")).toBe(PAGE);+ });++ it("never shows at the overview level what the contributor level hides", () => {+ const contributor = filterMarkdownByPersona(PAGE, "contributor");+ const overview = filterMarkdownByPersona(PAGE, "overview");++ for (const heading of PAGE.split("\n").filter((l) => l.startsWith("## "))) {+ if (!contributor.includes(heading)) expect(overview).not.toContain(heading);+ }+ expect(overview).not.toContain("## Public API");+ });++ it("leaves the persona control on a page it now filters", () => {+ // The control is gated on this; hiding two more sections may only make it+ // apply to more pages, never to fewer.+ expect(personaFilteringApplies(PAGE)).toBe(true);+ expect(DEFAULT_PERSONA).toBe("contributor");+ });++ it("still reports no effect on a page with nothing to hide", () => {+ expect(personaFilteringApplies("# Title\n\n## Overview\n\nProse.\n")).toBe(false);+ });+});diff --git a/packages/ui/src/docs/reader-persona.ts b/packages/ui/src/docs/reader-persona.tsindex 6b4483f90..ebc90fe11 100644--- a/packages/ui/src/docs/reader-persona.ts+++ b/packages/ui/src/docs/reader-persona.ts@@ -28,7 +28,33 @@ export function isReaderPersona(value: string | null | undefined): value is Read// Heading keywords (lowercased, matched as a prefix of the heading text) that// each persona hides. Matching is intentionally generous so it works across// the file/module/layer page templates without an exhaustive list.++// Contributor keeps almost everything; only the rawest machine-oriented dumps+// are hidden so the page stays readable.+//+// The last three are retrieval scaffolding rather than reference material. A+// deterministic page carries them so the index has the words a question is+// asked in — the vocabulary bag and the question block are the only parts of+// a file page written in a reader's words rather than in paths, and the third+// is the importer list a symbol page keeps once its resolved callers have+// answered the question. They earn their place in `content`, which is one+// string that FTS indexes, the vector store embeds and `get_context` returns+// verbatim; they do not earn a reader's scroll. Hidden here rather than+// dropped upstream so the index keeps them.+const CONTRIBUTOR_HIDE = [+ "raw metrics",+ "parse errors",+ "source snippet",+ "in the code",+ "questions this page answers",+ "files importing this module",+];++// Overview is contributor plus the reference dumps. Spread rather than+// restated: a section the balanced lens hides must never reappear in the+// narrower one.const OVERVIEW_HIDE = [+ ...CONTRIBUTOR_HIDE,"symbols","symbol","public api",@@ -40,18 +66,11 @@ const OVERVIEW_HIDE = ["class hierarchy","community","neighbors",- "raw metrics","dead code",- "parse errors","source",- "source snippet","metrics",];-// Contributor keeps almost everything; only the rawest machine-oriented dumps-// are hidden so the page stays readable.-const CONTRIBUTOR_HIDE = ["raw metrics", "parse errors", "source snippet"];-const HIDE_BY_PERSONA: Record<ReaderPersona, string[]> = {overview: OVERVIEW_HIDE,contributor: CONTRIBUTOR_HIDE,diff --git a/tests/unit/generation/test_deterministic_templates.py b/tests/unit/generation/test_deterministic_templates.pyindex b19d796df..68ae4c486 100644--- a/tests/unit/generation/test_deterministic_templates.py+++ b/tests/unit/generation/test_deterministic_templates.py@@ -246,23 +246,90 @@ def test_as_markdown_leaves_plain_text_alone():assert as_markdown(None) == ""-def test_signature_collapses_source_whitespace():- """Signatures span source lines, so raw text carries runs of indentation."""+def test_signature_reads_as_a_declaration_not_as_source():+ """Signatures span source lines, so raw text carries the author's layout."""from repowise.core.generation.page_generator.structural import signatureraw = "def go(\n a: int,\n b: str,\n ) -> None"- assert signature(raw) == "def go( a: int, b: str, ) -> None"+ assert signature(raw) == "def go(a: int, b: str) -> None"-def test_signature_truncates_at_an_argument_boundary_not_mid_token():+def test_signature_closes_a_capture_that_stopped_mid_expression():+ """A constant whose value opens a bracket is stored without its tail.++ Closed rather than cut back to the declaration: the page is also the index+ entry, so ``= re.compile(`` must not take ``re`` and ``compile`` with it.+ """+ from repowise.core.generation.page_generator.structural import signature++ assert signature("PRUNED_DIRS: frozenset[str] = frozenset(") == (+ "PRUNED_DIRS: frozenset[str] = frozenset(…)"+ )+ assert signature("ReasoningMode = Literal[") == "ReasoningMode = Literal[…]"+ assert signature("ROW_ACTIVE =") == "ROW_ACTIVE"+ # A value that closes is the declaration's meaning, and is kept.+ assert signature("MAX = 64") == "MAX = 64"+++def test_signature_never_rewrites_a_declaration_that_already_fits():+ """Under the limit, the only change may be the collapsed whitespace.++ Every pass reshapes source punctuation, and a signature routinely carries+ a regex or a path in a string literal. Rewriting inside one puts a value+ on the page that the source does not have, and the page is what the index+ embeds. These are real declarations from this repository.+ """+ from repowise.core.generation.page_generator.structural import signature++ for raw in (+ 'IDENTIFIER_RE = re.compile(rb"[A-Za-z_][A-Za-z0-9_]{2,}")',+ 'filenames: tuple[str, ...] = ("Cargo.toml",)',+ '_SPRING_CTOR_PARAM_RE = re.compile(r"([A-Z]w*)s+w+s*[,)]")',+ 'def _doc_paths(root: Path, *, patterns: tuple[str, ...] = ("*.md",)) -> list[Path]',+ ):+ assert signature(raw) == raw, raw+++def test_signature_reduces_a_parameter_to_its_name_not_to_a_string_it_contained():+ """A default value holding a comma must not split into two parameters."""+ from repowise.core.generation.page_generator.structural import signature++ raw = (+ 'def render(self, template: str, sep: str = ", ", prefix: str = "(", '+ 'suffix: str = ")", indent: int = 4, width: int = 88) -> str'+ )++ assert signature(raw) == "def render(self, template, sep, prefix, suffix, indent, width) -> str"+++def test_signature_does_not_count_a_bracket_inside_a_string_literal():+ """A character class is not an unclosed bracket."""from repowise.core.generation.page_generator.structural import signature- raw = "def go(" + ", ".join(f"argument_number_{i}: int = 0" for i in range(20)) + ") -> None"+ raw = '_META_RE = re.compile(r"[|&;<>]")'+ assert signature(raw) == raw+++def test_signature_sheds_parameter_detail_before_it_sheds_the_return_type():+ from repowise.core.generation.page_generator.structural import signature++ raw = "def go(" + ", ".join(f"argument_number_{i}: int = 0" for i in range(3)) + ") -> None"out = signature(raw, limit=80)- assert out.endswith(" …")- # The visible tail must be a whole parameter, never half an identifier.- assert not out.rstrip(" …").rstrip(",").endswith("argument_number")- assert "argument_number_0: int = 0" in out++ # What a function returns is the half a reader is looking for, so the+ # annotations and defaults go first and the return type survives.+ assert out.endswith(") -> None")+ assert "argument_number_0" in out+ assert "int = 0" not in out+++def test_signature_falls_back_to_an_ellipsis_when_even_the_names_are_too_long():+ from repowise.core.generation.page_generator.structural import signature++ raw = "def go(" + ", ".join(f"argument_number_{i}" for i in range(40)) + ") -> None"+ out = signature(raw, limit=60)++ assert out == "def go(…) -> None"def test_signature_leaves_short_signatures_untouched():diff --git a/tests/unit/generation/test_file_vocabulary.py b/tests/unit/generation/test_file_vocabulary.pyindex 03d1e2eee..64774b651 100644--- a/tests/unit/generation/test_file_vocabulary.py+++ b/tests/unit/generation/test_file_vocabulary.py@@ -31,11 +31,7 @@ from sqlalchemy.pool import StaticPoolfrom repowise.core.generation.context.file_vocabulary import file_vocabularyfrom repowise.core.generation.context_assembler import FilePageContext-from repowise.core.generation.page_generator.structural import (- as_markdown,- oneline,- signature,-)+from repowise.core.generation.page_generator.structural import register_filtersfrom repowise.core.generation.structural_labels import resolve_structural_labelsfrom repowise.core.persistence.crud import upsert_page, upsert_repositoryfrom repowise.core.persistence.database import init_db@@ -178,9 +174,7 @@ def jinja_env() -> jinja2.Environment:undefined=jinja2.StrictUndefined,autoescape=False,)- env.filters.setdefault("oneline", oneline)- env.filters.setdefault("as_markdown", as_markdown)- env.filters.setdefault("signature", signature)+ register_filters(env)env.globals["labels"] = resolve_structural_labels(None)return envdiff --git a/tests/unit/generation/test_kg_aware_file_pages.py b/tests/unit/generation/test_kg_aware_file_pages.pyindex e3ea8634e..fd2451124 100644--- a/tests/unit/generation/test_kg_aware_file_pages.py+++ b/tests/unit/generation/test_kg_aware_file_pages.py@@ -306,11 +306,7 @@ class TestFilePageTemplate:from jinja2 import Environment, FileSystemLoader- from repowise.core.generation.page_generator.structural import (- as_markdown,- oneline,- signature,- )+ from repowise.core.generation.page_generator.structural import register_filtersfrom repowise.core.generation.structural_labels import resolve_structural_labelstemplate_dir = (@@ -326,9 +322,7 @@ class TestFilePageTemplate:env = Environment(loader=FileSystemLoader(str(template_dir)))# Mirror the production environment, which registers these in# PageGenerator.__init__. Without them the templates fail to compile.- env.filters["oneline"] = oneline- env.filters["as_markdown"] = as_markdown- env.filters["signature"] = signature+ register_filters(env)env.globals["labels"] = resolve_structural_labels(None)return env@@ -356,7 +350,8 @@ class TestFilePageTemplate:)rendered = tmpl.render(ctx=ctx)assert "**Layer:** Core Pipeline" in rendered- assert "**Role:** internal" in rendered+ # The stored value is an enum member; the page spells it for a reader.+ assert "**Role:** internal to its layer" in rendereddef test_file_page_without_kg(self, jinja_env):tmpl = jinja_env.get_template("file_page.j2")diff --git a/tests/unit/generation/test_question_text_reaches_search.py b/tests/unit/generation/test_question_text_reaches_search.pyindex d456b7d37..cbc5f98b3 100644--- a/tests/unit/generation/test_question_text_reaches_search.py+++ b/tests/unit/generation/test_question_text_reaches_search.py@@ -22,11 +22,7 @@ from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_enginefrom sqlalchemy.pool import StaticPoolfrom repowise.core.generation.context_assembler import FilePageContext, SymbolSpotlightContext-from repowise.core.generation.page_generator.structural import (- as_markdown,- oneline,- signature,-)+from repowise.core.generation.page_generator.structural import register_filtersfrom repowise.core.generation.structural_labels import resolve_structural_labelsfrom repowise.core.persistence.crud import upsert_page, upsert_repositoryfrom repowise.core.persistence.database import init_db@@ -52,9 +48,7 @@ def jinja_env() -> jinja2.Environment:undefined=jinja2.StrictUndefined,autoescape=False,)- env.filters.setdefault("oneline", oneline)- env.filters.setdefault("as_markdown", as_markdown)- env.filters.setdefault("signature", signature)+ register_filters(env)env.globals["labels"] = resolve_structural_labels(None)return envdiff --git a/tests/unit/generation/test_structural_pages_read_like_a_wiki.py b/tests/unit/generation/test_structural_pages_read_like_a_wiki.pynew file mode 100644index 000000000..6d2ba53d0--- /dev/null+++ b/tests/unit/generation/test_structural_pages_read_like_a_wiki.py@@ -0,0 +1,532 @@+"""What the deterministic pages say now that they render what they were given.++``FilePageContext`` has carried git history, co-change partners and decision+records since long before this suite; ``file_page.j2`` rendered none of them,+and a page of twenty-five import paths was the result. These tests pin what a+page says when it has something to say, that it says nothing when it does not,+and — the constraint that shapes all of it — that nothing a reader stops+seeing has left ``content``, which is the same string FTS indexes, the vector+store embeds and ``get_context`` returns verbatim.++Everything here renders the real template. A page's markdown is not something+to type out and compare against: Jinja whitespace control decides where the+newlines land, and a hand-written expectation agreed with a renderer that was+emitting different bytes once already.+"""++from __future__ import annotations++import re+from pathlib import Path++import pytest++from repowise.core.generation.context_assembler import (+ ContextAssembler,+ FilePageContext,+ SymbolSpotlightContext,+)+from repowise.core.generation.models import GenerationConfig+from repowise.core.generation.page_generator import PageGenerator+from repowise.core.providers.llm.template import TemplateProvider++REPO_ROOT = Path(__file__).resolve().parents[3]+READER_PERSONA_TS = REPO_ROOT / "packages" / "ui" / "src" / "docs" / "reader-persona.ts"+++def generator() -> PageGenerator:+ config = GenerationConfig(deterministic=True)+ return PageGenerator(TemplateProvider(), ContextAssembler(config), config)+++def _symbol(name: str, kind: str = "function", **over) -> dict:+ return {+ "name": name,+ "qualified_name": f"pkg.mod.{name}",+ "kind": kind,+ "signature": over.pop("signature", f"def {name}() -> None"),+ "docstring": None,+ "visibility": over.pop("visibility", "public"),+ "is_async": False,+ "complexity_estimate": 1,+ "decorators": [],+ "parent_name": over.pop("parent_name", None),+ "start_line": 1,+ "end_line": 2,+ }+++def _context(**over) -> FilePageContext:+ base = dict(+ file_path="pkg/mod/walk.py",+ language="python",+ docstring="Walks a repository tree.",+ symbols=[_symbol("walk_repo")],+ imports=[],+ exports=[],+ pagerank_score=0.1,+ betweenness_score=0.0,+ community_id=0,+ dependents=[],+ dependencies=[],+ is_api_contract=False,+ is_entry_point=False,+ is_test=False,+ parse_errors=[],+ estimated_tokens=0,+ )+ base.update(over)+ return FilePageContext(**base)+++def render(generator: PageGenerator, ctx: FilePageContext) -> str:+ return generator._render("file_page.j2", style_prefix=False, ctx=ctx)+++GIT = {+ "commit_count_total": 27,+ "commit_count_90d": 9,+ "last_commit_at": "2026-08-17 05:38:14.000000",+ "primary_owner_name": "Ada Lovelace",+ "primary_owner_commit_pct": 0.62,+ "prior_defect_count": 12,+ "is_hotspot": True,+}+++# ---------------------------------------------------------------------------+# History+# ---------------------------------------------------------------------------+++class TestHistory:+ def test_it_says_what_the_git_history_knows(self, generator):+ page = render(generator, _context(git_metadata=GIT))++ assert "## History" in page+ assert "27 commits in its history, 9 in the last 90 days." in page+ assert "Ada Lovelace" in page+ assert "62%" in page+ assert "12 of those commits fixed a bug." in page+ assert "change hotspots" in page++ def test_the_date_is_absolute_so_the_page_does_not_move_on_its_own(self, generator):+ # The rendered bytes are this page's reuse key. "three days ago" would+ # restate every page in the wiki every day.+ page = render(generator, _context(git_metadata=GIT))++ assert "2026-08-17" in page+ assert "05:38:14" not in page++ def test_a_repository_with_no_history_renders_no_heading(self, generator):+ assert "## History" not in render(generator, _context())+ assert "## History" not in render(generator, _context(git_metadata={}))++ def test_a_fix_count_that_outruns_the_commit_log_is_left_out(self, generator):+ # The two are counted over different windows, so a file whose fixes+ # outnumber its own commits has been moved and the fixes belong to a+ # path this page no longer describes.+ page = render(+ generator,+ _context(git_metadata={"commit_count_total": 1, "prior_defect_count": 2}),+ )++ assert "## History" in page+ assert "fixed a bug" not in page++ def test_one_commit_is_not_described_in_the_plural(self, generator):+ page = render(generator, _context(git_metadata={"commit_count_total": 1}))++ assert "1 commit in its history" in page+++class TestChangesTogetherWith:+ def test_it_names_the_partner_and_how_often(self, generator):+ page = render(+ generator,+ _context(+ co_change_pages=[+ {"path": "pkg/mod/persist.py", "commits": 28, "last": "2026-08-29"}+ ]+ ),+ )++ assert "## Changes together with" in page+ assert "`pkg/mod/persist.py`" in page+ assert "28 shared commits" in page+ assert "2026-08-29" in page++ def test_no_partners_renders_no_heading(self, generator):+ assert "## Changes together with" not in render(generator, _context())+++class TestDecisions:+ def test_it_carries_the_decision_and_the_reason_for_it(self, generator):+ page = render(+ generator,+ _context(+ decision_records=[+ {+ "title": "Prune at traversal time",+ "decision": "Directories are pruned in `dirnames[:]`, never post-hoc.",+ "rationale": "An unpruned walk over vendored repos took minutes.",+ "source": "inline",+ "confidence": 0.9,+ "evidence_file": "pkg/mod/walk.py",+ }+ ]+ ),+ )++ assert "## Decisions touching this file" in page+ assert "Prune at traversal time" in page+ assert "never post-hoc" in page+ assert "took minutes" in page++ def test_no_decisions_renders_no_heading(self, generator):+ assert "## Decisions touching this file" not in render(generator, _context())+++# ---------------------------------------------------------------------------+# Public API+# ---------------------------------------------------------------------------+++class TestPublicApi:+ def test_module_bookkeeping_is_not_listed_as_api(self, generator):+ ctx = _context(+ symbols=[+ _symbol("log", "variable", signature="log = structlog.get_logger(__name__)"),+ _symbol("__all__", "variable", signature='__all__ = ["walk_repo"]'),+ _symbol("__init__", "method", parent_name="WalkSnapshot"),+ _symbol("walk_repo"),+ _symbol("SourceFile", "variable", signature="SourceFile = tuple[str, str]"),+ ]+ )+ table = render(generator, ctx).split("## Public API", 1)[1].split("Also defined", 1)[0]++ assert "`walk_repo`" in table+ # A capitalised module-level variable is a type alias, not module state.+ assert "`SourceFile`" in table+ for demoted in ("`log`", "`__all__`", "`__init__`"):+ assert demoted not in table++ def test_a_demoted_name_is_still_spelled_on_the_page(self, generator):+ # ``content`` is the index entry as well as the page. A name the table+ # stops carrying must not stop being findable.+ ctx = _context(+ symbols=[+ _symbol("log", "variable", signature="log = structlog.get_logger(__name__)"),+ _symbol("walk_repo"),+ ]+ )+ page = render(generator, ctx)++ # The signature, not the bare name: ``log`` alone would take+ # ``structlog``, ``get_logger`` and ``__name__`` off the page, and the+ # page is the index entry.+ assert "Also defined: `log = structlog.get_logger(__name__)`." in page++ def test_a_file_that_declares_only_bookkeeping_still_names_it(self, generator):+ ctx = _context(+ symbols=[_symbol("__all__", "variable", signature='__all__ = ["walk_repo"]')]+ )+ page = render(generator, ctx)++ assert "## Public API" in page+ assert '`__all__ = ["walk_repo"]`' in page++ def test_the_signature_column_reads_as_a_declaration(self, generator):+ ctx = _context(+ symbols=[+ _symbol(+ "walk_repo",+ signature=(+ "def walk_repo(\n root: Path | str,\n *,\n"+ " prune_dirs: frozenset[str] = PRUNED_DIRS,\n"+ " prune_nested_git: bool = True,\n"+ " max_depth: int = 64,\n"+ ") -> Iterator[tuple[Path, list[str], list[str]]]"+ ),+ )+ ]+ )+ row = next(ln for ln in render(generator, ctx).splitlines() if ln.startswith("| `walk_repo`"))++ assert "( root" not in row+ assert row.rstrip(" |").endswith("-> Iterator[tuple[Path, list[str], list[str]]]")+++# ---------------------------------------------------------------------------+# Dependency lists and the layer role+# ---------------------------------------------------------------------------+++DEPS = [+ "pkg/resolvers/go.py",+ "pkg/resolvers/ruby.py",+ "pkg/resolvers/swift.py",+ "pkg/pipeline/run.py",+]+++class TestDependencyGrouping:++ def test_paths_are_grouped_by_directory_busiest_first(self, generator):+ section = render(generator, _context(dependencies=DEPS)).split("## Depends on", 1)[1]+ headings = [ln for ln in section.splitlines() if ln.startswith("**`")]++ assert headings[:2] == ["**`pkg/resolvers`**", "**`pkg/pipeline`**"]++ def test_every_path_is_still_printed_whole(self, generator):+ page = render(generator, _context(dependencies=DEPS, dependents=DEPS))++ for path in DEPS:+ assert f"- `{path}`" in page++ def test_grouping_leaves_no_gap_between_sections(self, generator):+ page = render(+ generator,+ _context(dependencies=DEPS, dependents=DEPS, git_metadata=GIT),+ )++ assert "\n\n\n" not in page+++class TestLayerRole:+ @pytest.mark.parametrize(+ "role,expected",+ [+ ("edge_connector", "boundary"),+ ("entry_point", "entry point"),+ ("internal", "internal to its layer"),+ ],+ )+ def test_the_role_is_spelled_for_a_reader(self, generator, role, expected):+ page = render(generator, _context(kg_layer_name="Core Pipeline", kg_layer_role=role))++ assert expected in page+ assert "edge_connector" not in page+++class TestOverview:+ def test_a_file_with_no_docstring_borrows_the_graph_summary(self, generator):+ page = render(+ generator,+ _context(docstring=None, kg_node_summary="Prunes junk directories during a walk."),+ )++ assert "Prunes junk directories during a walk." in page+ # The structural sentence still follows it: it is what names the+ # language and the layer.+ assert "is a python source file" in page++ def test_a_docstring_still_wins(self, generator):+ page = render(generator, _context(kg_node_summary="Machine summary."))++ assert "Walks a repository tree." in page+ assert "Machine summary." not in page+++# ---------------------------------------------------------------------------+# The constraint: nothing leaves ``content``+# ---------------------------------------------------------------------------+++def test_no_identifier_the_context_carried_leaves_the_page(generator):+ """The page is the index entry, so a dropped identifier is a lost query.++ Pinned against the context rather than against a stored copy of the old+ markdown: an expectation derived from the inputs keeps failing for the+ right reason after the next template edit, where a golden file would only+ say that the bytes moved.+ """+ ctx = _context(+ docstring=None,+ kg_node_summary="Prunes junk directories during a walk.",+ symbols=[+ _symbol("walk_repo"),+ _symbol("log", "variable", signature="log = structlog.get_logger(__name__)"),+ _symbol("__all__", "variable"),+ _symbol("__init__", "method", parent_name="WalkSnapshot"),+ ],+ dependencies=["pkg/resolvers/go.py", "pkg/pipeline/run.py"],+ dependents=["pkg/cli/main.py"],+ git_metadata=GIT,+ co_change_pages=[{"path": "pkg/mod/persist.py", "commits": 28, "last": "2026-08-29"}],+ decision_records=[+ {+ "title": "Prune at traversal time",+ "decision": "Pruned in `dirnames[:]`.",+ "rationale": "",+ "source": "inline",+ "confidence": 0.9,+ "evidence_file": "pkg/mod/walk.py",+ }+ ],+ kg_layer_name="Core Pipeline",+ kg_layer_role="edge_connector",+ file_vocabulary="prune_dirs max_depth node_modules",+ )+ page = render(generator, ctx)++ expected = (+ {ctx.file_path}+ | set(ctx.dependencies)+ | set(ctx.dependents)+ | {s["name"] for s in ctx.symbols}+ | {cc["path"] for cc in ctx.co_change_pages}+ | set(ctx.file_vocabulary.split())+ )+ missing = sorted(name for name in expected if name not in page)++ assert not missing, missing+++def test_the_page_says_nothing_it_was_not_given(generator):+ """Every section below the Overview is conditional, so a bare context+ renders a page with no empty headings on it."""+ page = render(generator, _context(docstring=None, symbols=[]))++ for heading in (+ "## History",+ "## Changes together with",+ "## Decisions touching this file",+ "## Public API",+ "## Depends on",+ "## Used by",+ "## Usage Notes",+ ):+ assert heading not in page+++# ---------------------------------------------------------------------------+# The reader lens+# ---------------------------------------------------------------------------+++def _contributor_hide(source: str) -> set[str]:+ """The heading keywords the default reader persona drops."""+ body = source.split("const CONTRIBUTOR_HIDE", 1)[1].split("]", 1)[0]+ return set(re.findall(r'"([^"]+)"', body))+++def test_the_scaffolding_headings_are_the_ones_the_reader_lens_hides(generator):+ """The template and ``reader-persona.ts`` have to agree, byte for byte.++ ``## In the code`` and ``## Questions this page answers`` exist for+ retrieval: the vocabulary bag is the only part of the page written in the+ words a question uses, and the question block is the only part shaped like+ one. Neither can be dropped here without dropping it from the index, so+ the reader persona hides them client-side instead — and it matches on the+ heading text, lowercased, which is a string in another language's source+ file. The headings come out of a real render for that reason.+ """+ ctx = _context(+ dependents=["pkg/cli/main.py"],+ file_vocabulary="prune_dirs max_depth",+ )+ page = render(generator, ctx)+ rendered = {ln[3:].strip().lower() for ln in page.splitlines() if ln.startswith("## ")}+ assert {"in the code", "questions this page answers"} <= rendered++ hidden = _contributor_hide(READER_PERSONA_TS.read_text(encoding="utf-8"))++ assert {"in the code", "questions this page answers"} <= hidden+++# ---------------------------------------------------------------------------+# Symbol spotlight+# ---------------------------------------------------------------------------+++def _spotlight(**over) -> SymbolSpotlightContext:+ base = dict(+ symbol_name="PRUNED_DIRS",+ qualified_name="pkg.mod.walk.PRUNED_DIRS",+ kind="constant",+ signature="PRUNED_DIRS: frozenset[str]",+ docstring=None,+ file_path="pkg/mod/walk.py",+ decorators=[],+ is_async=False,+ complexity_estimate=0,+ callers=[],+ )+ base.update(over)+ return SymbolSpotlightContext(**base)+++class TestSymbolSpotlight:+ def test_the_title_is_the_symbol_not_a_dotted_path_of_directories(self, generator):+ page = generator._structural_symbol_spotlight(+ _spotlight(), "pkg/mod/walk.py::PRUNED_DIRS", "Symbol: pkg/mod/walk.py::PRUNED_DIRS"+ )++ assert page.content.startswith("# PRUNED_DIRS\n")+ # The file is on the line under it, which is where a reader looks.+ assert "`pkg/mod/walk.py`" in page.content+ # And the dotted name stays on the page, because it is an identifier+ # the index carries.+ assert "pkg.mod.walk.PRUNED_DIRS" in page.content++ def test_a_resolved_call_is_reported_as_a_call(self, generator):+ page = generator._structural_symbol_spotlight(+ _spotlight(+ callers=["pkg/cli/main.py"],+ call_sites=[{"caller": "walk_repo", "caller_file": "pkg/mod/walk.py"}],+ ),+ "pkg/mod/walk.py::PRUNED_DIRS",+ "Symbol: pkg/mod/walk.py::PRUNED_DIRS",+ )++ used = page.content.split("## Where it is used", 1)[1].split("\n## ", 1)[0]+ assert "Reached by 1 resolved call." in used+ assert "`walk_repo`" in used+ assert "not confirmed call sites" not in used+ assert "What calls `PRUNED_DIRS`?" in page.content++ def test_the_importers_move_under_a_heading_the_reader_lens_hides(self, generator):+ # They are the fifteen thousand file paths this change would otherwise+ # take out of the index, so they stay on the page and leave the view.+ page = generator._structural_symbol_spotlight(+ _spotlight(+ callers=["pkg/cli/main.py"],+ call_sites=[{"caller": "walk_repo", "caller_file": "pkg/mod/walk.py"}],+ ),+ "pkg/mod/walk.py::PRUNED_DIRS",+ "Symbol: pkg/mod/walk.py::PRUNED_DIRS",+ )++ assert "## Files importing this module" in page.content+ importers = page.content.split("## Files importing this module", 1)[1]+ assert "`pkg/cli/main.py`" in importers++ source = READER_PERSONA_TS.read_text(encoding="utf-8")+ hidden = _contributor_hide(source)+ assert "files importing this module" in hidden++ def test_the_count_is_the_real_total_not_the_printed_one(self, generator):+ page = generator._structural_symbol_spotlight(+ _spotlight(+ call_sites=[+ {"caller": f"caller_{i}", "caller_file": f"pkg/c{i}.py"} for i in range(30)+ ]+ ),+ "pkg/mod/walk.py::PRUNED_DIRS",+ "Symbol: pkg/mod/walk.py::PRUNED_DIRS",+ )++ assert "Reached by 30 resolved calls." in page.content+ assert "and 5 more." in page.content++ def test_an_unresolved_symbol_keeps_the_honest_import_wording(self, generator):+ page = generator._structural_symbol_spotlight(+ _spotlight(callers=["pkg/cli/main.py"]),+ "pkg/mod/walk.py::PRUNED_DIRS",+ "Symbol: pkg/mod/walk.py::PRUNED_DIRS",+ )++ assert "not confirmed call sites" in page.content+ assert "`pkg/cli/main.py`" in page.contentdiff --git a/tests/unit/generation/test_templates.py b/tests/unit/generation/test_templates.pyindex 7fa759e76..755bcbb8a 100644--- a/tests/unit/generation/test_templates.py+++ b/tests/unit/generation/test_templates.py@@ -19,11 +19,7 @@ from repowise.core.generation.context_assembler import (SymbolSpotlightContext,_TopFile,)-from repowise.core.generation.page_generator.structural import (- as_markdown,- oneline,- signature,-)+from repowise.core.generation.page_generator.structural import register_filtersfrom repowise.core.generation.structural_labels import resolve_structural_labelsfrom repowise.core.ingestion.models import PackageInfo@@ -53,9 +49,7 @@ def jinja_env() -> jinja2.Environment:# The same filters PageGenerator registers. Structural templates render# page content rather than a prompt, so they lean on these to keep# docstrings and signatures inside a table cell or list item.- env.filters.setdefault("oneline", oneline)- env.filters.setdefault("as_markdown", as_markdown)- env.filters.setdefault("signature", signature)+ register_filters(env)env.globals["labels"] = resolve_structural_labels(None)return env