432 lines
18 KiB
Python
432 lines
18 KiB
Python
"""Unit: document viewer (phase 10).
|
|
|
|
Python side:
|
|
* ``doc_format`` — format from the path suffix (incl. ``.markdown`` and the
|
|
no-suffix fallback);
|
|
* the content endpoint's 200/404 mapping — tested WITHOUT a database by
|
|
stubbing the session via FastAPI's dependency override (unknown pairs and
|
|
traversal-style paths map to 404 ``{detail: "document not found"}``;
|
|
known pairs map to the full ``DocContent`` shape).
|
|
|
|
Frontend side:
|
|
* the viewer URL builder — its real query-encoding behavior (paths with
|
|
spaces/slashes) executed under node when available, plus source pins that
|
|
run everywhere;
|
|
* the shared-renderer extraction — ``markdown.js`` holds the renderer,
|
|
loaded by the pages that use it via a relative ``<script src>`` before
|
|
the module scripts;
|
|
* phase 26 — the shared ``renderDocument`` export in ``document.js``, the
|
|
import-safe page guard, the modal skeleton on chat + Sources, and the
|
|
modal module's close/focus/URL contract.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import re
|
|
import shutil
|
|
import subprocess
|
|
from datetime import UTC, datetime
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
from fastapi.testclient import TestClient
|
|
|
|
from app.api.docs import doc_format
|
|
from app.db import get_db
|
|
from app.main import create_app
|
|
from app.models import Document
|
|
|
|
FRONTEND = Path(__file__).resolve().parents[2] / "frontend"
|
|
APP_JS = FRONTEND / "assets" / "app.js"
|
|
SOURCES_JS = FRONTEND / "assets" / "sources.js"
|
|
DOCUMENT_JS = FRONTEND / "assets" / "document.js"
|
|
MARKDOWN_JS = FRONTEND / "assets" / "markdown.js"
|
|
MODAL_JS = FRONTEND / "assets" / "document-modal.js" # phase 26: the modal owner
|
|
INDEX_HTML = FRONTEND / "index.html"
|
|
SOURCES_HTML = FRONTEND / "sources.html"
|
|
|
|
HAVE_NODE = shutil.which("node") is not None
|
|
|
|
|
|
def _read(path: Path) -> str:
|
|
return path.read_text(encoding="utf-8")
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# doc_format — format-from-suffix (phase 10, PLAN §4)
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
("path", "expected"),
|
|
[
|
|
("kubernetes.md", "md"),
|
|
("notes/sub/deep.markdown", "markdown"),
|
|
("NOTES/ARCHIVE.MD", "md"),
|
|
("homelab/container_gitlab/gitlab-compose.yaml", "yaml"),
|
|
("homelab/networking/static-dns.json", "json"),
|
|
("homelab/scripts/uptime_probe.py", "py"),
|
|
("homelab/ssh/ssh_aliases.txt", "txt"),
|
|
("noext", "text"), # no suffix → fallback
|
|
("a/b", "text"), # no suffix → fallback
|
|
],
|
|
)
|
|
def test_doc_format_from_suffix(path: str, expected: str) -> None:
|
|
assert doc_format(path) == expected
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Content endpoint mapping — stubbed session, no database required
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
class _FakeResult:
|
|
def __init__(self, row: object) -> None:
|
|
self._row = row
|
|
|
|
def first(self) -> object:
|
|
return self._row
|
|
|
|
|
|
class _FakeSession:
|
|
def __init__(self, row: object) -> None:
|
|
self._row = row
|
|
|
|
def execute(self, _stmt: object) -> _FakeResult:
|
|
return _FakeResult(self._row)
|
|
|
|
|
|
def _client_with_row(row: object) -> TestClient:
|
|
"""Fresh app whose ``get_db`` dependency is a stub returning ``row``
|
|
(``None`` → no matching document row)."""
|
|
app = create_app()
|
|
app.dependency_overrides[get_db] = lambda: _FakeSession(row)
|
|
return TestClient(app)
|
|
|
|
|
|
def test_content_unknown_pair_maps_to_404() -> None:
|
|
with _client_with_row(None) as client:
|
|
r = client.get(
|
|
"/api/documents/content",
|
|
params={"source": "Homelab", "path": "nope.md"},
|
|
)
|
|
assert r.status_code == 404
|
|
assert r.json() == {"detail": "document not found"}
|
|
|
|
|
|
def test_content_traversal_style_path_maps_to_404() -> None:
|
|
"""``../``-style values are just non-existent rows → 404, never a
|
|
file read (DB-only endpoint, no filesystem access)."""
|
|
with _client_with_row(None) as client:
|
|
r = client.get(
|
|
"/api/documents/content",
|
|
params={"source": "Homelab", "path": "../../etc/passwd"},
|
|
)
|
|
assert r.status_code == 404
|
|
assert r.json() == {"detail": "document not found"}
|
|
assert "root:" not in r.text # nothing leaked
|
|
|
|
|
|
def test_content_known_pair_maps_to_doc_content() -> None:
|
|
doc = Document(
|
|
source="Homelab",
|
|
path="notes/deep mark.md",
|
|
full_path="/tmp/deep mark.md",
|
|
title="Deep Mark",
|
|
content="# Deep Mark\n\nbody",
|
|
content_hash="f" * 64,
|
|
)
|
|
doc.indexed_at = datetime(2026, 8, 22, 1, 2, 3, tzinfo=UTC)
|
|
with _client_with_row((doc, 3)) as client:
|
|
r = client.get(
|
|
"/api/documents/content",
|
|
params={"source": "Homelab", "path": "notes/deep mark.md"},
|
|
)
|
|
assert r.status_code == 200
|
|
body = r.json()
|
|
assert set(body) == {"source", "path", "title", "format", "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["content"] == "# Deep Mark\n\nbody"
|
|
assert body["indexed_at"] == "2026-08-22T01:02:03+00:00"
|
|
assert body["chunks"] == 3
|
|
|
|
|
|
def test_content_requires_both_params() -> None:
|
|
with _client_with_row(None) as client:
|
|
assert client.get("/api/documents/content").status_code == 422
|
|
assert client.get("/api/documents/content", params={"source": "Homelab"}).status_code == 422
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Viewer URL builder — encoded query (spaces/slashes in real paths)
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
def test_viewer_url_builder_present_in_chat_and_sources() -> None:
|
|
"""Both entry points (chat chips, Sources rows) build the same
|
|
encoded viewer URL — kept as each link's ``href`` (no-JS /
|
|
context-menu escape hatch to the dedicated viewer).
|
|
|
|
Phase 13: the chat builder additionally carries ``back=/`` (encoded
|
|
%2F) so the viewer's back button returns to the chat; Sources links
|
|
intentionally omit the param (the viewer's /sources.html default).
|
|
|
|
Phase 26: the left-click no longer opens a new tab — it is
|
|
intercepted (preventDefault) and routed to openDocumentModal from
|
|
the shared modal module; no ``target="_blank"" survives on either
|
|
entry point."""
|
|
for name, js in (("app.js", _read(APP_JS)), ("sources.js", _read(SOURCES_JS))):
|
|
assert '"/document.html?source=" + encodeURIComponent(' in js, name
|
|
assert '"&path=" + encodeURIComponent(' in js, name
|
|
assert 'target = "_blank"' not in js, f"{name}: phase 26 — no new tabs"
|
|
|
|
app_js = _read(APP_JS)
|
|
# Chat: 3-arg builder with back defaulting to the chat page.
|
|
assert 'function documentUrl(source, path, back = "/")' in app_js
|
|
assert '"&back=" + encodeURIComponent(back)' in app_js
|
|
assert 'chip.href = documentUrl(s.source, s.path, "/")' in app_js
|
|
assert 'chip.addEventListener("click"' in app_js
|
|
assert "e.preventDefault()" in app_js
|
|
assert "openDocumentModal(s.source, s.path, chip)" in app_js
|
|
|
|
sources_js = _read(SOURCES_JS)
|
|
# Sources: unchanged 2-arg builder — no back param in the URL.
|
|
assert "function documentUrl(source, path)" in sources_js
|
|
assert 'link.className = "doc-link"' in sources_js
|
|
assert "link.href = documentUrl(d.source, d.path)" in sources_js
|
|
assert 'link.addEventListener("click"' in sources_js
|
|
assert "openDocumentModal(d.source, d.path, link)" in sources_js
|
|
# The full path stays the hover name on the ellipsized cell AND the link.
|
|
assert "pathTd.title = d.path" in sources_js
|
|
assert "link.title = d.path" in sources_js
|
|
|
|
|
|
def _run_node(script: str) -> str:
|
|
proc = subprocess.run(["node", "-e", script], capture_output=True, text=True, timeout=60)
|
|
assert proc.returncode == 0, f"node failed: {proc.stderr}"
|
|
return proc.stdout
|
|
|
|
|
|
def _extract_function(js: str, name: str) -> str:
|
|
match = re.search(
|
|
rf"(?:export )?function {name}\(source, path(?:, back = \"/\")?\) \{{.*?\n\}}", js, re.S
|
|
)
|
|
assert match, f"{name}(source, path) not found"
|
|
return match.group(0).replace("export ", "", 1)
|
|
|
|
|
|
@pytest.mark.skipif(not HAVE_NODE, reason="node not available")
|
|
def test_viewer_url_builder_encodes_spaces_and_slashes() -> None:
|
|
"""Behavioral check of the real builder (app.js) under node: slashes
|
|
and spaces in source/path values must come out percent-encoded, and
|
|
the back target is appended + encoded (phase 13)."""
|
|
fn = _extract_function(_read(APP_JS), "documentUrl")
|
|
out = _run_node(
|
|
f"{fn}\n"
|
|
"console.log(documentUrl('Homelab', 'kubernetes.md'));\n"
|
|
"console.log(documentUrl('Homelab', 'notes/my file.yaml'));\n"
|
|
"console.log(documentUrl('H omelab', 'a/b.md'));\n"
|
|
"console.log(documentUrl('Homelab', 'kubernetes.md', '/sources.html'));"
|
|
)
|
|
assert out.splitlines() == [
|
|
"/document.html?source=Homelab&path=kubernetes.md&back=%2F",
|
|
"/document.html?source=Homelab&path=notes%2Fmy%20file.yaml&back=%2F",
|
|
"/document.html?source=H%20omelab&path=a%2Fb.md&back=%2F",
|
|
"/document.html?source=Homelab&path=kubernetes.md&back=%2Fsources.html",
|
|
]
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Shared renderer extraction (phase 10 step 2)
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
def test_renderer_extracted_to_shared_markdown_js() -> None:
|
|
"""The renderer moved to assets/markdown.js (not duplicated in app.js)
|
|
and BOTH pages load it via a relative <script src> before their module
|
|
scripts — so the globals exist when app.js/document.js run."""
|
|
md = _read(MARKDOWN_JS)
|
|
assert "function renderMarkdown(md)" in md
|
|
assert "function escapeHtml(s)" in md
|
|
|
|
app_js = _read(APP_JS)
|
|
assert "function renderMarkdown" not in app_js, "renderer must live in markdown.js"
|
|
assert "function escapeHtml" not in app_js
|
|
|
|
for page in ("index.html", "document.html"):
|
|
html = _read(FRONTEND / page)
|
|
assert re.search(r'<script src="assets/markdown\.js"></script>', html), (
|
|
f"{page} must load markdown.js via a relative <script src>"
|
|
)
|
|
assert html.index('src="assets/markdown.js"') < html.index('type="module"'), (
|
|
f"{page}: markdown.js must load before the module script"
|
|
)
|
|
|
|
|
|
@pytest.mark.skipif(not HAVE_NODE, reason="node not available")
|
|
def test_markdown_renderer_stays_xss_safe_and_unchanged() -> None:
|
|
"""Behavioral check (node) that the extracted renderer still escapes
|
|
first: hostile content never becomes live HTML; basic transforms work."""
|
|
js = _read(MARKDOWN_JS)
|
|
out = _run_node(
|
|
js
|
|
+ "\nconsole.log(renderMarkdown('# Title\\n\\n<script>alert(1)</script>"
|
|
+ "\\n\\n**bold** and `code`'));"
|
|
)
|
|
html = out.strip()
|
|
assert "<script>" not in html # never live HTML
|
|
assert "<script>alert(1)</script>" in html
|
|
assert "<strong>bold</strong>" in html
|
|
assert "<code>code</code>" in html
|
|
assert "<h3>Title</h3>" in html
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Phase 26 — shared renderDocument + the document modal wiring
|
|
# ---------------------------------------------------------------------------
|
|
|
|
|
|
def test_render_document_exported_and_modal_imports_it() -> None:
|
|
"""Phase 26: document.js EXPORTS renderDocument(doc, { … }) — the
|
|
exact renderer the standalone page and the modal share (no drift).
|
|
The modal module imports it relatively, and BOTH page scripts import
|
|
the modal module relatively — no direct <script> tag (the header.js
|
|
single-evaluation design: esbuild inlines it into the page bundle,
|
|
one module instance per page)."""
|
|
doc_js = _read(DOCUMENT_JS)
|
|
# Task 03 signature: the page passes its #doc-title / #doc-meta /
|
|
# #doc-content elements under exactly these names.
|
|
assert "export function renderDocument(doc, { titleEl, metaEl, contentEl })" in doc_js, (
|
|
"document.js must export renderDocument(doc, { titleEl, metaEl, contentEl })"
|
|
)
|
|
# The standalone page renders through the SAME shared function with its
|
|
# own page elements (no second renderer copy).
|
|
assert "renderDocument(doc, { titleEl, metaEl, contentEl })" in doc_js
|
|
modal_js = _read(MODAL_JS)
|
|
assert 'from "./document.js"' in modal_js
|
|
assert "export function openDocumentModal(" in modal_js
|
|
assert "export function closeDocumentModal(" in modal_js
|
|
for name, js in (("app.js", _read(APP_JS)), ("sources.js", _read(SOURCES_JS))):
|
|
assert 'from "./document-modal.js"' in js, (
|
|
f"{name}: must import the modal module relatively"
|
|
)
|
|
for page in (INDEX_HTML, SOURCES_HTML):
|
|
text = _read(page)
|
|
assert not re.search(r"<script[^>]*document-modal\.js", text), (
|
|
f"{page.name}: no direct document-modal.js <script> tag "
|
|
"(single-evaluation design — the page script imports it)"
|
|
)
|
|
|
|
|
|
def test_document_js_page_init_is_import_safe() -> None:
|
|
"""Phase 26: the /document.html-specific init (back-link resolution,
|
|
whoami, content load) runs ONLY when #doc-title exists — the modal
|
|
module's `import { renderDocument } from "./document.js"` on the
|
|
chat/sources pages must have no side effects."""
|
|
js = _read(DOCUMENT_JS)
|
|
guard = js.find('querySelector("#doc-title")')
|
|
back_href = js.find("backLink.href = backTarget")
|
|
load_call = js.rfind("load();")
|
|
assert 0 < guard < back_href < load_call, (
|
|
"the viewer-page init must sit inside the #doc-title guard "
|
|
"(after it, and load() must be the guarded entry point)"
|
|
)
|
|
|
|
|
|
def test_both_pages_carry_the_modal_skeleton() -> None:
|
|
"""Phase 26: chat AND Sources ship the same modal skeleton (the
|
|
task-01 markup) — the a11y frame included: role=dialog +
|
|
aria-modal, a labelled close control, a focusable content target
|
|
(tabindex=-1), and a role=status announcer. Hidden by default —
|
|
inert until JS opens it."""
|
|
for page in (INDEX_HTML, SOURCES_HTML):
|
|
text = _read(page)
|
|
assert '<div class="doc-modal" id="doc-modal" hidden>' in text, page.name
|
|
assert 'id="doc-modal-backdrop"' in text, page.name
|
|
assert 'id="doc-modal-panel"' in text, page.name
|
|
assert 'role="dialog"' in text and 'aria-modal="true"' in text, page.name
|
|
assert 'id="doc-modal-title"' in text, page.name
|
|
assert 'id="doc-modal-meta"' in text, page.name
|
|
assert 'id="doc-modal-desc"' in text, page.name
|
|
assert 'id="doc-modal-open"' in text, page.name
|
|
assert re.search(r'id="doc-modal-content"[^>]*tabindex="-1"', text), page.name
|
|
assert re.search(
|
|
r'id="doc-modal-close"[^>]*aria-label="Close document"', text
|
|
), page.name
|
|
|
|
|
|
def test_sources_page_loads_markdown_before_its_module() -> None:
|
|
"""Phase 26: the modal renders md documents on the Sources page too —
|
|
so sources.html loads the classic markdown.js (global renderMarkdown)
|
|
via a relative <script src> BEFORE its module script, exactly like
|
|
index.html does."""
|
|
html = _read(SOURCES_HTML)
|
|
assert re.search(r'<script src="assets/markdown\.js"></script>', html)
|
|
assert html.index('src="assets/markdown.js"') < html.index('type="module"'), (
|
|
"sources.html: markdown.js must load before the module script"
|
|
)
|
|
|
|
|
|
def test_modal_close_contract_pins() -> None:
|
|
"""Phase 26: the modal closes on the close button, on backdrop
|
|
click, and on Escape (captured document-level, so it works from any
|
|
focus position); focus returns to the triggering control
|
|
(best-effort); the fetch goes to the stateless content endpoint with
|
|
the same percent-encoding the page uses, and success renders through
|
|
the shared renderDocument; the "Full page" link is rebuilt on open."""
|
|
js = _read(MODAL_JS)
|
|
assert 'e.key === "Escape"' in js
|
|
assert 'addEventListener("keydown"' in js
|
|
assert "backdropEl.addEventListener(\"click\", closeDocumentModal)" in js
|
|
assert "closeEl.addEventListener(\"click\", closeDocumentModal)" in js
|
|
assert "triggerEl.focus" in js # best-effort focus restore
|
|
assert '"/api/documents/content?source=" + encodeURIComponent(' in js
|
|
assert '"&path=" + encodeURIComponent(' in js
|
|
# The shared renderer (not a copy), called with the modal's own
|
|
# #doc-modal-title / #doc-modal-meta / #doc-modal-content elements.
|
|
assert "renderDocument(doc, { titleEl, metaEl, contentEl })" in js
|
|
assert 'openEl.href = fullPageUrl(source, path)' in js
|
|
|
|
|
|
@pytest.mark.skipif(not HAVE_NODE, reason="node not available")
|
|
def test_modal_url_builders_encode_like_the_page() -> None:
|
|
"""Behavioral check (node) of the modal's own URL builders: the
|
|
content fetch and the "Full page" href must come out percent-encoded
|
|
exactly like the page's builders (slashes/spaces in real paths)."""
|
|
js = _read(MODAL_JS)
|
|
content_fn = _extract_function(js, "contentUrl")
|
|
full_fn = _extract_function(js, "fullPageUrl")
|
|
out = _run_node(
|
|
content_fn
|
|
+ full_fn
|
|
+ "\nconsole.log(contentUrl('Homelab', 'notes/my file.yaml'));\n"
|
|
+ "console.log(fullPageUrl('H omelab', 'a/b.md'));"
|
|
)
|
|
assert out.splitlines() == [
|
|
"/api/documents/content?source=Homelab&path=notes%2Fmy%20file.yaml",
|
|
"/document.html?source=H%20omelab&path=a%2Fb.md",
|
|
]
|
|
|
|
|
|
def test_viewer_js_rendering_contracts() -> None:
|
|
"""document.js: raw formats go in via textContent (never parsed as
|
|
HTML), markdown via the shared renderer, 404 → designed not-found
|
|
state, and (phase 13) the back link resolves the ``back`` param —
|
|
same-origin relative URLs only, /sources.html default, no browser
|
|
history heuristics (both entry points are fresh tabs)."""
|
|
js = _read(DOCUMENT_JS)
|
|
assert "pre.textContent = doc.content" in js # raw formats: text node
|
|
assert "renderMarkdown(doc.content)" in js # md/markdown: shared renderer
|
|
assert "showNotFound" in js
|
|
# Phase 13: deterministic back-target resolution, no history heuristics.
|
|
assert "history.length" not in js
|
|
assert "window.history.back" not in js
|
|
assert 'backParam.startsWith("/")' in js # same-origin relative only…
|
|
assert 'backParam.startsWith("//")' in js # …and not protocol-relative
|
|
assert 'backLink.href = backTarget' in js # deterministic anchor navigation
|
|
assert '"/sources.html"' in js # default target + no-JS fallback value
|
|
assert '"Chat"' in js and '"Sources"' in js # labels for the two entry points
|
|
assert "encodeURIComponent" in js # content fetch uses the same encoding
|