phase: 145_git_source_links
**Phase 145 final verification pass — all green, no code changes needed** - **Verified (no defects found):** resolver `origin_for_source` + `_url_basename` (scp/`.git`/trailing-slash, sanitize, ambiguity WARNING); `origin:`/`branch:` lines in all four read shapes via shared `_origin_lines`; HIGH `<tools>` origin rule (verbatim + only-byte-change pins); `DocContent.origin_url/origin_branch` (absent-never-null serializer); `renderDocument` "Original" anchor (copyable verbatim URL, `_blank`/`noopener`, branch in title); mock scripted origin-link flow (disjoint trigger — grep-verified vs all other E2E files) - **Tests:** `uv run pytest --cov=app --cov-report=term-missing` → 3402 passed, `app/` coverage **99%** (>90% gate); `uv run pytest tests/e2e/test_git_source_links.py -v --no-cov` → **4 passed** in isolation; `uv run ruff check .` → clean; `uv run pyright` → 0 errors, 0 warnings - **Completion criteria:** (1) git read results carry origin/branch, local byte-identical — ✅ (unit pins + E2E control); (2) HIGH `<tools>` rule pinned, LOW byte-identical — ✅; (3) modal AND /document.html show Original link, branch in label when pinned, nothing for local — ✅; (4) full suite green + coverage + E2E + lint/types — ✅; (5) no completed-phase behavior change (read header line 1, mock prefix, done frame/SourceRef untouched, LOW sha) — ✅ - **Extra regression check:** re-ran shared-mock E2E suites `test_read_line_ranges.py` (2 passed) and `test_document_viewer.py` (8 passed) — no cross-suite regressions from the `mock_llm.py` addition - **Documentation:** README.md reviewed in full (env table ⊇ `.env.example`, pages/routes, config defaults, scripts, 17-color palette, 300 s guard, 2 s sync poll, phase-145 provenance section matches implementation) and AGENTS.md (72rem container, no-CDN test, smoke test, gitignore, gates) — **verified consistent, no changes needed** - **Notable:** phase-116 screenshot PNG was regenerated during this phase's E2E runs (byte re-encode only, visually identical, correct no-anchor local-source meta row) — left in tree for the harness commit - **Next pending phase:** `146_search_tool_scope` (then 147, 148, 149)
This commit is contained in:
@@ -20,9 +20,29 @@ Frontend side:
|
||||
* 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.
|
||||
|
||||
Phase 145 (task 03) — the content payload's git origin fields + the
|
||||
``renderDocument`` "Original" anchor (modal AND /document.html, one
|
||||
site):
|
||||
* the ``DocContent`` omission rule — both origin keys ABSENT on the
|
||||
wire when ``None`` (never ``null``; non-git payload byte-identical);
|
||||
* the content endpoint (stubbed session) — a matching ``kind='git'``
|
||||
row adds ``origin_url`` (+ ``origin_branch`` for a pinned row), a
|
||||
legacy embedded-credential row is served sanitized, and local /
|
||||
ambiguous sources keep the pre-phase key set;
|
||||
* the anchor itself (source pins + a node behavioral check over a
|
||||
minimal fake DOM) — ``createElement("a")``, the full URL verbatim as
|
||||
``href`` AND visible text (the copyable-link contract),
|
||||
``target="_blank" rel="noopener"``, the ``title`` = full URL (+
|
||||
`` — branch: <name>`` when pinned), inserted AFTER the path code and
|
||||
BEFORE the Created badge (absent → the pre-phase six children), no
|
||||
innerHTML/outerHTML (the module's ONE innerHTML survives), and the
|
||||
``.doc-origin`` CSS mirroring the ``.doc-path`` ellipsis idiom with
|
||||
the ``.doc-link`` affordance (+ the ≤640px squeeze).
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
import shutil
|
||||
import subprocess
|
||||
@@ -35,7 +55,8 @@ 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
|
||||
from app.models import Document, GitSource
|
||||
from app.schemas import DocContent
|
||||
from tests.conftest import ADMIN_PASSWORD
|
||||
|
||||
FRONTEND = Path(__file__).resolve().parents[2] / "frontend"
|
||||
@@ -126,22 +147,39 @@ class _FakeResult:
|
||||
return self._row
|
||||
|
||||
|
||||
class _FakeScalars:
|
||||
"""The resolver's ``db.scalars(...).all()`` — only the git rows
|
||||
ever reach the caller (the ``kind = 'git'`` WHERE clause is
|
||||
emulated, the task-01 ``_GitOnlySession`` pattern)."""
|
||||
|
||||
def __init__(self, rows: tuple[GitSource, ...]) -> None:
|
||||
self._rows = [row for row in rows if row.kind == "git"]
|
||||
|
||||
def all(self) -> list[GitSource]:
|
||||
return self._rows
|
||||
|
||||
|
||||
class _FakeSession:
|
||||
def __init__(self, row: object) -> None:
|
||||
def __init__(self, row: object, git_rows: tuple[GitSource, ...] = ()) -> None:
|
||||
self._row = row
|
||||
self._git_rows = git_rows
|
||||
|
||||
def execute(self, _stmt: object) -> _FakeResult:
|
||||
return _FakeResult(self._row)
|
||||
|
||||
def scalars(self, _stmt: object) -> _FakeScalars:
|
||||
return _FakeScalars(self._git_rows)
|
||||
|
||||
def _client_with_row(row: object) -> TestClient:
|
||||
|
||||
def _client_with_row(row: object, git_rows: tuple[GitSource, ...] = ()) -> TestClient:
|
||||
"""Fresh app whose ``get_db`` dependency is a stub returning ``row``
|
||||
(``None`` → no matching document row). Phase 79: the endpoint is
|
||||
user-gated, so the client signs in as the admin first — these tests
|
||||
pin the CONTENT mapping (200/404/422), not the auth contract (which
|
||||
``test_auth_api.py`` pins)."""
|
||||
(``None`` → no matching document row) and, for the phase-145
|
||||
origin lookup, *git_rows* (default: no rows — the non-git corner).
|
||||
Phase 79: the endpoint is user-gated, so the client signs in as
|
||||
the admin first — these tests pin the CONTENT mapping (200/404/
|
||||
422), not the auth contract (which ``test_auth_api.py`` pins)."""
|
||||
app = create_app()
|
||||
app.dependency_overrides[get_db] = lambda: _FakeSession(row)
|
||||
app.dependency_overrides[get_db] = lambda: _FakeSession(row, git_rows)
|
||||
client = TestClient(app)
|
||||
r = client.post("/api/login", json={"password": ADMIN_PASSWORD})
|
||||
assert r.status_code == 204, f"admin login failed: {r.status_code} {r.text}"
|
||||
@@ -217,6 +255,322 @@ def test_content_requires_both_params() -> None:
|
||||
assert client.get("/api/documents/content", params={"source": "Homelab"}).status_code == 422
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Phase 145 (task 03) — the content payload's git origin fields + the
|
||||
# renderDocument "Original" anchor (modal AND /document.html, one site)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _text_doc() -> Document:
|
||||
"""The content-endpoint stub's document row (a markdown doc — no
|
||||
summary, the pre-phase shape)."""
|
||||
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,
|
||||
is_image=False, # phase 122: the stub session never applies defaults
|
||||
)
|
||||
doc.indexed_at = datetime(2026, 8, 22, 1, 2, 3, tzinfo=UTC)
|
||||
doc.created_at = datetime(2026, 8, 20, 9, 0, 0, tzinfo=UTC)
|
||||
return doc
|
||||
|
||||
|
||||
def _text_doc_content(
|
||||
origin_url: str | None = None, origin_branch: str | None = None
|
||||
) -> DocContent:
|
||||
"""One text doc's content payload (the pre-phase shape) with the
|
||||
phase-145 origin fields optionally set."""
|
||||
return DocContent(
|
||||
source="S",
|
||||
path="a.md",
|
||||
title="A",
|
||||
format="md",
|
||||
created_at="2026-01-01T00:00:00+00:00",
|
||||
content="body",
|
||||
indexed_at="2026-01-01T00:00:00+00:00",
|
||||
chunks=1,
|
||||
origin_url=origin_url,
|
||||
origin_branch=origin_branch,
|
||||
)
|
||||
|
||||
|
||||
def test_doc_content_origin_fields_absent_on_the_wire_when_unset() -> None:
|
||||
"""The model-level omission rule (the :func:`_drop_absent_share_url`
|
||||
precedent, the ``image_url`` shape): a non-git document (no
|
||||
``origin_url``) serializes with BOTH origin keys ABSENT — never
|
||||
``null`` — so the payload is byte-identical to pre-phase. A
|
||||
sanitized-URL-only payload (an unpinned row) drops
|
||||
``origin_branch``; a pinned row keeps both keys."""
|
||||
dumped = _text_doc_content().model_dump()
|
||||
assert "origin_url" not in dumped # absent — never null
|
||||
assert "origin_branch" not in dumped # absent — never null
|
||||
dumped = _text_doc_content(origin_url="https://host/x.git").model_dump()
|
||||
assert dumped["origin_url"] == "https://host/x.git"
|
||||
assert "origin_branch" not in dumped # NULL = the default branch — nothing to show
|
||||
dumped = _text_doc_content(
|
||||
origin_url="https://host/x.git", origin_branch="docs"
|
||||
).model_dump()
|
||||
assert dumped["origin_branch"] == "docs"
|
||||
|
||||
|
||||
def test_content_origin_url_carried_for_a_matching_git_row() -> None:
|
||||
"""The endpoint (stubbed session, no database): a ``kind='git'``
|
||||
row whose URL basename matches the document's source adds
|
||||
``origin_url`` — the sanitized clone URL — to the payload, and
|
||||
every pre-phase key stands untouched. The row pins no branch →
|
||||
``origin_branch`` is ABSENT (never ``null``)."""
|
||||
row = GitSource(url="https://github.com/reese/Homelab.git", kind="git")
|
||||
with _client_with_row((_text_doc(), 3), git_rows=(row,)) 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", "summary", "created_at",
|
||||
"content", "indexed_at", "chunks", "is_image", "origin_url",
|
||||
}
|
||||
assert body["origin_url"] == "https://github.com/reese/Homelab.git"
|
||||
assert "origin_branch" not in body # absent — never null (unpinned row)
|
||||
|
||||
|
||||
def test_content_origin_branch_carried_for_a_pinned_row() -> None:
|
||||
"""A pinned row (phase 135 ``branch``) also carries
|
||||
``origin_branch`` — the branch the title attribute will show."""
|
||||
row = GitSource(
|
||||
url="https://github.com/reese/Homelab.git", kind="git", branch="docs"
|
||||
)
|
||||
with _client_with_row((_text_doc(), 3), git_rows=(row,)) as client:
|
||||
r = client.get(
|
||||
"/api/documents/content",
|
||||
params={"source": "Homelab", "path": "notes/deep mark.md"},
|
||||
)
|
||||
body = r.json()
|
||||
assert body["origin_url"] == "https://github.com/reese/Homelab.git"
|
||||
assert body["origin_branch"] == "docs"
|
||||
|
||||
|
||||
def test_content_origin_url_sanitizes_a_legacy_embedded_credential_row() -> None:
|
||||
"""End-to-end (stubbed): a legacy row whose credential is still
|
||||
embedded in the stored URL never leaks it — the payload carries
|
||||
the phase-121 sanitized URL (the resolver's guarantee, one mapping
|
||||
for the whole app)."""
|
||||
row = GitSource(url="https://user:tok@example.com/reese/Homelab.git", kind="git")
|
||||
with _client_with_row((_text_doc(), 3), git_rows=(row,)) as client:
|
||||
r = client.get(
|
||||
"/api/documents/content",
|
||||
params={"source": "Homelab", "path": "notes/deep mark.md"},
|
||||
)
|
||||
body = r.json()
|
||||
assert body["origin_url"] == "https://example.com/reese/Homelab.git"
|
||||
assert "user:tok" not in r.text # the credential stays out of the wire
|
||||
|
||||
|
||||
def test_content_origin_fields_absent_for_local_and_ambiguous_sources() -> None:
|
||||
"""No git row (a plain local source) OR two rows sharing the
|
||||
basename (ambiguous — never guess) → both origin keys ABSENT from
|
||||
the JSON (not ``null`` — the omission pinned on the wire; the
|
||||
payload is byte-identical to pre-phase, the ``test_content_known_
|
||||
pair_maps_to_doc_content`` key-set pin)."""
|
||||
local_only = (_text_doc(), 3)
|
||||
with _client_with_row(local_only) as client: # no git rows at all
|
||||
r = client.get(
|
||||
"/api/documents/content",
|
||||
params={"source": "Homelab", "path": "notes/deep mark.md"},
|
||||
)
|
||||
assert r.status_code == 200
|
||||
assert "origin_url" not in r.json()
|
||||
assert "origin_branch" not in r.json()
|
||||
|
||||
ambiguous = (
|
||||
GitSource(url="https://a.example/org/Homelab.git", kind="git"),
|
||||
GitSource(url="git@b.example:other/Homelab.git", kind="git"),
|
||||
)
|
||||
with _client_with_row(local_only, git_rows=ambiguous) as client:
|
||||
r = client.get(
|
||||
"/api/documents/content",
|
||||
params={"source": "Homelab", "path": "notes/deep mark.md"},
|
||||
)
|
||||
assert r.status_code == 200
|
||||
assert "origin_url" not in r.json()
|
||||
assert "origin_branch" not in r.json()
|
||||
|
||||
|
||||
# ---------- the renderDocument "Original" anchor (the shared core) ----------
|
||||
|
||||
|
||||
def _fn(js: str, name: str) -> str:
|
||||
"""The source of a top-level function via balanced-brace counting
|
||||
(the ``test_date_editor.py`` pattern)."""
|
||||
start = js.find(f"function {name}(")
|
||||
assert start != -1, f"{name}() must exist in document.js"
|
||||
i = js.find("(", start)
|
||||
depth = 0
|
||||
close = i
|
||||
while i < len(js):
|
||||
if js[i] == "(":
|
||||
depth += 1
|
||||
elif js[i] == ")":
|
||||
depth -= 1
|
||||
if depth == 0:
|
||||
close = i
|
||||
break
|
||||
i += 1
|
||||
brace = js.find("{", close)
|
||||
depth = 0
|
||||
for j in range(brace, len(js)):
|
||||
if js[j] == "{":
|
||||
depth += 1
|
||||
elif js[j] == "}":
|
||||
depth -= 1
|
||||
if depth == 0:
|
||||
return js[start : j + 1]
|
||||
raise AssertionError(f"unbalanced braces in {name}()")
|
||||
|
||||
|
||||
def test_origin_anchor_is_a_copyable_external_link() -> None:
|
||||
"""The anchor (house-style source contract): ``createElement("a")``
|
||||
(the never-build-HTML rule), the ``doc-origin`` class, ``href =
|
||||
doc.origin_url``, ``target="_blank" rel="noopener"`` (the modal's
|
||||
"Full page" escape-hatch idiom), the full URL VERBATIM as the
|
||||
visible text (the copyable-link contract — no decorative label),
|
||||
and the ``title`` = the full URL, plus `` — branch: <name>`` when
|
||||
the payload pins a branch (the pathCode precision idiom)."""
|
||||
body = _fn(_read(DOCUMENT_JS), "originAnchor")
|
||||
assert 'document.createElement("a")' in body
|
||||
assert 'a.className = "doc-origin"' in body
|
||||
assert "a.href = doc.origin_url" in body
|
||||
assert 'a.target = "_blank"' in body
|
||||
assert 'a.rel = "noopener"' in body
|
||||
assert "a.textContent = doc.origin_url" in body, (
|
||||
"the visible text is the full URL verbatim (copy-pasteable)"
|
||||
)
|
||||
branch_title = 'doc.origin_url + " — branch: " + doc.origin_branch'
|
||||
assert 'doc.origin_branch ? ' + branch_title + " : doc.origin_url" in body, (
|
||||
"the title carries the full URL (+ the pinned branch when present)"
|
||||
)
|
||||
# The never-build-HTML shape: no innerHTML/outerHTML in the new code.
|
||||
code = re.sub(r"//.*?$|/\*.*?\*/", "", body, flags=re.S | re.M)
|
||||
assert "innerHTML" not in code and "outerHTML" not in code
|
||||
|
||||
|
||||
@pytest.mark.skipif(not HAVE_NODE, reason="node not available")
|
||||
def test_origin_anchor_behaves_for_branch_and_no_branch_variants() -> None:
|
||||
"""Behavioral check (node, minimal fake DOM) of the real anchor
|
||||
builder: the exact ``href``/``target``/``rel``/``textContent``/
|
||||
``title`` for a git doc, branch and no-branch variants."""
|
||||
fn = _fn(_read(DOCUMENT_JS), "originAnchor")
|
||||
fake_dom = (
|
||||
"globalThis.document = { createElement: (tag) => {"
|
||||
' const el = { tag, className: "", href: "", target: "", rel: "",'
|
||||
' textContent: "", setAttribute(k, v) { this[k] = v; } };'
|
||||
" return el; } };"
|
||||
)
|
||||
out = _run_node(
|
||||
fake_dom
|
||||
+ "\n" + fn
|
||||
+ '\nconst g1 = originAnchor({ origin_url: "https://github.com/reese/skills.git",'
|
||||
' origin_branch: "main" });' + "\n"
|
||||
+ '\nconst g2 = originAnchor({ origin_url: "https://github.com/reese/skills.git" });' + "\n"
|
||||
+ "console.log(JSON.stringify(g1));\nconsole.log(JSON.stringify(g2));"
|
||||
)
|
||||
j1, j2 = (json.loads(line) for line in out.splitlines())
|
||||
for j in (j1, j2):
|
||||
assert j["tag"] == "a"
|
||||
assert j["className"] == "doc-origin"
|
||||
assert j["href"] == "https://github.com/reese/skills.git"
|
||||
assert j["target"] == "_blank"
|
||||
assert j["rel"] == "noopener"
|
||||
# The full URL VERBATIM as the visible text (copy-pasteable).
|
||||
assert j["textContent"] == "https://github.com/reese/skills.git"
|
||||
# The title: the full URL, + the pinned branch when present.
|
||||
assert j1["title"] == "https://github.com/reese/skills.git — branch: main"
|
||||
assert j2["title"] == "https://github.com/reese/skills.git"
|
||||
|
||||
|
||||
def test_origin_anchor_sits_after_the_path_code_before_the_created_badge() -> None:
|
||||
"""renderDocument (the ONE shared core — modal AND /document.html):
|
||||
the anchor joins the meta row AFTER the path ``code`` and BEFORE
|
||||
the Created badge — and ONLY when the payload carries
|
||||
``origin_url``. Absent (a non-git document — the field simply
|
||||
missing on the wire) → the gate builds the empty array, the
|
||||
spread adds nothing, and the meta row's children are EXACTLY the
|
||||
pre-phase six (the existing badge-order pins pass unchanged)."""
|
||||
render = _fn(_read(DOCUMENT_JS), "renderDocument")
|
||||
gate_i = render.find("const originItems = doc.origin_url ? [originAnchor(doc)] : [];")
|
||||
call_i = render.find("metaEl.replaceChildren(")
|
||||
path_i = render.find("pathCode,", call_i)
|
||||
spread_i = render.find("...originItems,", call_i)
|
||||
created_i = render.find('metaBadge("doc-created"', call_i)
|
||||
assert -1 < gate_i < call_i < path_i < spread_i < created_i, (
|
||||
"the anchor gate precedes the row build and lands AFTER the path code, "
|
||||
"BEFORE the Created badge"
|
||||
)
|
||||
# The gate: present only on a truthy origin_url — an ABSENT field
|
||||
# (undefined) is falsy → [] → the pre-phase children stand.
|
||||
assert "doc.origin_url ? [originAnchor(doc)] : []" in render
|
||||
# The spread is the meta row's ONLY conditional child (the six
|
||||
# pre-phase children are the fixed ones).
|
||||
assert render[call_i:].count("...") == 1
|
||||
|
||||
|
||||
def test_origin_anchor_keeps_the_module_xss_contract() -> None:
|
||||
"""The module's ONE innerHTML (the escape-first markdown render)
|
||||
survives — the new anchor adds no HTML-building of its own
|
||||
(createElement + properties/textContent only)."""
|
||||
code = re.sub(r"//.*", "", re.sub(r"/\*.*?\*/", "", _read(DOCUMENT_JS), flags=re.S))
|
||||
assert code.count("innerHTML") == 1
|
||||
assert "outerHTML" not in code
|
||||
|
||||
|
||||
def test_doc_origin_css_mirrors_the_doc_path_ellipsis_idiom() -> None:
|
||||
"""styles.css: the ``.doc-origin`` rule sits next to the
|
||||
``.doc-path`` family (mono, 0.75rem, the same 26rem ellipsis
|
||||
budget + 6rem floor) with the ``.doc-link`` affordance
|
||||
(brand-ink, underline on hover/focus — the existing link
|
||||
tokens), provenance-cited, and the ≤640px block squeezes it like
|
||||
the path (16rem — the row's own wrap/clip rules are unchanged:
|
||||
the anchor is one more inline item)."""
|
||||
css = _read(FRONTEND / "assets" / "styles.css")
|
||||
rule_i = css.find(".doc-origin {")
|
||||
assert rule_i != -1, "styles.css must style .doc-origin"
|
||||
# Provenance comment directly above the rule (house style).
|
||||
comment_start = css.rfind("/*", 0, rule_i)
|
||||
assert -1 < comment_start < rule_i and "Phase 145 (task 03)" in css[comment_start:rule_i]
|
||||
# Next to the .doc-path family (before .doc-chunks).
|
||||
assert css.find(".doc-path {") < rule_i < css.find(".doc-chunks {")
|
||||
rule = css[rule_i : css.find("}", rule_i)]
|
||||
for decl in (
|
||||
"font-family: var(--mono)",
|
||||
"font-size: 0.75rem",
|
||||
"max-width: 26rem",
|
||||
"white-space: nowrap",
|
||||
"overflow: hidden",
|
||||
"text-overflow: ellipsis",
|
||||
"min-width: 6rem",
|
||||
"color: var(--brand-ink)",
|
||||
"text-decoration: none",
|
||||
):
|
||||
assert decl in rule, f".doc-origin must carry {decl!r}"
|
||||
# The .doc-link hover/focus affordance (the existing link idiom).
|
||||
assert ".doc-origin:hover, .doc-origin:focus-visible { text-decoration: underline; }" in css
|
||||
# The ≤640px squeeze mirrors .doc-path's 16rem (same media block).
|
||||
mobile = css.find("@media (max-width: 640px)")
|
||||
path_sq = css.find(".doc-path { max-width: 16rem; }", mobile)
|
||||
origin_sq = css.find(".doc-origin { max-width: 16rem; }", mobile)
|
||||
close_640 = css.find("@media", mobile + 1)
|
||||
assert -1 < path_sq < origin_sq < (close_640 if close_640 != -1 else len(css)), (
|
||||
"the mobile block squeezes the anchor like the path"
|
||||
)
|
||||
assert "url(http" not in css and "@import url(" not in css, (
|
||||
"no CDN (AGENTS.md rule 6)"
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Viewer URL builder — encoded query (spaces/slashes in real paths)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
Reference in New Issue
Block a user