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.

fix(generation): stop the module_page prompt tripping its own validator, and bound the spotlight importer list (#1606)

Raghav Chamadiya28c861f72577
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 a66607c4c..0f273d73f 100644
--- a/packages/core/src/repowise/core/generation/page_generator/core.py
+++ b/packages/core/src/repowise/core/generation/page_generator/core.py
@@ -15,7 +15,7 @@ from __future__ import annotations
import hashlib
from collections.abc import Callable, Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
from pathlib import Path
from typing import TYPE_CHECKING, Any
@@ -46,14 +46,18 @@ from ..structural_labels import resolve_structural_labels, structural_page_title
from ..styles import ONBOARDING_PAGE_TYPE, resolve_style
from .helpers import _extract_summary, _now_iso, collapse_empty_duplicate_headings
from .pertype import PerTypeGenerationMixin
-from .prompts import SUPPORTED_LANGUAGES, SYSTEM_PROMPTS
+from .prompts import CORRECTIVE_RETRY_DIRECTIVE, SUPPORTED_LANGUAGES, SYSTEM_PROMPTS
from .structural import (
StructuralRenderMixin,
as_markdown,
oneline,
signature,
)
-from .validation import reset_artifact_check_counts, validate_generated_response
+from .validation import (
+ InvalidGeneratedContentError,
+ reset_artifact_check_counts,
+ validate_generated_response,
+)
if TYPE_CHECKING:
from pathlib import Path as _Path # noqa: F401
@@ -398,13 +402,60 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):
reasoning=self._config.reasoning,
cache_hints=cache_hints,
)
- validate_generated_response(response)
+ try:
+ validate_generated_response(response)
+ except InvalidGeneratedContentError as first_failure:
+ # One corrective re-ask. Without it a single banned phrase anywhere
+ # in a finished page discards the whole thing with the tokens
+ # already spent, and the only recovery is --resume regenerating it
+ # from scratch. The re-ask names the rule that was broken, because
+ # a blind retry at the same temperature tends to reproduce the
+ # sentence that failed.
+ if not first_failure.retryable:
+ raise
+ log.warning(
+ "page_generation.retrying_after_validation_failure",
+ page_type=page_type,
+ target_path=target_path,
+ reason=str(first_failure),
+ )
+ discarded = response
+ response = await self._provider.generate(
+ system_prompt,
+ self._corrective_prompt(user_prompt, first_failure),
+ max_tokens=self._config.max_tokens,
+ temperature=self._config.temperature,
+ request_id=request_id,
+ reasoning=self._config.reasoning,
+ cache_hints=cache_hints,
+ )
+ # A second failure raises, so the caller's stub-fallback path is
+ # reached exactly as it was before the retry existed.
+ validate_generated_response(response)
+ # The discarded attempt was billed. Carrying its tokens forward is
+ # what keeps the run report's totals equal to what the provider
+ # actually charged for; the page itself is the retry's content.
+ # ``self_repair`` fills the report row of the same name, which
+ # distinguishes a page that needed a second attempt from one that
+ # was lost — the artifact tallies alone cannot tell them apart.
+ response = replace(
+ response,
+ input_tokens=response.input_tokens + discarded.input_tokens,
+ output_tokens=response.output_tokens + discarded.output_tokens,
+ cached_tokens=response.cached_tokens + discarded.cached_tokens,
+ usage={**response.usage, "self_repair": True},
+ )
if self._config.cache_enabled:
self._cache[key] = response
return response
+ @staticmethod
+ def _corrective_prompt(user_prompt: str, failure: InvalidGeneratedContentError) -> str:
+ """The original request plus a note naming what the last attempt broke."""
+ return f"{user_prompt}\n\n{CORRECTIVE_RETRY_DIRECTIVE.format(reason=failure.retry_hint)}"
+
def _build_system_prompt(self, page_type: str) -> str:
base_system = SYSTEM_PROMPTS[page_type]
# Wiki style: append the style's framing note. Constant per run (per page
@@ -498,6 +549,11 @@ class PageGenerator(PerTypeGenerationMixin, StructuralRenderMixin):
# exists byte-identically.
if response.usage.get("reused_from_prior_run"):
page.metadata["reused_from_prior_run"] = True
+ # A first attempt was rejected and the re-ask produced this page. Feeds
+ # the report's "Self-repaired pages" row, so a run says how often the
+ # backstop was load-bearing instead of only how often it failed.
+ if response.usage.get("self_repair"):
+ page.metadata["self_repair"] = True
return page
def _render(self, template_name: str, *, style_prefix: bool = True, **kwargs: Any) -> str:
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 f5bdab52b..2691d05ed 100644
--- a/packages/core/src/repowise/core/generation/page_generator/prompts.py
+++ b/packages/core/src/repowise/core/generation/page_generator/prompts.py
@@ -28,7 +28,7 @@ SYSTEM_PROMPTS: dict[str, str] = {
"\n"
"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). "
+ "using the scope line below, 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. "
@@ -53,8 +53,14 @@ SYSTEM_PROMPTS: dict[str, str] = {
# heading bare, then again with the questions under it, on 86 of 92 pages
# measured across local indexes (gpt-5.4-nano). Pages written before the
# instruction was doubled show none of it. One instruction, one heading.
- "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."
+ # Worded around the reader-facing vocabulary the artifact rules ban.
+ # "the supplied material" is a literal hit for the ``supplied_context``
+ # rule in validation.py, and the model echoed the instruction back into
+ # the page, so this sentence destroyed the pages it was meant to keep
+ # honest. Say where to ground a claim without naming the prompt.
+ "Ground every claim in the files and signals listed below: 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. "
@@ -90,3 +96,20 @@ SYSTEM_PROMPTS: dict[str, str] = {
"Output markdown only — follow the exact section structure the user prompt prescribes."
),
}
+
+# Appended to the *user* prompt when a first attempt was rejected by
+# ``validate_generated_response``, so the re-ask says what went wrong instead of
+# asking again unchanged. The system prompt is left byte-identical, which keeps
+# the retry eligible for the same server-side prefix cache as the first call.
+#
+# It lives beside the system prompts so the artifact-hygiene guard covers it as
+# well: text telling a model what not to say is still text a model can echo, and
+# a correction that trips the rule it is correcting would burn the retry too.
+CORRECTIVE_RETRY_DIRECTIVE: str = (
+ "A previous attempt at this page was rejected before it could be published. "
+ "Reason: {reason}\n"
+ "Write the page again, in full, without that problem. Address the reader of "
+ "the documentation, who cannot see this request and does not know it exists: "
+ "never mention these instructions or the code you were shown, and never "
+ "speak as the page's author."
+)
diff --git a/packages/core/src/repowise/core/generation/page_generator/validation.py b/packages/core/src/repowise/core/generation/page_generator/validation.py
index af9467751..b0d1026ab 100644
--- a/packages/core/src/repowise/core/generation/page_generator/validation.py
+++ b/packages/core/src/repowise/core/generation/page_generator/validation.py
@@ -23,7 +23,32 @@ _WORD_RE = re.compile(r"\w+", re.UNICODE)
class InvalidGeneratedContentError(ValueError):
- """Raised when a fresh LLM response cannot be persisted as documentation."""
+ """Raised when a fresh LLM response cannot be persisted as documentation.
+
+ ``retry_hint`` is the same complaint with any quoted offending phrase
+ removed, for the corrective re-ask. The message itself keeps the quote
+ because a log that does not say which words failed cannot be acted on, but
+ feeding those words back to the model re-plants the vocabulary the retry is
+ trying to get rid of. Defaults to the message when there is nothing to
+ strip.
+
+ ``retryable`` says whether asking again can plausibly help. It is False for
+ a response that stopped at the token limit: the second call carries the
+ same ``max_tokens``, so it truncates in the same place and the only certain
+ result is twice the spend. Everything else is the model writing badly when
+ told what "badly" means, which is what the re-ask supplies.
+ """
+
+ def __init__(
+ self,
+ message: str,
+ *,
+ retry_hint: str | None = None,
+ retryable: bool = True,
+ ) -> None:
+ super().__init__(message)
+ self.retry_hint = retry_hint if retry_hint is not None else message
+ self.retryable = retryable
# ---------------------------------------------------------------------------
@@ -129,15 +154,21 @@ def reset_artifact_check_counts() -> None:
_artifact_check_counts.clear()
-def _artifact_detail(content: str) -> str | None:
- """Describe the first generation artifact in ``content``, if any."""
+def _artifact_detail(content: str) -> tuple[str, str] | None:
+ """Describe the first generation artifact in ``content``, if any.
+
+ Returns ``(detail, retry_hint)``: the first quotes the offending phrase for
+ the log, the second names only the rule so a re-ask built from it does not
+ repeat the words that failed.
+ """
prose = prose_text(content)
for rule in GENERATION_ARTIFACT_RULES:
match = rule.pattern.search(prose)
if match is not None:
_artifact_check_counts["rejected"] += 1
_artifact_check_counts[f"rejected:{rule.name}"] += 1
- return f"{rule.name}: {rule.explanation} ({match.group(0).strip()!r})"
+ detail = f"{rule.name}: {rule.explanation} ({match.group(0).strip()!r})"
+ return detail, f"{rule.name}: {rule.explanation}"
return None
@@ -182,7 +213,8 @@ def validate_generated_response(response: GeneratedResponse) -> None:
else ""
)
raise InvalidGeneratedContentError(
- f"generation reached a token limit before the documentation was complete{detail}"
+ f"generation reached a token limit before the documentation was complete{detail}",
+ retryable=False,
)
if not response.content.strip():
raise InvalidGeneratedContentError("provider returned empty documentation")
@@ -193,10 +225,12 @@ def validate_generated_response(response: GeneratedResponse) -> None:
f"provider returned pathologically repetitive documentation: {repetition_detail}"
)
- artifact_detail = _artifact_detail(response.content)
- if artifact_detail is not None:
+ artifact = _artifact_detail(response.content)
+ if artifact is not None:
+ detail, retry_hint = artifact
+ preamble = "provider returned text addressed to the prompter, not the reader — "
raise InvalidGeneratedContentError(
- f"provider returned text addressed to the prompter, not the reader — {artifact_detail}"
+ f"{preamble}{detail}", retry_hint=f"{preamble}{retry_hint}"
)
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 e3d3d1053..cdf21c43a 100644
--- a/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2
+++ b/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2
@@ -5,6 +5,12 @@
the same way; a template that claimed otherwise would over-state what the
graph actually 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
+ the true total. Unbounded, a fixture imported across a whole test suite
+ rendered 939 bullets and a 46k-char page, which is past the 30k the
+ embedder accepts, so the tail was dropped from the vector.
+
Every section but the Overview is conditional: a heading with nothing
under it costs a reader a stop and repeats a stock sentence across
thousands of pages, where it matches every query and distinguishes none.
@@ -40,9 +46,13 @@
## {{ 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) }}
-{% for c in ctx.callers %}
+{% for c in ctx.callers[:25] %}
- `{{ c }}`
{%- endfor %}
+{%- if ctx.callers | length > 25 %}
+
+_{{ labels.and_more.format(count=ctx.callers | length - 25) }}_
+{%- endif %}
{%- endif %}
{%- if ctx.source_body %}
diff --git a/tests/unit/generation/test_page_generator.py b/tests/unit/generation/test_page_generator.py
index cf08b18e2..27ac3ef89 100644
--- a/tests/unit/generation/test_page_generator.py
+++ b/tests/unit/generation/test_page_generator.py
@@ -219,6 +219,142 @@ async def test_invalid_provider_output_raises_and_is_not_cached(sample_config):
assert provider.call_count == 2
+# ---------------------------------------------------------------------------
+# The corrective retry
+#
+# A rejected page is a page already paid for, so one re-ask is cheaper than
+# losing it. The bound matters as much as the retry: a page that fails twice
+# must fall through to the caller's stub path rather than loop.
+# ---------------------------------------------------------------------------
+
+_BANNED_PHRASING = "# Queue status\n\nThe supplied material describes a queue reader."
+_CLEAN_PAGE = "# Queue status\n\n`QueueStatus` reports the active queue."
+
+
+def _page(content: str) -> GeneratedResponse:
+ return GeneratedResponse(content=content, input_tokens=10, output_tokens=20)
+
+
+async def test_artifact_violation_is_retried_once_and_recovers(sample_config):
+ provider = MockProvider(responses=[_page(_BANNED_PHRASING), _page(_CLEAN_PAGE)])
+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)
+
+ response = await generator._call_provider(
+ "module_page", "Document this module.", "request-id"
+ )
+
+ assert response.content == _CLEAN_PAGE
+ assert provider.call_count == 2
+
+
+async def test_corrective_retry_names_the_broken_rule_and_keeps_the_request(sample_config):
+ provider = MockProvider(responses=[_page(_BANNED_PHRASING), _page(_CLEAN_PAGE)])
+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)
+
+ await generator._call_provider("module_page", "Document this module.", "request-id")
+
+ retry_prompt = provider.calls[1]["user_prompt"]
+ assert "supplied_context" in retry_prompt
+ # The whole page is being rewritten, so the original request has to survive.
+ assert "Document this module." in retry_prompt
+ # The offending words must not be handed back: quoting them re-plants the
+ # vocabulary the retry exists to remove.
+ assert "supplied material" not in retry_prompt
+ # A byte-identical system prompt is what keeps the retry eligible for the
+ # provider's prefix cache.
+ assert provider.calls[1]["system_prompt"] == provider.calls[0]["system_prompt"]
+
+
+async def test_retry_carries_the_discarded_attempt_s_tokens(sample_config):
+ """The rejected attempt was billed, so the run report has to count it.
+
+ Only the retry's content survives, but dropping the first attempt's tokens
+ would make the reported total smaller than what the provider charged for.
+ """
+ first = GeneratedResponse(
+ content=_BANNED_PHRASING, input_tokens=100, output_tokens=200, cached_tokens=10
+ )
+ second = GeneratedResponse(
+ content=_CLEAN_PAGE, input_tokens=7, output_tokens=11, cached_tokens=3
+ )
+ provider = MockProvider(responses=[first, second])
+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)
+
+ response = await generator._call_provider(
+ "module_page", "Document this module.", "request-id"
+ )
+
+ assert response.content == _CLEAN_PAGE
+ assert response.input_tokens == 107
+ assert response.output_tokens == 211
+ assert response.cached_tokens == 13
+
+
+async def test_a_repaired_page_is_marked_as_self_repaired(sample_config):
+ """Fills the report's "Self-repaired pages" row.
+
+ The artifact tallies count rejections, which a recovered page and a lost
+ page both produce. This is what tells them apart.
+ """
+ provider = MockProvider(responses=[_page(_BANNED_PHRASING), _page(_CLEAN_PAGE)])
+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)
+
+ response = await generator._call_provider(
+ "module_page", "Document this module.", "request-id"
+ )
+ page = generator._build_generated_page(
+ "module_page", "pkg/mod.py", "Mod", response, "source-hash", 3
+ )
+
+ assert page.metadata.get("self_repair") is True
+
+
+async def test_a_first_time_page_is_not_marked_as_self_repaired(sample_config):
+ provider = MockProvider(responses=[_page(_CLEAN_PAGE)])
+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)
+
+ response = await generator._call_provider(
+ "module_page", "Document this module.", "request-id"
+ )
+ page = generator._build_generated_page(
+ "module_page", "pkg/mod.py", "Mod", response, "source-hash", 3
+ )
+
+ assert "self_repair" not in page.metadata
+
+
+async def test_second_violation_gives_up_rather_than_looping(sample_config):
+ # MockProvider repeats its last response, so every attempt violates.
+ provider = MockProvider(responses=[_page(_BANNED_PHRASING)])
+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)
+
+ with pytest.raises(InvalidGeneratedContentError, match="supplied_context"):
+ await generator._call_provider("module_page", "Document this module.", "request-id")
+
+ assert provider.call_count == 2
+
+
+async def test_token_limit_is_not_retried(sample_config):
+ """Re-asking with the same ``max_tokens`` truncates again and bills twice."""
+ provider = MockProvider(
+ responses=[
+ GeneratedResponse(
+ content="# Queue status\n\nIncomplete",
+ input_tokens=10,
+ output_tokens=20,
+ stop_reason="max_tokens",
+ provider_stop_reason="length",
+ )
+ ]
+ )
+ generator = PageGenerator(provider, ContextAssembler(sample_config), sample_config)
+
+ with pytest.raises(InvalidGeneratedContentError, match="token limit"):
+ await generator._call_provider("module_page", "Document this module.", "request-id")
+
+ assert provider.call_count == 1
+
+
def test_generated_page_retains_completion_stop_metadata(sample_config):
generator = PageGenerator(MockProvider(), ContextAssembler(sample_config), sample_config)
page = generator._build_generated_page(
diff --git a/tests/unit/generation/test_prompt_artifact_hygiene.py b/tests/unit/generation/test_prompt_artifact_hygiene.py
new file mode 100644
index 000000000..67e2d5514
--- /dev/null
+++ b/tests/unit/generation/test_prompt_artifact_hygiene.py
@@ -0,0 +1,100 @@
+"""The prompts must not use the vocabulary the artifact rules reject.
+
+A model echoes the phrasing it is instructed in. When a system prompt or a
+template contains a phrase that :mod:`validation` bans, the model reproduces it
+and the finished page is thrown away for saying what it was told to say —
+tokens spent, page lost, and the only clue is a validator complaining about the
+model rather than about the prompt.
+
+This has now happened twice. ``prompts.py`` carried "the supplied material",
+which is a literal hit for the ``supplied_context`` rule, and every
+``module_page`` that echoed it was destroyed. The comment at the same site
+records an earlier instance of the same shape. These tests make the class of
+bug fail at collection time instead of after a paid run.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from repowise.core.generation import page_generator
+from repowise.core.generation.page_generator.prompts import (
+ CORRECTIVE_RETRY_DIRECTIVE,
+ SYSTEM_PROMPTS,
+)
+from repowise.core.generation.page_generator.validation import (
+ GENERATION_ARTIFACT_RULES,
+ ArtifactRule,
+)
+
+_GENERATION_DIR = Path(page_generator.__file__).resolve().parent.parent
+_TEMPLATE_FILES = sorted(_GENERATION_DIR.rglob("*.j2"))
+
+
+def _offenders(text: str) -> list[tuple[ArtifactRule, str]]:
+ """Every artifact rule ``text`` trips, with the phrase that tripped it."""
+ hits = []
+ for rule in GENERATION_ARTIFACT_RULES:
+ match = rule.pattern.search(text)
+ if match is not None:
+ hits.append((rule, match.group(0).strip()))
+ return hits
+
+
[email protected]("page_type", sorted(SYSTEM_PROMPTS))
+def test_system_prompt_avoids_banned_vocabulary(page_type: str) -> None:
+ hits = _offenders(SYSTEM_PROMPTS[page_type])
+ assert not hits, (
+ f"the {page_type} system prompt uses phrasing that "
+ f"validate_generated_response rejects, so a model that echoes the "
+ f"instruction loses the page: "
+ + "; ".join(f"{rule.name} ({phrase!r}) — {rule.explanation}" for rule, phrase in hits)
+ )
+
+
+def test_corrective_retry_directive_avoids_banned_vocabulary() -> None:
+ """The correction must not trip the rule it exists to correct.
+
+ This directive is only ever sent after a page was already rejected once. A
+ banned phrase here would fail the retry as well and turn the backstop into
+ a second guaranteed loss.
+
+ Filled with a real ``retry_hint`` rather than a placeholder, because the
+ reason is interpolated into the prompt and is therefore part of what the
+ model reads. ``retry_hint`` is the phrase-free form for exactly this
+ reason; the quoted form goes to the log instead.
+ """
+ for rule in GENERATION_ARTIFACT_RULES:
+ reason = (
+ "provider returned text addressed to the prompter, not the reader — "
+ f"{rule.name}: {rule.explanation}"
+ )
+ hits = _offenders(CORRECTIVE_RETRY_DIRECTIVE.format(reason=reason))
+ assert not hits, (
+ f"the corrective retry directive, filled with the {rule.name} reason, "
+ f"uses phrasing that validate_generated_response rejects: "
+ + "; ".join(f"{hit.name} ({phrase!r})" for hit, phrase in hits)
+ )
+
+
+def test_templates_are_discovered() -> None:
+ """The template sweep needs a non-zero denominator to mean anything.
+
+ A glob that silently resolves to nothing passes every assertion below it,
+ which reads identically to a clean sweep.
+ """
+ assert _TEMPLATE_FILES, f"no .j2 templates found under {_GENERATION_DIR}"
+
+
+ "template_path", _TEMPLATE_FILES, ids=[p.name for p in _TEMPLATE_FILES]
+)
+def test_template_avoids_banned_vocabulary(template_path: Path) -> None:
+ hits = _offenders(template_path.read_text(encoding="utf-8"))
+ assert not hits, (
+ f"{template_path.relative_to(_GENERATION_DIR)} uses phrasing that "
+ f"validate_generated_response rejects: "
+ + "; ".join(f"{rule.name} ({phrase!r}) — {rule.explanation}" for rule, phrase in hits)
+ )
diff --git a/tests/unit/generation/test_templates.py b/tests/unit/generation/test_templates.py
index a5dd6aa70..7fa759e76 100644
--- a/tests/unit/generation/test_templates.py
+++ b/tests/unit/generation/test_templates.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import re
from pathlib import Path
import jinja2
@@ -432,6 +433,55 @@ def test_spotlight_keeps_the_importers_section_when_it_has_importers(
assert "1 file imports the module" in result
[email protected](scope="module")
+def widely_imported_spotlight_ctx() -> SymbolSpotlightContext:
+ """A fixture-shaped symbol: imported across a whole test suite.
+
+ 939 importers is what ``tests/conftest.py`` actually measured on this
+ repository, which is the case that produced a 46k-char page.
+ """
+ return SymbolSpotlightContext(
+ symbol_name="fixtures_dir",
+ qualified_name="tests.conftest.fixtures_dir",
+ kind="function",
+ signature="def fixtures_dir() -> Path:",
+ docstring="Path to the fixtures directory.",
+ file_path="tests/conftest.py",
+ decorators=[],
+ is_async=False,
+ complexity_estimate=1,
+ callers=[f"tests/unit/test_{index}.py" for index in range(939)],
+ )
+
+
+def test_spotlight_caps_the_importer_list(jinja_env, widely_imported_spotlight_ctx):
+ """An unbounded list pushed the page past what the embedder accepts.
+
+ ``EMBED_TEXT_MAX_CHARS`` is 30,000 and the tail past it is dropped from the
+ vector, so the page stayed searchable only by its first few hundred
+ importers. The bound is the one ``file_page.j2`` already applies to the
+ same data.
+ """
+ result = render(jinja_env, "symbol_spotlight.j2", widely_imported_spotlight_ctx)
+
+ listed = re.findall(r"^- `tests/unit/test_\d+\.py`$", result, re.M)
+ assert len(listed) == 25
+ assert "and 914 more." in result
+ assert len(result) < 30_000
+
+
+def test_spotlight_reports_the_true_importer_count_above_the_capped_list(
+ jinja_env, widely_imported_spotlight_ctx
+):
+ """Truncating the list must not truncate the fact.
+
+ The summary sentence is the only place the real number survives, so it
+ counts every importer even though 25 are shown.
+ """
+ result = render(jinja_env, "symbol_spotlight.j2", widely_imported_spotlight_ctx)
+ assert "939 files import the module" in result
+
+
def test_spotlight_still_describes_a_symbol_that_has_no_docstring(
jinja_env, unimported_spotlight_ctx
):