diff --git a/app/api/docs.py b/app/api/docs.py index 44cea24..717a8b2 100644 --- a/app/api/docs.py +++ b/app/api/docs.py @@ -98,6 +98,7 @@ def get_document_content( path=doc.path, title=doc.title, format=doc_format(doc.path), + summary=doc.summary, content=doc.content, indexed_at=doc.indexed_at.isoformat(), chunks=chunks, diff --git a/app/schemas.py b/app/schemas.py index 9ef272c..f5165fd 100644 --- a/app/schemas.py +++ b/app/schemas.py @@ -105,6 +105,10 @@ class DocContent(BaseModel): path: str title: str format: str + #: Lite-model summary (phase 30) — non-markdown A9 docs only; None for + #: markdown documents, pre-phase-30 rows, and the fail-soft path where + #: summary generation failed but the document was still indexed. + summary: str | None = None content: str indexed_at: str chunks: int diff --git a/frontend/assets/document.js b/frontend/assets/document.js index b997cdc..b93423b 100644 --- a/frontend/assets/document.js +++ b/frontend/assets/document.js @@ -12,7 +12,13 @@ * in a ≤46rem centered column; * • any other → the raw content as a text node inside *
(mono, horizontal
- * scroll).
+ * scroll);
+ * • doc.summary non-empty (phase 36 — phase 30 summaries exist
+ * only on non-markdown docs) → a labeled
+ * .doc-summary section ABOVE the content;
+ * null / empty / whitespace renders nothing, so
+ * markdown docs and fail-soft rows are
+ * byte-for-byte unchanged.
*
* 2. The /document.html page itself: reads `source`/`path` query
* params, fetches the stateless content endpoint
@@ -40,6 +46,11 @@
* around the page block below). Importing renderDocument elsewhere has
* no side effects: no back-link resolution, no whoami, no content
* fetch, no New Chat binding.
+ *
+ * Phase 36: the renderer owns the optional summary panel — a non-empty
+ * doc.summary renders as a labeled .doc-summary section above the
+ * original content on BOTH surfaces (page + modal) through this one
+ * core; the summary text is a text node (XSS contract unchanged).
*/
import { fetchIsAdmin, initSharedHeader } from "./header.js";
@@ -66,10 +77,13 @@ function metaBadge(cls, text) {
/* ---------- shared renderer (phase 26, task 02) ----------
* Populates the three elements every render surface provides: a title,
* a .doc-meta badge row (source · format · mono path · indexed ·
- * chunks), and a content container — .doc-md for md/markdown (the
- * shared escape-first renderer), otherwise. The
- * XSS contract: innerHTML only through renderMarkdown; every
- * document-derived string is a text node. */
+ * chunks), and a content container — an optional .doc-summary section
+ * first (phase 36: only when doc.summary is non-empty — markdown docs
+ * and fail-soft rows carry none, so they render exactly as before),
+ * then .doc-md for md/markdown (the shared escape-first renderer),
+ * otherwise. The XSS contract: innerHTML only
+ * through renderMarkdown; every document-derived string (summary text
+ * included) is a text node. */
export function renderDocument(doc, { titleEl, metaEl, contentEl }) {
titleEl.textContent = doc.title;
// Phase 34 task 04: the titlebar title ellipsizes — the full title
@@ -88,6 +102,24 @@ export function renderDocument(doc, { titleEl, metaEl, contentEl }) {
);
contentEl.replaceChildren();
+ // Phase 36: the summary panel — labeled section ABOVE the original
+ // content, on BOTH surfaces (page + modal) through this one core.
+ // Only a non-empty summary renders: markdown docs carry none (phase
+ // 30) and the fail-soft path leaves summary NULL, so both are
+ // byte-for-byte unchanged here.
+ if (doc.summary && doc.summary.trim() !== "") {
+ const section = document.createElement("section");
+ section.className = "doc-summary";
+ section.setAttribute("aria-label", "Summary");
+ const title = document.createElement("h2");
+ title.className = "doc-summary-title";
+ title.textContent = "Summary";
+ const body = document.createElement("p");
+ body.className = "doc-summary-text";
+ body.textContent = doc.summary; // text node — XSS contract unchanged
+ section.append(title, body);
+ contentEl.appendChild(section);
+ }
if (doc.format === "md" || doc.format === "markdown") {
const wrap = document.createElement("div");
wrap.className = "doc-md";
diff --git a/frontend/assets/styles.css b/frontend/assets/styles.css
index ca6b2bf..43f1ed6 100644
--- a/frontend/assets/styles.css
+++ b/frontend/assets/styles.css
@@ -1675,6 +1675,45 @@ details.thinking .thinking-text ul { margin: 0 0 0.5rem; }
.doc-md code { font-family: var(--mono); font-size: 0.88em; background: var(--brand-soft); padding: 0.08em 0.35em; border-radius: 5px; }
.doc-md pre code { background: none; padding: 0; }
+/* Summary panel (phase 36): the labeled "Summary" section the shared
+ renderDocument core (document.js) draws ABOVE the original content
+ whenever doc.summary is non-empty (phase 30 — non-markdown docs
+ only). A "summary, not content" look: the surface card carries a 3px
+ brand left border (no shadow — the content cards own those) and a
+ small-caps brand-ink label. Phase-08 tokens only; static content —
+ no animation (nothing for prefers-reduced-motion to still), and the
+ aria-label + heading carry the accessibility. */
+.doc-summary {
+ width: 100%;
+ background: var(--surface);
+ border: 1px solid var(--line);
+ border-left: 3px solid var(--brand);
+ border-radius: var(--radius);
+ padding: 0.9rem 1.1rem;
+ margin-bottom: 1rem;
+ overflow-wrap: anywhere;
+}
+/* md/markdown: the panel matches the .doc-md ≤46rem centered reading
+ column — it is the column's label. Raw formats stay full width (the
+ .doc-raw default above), matching the full-width pre; in engines
+ without :has() the panel degrades to that full-width default. */
+.doc-summary:has(+ .doc-md) {
+ max-width: 46rem;
+ margin-inline: auto;
+}
+.doc-summary-title {
+ margin: 0 0 0.4rem;
+ font-size: 0.75rem;
+ font-weight: 700;
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+ color: var(--brand-ink); /* #a5b4fc on --surface ≈8.7:1 */
+}
+.doc-summary-text {
+ margin: 0;
+ color: var(--ink); /* on --surface ≈14.5:1 */
+}
+
/* Raw (non-markdown) formats: full-width mono pre, horizontal scroll. */
.doc-raw {
width: 100%;
@@ -2011,6 +2050,7 @@ details.thinking .thinking-text ul { margin: 0 0 0.5rem; }
#doc-title { font-size: 1.1rem; }
.doc-path { max-width: 16rem; }
.doc-md { padding: 1.1rem 1rem; }
+ .doc-summary { padding: 0.75rem 0.9rem; }
.doc-raw { padding: 1rem; font-size: 0.8rem; }
/* Phase 26: the modal bar squeezes like the other bars — the Full page
pill goes icon-only (aria-label keeps the name), the title clips;
diff --git a/tests/e2e/test_summary_in_viewer.py b/tests/e2e/test_summary_in_viewer.py
new file mode 100644
index 0000000..8659d9e
--- /dev/null
+++ b/tests/e2e/test_summary_in_viewer.py
@@ -0,0 +1,349 @@
+"""Phase 36 E2E (Playwright): the summary and the original document
+are visible **together** in the viewer.
+
+Story: ``.agent/user_stories/summary-in-viewer.md``
+Run in isolation (DB must be up: ``podman compose up -d db``):
+
+ uv run pytest tests/e2e/test_summary_in_viewer.py -v --no-cov
+
+The fixture KB is the story-dedicated ``tests/fixtures/summary_kb/``
+directory (the same one the phase-30 suite imports — its machinery is
+reused here as closely as possible):
+
+* ``quadlet/qwen-llamacpp.yaml`` — a non-markdown A9 doc. At import the
+ mock ``lite`` model (``SUMMARY_MODE`` marker, ``tests/e2e/mock_llm.py``)
+ reduces it to a deterministic 24-token digest, stored on
+ ``documents.summary``. The sentinel ``RESE-SUMMARY-SENTINEL-7f3a`` sits
+ on the document's LAST line — **outside** the 24-token digest — so it
+ is a marker for "the original, not the summary".
+* ``notes/qwen-llamacpp-notes.md`` — a markdown control doc, never
+ summarized (phase 30 scope): the viewer must render it exactly as
+ before, with no Summary panel.
+
+This phase only surfaces the stored field: the content endpoint returns
+``summary`` (task 01) and the shared ``renderDocument`` core draws the
+labeled ``.doc-summary`` panel above the content on BOTH surfaces (task
+02) — the full-page viewer and the chat/sources modal. The tests assert
+exactly that contract, plus the phase-16 soft rule: the content
+endpoint stays public (anonymous fetch → 200, no admin cookie needed).
+"""
+from __future__ import annotations
+
+import asyncio
+import re
+from pathlib import Path
+from threading import Thread
+from typing import Any
+
+from playwright.sync_api import Page, expect
+from sqlalchemy import text
+
+from app.config import Settings
+from app.db import SessionLocal
+from app.rag.importer import ImportSummary, import_sources
+from app.rag.llm import LLMClient
+from e2e.auth_helpers import login
+from tests.e2e.mock_llm import TOKEN_RE
+
+REPO = Path(__file__).resolve().parents[2]
+FIXTURES = REPO / "tests" / "fixtures" / "summary_kb"
+
+SENTINEL = "RESE-SUMMARY-SENTINEL-7f3a"
+SOURCE = "summary_kb"
+YAML_PATH = "quadlet/qwen-llamacpp.yaml"
+MD_PATH = "notes/qwen-llamacpp-notes.md"
+
+#: Encoded viewer URL query values (slashes come out as %2F, same as the
+#: chips / Sources table links build them).
+YAML_URL_PATH = "quadlet%2Fqwen-llamacpp.yaml"
+MD_URL_PATH = "notes%2Fqwen-llamacpp-notes.md"
+
+
+# --- Importer + thread helpers (test_document_summaries.py pattern) ---
+
+
+async def _import_fixtures(mock_port: int) -> ImportSummary:
+ kwargs: dict[str, Any] = {
+ "_env_file": None,
+ "llm_base_url": f"http://127.0.0.1:{mock_port}/v1",
+ }
+ settings = Settings(**kwargs) # pyright: ignore[reportCallIssue]
+ return await import_sources([FIXTURES], LLMClient(settings))
+
+
+def _run_in_thread(coro: Any) -> Any:
+ """Run a coroutine on a worker thread.
+
+ Playwright's sync API keeps an asyncio loop running on the test thread,
+ so ``asyncio.run`` cannot be called directly from a test body.
+ """
+ box: dict[str, Any] = {}
+
+ def runner() -> None:
+ try:
+ box["value"] = asyncio.run(coro)
+ except BaseException as e: # noqa: BLE001 — re-raised on the test thread
+ box["error"] = e
+
+ t = Thread(target=runner)
+ t.start()
+ t.join()
+ if "error" in box:
+ raise box["error"]
+ return box["value"]
+
+
+def _reset_db_and_import(mock_llm: int) -> ImportSummary:
+ """Truncate the KB (and query log + steering) and re-import the
+ summary_kb fixtures — yaml summarized, md control not."""
+ with SessionLocal() as db:
+ db.execute(text("TRUNCATE chunks, documents, query_log, steering_notes"))
+ db.commit()
+ summary = _run_in_thread(_import_fixtures(mock_llm))
+ assert summary.added == 2 # yaml + md control
+ assert summary.summaries == 1 and summary.summary_errors == 0
+ assert summary.errors == 0
+ return summary
+
+
+def _expected_summary(content: str, source: str, path: str) -> str:
+ """The mock lite model's byte-stable digest + the code pointer line.
+
+ Mirrors ``mock_llm.compose_answer``'s ``SUMMARY_MODE`` branch (first
+ 24 tokens of the document content) plus the summarizer's
+ deterministic ``Source:`` line — no model output is ever trusted.
+ """
+ digest = " ".join(TOKEN_RE.findall(content.lower())[:24])
+ return f"This document covers {digest}.\nSource: {source}/{path}"
+
+
+def _summary_lines(source: str, path: str) -> tuple[str, str]:
+ """(digest line, pointer line) of the stored summary for a fixture."""
+ expected = _expected_summary(
+ (FIXTURES / path).read_text(encoding="utf-8"), source, path
+ )
+ digest_line, pointer_line = expected.split("\n", 1)
+ return digest_line, pointer_line
+
+
+# ---------------------------------------------------------------------------
+# 1. Full page: labeled Summary panel ABOVE the original, both visible
+# ---------------------------------------------------------------------------
+
+
+def test_full_page_shows_summary_and_original_together(
+ page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+ """The dedicated viewer for a summarized yaml shows the labeled
+ Summary panel (deterministic mock digest) and, below it, the FULL
+ original content — its tail sentinel, which the 24-token digest
+ cannot contain, is rendered in the raw ````."""
+ _reset_db_and_import(mock_llm)
+ page.set_default_timeout(30_000)
+
+ digest_line, pointer_line = _summary_lines(SOURCE, YAML_PATH)
+ page.goto(f"{app_url}/document.html?source={SOURCE}&path={YAML_URL_PATH}")
+
+ # Title + meta row unchanged by the phase (badge row is untouched).
+ expect(page.locator("#doc-title")).to_have_text("qwen-llamacpp")
+ expect(page.locator("#doc-meta .doc-source-badge")).to_have_text(SOURCE)
+ expect(page.locator("#doc-meta .format-badge")).to_have_text("yaml")
+ expect(page.locator("#doc-meta .doc-path")).to_have_text(YAML_PATH)
+
+ # Exactly one labeled Summary section — a real
+ # with a visible heading (UI Structure Check: labeled section).
+ panel = page.locator(".doc-summary")
+ expect(panel).to_have_count(1)
+ expect(panel).to_be_visible()
+ expect(panel).to_have_attribute("aria-label", "Summary")
+ expect(panel.locator(".doc-summary-title")).to_have_text("Summary")
+
+ # The panel carries the DETERMINISTIC digest (byte-stable, no real
+ # LLM) — digest line + code pointer line — and nothing from the raw
+ # body beyond the first 24 tokens ("healthcheck" is deeper in the
+ # file, so the panel cannot be the original content).
+ expect(panel).to_contain_text(digest_line)
+ expect(panel).to_contain_text(pointer_line)
+ expect(panel).not_to_contain_text("healthcheck")
+
+ # The ORIGINAL is fully visible: the raw yaml in its , including
+ # the tail sentinel that sits outside the digest.
+ pre = page.locator("#doc-content pre.doc-raw")
+ expect(pre).to_have_count(1)
+ expect(pre).to_contain_text(SENTINEL)
+ expect(pre).to_contain_text("healthcheck")
+
+ # The panel sits ABOVE the content: first child of #doc-content.
+ order = page.evaluate(
+ "() => [...document.querySelector('#doc-content').children]"
+ ".map((el) => el.className)"
+ )
+ assert order[0] == "doc-summary", f"panel not first: {order}"
+ assert "doc-raw" in order and order.index("doc-raw") > order.index("doc-summary")
+
+ # Theme (phase 08): panel on the surface colour, title in brand-ink
+ # (#a5b4fc on #121a2e ≈8.7:1 ≥4.5:1), and the panel matches the
+ # raw-content width — it does not break the content layout.
+ bg = panel.evaluate("el => getComputedStyle(el).backgroundColor")
+ assert bg == "rgb(18, 26, 46)", f"panel not on the Phase-08 surface: {bg}"
+ title_color = panel.locator(".doc-summary-title").evaluate(
+ "el => getComputedStyle(el).color"
+ )
+ assert title_color == "rgb(165, 180, 252)", f"title not brand-ink: {title_color}"
+ panel_box = panel.bounding_box()
+ pre_box = pre.bounding_box()
+ assert panel_box is not None and pre_box is not None
+ assert abs(panel_box["width"] - pre_box["width"]) < 2, (
+ f"panel width {panel_box['width']} != raw width {pre_box['width']}"
+ )
+ assert panel_box["y"] < pre_box["y"], "panel must sit above the content"
+
+
+# ---------------------------------------------------------------------------
+# 2. Modal from the Sources table: same panel + content; "Full page"
+# agrees (the two surfaces cannot drift — one shared renderer)
+# ---------------------------------------------------------------------------
+
+
+def test_modal_shows_panel_and_full_page_agrees(
+ page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+ """Admin opens the yaml from the Sources table row: the SAME-PAGE
+ modal shows the Summary panel + the sentinel-bearing original; the
+ 'Full page' escape hatch lands on the dedicated page with the panel
+ still there — both surfaces render through one shared core."""
+ _reset_db_and_import(mock_llm)
+ page.set_default_timeout(30_000)
+ login(page, app_url) # phase 16: the Sources catalog is admin-only
+
+ digest_line, pointer_line = _summary_lines(SOURCE, YAML_PATH)
+ row = page.locator("#docs-tbody tr", has_text=YAML_PATH)
+ expect(row).to_have_count(1)
+ before = len(page.context.pages)
+ row.locator("td:nth-child(2) a.doc-link").click()
+ assert len(page.context.pages) == before, "row link must not open a new tab"
+
+ # The modal shows the panel + the original content, in order.
+ expect(page.locator(".doc-modal")).to_be_visible()
+ expect(page.locator("#doc-modal-title")).to_have_text("qwen-llamacpp")
+ modal_panel = page.locator("#doc-modal .doc-summary")
+ expect(modal_panel).to_have_count(1)
+ expect(modal_panel).to_be_visible()
+ expect(modal_panel).to_have_attribute("aria-label", "Summary")
+ expect(modal_panel).to_contain_text(digest_line)
+ expect(modal_panel).to_contain_text(pointer_line)
+ modal_pre = page.locator("#doc-modal pre.doc-raw")
+ expect(modal_pre).to_have_count(1)
+ expect(modal_pre).to_contain_text(SENTINEL)
+ order = page.evaluate(
+ "() => [...document.querySelector('#doc-modal-content').children]"
+ ".map((el) => el.className)"
+ )
+ assert order[0] == "doc-summary", f"panel not first in the modal: {order}"
+
+ # "Full page" (the #doc-modal-open escape hatch — target=_blank by
+ # design) opens the dedicated viewer in a NEW TAB, and the panel is
+ # there with the same digest and the same sentinel: the surfaces
+ # agree (one shared renderer, no drift).
+ with page.expect_popup() as popup_info:
+ page.click("#doc-modal-open")
+ full_page = popup_info.value
+ expect(
+ full_page
+ ).to_have_url(
+ re.compile(
+ r"^" + re.escape(f"{app_url}/document.html")
+ + r"\?source=summary_kb&path=quadlet%2Fqwen-llamacpp\.yaml$"
+ ),
+ timeout=30_000,
+ )
+ full_panel = full_page.locator(".doc-summary")
+ expect(full_panel).to_have_count(1)
+ expect(full_panel).to_be_visible()
+ expect(full_panel).to_contain_text(digest_line)
+ expect(full_panel).to_contain_text(pointer_line)
+ expect(full_page.locator("#doc-content pre.doc-raw")).to_contain_text(SENTINEL)
+
+
+# ---------------------------------------------------------------------------
+# 3. No-summary control: the markdown doc renders exactly as before
+# ---------------------------------------------------------------------------
+
+
+def test_markdown_doc_has_no_summary_panel(
+ page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+ """Control doc (markdown — never summarized): NO .doc-summary
+ element on either surface, and the content renders exactly as
+ before (first child of the content container is the doc body)."""
+ _reset_db_and_import(mock_llm)
+ page.set_default_timeout(30_000)
+
+ # Full page: no panel, markdown column untouched.
+ page.goto(f"{app_url}/document.html?source={SOURCE}&path={MD_URL_PATH}")
+ expect(page.locator(".doc-summary")).to_have_count(0)
+ expect(page.locator("#doc-content .doc-md")).to_have_count(1)
+ expect(page.locator("#doc-content")).to_contain_text(
+ "came out of a week of"
+ )
+ order = page.evaluate(
+ "() => [...document.querySelector('#doc-content').children]"
+ ".map((el) => el.className)"
+ )
+ assert order == ["doc-md"], f"markdown doc gained children: {order}"
+
+ # Modal: same story — no panel, .doc-md is the sole content child.
+ login(page, app_url)
+ row = page.locator("#docs-tbody tr", has_text=MD_PATH)
+ expect(row).to_have_count(1)
+ row.locator("td:nth-child(2) a.doc-link").click()
+ expect(page.locator(".doc-modal")).to_be_visible()
+ expect(page.locator("#doc-modal .doc-summary")).to_have_count(0)
+ expect(page.locator("#doc-modal .doc-md")).to_have_count(1)
+ expect(page.locator("#doc-modal-content")).to_contain_text(
+ "came out of a week of"
+ )
+ order = page.evaluate(
+ "() => [...document.querySelector('#doc-modal-content').children]"
+ ".map((el) => el.className)"
+ )
+ assert order == ["doc-md"], f"markdown modal gained children: {order}"
+
+
+# ---------------------------------------------------------------------------
+# 4. API shape (cheap, via the page context's request — still anonymous)
+# ---------------------------------------------------------------------------
+
+
+def test_content_api_summary_shape_anonymous(
+ page: Page, app_url: str, mock_llm: int, db_ready: None
+) -> None:
+ """``GET /api/documents/content`` carries ``summary`` — the string
+ for the summarized yaml, ``null`` for the markdown control — and
+ stays PUBLIC: no admin cookie is set anywhere in this test, so both
+ 200s prove the phase-16 soft rule (viewer public) is unchanged."""
+ _reset_db_and_import(mock_llm)
+
+ digest_line, _ = _summary_lines(SOURCE, YAML_PATH)
+ expected_summary = f"{digest_line}\nSource: {SOURCE}/{YAML_PATH}"
+
+ resp = page.context.request.get(
+ f"{app_url}/api/documents/content?source={SOURCE}&path={YAML_URL_PATH}"
+ )
+ assert resp.status == 200, "anonymous viewer access must stay public"
+ body = resp.json()
+ assert body["source"] == SOURCE
+ assert body["path"] == YAML_PATH
+ assert body["format"] == "yaml"
+ assert isinstance(body["summary"], str)
+ assert body["summary"] == expected_summary
+ assert SENTINEL in body["content"] # full original, never just the digest
+
+ resp_md = page.context.request.get(
+ f"{app_url}/api/documents/content?source={SOURCE}&path={MD_URL_PATH}"
+ )
+ assert resp_md.status == 200, "anonymous viewer access must stay public"
+ md_body = resp_md.json()
+ assert md_body["format"] == "md"
+ assert md_body["summary"] is None, "markdown docs never carry a summary"
+ assert "came out of a week of" in md_body["content"]
diff --git a/tests/integration/test_auth_api.py b/tests/integration/test_auth_api.py
index 0ebf4d5..d837f8e 100644
--- a/tests/integration/test_auth_api.py
+++ b/tests/integration/test_auth_api.py
@@ -161,10 +161,12 @@ def test_anonymous_document_content_stays_public(client: TestClient, db) -> None
"path",
"title",
"format",
+ "summary", # nullable field added in phase 36 (null here — markdown)
"content",
"indexed_at",
"chunks",
}
+ assert body["summary"] is None
# Unknown docs still 404 anonymously (no enumeration of titles).
r = client.get("/api/documents/content", params={"source": "docs", "path": "nope.md"})
diff --git a/tests/integration/test_document_content.py b/tests/integration/test_document_content.py
index 0395454..dbf1691 100644
--- a/tests/integration/test_document_content.py
+++ b/tests/integration/test_document_content.py
@@ -2,6 +2,8 @@
Uses the real compose Postgres (``db`` fixture) and FastAPI's TestClient:
* 200 with the full field set for a seeded document (all formats);
+* ``summary`` surfaced for summarized docs, ``null`` for markdown (phase 36);
+* anonymous access stays 200 (phase 16 soft rule — public viewer);
* 404 for an unknown (source, path) pair;
* 404 for traversal-style ``path`` values (no filesystem access → no leak).
"""
@@ -21,6 +23,7 @@ def _seed_doc(
title: str = "Kubernetes Homelab Cluster",
content: str = "# Kubernetes\n\nTalos on 3 nodes.",
chunks: int = 2,
+ summary: str | None = None,
) -> None:
"""Truncate the KB and insert one document with ``chunks`` chunk rows."""
db.execute(text("TRUNCATE chunks, documents"))
@@ -33,6 +36,7 @@ def _seed_doc(
content=content,
content_hash="a" * 64,
indexed_at=datetime.now(UTC),
+ summary=summary,
)
db.add(doc)
db.flush()
@@ -53,11 +57,14 @@ def test_content_200_all_fields(client, db) -> None:
)
assert r.status_code == 200
body = r.json()
- assert set(body) == {"source", "path", "title", "format", "content", "indexed_at", "chunks"}
+ assert set(body) == {
+ "source", "path", "title", "format", "summary", "content", "indexed_at", "chunks"
+ }
assert body["source"] == "Homelab"
assert body["path"] == "kubernetes.md"
assert body["title"] == "Kubernetes Homelab Cluster"
assert body["format"] == "md"
+ assert body["summary"] is None # markdown doc → no summary (phase 36)
assert body["content"] == "# Kubernetes\n\nTalos on 3 nodes."
assert body["chunks"] == 2
datetime.fromisoformat(body["indexed_at"]) # raises if not ISO-8601
@@ -66,6 +73,62 @@ def test_content_200_all_fields(client, db) -> None:
db.commit()
+def test_content_summary_surfaced_for_summarized_doc(client, db) -> None:
+ """A non-markdown document with a phase-30 summary returns it verbatim
+ (phase 36 — the viewer's data contract gains the nullable field).
+
+ Anonymous by design: the ``client`` fixture carries no admin cookie,
+ so the 200 here re-confirms the phase-16 soft rule (public viewer).
+ """
+ summary = (
+ "GitLab CE runs in a Podman compose stack on the homelab NAS with a "
+ "persistent volume for data and a backup job."
+ )
+ _seed_doc(
+ db,
+ path="container_gitlab/gitlab-compose.yaml",
+ title="gitlab-compose",
+ content="services:\n gitlab:\n image: gitlab/gitlab-ce",
+ summary=summary,
+ )
+ try:
+ r = client.get(
+ "/api/documents/content",
+ params={"source": "Homelab", "path": "container_gitlab/gitlab-compose.yaml"},
+ )
+ assert r.status_code == 200 # anonymous (no cookie) — public viewer
+ body = r.json()
+ assert body["summary"] == summary # verbatim, no wrapping
+ assert body["content"] == "services:\n gitlab:\n image: gitlab/gitlab-ce"
+ finally:
+ db.execute(text("TRUNCATE chunks, documents"))
+ db.commit()
+
+
+def test_content_summary_null_for_markdown_doc(client, db) -> None:
+ """Markdown documents carry no summary (phase 30) → JSON ``null``, and
+ anonymous access still returns 200 (phase 16 soft rule)."""
+ _seed_doc(
+ db,
+ path="kubernetes.md",
+ content="# Kubernetes\n\nTalos on 3 nodes.",
+ summary=None,
+ )
+ try:
+ r = client.get(
+ "/api/documents/content",
+ params={"source": "Homelab", "path": "kubernetes.md"},
+ )
+ assert r.status_code == 200 # anonymous (no cookie) — public viewer
+ body = r.json()
+ assert "summary" in body
+ assert body["summary"] is None
+ assert body["content"] == "# Kubernetes\n\nTalos on 3 nodes."
+ finally:
+ db.execute(text("TRUNCATE chunks, documents"))
+ db.commit()
+
+
def test_content_404_unknown_path(client, db) -> None:
_seed_doc(db)
try:
diff --git a/tests/unit/test_document_viewer.py b/tests/unit/test_document_viewer.py
index 4c331a0..7ee22b8 100644
--- a/tests/unit/test_document_viewer.py
+++ b/tests/unit/test_document_viewer.py
@@ -143,11 +143,14 @@ def test_content_known_pair_maps_to_doc_content() -> None:
)
assert r.status_code == 200
body = r.json()
- assert set(body) == {"source", "path", "title", "format", "content", "indexed_at", "chunks"}
+ assert set(body) == {
+ "source", "path", "title", "format", "summary", "content", "indexed_at", "chunks"
+ }
assert body["source"] == "Homelab"
assert body["path"] == "notes/deep mark.md"
assert body["title"] == "Deep Mark"
assert body["format"] == "md"
+ assert body["summary"] is None # markdown doc → no summary (phase 36)
assert body["content"] == "# Deep Mark\n\nbody"
assert body["indexed_at"] == "2026-08-22T01:02:03+00:00"
assert body["chunks"] == 3