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.

refactor(embeddings): one recipe for every page vector (#1200)

Swati Ahuja72f6e1fae119
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
index 87fe52422..ef9eea32e 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
@@ -548,19 +548,34 @@ def _run_repo_checks(
from sqlalchemy import select
from repowise.core.persistence.models import Page
+ from repowise.core.persistence.vector_store import embed_item
rows = await session.execute(
select(Page).where(Page.id.in_(list(missing_from_vector)))
)
for page in rows.scalars().all():
+ if not (page.title or "").strip():
+ # A repair that writes an unfindable row is
+ # not a repair. Leave it reported as missing
+ # rather than filling the gap with a vector
+ # no search can reach by name.
+ console.print(
+ f" [yellow]Skipped {page.id}: no title to "
+ f"index it by.[/yellow]"
+ )
+ continue
+ # Same recipe as generation and ``reindex``, so a
+ # repaired page is comparable with its neighbours
+ # instead of being embedded on different terms.
await vs.embed_and_upsert(
- page.id,
- page.content,
- {
- "title": page.title,
- "page_type": page.page_type,
- "target_path": page.target_path,
- },
+ *embed_item(
+ page.id,
+ title=page.title,
+ page_type=page.page_type or "",
+ target_path=page.target_path or "",
+ summary=page.summary or "",
+ content=page.content or "",
+ )
)
repaired += 1
diff --git a/packages/cli/src/repowise/cli/commands/reindex_cmd.py b/packages/cli/src/repowise/cli/commands/reindex_cmd.py
index 6693fb3ca..98b28d703 100644
--- a/packages/cli/src/repowise/cli/commands/reindex_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/reindex_cmd.py
@@ -112,6 +112,10 @@ async def _reindex(repo_path, embedder_name: str, batch_size: int) -> None:
return
# --- Embed and upsert pages in batches ---
+ # The recipe is shared with generation and ``doctor --repair`` so a page
+ # reindexed here gets the same vector it would have got from any of them.
+ from repowise.core.persistence.vector_store import embed_item
+
indexed = 0
failed = 0
@@ -160,18 +164,27 @@ async def _reindex(repo_path, embedder_name: str, batch_size: int) -> None:
batch = pages[i : i + batch_size]
items = []
for page in batch:
- text = f"{page.title}\n{page.content}" if page.content else page.title or ""
- if not text.strip():
- continue # embedders reject empty input; nothing to index
+ if not (page.title or "").strip():
+ # The shared recipe refuses a blank title, and it is right
+ # to: the row would be unfindable by name. Here that must
+ # not abort a whole reindex over one bad row, so the page
+ # is skipped and counted like any other failure.
+ failed += 1
+ warned += 1
+ if warned <= 3:
+ console.print(
+ f"[yellow] Warning: skipped {page.id}: no title to index it by"
+ "[/yellow]"
+ )
+ continue
items.append(
- (
+ embed_item(
page.id,
- text,
- {
- "title": page.title or "",
- "page_type": page.page_type or "",
- "target_path": page.target_path or "",
- },
+ title=page.title,
+ page_type=page.page_type or "",
+ target_path=page.target_path or "",
+ summary=page.summary or "",
+ content=page.content or "",
)
)
await _embed_slice(items)
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 6ba5032ff..57fad1c01 100644
--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
@@ -18,6 +18,7 @@ from typing import TYPE_CHECKING, Any
import structlog
+from ...persistence.vector_store import embed_item
from ..context_assembler import FilePageContext
from ..models import (
STRUCTURALLY_KEYED_PAGE_TYPES,
@@ -904,18 +905,22 @@ def _embed_item(page: GeneratedPage) -> tuple[str, str, dict]:
(as this did until 2026-07) left every page embedded at generation time
with a blank title, while ``reindex`` and ``doctor --repair`` set it, so
the store disagreed with itself depending on how a page got there.
+
+ The recipe itself is shared with those two commands rather than repeated
+ here, which is what stops that class of disagreement recurring.
+
+ ``page.summary`` and not a summary derived here: it is the same field the
+ full-text index is given, so both arms describe a page the same way. The
+ two used to differ, and a page's summary then depended on which arm you
+ asked.
"""
- summary = overview_summary(page.content)
- return (
+ return embed_item(
page.page_id,
- page.content,
- {
- "title": page.title,
- "page_type": page.page_type,
- "target_path": page.target_path,
- "content": page.content[:600],
- "summary": summary,
- },
+ title=page.title,
+ page_type=page.page_type,
+ target_path=page.target_path,
+ summary=page.summary,
+ content=page.content,
)
diff --git a/packages/core/src/repowise/core/persistence/vector_store/__init__.py b/packages/core/src/repowise/core/persistence/vector_store/__init__.py
index 84716d669..9c7ec11a0 100644
--- a/packages/core/src/repowise/core/persistence/vector_store/__init__.py
+++ b/packages/core/src/repowise/core/persistence/vector_store/__init__.py
@@ -26,7 +26,7 @@ to avoid one embedding round-trip per page; the single-item
from __future__ import annotations
-from ._base import VectorStore, cosine_similarity
+from ._base import VectorStore, cosine_similarity, embed_item
from .in_memory import InMemoryVectorStore
from .lancedb_store import LanceDBVectorStore
from .pgvector_store import PgVectorStore
@@ -37,4 +37,5 @@ __all__ = [
"PgVectorStore",
"VectorStore",
"cosine_similarity",
+ "embed_item",
]
diff --git a/packages/core/src/repowise/core/persistence/vector_store/_base.py b/packages/core/src/repowise/core/persistence/vector_store/_base.py
index a038bd1fd..ff993b33e 100644
--- a/packages/core/src/repowise/core/persistence/vector_store/_base.py
+++ b/packages/core/src/repowise/core/persistence/vector_store/_base.py
@@ -18,8 +18,10 @@ from ..search import SearchResult
__all__ = [
"EMBED_BATCH_MAX_ITEMS",
"EMBED_TEXT_MAX_CHARS",
+ "STORED_SNIPPET_CHARS",
"VectorStore",
"cosine_similarity",
+ "embed_item",
"iter_embed_chunks",
]
@@ -38,6 +40,68 @@ EMBED_BATCH_MAX_ITEMS = 16
# ~8,192 tokens, and one oversized page must not sink its whole chunk.
EMBED_TEXT_MAX_CHARS = 30_000
+# How much of a page's content a vector row keeps for its evidence snippet.
+#
+# Defined here rather than in a backend because it belongs to the item every
+# backend is handed, not to any one store: a row can only ever show what the
+# recipe put in front of it, so a store that cuts at a width the recipe never
+# reaches is cutting nothing. That is what happened when this widened — the
+# store raised its ceiling while the recipe still handed it 600 characters,
+# and on the paths that passed no content at all, an empty string.
+STORED_SNIPPET_CHARS = 2_000
+
+
+def embed_item(
+ page_id: str,
+ *,
+ title: str,
+ page_type: str,
+ target_path: str,
+ summary: str,
+ content: str,
+) -> tuple[str, str, dict]:
+ """Build the one ``(page_id, text, metadata)`` item every writer embeds.
+
+ Four things write vectors for a page — generation, ``reindex``,
+ ``doctor --repair`` and the hosted indexer — and until now each built its
+ own text. One embedded the content alone, one prefixed the title, one
+ passed neither summary nor path. A vector was therefore not comparable
+ with another vector: whether a page could be found by its own name
+ depended on which command last wrote it, and nothing anywhere reported
+ the difference.
+
+ The text carries all four fields because each answers a question the
+ others cannot. ``target_path`` is the strongest one: a page about
+ ``search.py`` has no idea it is about ``search.py`` unless its prose
+ happens to say so, and prose usually does not repeat its own filename.
+
+ ``title`` is required. A page with no title is not a page whose title is
+ empty — it is a writer that lost it, and the row it produces looks
+ healthy while being unfindable by name, so this raises rather than
+ storing it. The other three may legitimately be empty (some page types
+ have no summary; a repository-wide page has no path).
+ """
+ if not title.strip():
+ raise ValueError(
+ f"embed_item: page {page_id!r} has no title. A blank title writes a "
+ f"vector that cannot be found by name and reports nothing wrong; "
+ f"pass the page's real title."
+ )
+ parts = [p for p in (title, target_path, summary, content) if p]
+ return (
+ page_id,
+ "\n".join(parts),
+ {
+ "title": title,
+ "page_type": page_type,
+ "target_path": target_path,
+ "summary": summary,
+ # Wide enough for a store to cut an evidence window out of, and a
+ # prefix rather than the page so a large corpus is not held twice.
+ "content": content[:STORED_SNIPPET_CHARS],
+ },
+ )
+
def iter_embed_chunks(
items: list[tuple[str, str, dict]],
diff --git a/packages/core/src/repowise/core/persistence/vector_store/lancedb_store.py b/packages/core/src/repowise/core/persistence/vector_store/lancedb_store.py
index 24e354653..2775aaec3 100644
--- a/packages/core/src/repowise/core/persistence/vector_store/lancedb_store.py
+++ b/packages/core/src/repowise/core/persistence/vector_store/lancedb_store.py
@@ -5,24 +5,21 @@ from __future__ import annotations
from repowise.core.providers.embedding.base import Embedder
from ..search import _SNIPPET_LEN, SearchResult, snippet_around
-from ._base import VectorStore, iter_embed_chunks
+from ._base import STORED_SNIPPET_CHARS, VectorStore, iter_embed_chunks
__all__ = ["STORED_SNIPPET_CHARS", "LanceDBVectorStore"]
-# How much of a page's content each row keeps.
+# ``STORED_SNIPPET_CHARS`` — how much of a page's content each row keeps — is
+# defined with the embed recipe and re-exported here so the historical import
+# path keeps working.
#
# A hit's evidence snippet should show the region the query matched, not the
-# page's opening line — on a generated page that opener is the same
+# page's opening line: on a generated page that opener is the same
# ``## Overview`` paragraph every time. The full-text arm holds the whole page
# at search time and can cut a window from it; this arm cannot, because what a
# search sees was fixed when the row was written. So the row keeps enough
-# content for a window to exist inside it.
-#
-# It is a prefix, not the whole page: this column is read on the hot path and
-# duplicated per row, and a match beyond the first few thousand characters is
-# rare enough not to be worth the store. A row written before this widening
+# content for a window to exist inside it. A row written before the widening
# holds 200 characters and simply windows to its opener.
-STORED_SNIPPET_CHARS = 2_000
def _evidence(stored: str, query: str | None) -> str:
diff --git a/tests/unit/cli/test_doctor_embed_recipe.py b/tests/unit/cli/test_doctor_embed_recipe.py
new file mode 100644
index 000000000..e623b5670
--- /dev/null
+++ b/tests/unit/cli/test_doctor_embed_recipe.py
@@ -0,0 +1,168 @@
+"""``doctor --repair`` re-embeds a missing page on the shared recipe.
+
+It used to embed the bare content with neither the page's path nor its
+summary, so a page whose vector this command restored came back weaker than
+its neighbours — findable by fewer things than the page next to it, with the
+store reporting itself repaired.
+
+The repair runs deep inside ``_run_repo_checks``, so this drives the whole
+command against a real store rather than reaching for the closure: a test
+that cannot see the repair actually fire is not evidence the repair changed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from repowise.cli.commands.doctor_cmd import repo_checks
+from repowise.core.persistence.vector_store import embed_item
+
+PAGE_IN_STORE = "file_page:kept.py"
+PAGE_MISSING = "file_page:packages/core/search.py"
+
+
+class _RecordingStore:
+ """Stands in for the store the repair writes through."""
+
+ def __init__(self) -> None:
+ self.items: list[tuple[str, str, dict]] = []
+
+ async def embed_and_upsert(self, page_id: str, text: str, meta: dict) -> None:
+ self.items.append((page_id, text, meta))
+
+ async def delete(self, page_id: str) -> None:
+ return None
+
+ async def close(self) -> None:
+ return None
+
+
+async def _build_repo(tmp_path: Path, *, missing_title: str) -> Path:
+ """A repo whose store holds one page and whose database holds two.
+
+ The reconciliation only reports a missing page when the store is
+ non-empty — an empty store reads as "not indexed yet", not as drift — so
+ the kept page is what makes the missing one visible.
+ """
+ import git as gitpython
+
+ from repowise.core.persistence import create_engine, create_session_factory, get_session
+ from repowise.core.persistence.crud import upsert_page, upsert_repository
+ from repowise.core.persistence.database import init_db
+ from repowise.core.persistence.vector_store import LanceDBVectorStore
+ from repowise.core.providers.embedding.base import MockEmbedder
+
+ # Resolved: on macOS tmp_path is a symlink, and the command looks the
+ # repository up by the path it resolves to. An unresolved local_path
+ # simply finds no repository and every reconciliation returns empty.
+ repo_path = (tmp_path / "repo").resolve()
+ repo_path.mkdir()
+ gitpython.Repo.init(repo_path)
+ repowise_dir = repo_path / ".repowise"
+ repowise_dir.mkdir()
+
+ engine = create_engine(f"sqlite+aiosqlite:///{repowise_dir / 'wiki.db'}")
+ await init_db(engine)
+ sf = create_session_factory(engine)
+ async with get_session(sf) as session:
+ repo = await upsert_repository(
+ session, name="repo", local_path=str(repo_path), url="https://example.test/repo"
+ )
+ common = {
+ "repository_id": repo.id,
+ "page_type": "file_page",
+ "source_hash": "",
+ "model_name": "mock",
+ "provider_name": "mock",
+ }
+ await upsert_page(
+ session,
+ page_id=PAGE_IN_STORE,
+ title="File: kept.py",
+ content="Kept.",
+ summary="",
+ target_path="kept.py",
+ **common,
+ )
+ await upsert_page(
+ session,
+ page_id=PAGE_MISSING,
+ title=missing_title,
+ content="## Overview\n\nBuilds the query and ranks the rows.",
+ summary="Full-text search over the wiki index.",
+ target_path="packages/core/search.py",
+ **common,
+ )
+ await session.commit()
+ await engine.dispose()
+
+ # The real store, holding only the kept page.
+ store = LanceDBVectorStore(str(repowise_dir / "lancedb"), embedder=MockEmbedder())
+ await store.embed_and_upsert(PAGE_IN_STORE, "Kept.", {"title": "File: kept.py"})
+ await store.close()
+
+ return repo_path
+
+
+def repair(monkeypatch):
+ """Run ``doctor --repair`` over the fixture repo; return what it embedded.
+
+ Synchronous on purpose: the command drives its own event loop, so calling
+ it from inside one raises before a single check runs.
+ """
+
+ def _run(repo_path: Path) -> _RecordingStore:
+ recorder = _RecordingStore()
+ monkeypatch.setattr("repowise.cli.providers.resolve_embedder_for_repo", lambda _p: "mock")
+ monkeypatch.setattr("repowise.cli.providers.build_embedder", lambda _n: object())
+ monkeypatch.setattr("repowise.cli.providers.build_vector_store", lambda _p, _e: recorder)
+ repo_checks._run_repo_checks(Path(repo_path), repair=True)
+ return recorder
+
+ return _run
+
+
+def test_the_repair_embeds_the_shared_recipe(tmp_path: Path, repair) -> None:
+ repo_path = asyncio.run(_build_repo(tmp_path, missing_title="File: packages/core/search.py"))
+
+ recorder = repair(repo_path)
+
+ assert recorder.items == [
+ embed_item(
+ PAGE_MISSING,
+ title="File: packages/core/search.py",
+ page_type="file_page",
+ target_path="packages/core/search.py",
+ summary="Full-text search over the wiki index.",
+ content="## Overview\n\nBuilds the query and ranks the rows.",
+ )
+ ]
+
+
+def test_the_repaired_vector_carries_the_path_and_summary(tmp_path: Path, repair) -> None:
+ """Named directly, so the assertion does not rest on the helper alone."""
+ repo_path = asyncio.run(_build_repo(tmp_path, missing_title="File: packages/core/search.py"))
+
+ recorder = repair(repo_path)
+
+ _pid, text, meta = recorder.items[0]
+ assert "packages/core/search.py" in text
+ assert "Full-text search over the wiki index." in text
+ assert meta["summary"] == "Full-text search over the wiki index."
+
+
+def test_a_titleless_page_is_left_reported_missing(tmp_path: Path, repair) -> None:
+ """A repair that writes an unfindable row is not a repair.
+
+ Better to leave the page reported as missing, where the next run says so
+ again, than to fill the gap with a vector no search can reach by name.
+ """
+ repo_path = asyncio.run(_build_repo(tmp_path, missing_title=""))
+
+ recorder = repair(repo_path)
+
+ assert recorder.items == []
diff --git a/tests/unit/cli/test_embedder_resolution.py b/tests/unit/cli/test_embedder_resolution.py
index c511dfc6e..8a25e1826 100644
--- a/tests/unit/cli/test_embedder_resolution.py
+++ b/tests/unit/cli/test_embedder_resolution.py
@@ -213,6 +213,9 @@ async def test_reindex_persists_its_resolved_embedder(
content = "hello"
page_type = "file_page"
target_path = "a.py"
+ # Non-nullable on the real model, so a stand-in that omits it is a
+ # stand-in for a page that cannot exist.
+ summary = "what a.py does"
class _Result:
def __init__(self, rows: list) -> None:
diff --git a/tests/unit/cli/test_reindex_embed_recipe.py b/tests/unit/cli/test_reindex_embed_recipe.py
new file mode 100644
index 000000000..03349d312
--- /dev/null
+++ b/tests/unit/cli/test_reindex_embed_recipe.py
@@ -0,0 +1,187 @@
+"""``reindex`` writes the same vector generation would have written.
+
+It used to build its own text — the title, a newline, the content — while
+generation embedded the content alone and neither carried the page's path or
+summary. Reindexing a wiki therefore changed what its vectors meant, and
+nothing reported it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from repowise.cli.commands import reindex_cmd
+from repowise.core.persistence.vector_store import embed_item
+
+
+class _DummyEngine:
+ async def dispose(self) -> None:
+ return None
+
+
+class _Page:
+ def __init__(self, **kw: Any) -> None:
+ self.__dict__.update(kw)
+
+
+class _Result:
+ def __init__(self, rows: list[Any]) -> None:
+ self._rows = rows
+
+ def scalars(self) -> _Result:
+ return self
+
+ def all(self) -> list[Any]:
+ return self._rows
+
+
+class _Session:
+ """Serves the page rows on the first query and nothing after.
+
+ ``_reindex`` opens one session for pages and another for decision
+ records, so the counter is shared across sessions rather than held per
+ session — otherwise the pages come back a second time as decisions.
+ """
+
+ def __init__(self, rows: list[Any], state: dict) -> None:
+ self._rows = rows
+ self._state = state
+
+ async def __aenter__(self) -> _Session:
+ return self
+
+ async def __aexit__(self, *args: object) -> None:
+ return None
+
+ async def execute(self, _stmt: object) -> _Result:
+ self._state["calls"] = self._state.get("calls", 0) + 1
+ return _Result(self._rows if self._state["calls"] == 1 else [])
+
+
+class _RecordingStore:
+ """Captures the items handed to the store instead of embedding them."""
+
+ def __init__(self, *args: object, **kwargs: object) -> None:
+ self.items: list[tuple[str, str, dict]] = []
+
+ async def embed_batch(self, items: list[tuple[str, str, dict]]) -> None:
+ self.items.extend(items)
+
+ async def embed_and_upsert(self, page_id: str, text: str, meta: dict) -> None:
+ self.items.append((page_id, text, meta))
+
+ async def close(self) -> None:
+ return None
+
+
+def run_reindex(monkeypatch, tmp_path: Path):
+ """Run ``_reindex`` over *rows* and return the store that recorded it."""
+
+ async def _run(rows: list[Any]) -> _RecordingStore:
+ store = _RecordingStore()
+
+ state: dict = {}
+
+ def sessionmaker(*_a: object, **_kw: object):
+ return lambda: _Session(rows, state)
+
+ monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+ monkeypatch.setattr(
+ reindex_cmd, "get_db_url_for_repo", lambda _p: "sqlite+aiosqlite:///:memory:"
+ )
+ monkeypatch.setattr(
+ "repowise.core.persistence.database.create_engine", lambda _url: _DummyEngine()
+ )
+
+ async def _noop(_engine: object) -> None:
+ return None
+
+ monkeypatch.setattr("repowise.core.persistence.database.init_db", _noop)
+ monkeypatch.setattr("sqlalchemy.ext.asyncio.async_sessionmaker", sessionmaker)
+ monkeypatch.setattr(
+ "repowise.core.persistence.vector_store.LanceDBVectorStore",
+ lambda *a, **kw: store,
+ )
+
+ await reindex_cmd._reindex(tmp_path, "openai", batch_size=20)
+ return store
+
+ return _run
+
+
+async def test_reindex_embeds_the_shared_recipe(run_reindex) -> None:
+ page = _Page(
+ id="file_page:packages/core/search.py",
+ title="File: packages/core/search.py",
+ page_type="file_page",
+ target_path="packages/core/search.py",
+ summary="Full-text search over the wiki index.",
+ content="## Overview\n\nBuilds the query and ranks the rows.",
+ )
+
+ store = await run_reindex([page])
+
+ assert store.items == [
+ embed_item(
+ page.id,
+ title=page.title,
+ page_type=page.page_type,
+ target_path=page.target_path,
+ summary=page.summary,
+ content=page.content,
+ )
+ ]
+
+
+async def test_reindex_carries_the_path_and_summary_into_the_text(run_reindex) -> None:
+ """The two fields it never used to pass, named directly.
+
+ Asserting equality against the helper alone would still pass if the
+ helper itself dropped them.
+ """
+ page = _Page(
+ id="file_page:a/b/widget.py",
+ title="File: a/b/widget.py",
+ page_type="file_page",
+ target_path="a/b/widget.py",
+ summary="Draws the widget.",
+ content="Body with neither word in it.",
+ )
+
+ store = await run_reindex([page])
+
+ _pid, text, meta = store.items[0]
+ assert "a/b/widget.py" in text
+ assert "Draws the widget." in text
+ assert meta["summary"] == "Draws the widget."
+
+
+async def test_a_titleless_page_is_skipped_not_indexed(run_reindex) -> None:
+ """One unusable row must not abort a whole reindex, and must not be
+ written either: a vector with no title cannot be found by name."""
+ rows = [
+ _Page(
+ id="file_page:nameless.py",
+ title="",
+ page_type="file_page",
+ target_path="nameless.py",
+ summary="",
+ content="Body.",
+ ),
+ _Page(
+ id="file_page:fine.py",
+ title="File: fine.py",
+ page_type="file_page",
+ target_path="fine.py",
+ summary="",
+ content="Body.",
+ ),
+ ]
+
+ store = await run_reindex(rows)
+
+ assert [item[0] for item in store.items] == ["file_page:fine.py"]
diff --git a/tests/unit/persistence/test_embed_recipe.py b/tests/unit/persistence/test_embed_recipe.py
new file mode 100644
index 000000000..01bea2e33
--- /dev/null
+++ b/tests/unit/persistence/test_embed_recipe.py
@@ -0,0 +1,192 @@
+"""One embed recipe, shared by everything that writes a page's vector.
+
+Four commands write vectors for a wiki page — generation, ``reindex``,
+``doctor --repair`` and the hosted indexer — and each used to build its own
+text. One embedded the content alone, one prefixed the title, none carried
+the path or the summary. A vector was therefore not comparable with another
+vector: whether a page could be found by its own name depended on which
+command last wrote it, and nothing reported the difference.
+
+These pin the recipe itself and then pin each caller to it, because a shared
+helper that one caller quietly stops using is the same bug again.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.persistence.vector_store import embed_item
+from repowise.core.persistence.vector_store._base import STORED_SNIPPET_CHARS
+
+PAGE = {
+ "page_id": "file_page:packages/core/search.py",
+ "title": "File: packages/core/search.py",
+ "page_type": "file_page",
+ "target_path": "packages/core/search.py",
+ "summary": "Full-text search over the wiki index.",
+ "content": "## Overview\n\nBuilds the query and ranks the rows.",
+}
+
+
+def test_the_recipe_is_title_then_path_then_summary_then_content():
+ """Pinned byte for byte — the text is the whole product of this helper."""
+ page_id, text, _meta = embed_item(
+ PAGE["page_id"], **{k: v for k, v in PAGE.items() if k != "page_id"}
+ )
+
+ assert page_id == "file_page:packages/core/search.py"
+ assert text == (
+ "File: packages/core/search.py\n"
+ "packages/core/search.py\n"
+ "Full-text search over the wiki index.\n"
+ "## Overview\n\nBuilds the query and ranks the rows."
+ )
+
+
+def test_the_path_reaches_the_vector():
+ """The reason the path is in the text at all.
+
+ A page about ``search.py`` has no idea it is about ``search.py`` unless
+ its prose happens to say so, and prose rarely repeats its own filename.
+ """
+ _pid, text, _meta = embed_item(
+ "file_page:a/b/widget.py",
+ title="File: a/b/widget.py",
+ page_type="file_page",
+ target_path="a/b/widget.py",
+ summary="",
+ content="This module does a thing.",
+ )
+
+ assert "a/b/widget.py" in text
+ assert "widget.py" not in "This module does a thing."
+
+
+def test_an_absent_field_leaves_no_blank_line():
+ """Empty fields drop out rather than padding the text with separators.
+
+ Two pages with the same words must embed to the same string whether or
+ not one of them happens to carry a summary.
+ """
+ _pid, text, _meta = embed_item(
+ "repo_overview:repowise",
+ title="Overview",
+ page_type="repo_overview",
+ target_path="",
+ summary="",
+ content="Body.",
+ )
+
+ assert text == "Overview\nBody."
+
+
+def test_a_blank_title_raises():
+ """A titleless row looks healthy and cannot be found by name.
+
+ Accepting it writes a vector whose only defect shows up as an absence in
+ someone's search results months later, which is why this is a raise and
+ not a warning.
+ """
+ with pytest.raises(ValueError, match="no title"):
+ embed_item(
+ "file_page:a.py",
+ title=" ",
+ page_type="file_page",
+ target_path="a.py",
+ summary="",
+ content="Body.",
+ )
+
+
+def test_the_metadata_carries_every_field_a_store_reads():
+ _pid, _text, meta = embed_item(
+ PAGE["page_id"], **{k: v for k, v in PAGE.items() if k != "page_id"}
+ )
+
+ assert meta == {
+ "title": "File: packages/core/search.py",
+ "page_type": "file_page",
+ "target_path": "packages/core/search.py",
+ "summary": "Full-text search over the wiki index.",
+ "content": "## Overview\n\nBuilds the query and ranks the rows.",
+ }
+
+
+def test_the_stored_content_is_wide_enough_for_an_evidence_window():
+ """The store cuts at ``STORED_SNIPPET_CHARS``; the recipe must reach it.
+
+ A store that keeps 2,000 characters of a page it was only ever handed 600
+ of keeps 600. The widening is only real if the recipe hands over that
+ much, which is what this pins.
+ """
+ _pid, _text, meta = embed_item(
+ "file_page:big.py",
+ title="File: big.py",
+ page_type="file_page",
+ target_path="big.py",
+ summary="",
+ content="y" * (STORED_SNIPPET_CHARS + 500),
+ )
+
+ assert len(meta["content"]) == STORED_SNIPPET_CHARS
+
+
+def test_generation_produces_exactly_the_shared_recipe():
+ from repowise.core.generation.models import GeneratedPage
+ from repowise.core.generation.page_generator.orchestrate import _embed_item
+
+ page = GeneratedPage(
+ page_id=PAGE["page_id"],
+ page_type=PAGE["page_type"],
+ title=PAGE["title"],
+ content=PAGE["content"],
+ source_hash="",
+ model_name="mock",
+ provider_name="mock",
+ input_tokens=0,
+ output_tokens=0,
+ cached_tokens=0,
+ generation_level=1,
+ target_path=PAGE["target_path"],
+ created_at="2026-01-01T00:00:00Z",
+ updated_at="2026-01-01T00:00:00Z",
+ summary=PAGE["summary"],
+ )
+
+ assert _embed_item(page) == embed_item(
+ PAGE["page_id"], **{k: v for k, v in PAGE.items() if k != "page_id"}
+ )
+
+
+def test_generation_embeds_the_summary_the_index_was_given():
+ """Both arms must describe a page the same way.
+
+ Generation used to derive its own summary for the vector while the
+ full-text index was given ``page.summary``. The two differ, so a page's
+ summary depended on which arm you asked.
+ """
+ from repowise.core.generation.models import GeneratedPage
+ from repowise.core.generation.page_generator.orchestrate import _embed_item
+
+ page = GeneratedPage(
+ page_id="file_page:a.py",
+ page_type="file_page",
+ title="File: a.py",
+ content="## Overview\n\nSomething else entirely.",
+ source_hash="",
+ model_name="mock",
+ provider_name="mock",
+ input_tokens=0,
+ output_tokens=0,
+ cached_tokens=0,
+ generation_level=1,
+ target_path="a.py",
+ created_at="2026-01-01T00:00:00Z",
+ updated_at="2026-01-01T00:00:00Z",
+ summary="The stored summary.",
+ )
+
+ _pid, text, meta = _embed_item(page)
+
+ assert "The stored summary." in text
+ assert meta["summary"] == "The stored summary."