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
"""A module page is stored in the shape a reader reads, whatever the model sent.
Checked on the page as stored, after every post-processing step: no diagram
the renderer rejects, no citation of a file that does not exist, the agent
material in the digest, and headings that name what the module does. Every
built-in style asks for the same shape.
"""
from __future__ import annotations
import re
from dataclasses import replace
import networkx as nx
import pytest
from repowise.core.generation.context_assembler import ContextAssembler, FilePageContext
from repowise.core.generation.mermaid_safety import invalid_mermaid_blocks
from repowise.core.generation.page_generator import PageGenerator
from repowise.core.providers.llm.mock import MockProvider
_GENERIC_HEADINGS = {
"overview",
"architecture",
"key files",
"public api",
"dependencies",
"summary",
"introduction",
"components",
}
_REQUIRED_TAIL = ["Where to start reading", "How it connects"]
def table_line_share(markdown: str) -> float:
lines = [line for line in markdown.splitlines() if line.strip()]
return sum(1 for line in lines if line.lstrip().startswith("|")) / max(1, len(lines))
def generic_headings(markdown: str) -> list[str]:
return [
h for h in re.findall(r"^##\s+(.+?)\s*$", markdown, re.M) if h.lower() in _GENERIC_HEADINGS
]
_SECTION = (
"The {part} part {verb} every order that reaches it. It reads the basket, checks what the "
"shop still holds and records the outcome before anything is charged. Keeping this step in "
"one place means a failed check never leaves a half written order behind, and the next "
"step can trust what it receives. The work is small on purpose: each function does one "
"thing, and the order moves through them in a fixed sequence that is easy to follow when "
"something goes wrong. Retries happen here and not further along, because only this "
"step knows which half of the work already succeeded.\n\n"
"A reader who wants the rules should open `{file}` first. It keeps the decisions near the "
"data they depend on, so a change to one rule rarely touches another part of the flow. "
"Tests for the step sit beside it and describe each rule in plain words."
)
_RESPONSE = "\n\n".join(
[
"# Order Handling",
"Order handling turns a customer's basket into a paid, reserved order. It sits between "
"the web views that take requests and the store that keeps the results, so the rest of "
"the shop never deals with half finished orders.",
"```mermaid\nflowchart LR\n Orders[\"Orders<br/><small>orders/</small>\"] -->|asks to charge| "
"Billing[\"Billing<br/><small>billing/</small>\"]\n Orders -->|reserves stock in| "
"Stock[\"Stock<br/><small>stock/</small>\"]\n Web[\"Web views\"]:::ext -->|places orders "
"through| Orders\n classDef ext stroke-dasharray:4 3;\n```",
"## From a basket to a placed order",
_SECTION.format(part="orders", verb="validates", file="orders/place.py"),
"Sources: `orders/place.py`",
"## Taking the payment",
_SECTION.format(part="billing", verb="charges", file="billing/charge.py"),
"Sources: `billing/charge.py`",
"## Holding the stock",
_SECTION.format(part="stock", verb="reserves stock for", file="stock/reserve.py"),
"Sources: `stock/reserve.py`, `stock/ghost.py`",
"## Following one order",
"The order moves from the basket to the store.",
"```mermaid\nsequenceDiagram\n Orders calls Billing\n```",
"## Where to start reading",
"- `orders/place.py` - where an order starts.\n"
"- `billing/charge.py` - how payment is taken.\n"
"- `stock/reserve.py` - how stock is held.",
"## How it connects",
"Web views call into order handling, and order handling writes through the store.",
"## Questions this page answers",
"- How is an order placed?\n- Where is payment taken?",
]
)
_FILES = ["src/shop/orders/place.py", "src/shop/billing/charge.py", "src/shop/stock/reserve.py"]
class _Provider(MockProvider):
async def generate(self, *args, **kwargs):
response = await super().generate(*args, **kwargs)
return replace(response, content=_RESPONSE)
def _context(path: str) -> FilePageContext:
return FilePageContext(
file_path=path,
language="python",
docstring=None,
symbols=[],
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=10,
)
async def _page(config, provider=None):
gen = PageGenerator(provider or _Provider(), ContextAssembler(config), config)
graph = nx.DiGraph()
graph.add_nodes_from(_FILES)
return await gen.generate_module_page(
"Order Handling",
"python",
[_context(f) for f in _FILES],
graph,
target_path="src/shop",
structural_key="k",
)
async def test_post_processing_keeps_the_shape_and_moves_agent_material(sample_config):
"""What the pipeline does to a response, not what the fixture already is:
the broken diagram and the invented citation go, the questions move to the
digest, and the reading shape survives."""
page = await _page(sample_config)
assert page.content.count("```mermaid") == 1
assert invalid_mermaid_blocks(page.content) == []
assert "ghost.py" not in page.content
assert page.content.count("Sources: `") == 3
assert "Questions this page answers" not in page.content
assert page.digest.startswith("## Questions this page answers")
assert table_line_share(page.content) == 0
assert generic_headings(page.content) == []
headings = re.findall(r"^##\s+(.+?)\s*$", page.content, re.M)
assert headings[-2:] == _REQUIRED_TAIL
@pytest.mark.parametrize("style", ["comprehensive", "caveman", "reference", "tutorial"])
def test_every_style_keeps_the_page_shape(sample_config, style):
config = replace(sample_config, wiki_style=style)
gen = PageGenerator(MockProvider(), ContextAssembler(config), config)
ctx = gen._assembler.assemble_module_page(
"Order Handling", "python", [_context(f) for f in _FILES], nx.DiGraph()
)
prompt = gen._render("module_page.j2", ctx=ctx)
for rule in ("fenced `mermaid` block", "Sources: ", "## Where to start reading", "500 to 800"):
assert rule in prompt
if style != "comprehensive":
assert style.upper() in prompt