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): add the questions block the tests already assert (#1210)

Swati Ahuja752f395b48e6
diff --git a/packages/core/src/repowise/core/generation/templates/file_page.j2 b/packages/core/src/repowise/core/generation/templates/file_page.j2
index f3688fc57..7882b13c5 100644
--- a/packages/core/src/repowise/core/generation/templates/file_page.j2
+++ b/packages/core/src/repowise/core/generation/templates/file_page.j2
@@ -70,5 +70,40 @@ Part of the **{{ ctx.community_label }}** module cluster.
**Layer:** {{ ctx.kg_layer_name }}{% if ctx.kg_layer_role %} | **Role:** {{ ctx.kg_layer_role }}{% endif %}
{%- endif %}
{%- endif %}
+{#- Question-shaped text, built from structure rather than prose.
+
+ Every search query is a question and this page is a declarative reference,
+ so the two share almost no vocabulary. The identifiers are the whole point:
+ thousands of file pages asking the same question differ only in the file
+ and symbol they name, and without those they would be one sentence
+ repeated across the corpus, matching everything and distinguishing nothing.
+
+ A question is emitted only where the page can answer it. A question whose
+ answer is not below it puts the words of a promise into the index and then
+ breaks it, which is the failure this block exists to avoid. Last on the
+ page so it cannot become the summary ``_extract_summary`` reads back.
+
+ Built as a list and capped, because a fully-connected file qualifies for
+ more of them than are worth carrying: past three the block stops being
+ question-shaped text and starts being padding on every page in the corpus.
+-#}
+{%- set questions = [] -%}
+{%- if public_syms -%}
+{%- set _ = questions.append("What does `" ~ ctx.file_path ~ "` export?") -%}
+{%- set _ = questions.append("Where is `" ~ public_syms[0].name ~ "` defined?") -%}
+{%- endif -%}
+{%- if ctx.dependents -%}
+{%- set _ = questions.append("What imports `" ~ ctx.file_path ~ "`?") -%}
+{%- endif -%}
+{%- if ctx.dependencies -%}
+{%- set _ = questions.append("What does `" ~ ctx.file_path ~ "` depend on?") -%}
+{%- endif -%}
+{%- if questions %}
+
+## Questions this page answers
+{% for q in questions[:3] %}
+- {{ q }}
+{%- endfor %}
+{%- endif %}
{% include "_footer.j2" %}
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 f7a0ef5ce..5ac5446ba 100644
--- a/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2
+++ b/packages/core/src/repowise/core/generation/templates/symbol_spotlight.j2
@@ -52,5 +52,23 @@
{{ ctx.source_body }}
```
{%- endif %}
+{#- Question-shaped text, built from structure rather than prose. The file
+ page carries the same block; the identifiers are what make it worth
+ anything, since otherwise it is one sentence repeated across the corpus.
+
+ This context is thinner than the file page's: no layer, no dependents, no
+ dependencies. And ``callers`` holds files importing the defining module,
+ not verified call sites, so "what calls this?" is a question this page
+ cannot honestly ask. Two it can always answer, plus one when there are
+ importers — fewer than the file page, and honest rather than padded.
+#}
+
+## Questions this page answers
+
+- Where is `{{ ctx.symbol_name }}` defined?
+- What is `{{ ctx.qualified_name }}`?
+{%- if ctx.callers %}
+- Which files import the module that defines `{{ ctx.symbol_name }}`?
+{%- endif %}
{% include "_footer.j2" %}