Repository navigation
fix(design-critique): refuse a junctioned dir in the served signature - #14595
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Confirm the windows-latest CI leg collected and passed [DESIGN-REVIEWED] 9178581 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Confirm the Windows CI leg actually collects this in-package test file, so the junction path runs red-before/green-after rather than only the Linux symlink half. What this change shipsInventory (5 items) — 5 justifiedIntent: FIX — stop the Design Critique screenshot cache from discarding good screenshots when files change behind a Windows junction the preview server never serves.
[FIRST-PRINCIPLES-REVIEWED] 9178581 |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
bd274ee to
33bab24
Compare
_served_signature's os.path.islink guards returned False for a Windows directory junction, so the signature walk descended into a junction inside the build dir and signed bytes the preview server never serves. Both guards now go through platform_compat.is_link_or_junction (already imported), which tries os.path.islink first so symlink behaviour is bit-for-bit unchanged and each guard is strictly widened. The corrected docstring paragraph is updated in the same change. A Windows _winapi.CreateJunction-backed test pins that the digest and newest_mtime_ns do not move for bytes behind the junction, with a guard-the-guard assertion; CreateJunction is resolved via a guarded module import + getattr so mypy on Linux does not error on the win32-only attribute. The is_link_or_junction guard makes _served_signature a screen-then-read site the link-screen ratchet discovers, so it is recorded in the regenerated test/link_screen_sites.py baseline. It is a REFUSING site, not a held one: both guards drop every link/junction (the dirs prune skips them, the files loop continues past them) and it never traverses one, so no hold is needed and it is not added to HELD_SITES. Co-authored-by: Leon <276034861+leonlaiyc@users.noreply.github.com>
33bab24 to
9178581
Compare
Pull Request is not mergeable
bolichen97
left a comment
There was a problem hiding this comment.
os.path.islink -> platform_compat.is_link_or_junction on both the dir prune and the file skip, matching capture-build.mjs's Dirent test; link-screen site declared. 122 tests pass locally (Linux half). LGTM.
Problem / Motivation
Goal: On Windows, stop the Design Critique screenshot cache from throwing away good screenshots when files change behind a directory junction the preview server never serves.
_served_signaturein the Design Critique backend digests the filescapture-build.mjswill actually serve, so/rendercan tell whether a cachedprobe screenshot still matches the current build output. The two enumerations are
a documented contract. Node's
Direnttest refuses a Windows directory junction(it reports one as a symbolic link), so the server serves nothing behind it. The
Python half used
os.path.islink, which returnsFalsefor that same junction —so the walk descended into it and signed bytes the server never serves.
Why it matters
On Windows, signing an unserved tree behind a junction has three costs the
signature's own docstring names:
screenshot for the whole reuse TTL, and a re-capture is a full headless render.
newest_mtime_ns,the high-water mark the mid-capture check reads, and make a fine capture look stale.
_SIGNATURE_MAX_FILESpressure. Files behind the junction increment thecounter, so a junction over a large tree can push a small build over the cap and
make the signature return
None(callers must then refuse reuse entirely).This is not a disclosure bug and does not claim to be one: the token is a digest
and is never served.
Not a goal
different helper (
first_linked_ancestor); the build dir is already anchoredlexically under the validated project dir. Out of scope, and not measured here.
What changed (motivation → approach → change)
Symptom: on Windows the cache token moves for bytes the server will not serve.
Root cause:
os.path.islinkis the wrong predicate for the contract — Noderefuses a junction, Python admits it. Change: both guards in
_served_signaturenow go through
platform_compat.is_link_or_junction, which is already imported inthe module and tries
os.path.islinkfirst, so symlink behaviour is unchanged andeach guard is only widened. The docstring paragraph that claimed the two
enumerations agree is corrected in the same change.
The two guards, one contract:
dirs[:]pruneos.walk's files list); changed so both halves read through one predicatecapture-build.mjsneeds no change — it already excludes the junction.Backwards compatibility
Compatible:
is_link_or_junctiontriesos.path.islinkfirst, so on POSIX andfor symlinks the result is bit-for-bit identical; the only behaviour change is that
a Windows junction is now refused, which restores the intended contract.
Tests
test_served_signature_refuses_a_junctioned_directory(in the existingtest_backend_routes.py) pins that, with a junction inside the build dir, thedigest does not move when the junction appears, the digest does not move when a
file behind it changes, and
newest_mtime_nsis unchanged by that edit — thefield the existing symlink test does not assert. It carries a guard-the-guard
assertion so on Windows the link is really the shape
os.path.islinkmisreads(
islinkFalse,isdirTrue), and it uses a junction on Windows (no privilegerequired) and a symlink elsewhere, so on Linux CI it is a no-regression check and
only Windows exercises the fix.
The test resolves
_winapi.CreateJunctionthrough a guarded module-level importplus
getattr, mirroringplatform_compat's owngetattr(os.path, "isjunction", None), so mypy on Linux does not error on the win32-only attribute. The Windowspath creates a real junction and nothing else — never a symlink fallback, which is
the shape
os.path.islinkalready refused.The new
is_link_or_junctionguard makes_served_signaturea screen-then-readsite the link-screen ratchet discovers, so it is recorded in the regenerated
test/link_screen_sites.pybaseline — a refusing site (both guards drop everylink/junction and it never traverses one), not a held one, so it is not added to
HELD_SITES.Manual verification
N/A — unit coverage sufficient. The behaviour is a pure function of a directory
tree, and the test builds the exact tree the defect needs; the cross-language half
of the contract is Node's
Direntpredicate, which already excludes the junction.Related Issues
no linked issue: this site was named by First Principles on merged
#8767 and accepted-and-deferred there, then re-measured against
current main before this PR.
Pattern harvest
Rule candidate: review-prompt
Pattern: an
os.path.islinkguard that must refuse a Windows junction — correct onPOSIX, silently open on Windows, where
islinkcalls a junction a plain directory.Scoped as a review prompt, not a sweep: these sites are decided one at a time on
harm, and the harm differs between them (this one is digest coverage, not
disclosure). A second, narrower pattern hid this one: a contract asserted across
two languages but tested on only one of them.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)docs/spec covers_served_signatureSupersedes #9021 (fork PR by @leonlaiyc). Re-applies that work onto current main as
an in-repo PR so the CI + review lanes run without fork friction; authorship and
credit preserved via the commit author and a
Co-authored-bytrailer.