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.

feat(embeddings): a page below the information floor gets no vector (#1203)

Swati Ahujae20fdab1cee5
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 ef9eea32e..86a838baf 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
@@ -228,6 +228,9 @@ def _run_repo_checks(
get_session,
list_pages,
)
+ from repowise.core.persistence.information_floor import (
+ meets_information_floor,
+ )
from repowise.core.persistence.vector_store import (
LanceDBVectorStore,
)
@@ -260,6 +263,18 @@ def _run_repo_checks(
# match text, swallowed embed failure) and repair cannot
# re-embed it, so flagging it would be permanent noise.
vector_sql_ids = sql_ids | await _decision_vector_ids(session, repo.id)
+ # A page below the information floor is held out of both
+ # indexes on purpose, so its absence is the correct state
+ # and not drift. Without this it is reported missing on
+ # every run and ``--repair`` cannot fix it, because the
+ # repair applies the same rule and declines — the same
+ # permanent-noise argument the decision namespace is
+ # excluded for, one line above. It stays on the ORPHAN
+ # side: a stored vector for a page now below the floor is
+ # real drift, and deleting it is a repair that works.
+ indexable_ids = {
+ p.id for p in pages if meets_information_floor(p.content or "")
+ }
# Check vector store
vs_ids: set[str] = set()
@@ -273,7 +288,7 @@ def _run_repo_checks(
except Exception:
pass # LanceDB not available
- m_vec = sql_ids - vs_ids if vs_ids else set()
+ m_vec = indexable_ids - vs_ids if vs_ids else set()
o_vec = vs_ids - vector_sql_ids if vs_ids else set()
# Check FTS
@@ -282,7 +297,7 @@ def _run_repo_checks(
fts_ids = await fts.list_indexed_ids()
except Exception:
fts_ids = set()
- m_fts = sql_ids - fts_ids if fts_ids else set()
+ m_fts = indexable_ids - fts_ids if fts_ids else set()
o_fts = fts_ids - sql_ids if fts_ids else set()
await engine.dispose()
@@ -567,16 +582,25 @@ def _run_repo_checks(
# 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(
- *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 "",
- )
+ item = 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 "",
)
+ if item is None:
+ # Below the information floor, so its absence
+ # from the store is correct and there is
+ # nothing to repair. Said out loud, because a
+ # page silently left missing by the repair
+ # reads as the repair having failed on it.
+ console.print(
+ f" [dim]Left out {page.id}: too thin to index.[/dim]"
+ )
+ continue
+ await vs.embed_and_upsert(*item)
repaired += 1
for pid in orphaned_vector:
diff --git a/packages/cli/src/repowise/cli/commands/reindex_cmd.py b/packages/cli/src/repowise/cli/commands/reindex_cmd.py
index 98b28d703..70848452e 100644
--- a/packages/cli/src/repowise/cli/commands/reindex_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/reindex_cmd.py
@@ -118,6 +118,7 @@ async def _reindex(repo_path, embedder_name: str, batch_size: int) -> None:
indexed = 0
failed = 0
+ below_floor = 0
with Progress(
SpinnerColumn(spinner_name=OWL_SPINNER, style=BRAND_STYLE),
@@ -177,16 +178,22 @@ async def _reindex(repo_path, embedder_name: str, batch_size: int) -> None:
"[/yellow]"
)
continue
- items.append(
- 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 "",
- )
+ item = 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 "",
)
+ if item is None:
+ # Below the information floor. Not a failure — the page is
+ # deliberately kept out of the index and is counted apart
+ # from the ones that broke, because a reindex reporting
+ # them together would read as an embedder losing rows.
+ below_floor += 1
+ continue
+ items.append(item)
await _embed_slice(items)
progress.advance(task, advance=len(batch))
@@ -234,5 +241,10 @@ async def _reindex(repo_path, embedder_name: str, batch_size: int) -> None:
console.print(
f"\n[bold green]Done![/bold green] Indexed {indexed} items"
+ (f" ({failed} failed)" if failed else "")
+ # Named separately from failures, and only when it happened: a count
+ # folded into "failed" would read as an embedder losing rows, and a
+ # standing "0 held back" would read as a problem on every run that
+ # never had one.
+ + (f" ({below_floor} held back as too thin to index)" if below_floor else "")
+ f" -> {lance_dir}"
)
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 c3f20b44f..ca67ef987 100644
--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
@@ -614,7 +614,14 @@ class _GenerationRun:
and getattr(self.vector_store, "persists_across_runs", False)
)
):
- embed_items.append(_embed_item(result))
+ # None below the information floor: the page is kept and
+ # still resolves as a link target, it just gets no
+ # vector. ``embed_item`` tallies those itself, so the
+ # run can report how much it held back instead of
+ # leaving the index quietly smaller than the wiki.
+ item = _embed_item(result)
+ if item is not None:
+ embed_items.append(item)
return result
except Exception as exc:
if self.job_system is not None and self.job_id is not None:
@@ -911,9 +918,12 @@ def _compute_kg_file_scores(kg_ctx: Any) -> dict[str, float]:
return scores
-def _embed_item(page: GeneratedPage) -> tuple[str, str, dict]:
+def _embed_item(page: GeneratedPage) -> tuple[str, str, dict] | None:
"""Build the ``(page_id, text, metadata)`` tuple for embedding.
+ ``None`` when the page falls below the information floor and should get no
+ vector; the caller counts those rather than embedding them.
+
``title`` is load-bearing, not decoration: it feeds the coverage rerank
haystack and the grounding corpus on the serving side. Omitting it here
(as this did until 2026-07) left every page embedded at generation time
diff --git a/packages/core/src/repowise/core/generation/report.py b/packages/core/src/repowise/core/generation/report.py
index 17d0ed10c..2b71af27b 100644
--- a/packages/core/src/repowise/core/generation/report.py
+++ b/packages/core/src/repowise/core/generation/report.py
@@ -53,6 +53,11 @@ class GenerationReport:
# when the run produced no overview. ``None`` and ``0`` are different
# facts: nothing was measured, versus an overview with nothing in it.
overview_prose_words: int | None = None
+ # Pages this run wrote but did not embed, because they say too little to be
+ # worth one of the fixed number of rows retrieval fetches. The page is
+ # kept and still resolves as a link target; only its vector is withheld.
+ # Zero whenever the information floor is off, which is the default.
+ pages_denied_a_vector: int = 0
@classmethod
def from_pages(
@@ -66,6 +71,7 @@ class GenerationReport:
) -> GenerationReport:
# Deferred: the page generator pulls in the provider stack, and the
# report is importable on its own (the CLI renders it lazily).
+ from ..persistence.information_floor import pages_denied_a_vector
from .page_generator.validation import artifact_check_counts
by_type = dict(Counter(p.page_type for p in pages))
@@ -85,6 +91,7 @@ class GenerationReport:
orientation_overlap=measure_orientation_overlap(pages),
layer_grouping=measure_layer_grouping(pages),
artifact_checks=artifact_check_counts(),
+ pages_denied_a_vector=pages_denied_a_vector(),
overview_prose_words=next(
(
prose_word_count(p.content or "")
diff --git a/packages/core/src/repowise/core/persistence/information_floor.py b/packages/core/src/repowise/core/persistence/information_floor.py
index 976b1e357..64bccb556 100644
--- a/packages/core/src/repowise/core/persistence/information_floor.py
+++ b/packages/core/src/repowise/core/persistence/information_floor.py
@@ -20,9 +20,24 @@ __all__ = [
"INFORMATION_FLOOR_ENV",
"information_floor",
"meets_information_floor",
+ "pages_denied_a_vector",
+ "reset_pages_denied_a_vector",
"substantive_text",
]
+# Pages the embed recipe refused a vector, for the whole process.
+#
+# A run's page count and its vector count differ for several innocent reasons
+# — a resumed run skips pages, a stubbed page is not embedded, a keyless run
+# has no store at all — so an index smaller than its wiki is only readable if
+# the deliberate part of the gap is named. Without this, raising the floor
+# looks exactly like an embedder that quietly dropped work.
+#
+# Process-level rather than threaded through, because the report is built from
+# the page list by a caller that never sees the store. Same shape as the
+# generation artifact-check tallies, which exist for the same reason.
+_pages_denied_a_vector = 0
+
# Chars of substantive prose a page needs before it is worth a search slot.
#
# Zero: off. Nothing is excluded until a value is set, so installing this
@@ -133,6 +148,23 @@ def information_floor() -> int:
return value if value >= 0 else DEFAULT_INFORMATION_FLOOR
+def pages_denied_a_vector() -> int:
+ """How many pages the embed recipe held out of the index this process."""
+ return _pages_denied_a_vector
+
+
+def count_page_denied_a_vector() -> None:
+ """Record one held-back page. Called by the embed recipe, nowhere else."""
+ global _pages_denied_a_vector
+ _pages_denied_a_vector += 1
+
+
+def reset_pages_denied_a_vector() -> None:
+ """Clear the tally. Used between runs and between tests."""
+ global _pages_denied_a_vector
+ _pages_denied_a_vector = 0
+
+
def meets_information_floor(content: str, floor: int | None = None) -> bool:
"""Whether *content* says enough to be worth a slot in the index.
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 ff993b33e..301177d80 100644
--- a/packages/core/src/repowise/core/persistence/vector_store/_base.py
+++ b/packages/core/src/repowise/core/persistence/vector_store/_base.py
@@ -13,6 +13,7 @@ import math
from abc import ABC, abstractmethod
from collections.abc import Iterator
+from ..information_floor import count_page_denied_a_vector, meets_information_floor
from ..search import SearchResult
__all__ = [
@@ -59,9 +60,12 @@ def embed_item(
target_path: str,
summary: str,
content: str,
-) -> tuple[str, str, dict]:
+) -> tuple[str, str, dict] | None:
"""Build the one ``(page_id, text, metadata)`` item every writer embeds.
+ Returns ``None`` when the page says too little to be worth a search slot,
+ which callers skip. See the information floor note below.
+
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
@@ -80,6 +84,20 @@ def embed_item(
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).
+
+ **The information floor.** A page whose content says too little to answer
+ anything gets no vector, and ``None`` comes back instead. The full-text
+ index already applies the same rule, and it has to be the same rule: a
+ page held out of one arm and kept in the other is still fetched, still
+ occupies one of the fixed number of rows retrieval takes before it filters
+ anything, and still displaces a page that could have answered. The test is
+ applied to ``content`` alone for that reason — the same input the
+ full-text side measures, so the two arms cannot disagree about a page.
+
+ The page itself is untouched either way. It stays in ``wiki_pages``, still
+ resolves as a link target, and a reader who arrives at it still learns the
+ file exists. It is only kept out of the index, where its cost is paid by
+ other pages. The floor is 0 by default, which admits everything.
"""
if not title.strip():
raise ValueError(
@@ -87,6 +105,9 @@ def embed_item(
f"vector that cannot be found by name and reports nothing wrong; "
f"pass the page's real title."
)
+ if not meets_information_floor(content):
+ count_page_denied_a_vector()
+ return None
parts = [p for p in (title, target_path, summary, content) if p]
return (
page_id,
diff --git a/tests/unit/cli/test_doctor_information_floor.py b/tests/unit/cli/test_doctor_information_floor.py
new file mode 100644
index 000000000..6662c39ee
--- /dev/null
+++ b/tests/unit/cli/test_doctor_information_floor.py
@@ -0,0 +1,124 @@
+"""``doctor`` does not report a deliberately unindexed page as drift.
+
+A page below the information floor is held out of both indexes on purpose,
+so its absence is the correct state. Counting it as missing makes every run
+report drift that ``--repair`` cannot fix — the repair applies the same rule
+and declines — which is the permanent noise the decision namespace is
+already excluded from the MISSING check to avoid.
+
+It stays on the ORPHAN side. A stored vector for a page that is now below
+the floor is real drift, and deleting it is a repair that works.
+"""
+
+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.information_floor import INFORMATION_FLOOR_ENV
+
+THICK = "file_page:thick.py"
+THIN = "file_page:thin.py"
+
+# Stripped to nothing by the floor: a heading and a metadata strip.
+THIN_BODY = "# thin.py\n\n**Kind:** module | **Defined in:** `thin.py`\n"
+THICK_BODY = (
+ "## Overview\n\n"
+ "Resolves each import against the package manifest before descending, so "
+ "a symlinked workspace member is visited once rather than once per alias "
+ "that reaches it. Cycles break on the real path, never the alias, which "
+ "is why two aliases of one directory cannot both claim to own a module. "
+ "The manifest is read once per package and cached for the walk.\n"
+)
+
+
+async def _build_repo(tmp_path: Path) -> Path:
+ """Both pages in the database; only the thick one in either index."""
+ import git as gitpython
+
+ from repowise.core.persistence import (
+ FullTextSearch,
+ 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
+
+ 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"
+ )
+ for page_id, path, body in (
+ (THICK, "thick.py", THICK_BODY),
+ (THIN, "thin.py", THIN_BODY),
+ ):
+ await upsert_page(
+ session,
+ page_id=page_id,
+ repository_id=repo.id,
+ page_type="file_page",
+ title=f"File: {path}",
+ content=body,
+ summary="",
+ target_path=path,
+ source_hash="",
+ model_name="mock",
+ provider_name="mock",
+ )
+ await session.commit()
+
+ fts = FullTextSearch(engine)
+ await fts.ensure_index()
+ await fts.index(THICK, "File: thick.py", THICK_BODY, summary="", target_path="thick.py")
+ await engine.dispose()
+
+ store = LanceDBVectorStore(str(repowise_dir / "lancedb"), embedder=MockEmbedder())
+ await store.embed_and_upsert(THICK, THICK_BODY, {"title": "File: thick.py"})
+ await store.close()
+
+ return repo_path
+
+
+def _rows(repo_path: Path) -> dict[str, tuple[bool, str]]:
+ _all_ok, checks = repo_checks._run_repo_checks(repo_path, repair=False)
+ return {c.name: (c.ok, c.detail) for c in checks}
+
+
+def test_a_page_below_the_floor_is_not_reported_as_drift(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setenv(INFORMATION_FLOOR_ENV, "300")
+ rows = _rows(asyncio.run(_build_repo(tmp_path)))
+
+ assert rows["SQL ↔ Vector Store"] == (True, "in sync")
+ assert rows["SQL ↔ FTS Index"] == (True, "in sync")
+
+
+def test_the_same_page_is_drift_when_the_floor_is_off(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The exclusion has to follow the floor, not the page.
+
+ With the floor off, that page belongs in both indexes and its absence is
+ ordinary drift the repair can and should fix.
+ """
+ monkeypatch.delenv(INFORMATION_FLOOR_ENV, raising=False)
+ rows = _rows(asyncio.run(_build_repo(tmp_path)))
+
+ assert rows["SQL ↔ Vector Store"] == (False, "1 missing, 0 orphaned")
+ assert rows["SQL ↔ FTS Index"] == (False, "1 missing, 0 orphaned")
diff --git a/tests/unit/generation/test_generation_information_floor.py b/tests/unit/generation/test_generation_information_floor.py
new file mode 100644
index 000000000..ddd7233d2
--- /dev/null
+++ b/tests/unit/generation/test_generation_information_floor.py
@@ -0,0 +1,118 @@
+"""Generation skips the vector for a page below the information floor.
+
+The recipe returning ``None`` is not the fix on its own — the caller acting
+on it is. Generation is the path that writes almost every vector a user ever
+searches, so a caller that appended ``None`` into the embed batch would fail
+at the store instead of holding the page back, and one that ignored the
+return would embed everything exactly as before.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.generation.models import GeneratedPage
+from repowise.core.generation.page_generator.orchestrate import _embed_item
+from repowise.core.generation.report import GenerationReport
+from repowise.core.persistence.information_floor import INFORMATION_FLOOR_ENV
+
+SKELETON = (
+ "# packages.api-client.src.types.graph.GraphLike\n\n"
+ "**Kind:** interface | **Defined in:** `packages/api-client/src/types/graph.ts`\n"
+)
+
+SUBSTANTIAL = (
+ "## Overview\n\n"
+ "Resolves each import against the package manifest before descending, so "
+ "a symlinked workspace member is visited once rather than once per alias "
+ "that reaches it. Cycles break on the real path, never the alias, which "
+ "is why two aliases of one directory cannot both claim to own a module. "
+ "The manifest is read once per package and cached for the walk, because "
+ "re-reading it per import made a large monorepo spend most of the walk in "
+ "the filesystem rather than in the resolver.\n"
+)
+
+
[email protected](autouse=True)
+def _floor_off_by_default(monkeypatch: pytest.MonkeyPatch):
+ """Each test states its own floor rather than inheriting a stray one."""
+ monkeypatch.delenv(INFORMATION_FLOOR_ENV, raising=False)
+
+
+def tally():
+ """The process-wide count of pages held back, cleared around the test.
+
+ Imported inside the fixture, not at module scope, so the two behaviour
+ tests below stay collectable against a build that has no tally — which is
+ what makes their failure read as the change rather than an absent name.
+ """
+ from repowise.core.persistence.information_floor import (
+ pages_denied_a_vector,
+ reset_pages_denied_a_vector,
+ )
+
+ reset_pages_denied_a_vector()
+ yield pages_denied_a_vector
+ reset_pages_denied_a_vector()
+
+
+def _page(page_id: str, content: str) -> GeneratedPage:
+ return GeneratedPage(
+ page_id=page_id,
+ page_type="symbol_spotlight",
+ title=page_id,
+ content=content,
+ source_hash="",
+ model_name="mock",
+ provider_name="mock",
+ input_tokens=0,
+ output_tokens=0,
+ cached_tokens=0,
+ generation_level=1,
+ target_path="packages/api-client/src/types/graph.ts",
+ created_at="2026-01-01T00:00:00Z",
+ updated_at="2026-01-01T00:00:00Z",
+ summary="",
+ )
+
+
+def test_generation_holds_back_a_thin_page(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv(INFORMATION_FLOOR_ENV, "300")
+
+ assert _embed_item(_page("symbol_spotlight:thin", SKELETON)) is None
+
+
+def test_generation_still_embeds_a_real_page(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv(INFORMATION_FLOOR_ENV, "300")
+
+ assert _embed_item(_page("symbol_spotlight:real", SUBSTANTIAL)) is not None
+
+
+def test_the_run_reports_how_many_it_held_back(monkeypatch: pytest.MonkeyPatch, tally):
+ """Otherwise raising the floor is indistinguishable from an embedder
+ quietly dropping work: both leave the index smaller than the wiki."""
+ monkeypatch.setenv(INFORMATION_FLOOR_ENV, "300")
+ pages = [
+ _page("symbol_spotlight:thin-1", SKELETON),
+ _page("symbol_spotlight:thin-2", SKELETON),
+ _page("symbol_spotlight:real", SUBSTANTIAL),
+ ]
+ for page in pages:
+ _embed_item(page)
+
+ report = GenerationReport.from_pages(pages)
+
+ assert report.pages_denied_a_vector == 2
+ # The page itself is untouched: it is in the wiki, it is only out of the
+ # index. A report that dropped it from the page counts would say the run
+ # produced fewer pages than it did.
+ assert sum(report.pages_by_type.values()) == 3
+
+
+def test_the_report_says_zero_when_the_floor_is_off(tally):
+ pages = [_page("symbol_spotlight:thin", SKELETON)]
+ for page in pages:
+ _embed_item(page)
+
+ assert GenerationReport.from_pages(pages).pages_denied_a_vector == 0
diff --git a/tests/unit/persistence/test_embed_recipe_information_floor.py b/tests/unit/persistence/test_embed_recipe_information_floor.py
new file mode 100644
index 000000000..8343890b8
--- /dev/null
+++ b/tests/unit/persistence/test_embed_recipe_information_floor.py
@@ -0,0 +1,129 @@
+"""A page too thin to be worth a search slot gets no vector either.
+
+The full-text index already refuses these. The vector arm has to refuse the
+same ones, and on the same input, or the exclusion does nothing: retrieval
+fetches a fixed number of rows from each arm *before* it filters anything, so
+a page held out of one and kept in the other is still fetched and still
+displaces a page that could have answered.
+
+The page is never touched. It stays in ``wiki_pages``, still resolves as a
+link target, and a reader who arrives at it still learns the file exists.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.persistence.information_floor import (
+ INFORMATION_FLOOR_ENV,
+ meets_information_floor,
+ pages_denied_a_vector,
+ reset_pages_denied_a_vector,
+)
+from repowise.core.persistence.vector_store import embed_item
+
+# A real spotlight for a bare interface, verbatim in shape: a heading and a
+# metadata strip, which the floor strips to nothing.
+SKELETON = (
+ "# packages.api-client.src.types.graph.GraphLike\n\n"
+ "**Kind:** interface | **Defined in:** `packages/api-client/src/types/graph.ts` "
+ "| **Estimated complexity:** 1\n"
+)
+
+SUBSTANTIAL = (
+ "## Overview\n\n"
+ "The walker resolves each import against the package manifest before it "
+ "descends, so a symlinked workspace member is visited once rather than "
+ "once per alias that reaches it. Cycles are broken on the real path, not "
+ "the alias, which is why two aliases of one directory cannot both claim "
+ "to own a module.\n"
+)
+
+
[email protected](autouse=True)
+def _floor(monkeypatch: pytest.MonkeyPatch):
+ """Each test states its own floor; the default is off."""
+ monkeypatch.delenv(INFORMATION_FLOOR_ENV, raising=False)
+ reset_pages_denied_a_vector()
+ yield
+ reset_pages_denied_a_vector()
+
+
+def _item(content: str):
+ return embed_item(
+ "symbol_spotlight:a.ts::GraphLike",
+ title="GraphLike",
+ page_type="symbol_spotlight",
+ target_path="packages/api-client/src/types/graph.ts",
+ summary="",
+ content=content,
+ )
+
+
+def test_a_skeleton_page_gets_no_vector(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv(INFORMATION_FLOOR_ENV, "300")
+
+ assert _item(SKELETON) is None
+
+
+def test_a_substantial_page_is_still_embedded(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv(INFORMATION_FLOOR_ENV, "300")
+
+ item = _item(SUBSTANTIAL)
+
+ assert item is not None
+ assert item[0] == "symbol_spotlight:a.ts::GraphLike"
+
+
+def test_the_floor_is_off_by_default():
+ """Installing this must change nobody's index until a value is set."""
+ assert _item(SKELETON) is not None
+
+
+def test_both_arms_judge_the_same_page_the_same_way(monkeypatch: pytest.MonkeyPatch):
+ """The two arms measure ``content``, and must measure the same thing.
+
+ A page kept by one arm and dropped by the other is still fetched, so the
+ exclusion buys nothing and the disagreement is pure confusion.
+ """
+ monkeypatch.setenv(INFORMATION_FLOOR_ENV, "300")
+
+ for content in (SKELETON, SUBSTANTIAL):
+ assert (_item(content) is not None) == meets_information_floor(content)
+
+
+def test_a_held_back_page_is_counted(monkeypatch: pytest.MonkeyPatch):
+ """A smaller index has innocent explanations; the deliberate part is named."""
+ monkeypatch.setenv(INFORMATION_FLOOR_ENV, "300")
+
+ _item(SKELETON)
+ _item(SKELETON)
+ _item(SUBSTANTIAL)
+
+ assert pages_denied_a_vector() == 2
+
+
+def test_nothing_is_counted_when_the_floor_is_off():
+ _item(SKELETON)
+
+ assert pages_denied_a_vector() == 0
+
+
+def test_a_blank_title_still_raises_below_the_floor(monkeypatch: pytest.MonkeyPatch):
+ """The two rules are about different failures and must not mask each other.
+
+ A missing title is a writer that lost it — a defect to fix — while being
+ below the floor is a page working as intended. Returning ``None`` for a
+ titleless thin page would file the first as the second and lose it.
+ """
+ monkeypatch.setenv(INFORMATION_FLOOR_ENV, "300")
+
+ with pytest.raises(ValueError, match="no title"):
+ embed_item(
+ "file_page:a.py",
+ title=" ",
+ page_type="file_page",
+ target_path="a.py",
+ summary="",
+ content=SKELETON,
+ )