Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(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.pyindex 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.pyindex 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: floatfiles: 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, sodiff --git a/packages/core/src/repowise/core/generation/page_generator/levels.py b/packages/core/src/repowise/core/generation/page_generator/levels.pyindex 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.pyindex 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 = 0for section in outline.sections:for page in section.pages:title_of[page.structural_key] = page.titlesection_of[page.structural_key] = section.titleorder_of[page.structural_key] = position+ scope_of[page.structural_key] = page.scopeposition += 1from 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 mostdiff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.pyindex 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 = Noneif 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.pyindex 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: F401SYSTEM_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.pyindex 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 structlogfrom repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRYfrom ..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_slugfrom .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.j2index 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.j2index 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 activityMost 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.pyindex 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 sysimport textwrapfrom pathlib import Path+from repowise.core.generation.concept_tree.grouping import ConceptGroupfrom repowise.core.generation.models import GenerationConfigfrom 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)), titlesassert 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}