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(generation): concept pages read as subsystem docs, plus parent-dir overviews (#1043)

Raghav Chamadiya77bbb2ce4bca
diff --git a/packages/core/src/repowise/core/generation/context/assembler.py b/packages/core/src/repowise/core/generation/context/assembler.py
index 7fe968368..467da80fa 100644
--- a/packages/core/src/repowise/core/generation/context/assembler.py
+++ b/packages/core/src/repowise/core/generation/context/assembler.py
@@ -290,6 +290,9 @@ class ContextAssembler:
external_systems: list[dict] | None = None,
community_label: str | None = None,
community_cohesion: float | None = None,
+ scope: str = "",
+ is_rollup: bool = False,
+ child_pages: list[dict] | None = None,
) -> ModulePageContext:
"""Assemble context for the module_page template."""
total_symbols = sum(len(fc.symbols) for fc in file_contexts)
@@ -380,6 +383,19 @@ class ContextAssembler:
{parent for f in files if (parent := str(PurePosixPath(f).parent)) != "."}
)
+ # Git-derived subsystem health, aggregated over the member files. These
+ # are what a reader cannot get from the code alone, and they degrade to
+ # nothing when a repository has no git history rather than inventing a
+ # number. Reuses the same per-file fields the repo overview reads.
+ (
+ hotspot_count,
+ stable_count,
+ single_owner_files,
+ coupled_modules,
+ bugfix_total,
+ most_fixed_file,
+ ) = self._module_git_enrichment(files, set(files), git_meta_map)
+
return ModulePageContext(
title=title,
directories=directories,
@@ -400,6 +416,85 @@ class ContextAssembler:
external_systems=external_systems or [],
key_files=key_files,
top_owners=top_owners,
+ scope=scope,
+ is_rollup=is_rollup,
+ child_pages=child_pages or [],
+ hotspot_count=hotspot_count,
+ stable_count=stable_count,
+ single_owner_files=single_owner_files,
+ coupled_modules=coupled_modules,
+ bugfix_total=bugfix_total,
+ most_fixed_file=most_fixed_file,
+ )
+
+ @staticmethod
+ def _module_git_enrichment(
+ files: list[str],
+ member_set: set[str],
+ git_meta_map: dict[str, dict] | None,
+ ) -> tuple[int, int, int, list[dict], int, dict]:
+ """Aggregate the git signals a subsystem page can carry over its members.
+
+ Returns ``(hotspot_count, stable_count, single_owner_files,
+ coupled_modules, bugfix_total, most_fixed_file)``. Everything is zero or
+ empty when there is no git metadata, so a repository indexed without
+ history renders none of it rather than a fabricated health line.
+ """
+ import json as _json
+ from collections import Counter
+
+ if not git_meta_map:
+ return 0, 0, 0, [], 0, {}
+
+ metas = [git_meta_map[f] for f in files if f in git_meta_map]
+ if not metas:
+ return 0, 0, 0, [], 0, {}
+
+ hotspot_count = sum(1 for m in metas if m.get("is_hotspot"))
+ stable_count = sum(1 for m in metas if m.get("is_stable"))
+ # bus_factor is the number of authors covering the bulk of a file's
+ # history; 1 means one person carries it. 0 is "not computed" and does
+ # not count as a risk.
+ single_owner_files = sum(1 for m in metas if 0 < (m.get("bus_factor") or 0) <= 1)
+
+ # Files this subsystem changes together with in history but that live in
+ # another module. History coupling the import graph never shows.
+ coupled: Counter[str] = Counter()
+ for m in metas:
+ raw = m.get("co_change_partners_json") or "[]"
+ try:
+ partners = _json.loads(raw) if isinstance(raw, str) else raw
+ except Exception:
+ partners = []
+ for p in partners:
+ # Co-change entries are dicts keyed by ``file_path`` (see
+ # git_indexer/co_change.py); tolerate a bare string too.
+ partner_path = (p.get("file_path") or p.get("path")) if isinstance(p, dict) else p
+ if (
+ isinstance(partner_path, str)
+ and partner_path
+ and partner_path not in member_set
+ ):
+ module = partner_path.rsplit("/", 1)[0] if "/" in partner_path else partner_path
+ coupled[module] += 1
+ coupled_modules = [{"path": path, "count": count} for path, count in coupled.most_common(5)]
+
+ bugfix_total = sum(int(m.get("prior_defect_count") or 0) for m in metas)
+ most = max(metas, key=lambda m: int(m.get("prior_defect_count") or 0))
+ most_fixed_file: dict = {}
+ if int(most.get("prior_defect_count") or 0) > 0:
+ most_fixed_file = {
+ "path": most.get("file_path", ""),
+ "fixes": int(most.get("prior_defect_count") or 0),
+ }
+
+ return (
+ hotspot_count,
+ stable_count,
+ single_owner_files,
+ coupled_modules,
+ bugfix_total,
+ most_fixed_file,
)
# ------------------------------------------------------------------
diff --git a/packages/core/src/repowise/core/generation/context/contexts.py b/packages/core/src/repowise/core/generation/context/contexts.py
index edfb9d724..47662b98b 100644
--- a/packages/core/src/repowise/core/generation/context/contexts.py
+++ b/packages/core/src/repowise/core/generation/context/contexts.py
@@ -95,6 +95,31 @@ class ModulePageContext:
dependents: list[str]
pagerank_mean: float
files: list[str]
+ # One sentence saying what this page covers and what it deliberately does
+ # NOT, computed by the outline planner to keep adjacent pages from
+ # describing each other. Rendered as guidance so the opener situates the
+ # page against its siblings; the page itself does not echo it verbatim.
+ scope: str = ""
+ # A rollup page summarises a subsystem directory whose detail lives on the
+ # child concept pages below it, rather than owning files of its own.
+ is_rollup: bool = False
+ # Child concept pages this rollup sits above: [{"title", "path", "summary"}].
+ child_pages: list[dict] = field(default_factory=list)
+ # Git-derived subsystem health, aggregated over the page's member files.
+ # All degrade to zero/empty when no git metadata is available, so the
+ # template renders nothing rather than a wrong number.
+ hotspot_count: int = 0
+ stable_count: int = 0
+ # Files maintained by effectively one person (bus_factor <= 1): a
+ # single-maintainer risk a reader cannot see from the code alone.
+ single_owner_files: int = 0
+ # Other modules this one changes together with in history but does not
+ # import: [{"path", "count"}]. Coupling the import graph does not show.
+ coupled_modules: list[dict] = field(default_factory=list)
+ # Bug-fix history: total fix commits across members and the file that drew
+ # the most, so the page can name where the defects have clustered.
+ bugfix_total: int = 0
+ most_fixed_file: dict = field(default_factory=dict)
# The directories the page covers, shallowest first. The title says what
# the page is about; this says where it lives, which is what a reader
# needs to go and look. Derived from the members rather than passed in, so
diff --git a/packages/core/src/repowise/core/generation/page_generator/levels.py b/packages/core/src/repowise/core/generation/page_generator/levels.py
index 25a7ec625..e6f94ab79 100644
--- a/packages/core/src/repowise/core/generation/page_generator/levels.py
+++ b/packages/core/src/repowise/core/generation/page_generator/levels.py
@@ -196,6 +196,26 @@ def build_level3_coros(run: _GenerationRun) -> list[tuple[str, Any]]:
return coros
+def _rollup_child_pages(rollup: Any, groups: list[Any]) -> list[dict]:
+ """The pages a rollup links down to: its *immediate* children only.
+
+ A page is an immediate child when the rollup's key is exactly the parent
+ directory of the page's key. Immediate rather than recursive so a nested
+ overview links to the next level down (a sub-overview or a leaf), not to
+ every descendant leaf — otherwise ``a/b`` and ``a/b/c`` would both list the
+ same leaves under ``a/b/c``. A sub-rollup is a legitimate child and is kept;
+ the rollup itself is excluded. Titles are read after naming, so they match
+ what the tree shows.
+ """
+ children = [
+ g
+ for g in groups
+ if g.key != rollup.key and "/" in g.key and g.key.rsplit("/", 1)[0] == rollup.key
+ ]
+ children.sort(key=lambda g: g.key)
+ return [{"title": g.display, "path": g.key} for g in children]
+
+
def build_level4_coros(run: _GenerationRun) -> list[tuple[str, Any]]:
"""Level 4 (module_page), allow-set filtered."""
gen = run.gen
@@ -238,6 +258,14 @@ def build_level4_coros(run: _GenerationRun) -> list[tuple[str, Any]]:
members=list(mg.file_paths),
section=mg.section,
order=mg.order,
+ scope=getattr(mg, "scope", ""),
+ is_rollup=getattr(mg, "is_rollup", False),
+ child_pages=(
+ _rollup_child_pages(mg, run.sel_module_groups)
+ if getattr(mg, "is_rollup", False)
+ else None
+ ),
+ owns_files=not getattr(mg, "is_rollup", False),
),
)
)
diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
index cd93a785b..bb3a0e8ae 100644
--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
@@ -360,12 +360,14 @@ class _GenerationRun:
title_of: dict[str, str] = {}
section_of: dict[str, str] = {}
order_of: dict[str, int] = {}
+ scope_of: dict[str, str] = {}
position = 0
for section in outline.sections:
for page in section.pages:
title_of[page.structural_key] = page.title
section_of[page.structural_key] = section.title
order_of[page.structural_key] = position
+ scope_of[page.structural_key] = page.scope
position += 1
from dataclasses import replace as _replace
@@ -387,6 +389,7 @@ class _GenerationRun:
display=title,
section=section_of.get(mg.structural_key, ""),
order=order_of.get(mg.structural_key, 0),
+ scope=scope_of.get(mg.structural_key, mg.scope),
)
)
# Generation order is left alone: it is summed PageRank, so the most
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 b92339af4..01d50d9e7 100644
--- a/packages/core/src/repowise/core/generation/page_generator/pertype.py
+++ b/packages/core/src/repowise/core/generation/page_generator/pertype.py
@@ -88,6 +88,10 @@ class PerTypeGenerationMixin:
members: list[str] | None = None,
section: str = "",
order: int = 0,
+ scope: str = "",
+ is_rollup: bool = False,
+ child_pages: list[dict] | None = None,
+ owns_files: bool = True,
) -> GeneratedPage:
ctx = self._assembler.assemble_module_page(
title,
@@ -101,6 +105,9 @@ class PerTypeGenerationMixin:
external_systems=external_systems,
community_label=community_label,
community_cohesion=community_cohesion,
+ scope=scope,
+ is_rollup=is_rollup,
+ child_pages=child_pages,
)
module_git_summary = None
if git_meta_map:
@@ -141,7 +148,15 @@ class PerTypeGenerationMixin:
# group. Placement resolves file ownership from this list, so the
# dropped files would be parented somewhere else entirely, and the two
# records of what the page covers would disagree.
- covered = sorted(members) if members else sorted(fc.file_path for fc in file_contexts)
+ # A rollup page sits above its child concept pages and owns no files of
+ # its own: its members already belong to the leaves below it, so
+ # claiming them here would parent those files twice and scramble the
+ # tree. It keeps an empty member list, which is exactly what
+ # ``assign_page_tree`` reads as "owns nothing".
+ if owns_files:
+ covered = sorted(members) if members else sorted(fc.file_path for fc in file_contexts)
+ else:
+ covered = []
def _stamp_concept(page: GeneratedPage) -> GeneratedPage:
"""Record where the namer put this page in the reading order.
diff --git a/packages/core/src/repowise/core/generation/page_generator/prompts.py b/packages/core/src/repowise/core/generation/page_generator/prompts.py
index e16505fa6..010e3e9c1 100644
--- a/packages/core/src/repowise/core/generation/page_generator/prompts.py
+++ b/packages/core/src/repowise/core/generation/page_generator/prompts.py
@@ -22,18 +22,39 @@ from ..languages import SUPPORTED_LANGUAGES # noqa: F401
SYSTEM_PROMPTS: dict[str, str] = {
"module_page": (
"You are repowise, an expert technical documentation generator. "
- "Write a module-level overview page summarising all files in the module. "
+ "Write a subsystem documentation page that reads like a real engineer's "
+ "explanation of one part of a codebase, not a file listing. "
"Output markdown only. "
"\n"
- "CRITICAL — lead-with-role rule: the FIRST sentence under ## Overview must "
- "state the module's job in the larger system. Use architectural vocabulary "
- "(ingestion subsystem, generation pipeline, persistence layer, transport "
- "adapter, etc.) and name the inputs it consumes and the outputs it produces. "
- "Bad: 'The X module contains 15 files responsible for...' "
- "Good: 'The ingestion module is the entry stage of repowise's indexing "
- "pipeline — it traverses a repository, parses files into ASTs, extracts "
- "symbols, and yields ParsedFile objects for downstream analysis.' "
- "Required sections: ## Overview, ## Public API Summary, ## Architecture Notes."
+ "FORM: Open with one or two paragraphs that state the subsystem's job in "
+ "the larger system and situate it against its neighbours (what it does and, "
+ "using the supplied scope line, what it deliberately leaves to other pages). "
+ "Lead the first sentence with the role, in architectural vocabulary (entry "
+ "stage, orchestration layer, persistence boundary, transport adapter, and so "
+ "on), naming the inputs it consumes and the outputs it produces. "
+ "Bad: 'The X module contains 15 files responsible for...'. "
+ "Good: 'The ingestion layer is the entry stage of the indexing pipeline: it "
+ "traverses a repository, parses files into ASTs, and yields structured "
+ "records for downstream analysis.' "
+ "\n"
+ "Choose H2/H3 headings that name THIS subsystem's actual concerns rather "
+ "than any fixed template. Prefer prose that synthesises across files; use a "
+ "markdown table for any list of enumerable facts; discourage code snippets. "
+ "Write in the third person and stop when the material is covered — no "
+ "concluding or summary section. "
+ "\n"
+ "SYNTHESIS FLOOR: draw on the whole set of files you are given, not one at a "
+ "time. A page that walks through files one by one has failed even if every "
+ "sentence is true. Synthesise. "
+ "\n"
+ "REQUIRED SECTION: end the page with a section '## Questions this page "
+ "answers' listing 3 to 6 questions a developer or agent would ask that this "
+ "page answers, phrased the way they would actually be asked (for example "
+ "'How is the dependency graph built?' or 'Where do I add a new X?'). This "
+ "section is mandatory. "
+ "\n"
+ "Ground every claim in the supplied material: do not invent files, symbols, "
+ "or rationale that are not listed. Draw on the whole file set, not one file."
),
"repo_overview": (
"You are repowise, an expert technical documentation generator. "
diff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.py
index b5377f95a..c011f2c94 100644
--- a/packages/core/src/repowise/core/generation/selection/selector.py
+++ b/packages/core/src/repowise/core/generation/selection/selector.py
@@ -18,8 +18,13 @@ import structlog
from repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY
from ..concept_tree.grouping import ConceptGroup, group_files
-from ..concept_tree.naming import deterministic_title, disambiguate_titles
-from ..models import scc_page_slug
+from ..concept_tree.naming import (
+ _humanise,
+ deterministic_scope,
+ deterministic_title,
+ disambiguate_titles,
+)
+from ..models import member_structural_key, scc_page_slug
from .scoring import (
score_api_contract,
score_file,
@@ -76,6 +81,14 @@ class ModuleGroup:
#: re-run that re-sections the wiki renumbers it and mints nothing.
section: str = ""
order: int = 0
+ #: One sentence saying what the page covers and what it does not, from the
+ #: outline planner. Threaded to the renderer so the opener can situate the
+ #: page against its siblings. Empty on the deterministic path until named.
+ scope: str = ""
+ #: A rollup page overviews a subsystem directory whose detail lives on the
+ #: child concept pages below it. It carries its members only for context and
+ #: owns none of them, so the leaves keep their files.
+ is_rollup: bool = False
@dataclass
@@ -406,13 +419,122 @@ def _build_module_groups(inputs: SelectionInputs) -> ConceptCandidates:
label=None,
cohesion=None,
structural_key=group.structural_key,
+ # Filled here so the deterministic path carries a scope
+ # sentence; the naming call overwrites it with a written one
+ # when a provider is present.
+ scope=deterministic_scope(group),
),
)
)
+ scored.extend(_build_rollup_groups(groups, files, lang_of, inputs.pagerank))
scored.sort(key=lambda x: (-x[0], x[1].key))
return ConceptCandidates(scored=scored, groups=groups, layer_labels=layer_labels)
+# A rollup covering more than this fraction of the whole repository is not a
+# subsystem overview, it is the repository overview under another name — that
+# page already exists, so the rollup is skipped rather than made to compete with
+# it. Applies to the near-root case in a monorepo where everything lives under a
+# single top-level directory ("packages/", "src/").
+_ROLLUP_MAX_MEMBER_FRACTION = 0.5
+
+
+def _build_rollup_groups(
+ groups: list[ConceptGroup],
+ files: list[str],
+ lang_of: dict[str, str],
+ pagerank: dict[str, float],
+) -> list[tuple[float, ModuleGroup]]:
+ """Emit one overview page per parent directory that owns several concept pages.
+
+ The partition splits a large subsystem into path-local leaves, so a
+ directory such as ``.../ingestion`` gets no page of its own — only its
+ children do. A reader asking "what is the ingestion subsystem" then lands on
+ a file, not the subsystem, and a directory-level retrieval query has nothing
+ to match against, because directory-level retrieval matches a page to a
+ directory by exact ``target_path`` equality. This adds a page whose
+ ``target_path`` is exactly that parent directory: an overview that names its
+ child pages and links down to them from its body.
+
+ The rule is purely structural and repo-agnostic: a parent is eligible when at
+ least two leaf concept pages are its *immediate* children and no leaf already
+ claims that directory. With leaves at mixed depths several ancestor levels can
+ each qualify, so two guards keep the set sane: a parent covering more than
+ ``_ROLLUP_MAX_MEMBER_FRACTION`` of the repository is left to the repository
+ overview, and colliding titles are disambiguated the same way leaf titles are.
+
+ A rollup carries its subsystem's files only so the renderer has real material
+ to summarise; it owns none of them (``is_rollup`` → empty ``file_paths``), so
+ the leaves below keep their files and nothing is documented twice. In the nav
+ tree it currently sits alongside its children under their shared layer rather
+ than nesting them; the body still links down via ``child_pages``. True tree
+ nesting is a deferred nicety, not a correctness requirement.
+
+ All paths here are POSIX-normalised upstream (the grouper lowercases
+ separators), so the ``/`` splits below are safe.
+ """
+ total = len(files)
+ leaf_targets = {g.target_path for g in groups}
+ direct_children: dict[str, list[ConceptGroup]] = {}
+ for g in groups:
+ tp = g.target_path
+ if "/" not in tp:
+ continue
+ parent = tp.rsplit("/", 1)[0]
+ direct_children.setdefault(parent, []).append(g)
+
+ # First pass: which parents qualify, and over what members. Titles are
+ # computed in a second pass so they can be disambiguated as a set.
+ candidates: list[tuple[str, list[str]]] = []
+ for parent, children in sorted(direct_children.items()):
+ if len(children) < 2 or parent in leaf_targets:
+ continue
+ members = sorted(f for f in files if f.startswith(parent + "/"))
+ if not members or (total and len(members) > _ROLLUP_MAX_MEMBER_FRACTION * total):
+ continue
+ candidates.append((parent, members))
+
+ # Disambiguate overview titles against each other exactly as leaf titles are,
+ # so two same-named subsystems in different packages ("Components Overview"
+ # under packages/web and packages/vscode) do not render as identical rows.
+ def _base_title(parent: str) -> str:
+ segment = parent.rsplit("/", 1)[-1] if "/" in parent else parent
+ return f"{_humanise(segment)} Overview".strip()
+
+ titles = disambiguate_titles([(_base_title(p), p) for p, _ in candidates])
+
+ rollups: list[tuple[float, ModuleGroup]] = []
+ for (parent, members), title in zip(candidates, titles, strict=True):
+ langs = Counter(lang_of.get(m, "") for m in members)
+ langs.pop("", None)
+ segment = parent.rsplit("/", 1)[-1] if "/" in parent else parent
+ score = sum(pagerank.get(m, 0.0) for m in members)
+ rollups.append(
+ (
+ score,
+ ModuleGroup(
+ key=parent,
+ display=title,
+ language=langs.most_common(1)[0][0] if langs else "unknown",
+ file_paths=tuple(members),
+ label=None,
+ cohesion=None,
+ # Hashed over the full subsystem with a distinct prefix so a
+ # rollup can never collide with a leaf whose members are a
+ # subset of these, and so the sweep tracks it as its own row.
+ structural_key=member_structural_key(members, prefix="concept-rollup"),
+ scope=(
+ f"Overviews the {_humanise(segment)} subsystem as a whole and "
+ "links to the concept pages documenting its parts; the detail "
+ "lives on those child pages, not here."
+ ),
+ is_rollup=True,
+ ),
+ )
+ )
+ return rollups
+
+
def _build_api_candidates(inputs: SelectionInputs) -> list[tuple[float, str]]:
scored: list[tuple[float, str]] = []
for p in inputs.parsed_files:
diff --git a/packages/core/src/repowise/core/generation/templates/module_page.j2 b/packages/core/src/repowise/core/generation/templates/module_page.j2
index ecbcbe5da..1175a3586 100644
--- a/packages/core/src/repowise/core/generation/templates/module_page.j2
+++ b/packages/core/src/repowise/core/generation/templates/module_page.j2
@@ -1,99 +1,137 @@
+{% if ctx.is_rollup %}
+You are documenting **{{ ctx.title }}**, an OVERVIEW of the `{{ ctx.directories[0] if ctx.directories else ctx.title }}` subsystem as a whole. Detail lives on the child pages listed below; this page situates the subsystem, explains how its parts fit together, and points a reader to the right child page. Do not re-document each file.
+{% else %}
You are documenting **{{ ctx.title }}** (language: {{ ctx.language }}), a group of files that belong together, not a single directory. Write about what the group does as a whole.
+{% endif %}
+
+{% if ctx.scope %}
+SCOPE (use this to open by situating the page against its siblings — say what it covers and what it deliberately leaves to other pages; do NOT quote this line verbatim):
+> {{ ctx.scope }}
+{% endif %}
-## Module Overview
+## Material
**Covers:** {% if ctx.directories %}{% for d in ctx.directories[:6] %}`{{ d }}`{% if not loop.last %}, {% endif %}{% endfor %}{% if ctx.directories | length > 6 %} and {{ ctx.directories | length - 6 }} more{% endif %}{% else %}the repository root{% endif %} | **Language:** {{ ctx.language }} | **Files:** {{ ctx.files | length }} | **Public symbols:** {{ ctx.public_symbols }} / {{ ctx.total_symbols }}{% if ctx.community_label %} | **Community:** {{ ctx.community_label }}{% if ctx.community_cohesion > 0 %} (cohesion {{ "%.2f"|format(ctx.community_cohesion) }}){% endif %}{% endif %}
-{# The role-leading sentence is the highest-leverage signal a module page
- carries. Surface the module's position in the system so the LLM can frame
- the Overview correctly — high-PageRank modules are usually orchestrators
- or shared infrastructure, low-PageRank modules are leaf consumers. #}
{%- set _mod_signals = [] -%}
{%- if ctx.entry_points -%}{%- set _ = _mod_signals.append("hosts entry points into this subsystem") -%}{%- endif -%}
{%- if ctx.pagerank_mean is defined and ctx.pagerank_mean >= 0.005 -%}{%- set _ = _mod_signals.append("architecturally central (high mean PageRank across its files)") -%}{%- endif -%}
{% if _mod_signals %}
-**Architectural signals:** {{ _mod_signals | join("; ") }}.
+**Architectural signals:** {{ _mod_signals | join("; ") }}. Weave these into the opening rather than listing them.
+{% endif %}
-Lead the ## Overview's first sentence with the module's role in repowise's pipeline; weave the signals above into that opening rather than re-listing them.
+{% if ctx.is_rollup and ctx.child_pages %}
+### Child pages (this overview links down to these)
+Name each in backticks by its path so it resolves to a wiki link; explain in one clause what each covers and when a reader should go there.
+{% for cp in ctx.child_pages %}
+- **{{ cp.title }}** — `{{ cp.path }}`
+{% endfor %}
{% endif %}
{% if ctx.entry_points %}
-## Entry Points
+### Entry points
{% for ep in ctx.entry_points %}
- `{{ ep }}`
{% endfor %}
{% endif %}
{% if ctx.key_files %}
-## Key Files
-The highest-PageRank files in this module — the ones to read first when learning the area.
+### Key files (highest PageRank first — read these first)
{% for kf in ctx.key_files %}
- `{{ kf.path }}`{% if kf.is_entry_point %} *(entry point)*{% endif %}{% if kf.summary %} — {{ kf.summary }}{% endif %}
{% endfor %}
{% endif %}
{% if ctx.decision_records %}
-## Architectural decisions
-Use these to explain *why* the module is shaped the way it is. Do not invent rationale beyond what is listed.
+### Architectural decisions
+Use these to explain *why* the subsystem is shaped the way it is. Do not invent rationale beyond what is listed.
{% for dr in ctx.decision_records[:5] %}
- **{{ dr.title }}** — {{ dr.decision }}{% if dr.rationale %} *(Why: {{ dr.rationale }})*{% endif %}
{% endfor %}
{% endif %}
{% if ctx.dependencies %}
-## Dependencies (modules this imports)
+### Depends on (modules this imports)
{% for dep in ctx.dependencies[:25] %}
- `{{ dep }}`
{% endfor %}
{% endif %}
{% if ctx.dependents %}
-## Dependents (modules that import this)
+### Depended on by (modules that import this)
{% for dep in ctx.dependents[:25] %}
- `{{ dep }}`
{% endfor %}
{% endif %}
{% if ctx.external_systems %}
-## External systems used
+### External systems used
{% for sys in ctx.external_systems[:15] %}
- `{{ sys.name }}`{% if sys.category and sys.category != 'library' %} *({{ sys.category }})*{% endif %}{% if sys.ecosystem %} — {{ sys.ecosystem }}{% endif %}
{% endfor %}
{% endif %}
+{# Health and history signals a reader cannot get from the code alone. Only
+ surfaced when git metadata supplied them; all zero/empty degrades to nothing
+ rather than a fabricated number. This is repowise's differentiation — weave
+ the true ones into the narrative, do not tabulate them mechanically. #}
+{%- set _health = [] -%}
+{%- if ctx.hotspot_count > 0 -%}{%- set _ = _health.append(ctx.hotspot_count ~ " file" ~ ("s" if ctx.hotspot_count != 1 else "") ~ " flagged as change hotspots") -%}{%- endif -%}
+{%- if ctx.single_owner_files > 0 -%}{%- set _ = _health.append(ctx.single_owner_files ~ " file" ~ ("s" if ctx.single_owner_files != 1 else "") ~ " with a bus factor of one (single-maintainer risk)") -%}{%- endif -%}
+{%- if ctx.bugfix_total > 0 -%}{%- set _ = _health.append(ctx.bugfix_total ~ " bug-fix commit" ~ ("s" if ctx.bugfix_total != 1 else "") ~ " in recent history" ~ (", most in `" ~ ctx.most_fixed_file.path ~ "`" if ctx.most_fixed_file else "")) -%}{%- endif -%}
+{%- if ctx.stable_count > 0 -%}{%- set _ = _health.append(ctx.stable_count ~ " file" ~ ("s" if ctx.stable_count != 1 else "") ~ " that have been stable") -%}{%- endif -%}
+{% if _health %}
+### Subsystem health (from git history — state the notable ones plainly)
+{% for h in _health %}
+- {{ h }}
+{% endfor %}
+{% endif %}
+
+{% if ctx.coupled_modules %}
+### Change-coupled with (co-changes in history, not import edges)
+These modules change together with this one in history without importing it — hidden coupling worth naming.
+{% for cm in ctx.coupled_modules %}
+- `{{ cm.path }}` (co-changed {{ cm.count }}×)
+{% endfor %}
+{% endif %}
+
{% if ctx.top_owners %}
-## Ownership
+### Ownership
{% for o in ctx.top_owners %}
- **{{ o.name }}** — primary maintainer of {{ o.file_count }} file(s)
{% endfor %}
{% endif %}
{% if ctx.key_classes %}
-## Class Hierarchy
+### Class hierarchy
{% for h in ctx.key_classes %}
- `{{ h.child }}` {{ h.kind }} `{{ h.parent }}`{% if h.parent_file is defined and h.parent_file %} (in `{{ h.parent_file }}`){% endif %}
{% endfor %}
{% endif %}
{% if ctx.dead_code_findings %}
-## Potentially unused code in this module
+### Potentially unused code
{% for finding in ctx.dead_code_findings[:10] %}
- `{{ finding.symbol_name or '?' }}` — {{ finding.reason }} ({{ (finding.confidence * 100) | int }}%{% if finding.safe_to_delete %}, cleanup-ready{% endif %})
{% endfor %}
{% endif %}
{% if module_git_summary is defined and module_git_summary %}
-## Recent activity
-Most active file: `{{ module_git_summary.most_active_file }}`
-({{ module_git_summary.most_active_commits_90d }} commits in 90 days)
+### Recent activity
+Most active file: `{{ module_git_summary.most_active_file }}` ({{ module_git_summary.most_active_commits_90d }} commits in 90 days).
{% endif %}
-Cross-references: name the module's key files and the neighboring modules it consumes
-or serves in backticks exactly as listed above so they resolve to wiki links. Mention
-a neighbor only where it explains this module's role: no references added purely for
-link density, and no reciprocal mentions out of symmetry.
+## How to write this page
+
+Write the page now from the material above. Requirements:
+
+- Open with the role-leading opener described, situating this page against its siblings using the scope line. Do not begin with "This module contains N files".
+- Choose H2/H3 headings that name this subsystem's real concerns. There is no fixed heading list — do not emit generic "Overview / Public API / Architecture Notes" headings unless they are genuinely the right names here.
+- Synthesise across the whole file set. Draw on the material as a body of evidence; a file-by-file walkthrough is a failure even when accurate. Draw on many files, not one.
+- Put any enumerable list (key files, dependencies, decisions) in a markdown table where it reads better than prose.
+- Name the subsystem's key files and the neighbouring modules it consumes or serves in backticks exactly as written above so they resolve to wiki links. Mention a neighbour only where it explains this subsystem's role — no links for density, no reciprocal mentions for symmetry.
+- Weave the true health and history signals (hotspots, bus factor, change coupling, fix history) into the narrative where they explain the subsystem's character. Skip any that are absent; never invent one.
+- Third person throughout. No concluding or summary section.
+- End with the mandatory `## Questions this page answers` section: 3 to 6 real questions this page answers, phrased as a developer or agent would ask them.
-Generate a complete wiki page following the sections above. Required sections in the
-output: ## Overview, ## Public API Summary, ## Architecture Notes. Use the supplied
-key files, decisions, and external systems to ground the narrative; do not fabricate
-modules, files, or rationale that are not listed here.
+Ground everything in the material above. Do not fabricate files, symbols, modules, or rationale that are not listed.
diff --git a/packages/core/src/repowise/core/generation/templates/stub/module_page.j2 b/packages/core/src/repowise/core/generation/templates/stub/module_page.j2
index 8cea6ddd2..556e28858 100644
--- a/packages/core/src/repowise/core/generation/templates/stub/module_page.j2
+++ b/packages/core/src/repowise/core/generation/templates/stub/module_page.j2
@@ -11,6 +11,17 @@
**Language:** {{ ctx.language }} | **Files:** {{ ctx.files | length }} | **Public symbols:** {{ ctx.public_symbols }} / {{ ctx.total_symbols }}{% if ctx.community_label %} | **Cluster:** {{ ctx.community_label }}{% if ctx.community_cohesion > 0 %} (cohesion {{ "%.2f"|format(ctx.community_cohesion) }}){% endif %}{% endif %}
+{% if ctx.scope %}
+{{ ctx.scope }}
+{% endif %}
+
+{% if ctx.is_rollup and ctx.child_pages %}
+## Parts of this subsystem
+{% for cp in ctx.child_pages %}
+- **{{ cp.title }}** — `{{ cp.path }}`
+{% endfor %}
+{% endif %}
+
## Overview
{% set _role = [] -%}
@@ -88,8 +99,35 @@ Highest-PageRank first: the order to read them in.
{% endfor %}
{% endif %}
+{%- set _health = [] -%}
+{%- if ctx.hotspot_count > 0 -%}{%- set _ = _health.append(ctx.hotspot_count ~ " file" ~ ("s" if ctx.hotspot_count != 1 else "") ~ " flagged as change hotspots") -%}{%- endif -%}
+{%- if ctx.single_owner_files > 0 -%}{%- set _ = _health.append(ctx.single_owner_files ~ " file" ~ ("s" if ctx.single_owner_files != 1 else "") ~ " with a bus factor of one (single-maintainer risk)") -%}{%- endif -%}
+{%- if ctx.bugfix_total > 0 -%}{%- set _ = _health.append(ctx.bugfix_total ~ " bug-fix commit" ~ ("s" if ctx.bugfix_total != 1 else "") ~ " in recent history" ~ (", most in " ~ ctx.most_fixed_file.path if ctx.most_fixed_file else "")) -%}{%- endif -%}
+{%- if ctx.stable_count > 0 -%}{%- set _ = _health.append(ctx.stable_count ~ " file" ~ ("s" if ctx.stable_count != 1 else "") ~ " that have been stable") -%}{%- endif -%}
+{% if _health %}
+## Subsystem health
+{% for h in _health %}
+- {{ h }}
+{% endfor %}
+{% endif %}
+
+{% if ctx.coupled_modules %}
+## Change-coupled with
+Modules that change together with this one in history without importing it.
+{% for cm in ctx.coupled_modules %}
+- `{{ cm.path }}` (co-changed {{ cm.count }}×)
+{% endfor %}
+{% endif %}
+
{% if module_git_summary %}
## Recent activity
Most active file: `{{ module_git_summary.most_active_file }}` ({{ module_git_summary.most_active_commits_90d }} commits in the last 90 days).
{% endif %}
-{% include "stub/_footer.j2" %}
+
+## Questions this page answers
+- What does {{ ctx.title }} do, and where does it sit in the system?
+- Which files make up {{ ctx.title }}{% if ctx.directories %} (under {% for d in ctx.directories[:3] %}`{{ d }}`{% if not loop.last %}, {% endif %}{% endfor %}){% endif %}?
+{% if ctx.entry_points %}- What are the entry points into {{ ctx.title }}?
+{% endif %}{% if ctx.dependencies %}- What does {{ ctx.title }} depend on?
+{% endif %}{% if ctx.dependents %}- What relies on {{ ctx.title }}?
+{% endif %}{% include "stub/_footer.j2" %}
diff --git a/tests/unit/generation/test_selection_concept_groups.py b/tests/unit/generation/test_selection_concept_groups.py
index d0f707079..13989f4e2 100644
--- a/tests/unit/generation/test_selection_concept_groups.py
+++ b/tests/unit/generation/test_selection_concept_groups.py
@@ -21,9 +21,13 @@ import sys
import textwrap
from pathlib import Path
+from repowise.core.generation.concept_tree.grouping import ConceptGroup
from repowise.core.generation.models import GenerationConfig
from repowise.core.generation.selection import SelectionInputs, select_pages
-from repowise.core.generation.selection.selector import _build_module_groups
+from repowise.core.generation.selection.selector import (
+ _build_module_groups,
+ _build_rollup_groups,
+)
from tests.unit.generation.test_selection_contract import (
FakeFileInfo,
FakeParsedFile,
@@ -118,9 +122,9 @@ def test_root_level_files_get_a_usable_target_path():
assert any("main.py" in g.file_paths for g in groups)
for g in groups:
assert g.key, "a group persisted an empty target_path"
- assert any(g.key == "root" for g in owning), (
- f"root-anchored group did not get the root target: {[g.key for g in owning]}"
- )
+ assert any(
+ g.key == "root" for g in owning
+ ), f"root-anchored group did not get the root target: {[g.key for g in owning]}"
def test_test_files_never_enter_the_concept_tree():
@@ -224,9 +228,9 @@ def test_root_documentation_and_examples_get_no_concept_page():
assert claimed, "fixture produced no groups"
for prefix in ("docs/", "docs_src/", "examples/", "samples/"):
- assert not any(p.startswith(prefix) for p in claimed), (
- f"{prefix} reached the concept tree: {[p for p in claimed if p.startswith(prefix)]}"
- )
+ assert not any(
+ p.startswith(prefix) for p in claimed
+ ), f"{prefix} reached the concept tree: {[p for p in claimed if p.startswith(prefix)]}"
# The fixture is only meaningful if those files were in the input.
assert any(p.startswith("docs_src/") for p in _support_paths())
@@ -293,15 +297,15 @@ def test_ranked_by_summed_pagerank_not_by_path():
assert len(scored) > 1, "a one-group fixture cannot test ordering"
# The fixture is only meaningful if path order disagrees with score order,
# or the assertion below would pass on a sorted-by-path implementation.
- assert ordered_keys != sorted(ordered_keys), (
- f"fixture is degenerate: score order equals path order ({ordered_keys})"
- )
+ assert ordered_keys != sorted(
+ ordered_keys
+ ), f"fixture is degenerate: score order equals path order ({ordered_keys})"
# ui/c4 carries 1.0 per file against 0.1 elsewhere, so whichever group
# holds it must come first.
top_group = scored[0][1]
- assert any("/ui/c4/" in p for p in top_group.file_paths), (
- f"expected the ui/c4 mass to rank first, got {top_group.key}"
- )
+ assert any(
+ "/ui/c4/" in p for p in top_group.file_paths
+ ), f"expected the ui/c4 mass to rank first, got {top_group.key}"
def test_display_is_a_name_not_a_bare_path():
@@ -384,3 +388,82 @@ def test_two_groups_never_share_a_title():
titles = [g.display for g in groups]
assert len(titles) == len(set(titles)), titles
assert len({g.key for g in groups}) == len(groups)
+
+
+# ---------------------------------------------------------------------------
+# Parent-directory rollup overview pages
+# ---------------------------------------------------------------------------
+
+
+def _leaf(members: list[str]) -> ConceptGroup:
+ """A concept group whose target_path is its members' shared directory."""
+ tp = members[0].rsplit("/", 1)[0]
+ return ConceptGroup(members=sorted(members), dirs=[tp], target_path=tp)
+
+
+def test_rollup_emitted_for_parent_of_two_leaf_pages():
+ """A parent that owns >=2 leaf pages and is itself no leaf gets an overview.
+
+ Its target_path is exactly that directory, because directory-level retrieval
+ matches a page to a directory by exact target_path equality.
+ """
+ leaves = [
+ _leaf(["p/ingestion/languages/a.py", "p/ingestion/languages/b.py"]),
+ _leaf(["p/ingestion/graph/c.py", "p/ingestion/graph/d.py"]),
+ # Two unrelated subsystems so ingestion stays a minority of the repo and
+ # the near-repo-wide guard does not fire; each owns a single leaf, so
+ # neither earns an overview of its own.
+ _leaf([f"p/other/e{i}.py" for i in range(6)]),
+ _leaf([f"p/extra/g{i}.py" for i in range(6)]),
+ ]
+ files = [m for g in leaves for m in g.members] + ["p/ingestion/loose.py"]
+ lang_of = {f: "python" for f in files}
+
+ rollups = _build_rollup_groups(leaves, files, lang_of, {})
+ keys = {m.key for _, m in rollups}
+
+ # ingestion owns two leaf children; the others own one each, so no overview.
+ assert keys == {"p/ingestion"}
+ (_, roll) = rollups[0]
+ assert roll.is_rollup is True
+ assert roll.structural_key.startswith("concept-rollup")
+ # It carries the subsystem's files for context, including loose ones.
+ assert "p/ingestion/loose.py" in roll.file_paths
+
+
+def test_rollup_target_never_collides_with_a_leaf():
+ """A parent that is already a leaf page is not given a second overview."""
+ leaves = [
+ _leaf(["p/svc/a.py", "p/svc/b.py"]), # target p/svc — the parent itself
+ _leaf(["p/svc/api/c.py", "p/svc/api/d.py"]),
+ _leaf(["p/svc/db/e.py", "p/svc/db/f.py"]),
+ ]
+ files = [m for g in leaves for m in g.members]
+ rollups = _build_rollup_groups(leaves, files, {f: "python" for f in files}, {})
+ # p/svc is a leaf target, so no rollup claims that page id.
+ assert "p/svc" not in {m.key for _, m in rollups}
+
+
+def test_rollup_titles_are_disambiguated():
+ """Two same-named subsystems in different packages get distinct titles."""
+ leaves = [
+ _leaf(["a/web/components/x/1.py", "a/web/components/x/2.py"]),
+ _leaf(["a/web/components/z/3.py", "a/web/components/z/4.py"]),
+ _leaf(["a/ext/components/y/5.py", "a/ext/components/y/6.py"]),
+ _leaf(["a/ext/components/w/7.py", "a/ext/components/w/8.py"]),
+ ]
+ files = [m for g in leaves for m in g.members]
+ rollups = _build_rollup_groups(leaves, files, {f: "python" for f in files}, {})
+ titles = [m.display for _, m in rollups]
+ assert len(titles) == len(set(titles)), titles
+
+
+def test_rollup_skips_near_repo_wide_parent():
+ """A parent covering most of the repo is the repo overview, not a rollup."""
+ leaves = [
+ _leaf(["mono/a/x.py", "mono/a/y.py"]),
+ _leaf(["mono/b/z.py", "mono/b/w.py"]),
+ ]
+ files = [m for g in leaves for m in g.members]
+ rollups = _build_rollup_groups(leaves, files, {f: "python" for f in files}, {})
+ assert "mono" not in {m.key for _, m in rollups}