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.

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.py
index 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 depth
depth = 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 metadata
call_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 symbol
source_body = None
if 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 unique
diff --git a/packages/core/src/repowise/core/generation/context/contexts.py b/packages/core/src/repowise/core/generation/context/contexts.py
index 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: bool
complexity_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)
@dataclass
diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.py
index 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 PerTypeGenerationMixin
from .prompts import CORRECTIVE_RETRY_DIRECTIVE, SUPPORTED_LANGUAGES, SYSTEM_PROMPTS
from .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 of
diff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.py
index 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.py
index 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.py
index 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.j2
index 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 own
symbols, 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 nothing
under 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 results
and 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 whose
answer 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 the
page 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.j2
index 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 the
summary 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.ts
new file mode 100644
index 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.ts
index 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.py
index 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 signature
raw = "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.py
index 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 StaticPool
from repowise.core.generation.context.file_vocabulary import file_vocabulary
from 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_filters
from repowise.core.generation.structural_labels import resolve_structural_labels
from repowise.core.persistence.crud import upsert_page, upsert_repository
from 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 env
diff --git a/tests/unit/generation/test_kg_aware_file_pages.py b/tests/unit/generation/test_kg_aware_file_pages.py
index 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_filters
from repowise.core.generation.structural_labels import resolve_structural_labels
template_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 rendered
def 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.py
index 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_engine
from sqlalchemy.pool import StaticPool
from 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_filters
from repowise.core.generation.structural_labels import resolve_structural_labels
from repowise.core.persistence.crud import upsert_page, upsert_repository
from 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 env
diff --git a/tests/unit/generation/test_structural_pages_read_like_a_wiki.py b/tests/unit/generation/test_structural_pages_read_like_a_wiki.py
new file mode 100644
index 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.content
diff --git a/tests/unit/generation/test_templates.py b/tests/unit/generation/test_templates.py
index 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_filters
from repowise.core.generation.structural_labels import resolve_structural_labels
from 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