Skip to content

fix(design-critique): refuse a junctioned dir in the served signature - #14595

Merged
chenmingwei23 merged 1 commit into
mainfrom
fix/design-critique-signature-junction-inrepo
Sep 28, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
fix/design-critique-signature-junction-inrepo

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

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_signature in the Design Critique backend digests the files
capture-build.mjs will actually serve, so /render can tell whether a cached
probe screenshot still matches the current build output. The two enumerations are
a documented contract. Node's Dirent test 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 returns False for 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:

  • Needless re-captures. Churn behind the junction invalidates a valid cached
    screenshot for the whole reuse TTL, and a re-capture is a full headless render.
  • A false staleness signal. An unserved edit could raise newest_mtime_ns,
    the high-water mark the mid-capture check reads, and make a fine capture look stale.
  • _SIGNATURE_MAX_FILES pressure. Files behind the junction increment the
    counter, 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

  • A junction in an ancestor of the build dir. That is a different threat with a
    different helper (first_linked_ancestor); the build dir is already anchored
    lexically 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.islink is the wrong predicate for the contract — Node
refuses a junction, Python admits it. Change: both guards in _served_signature
now go through platform_compat.is_link_or_junction, which is already imported in
the module and tries os.path.islink first, so symlink behaviour is unchanged and
each guard is only widened. The docstring paragraph that claimed the two
enumerations agree is corrected in the same change.

The two guards, one contract:

Guard Role
the dirs[:] prune the load-bearing one — the site the defect reproduces against
the files-loop check behaviour-preserving on its own (a junction never lands in os.walk's files list); changed so both halves read through one predicate

capture-build.mjs needs no change — it already excludes the junction.

Backwards compatibility

Compatible: is_link_or_junction tries os.path.islink first, so on POSIX and
for 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 existing
test_backend_routes.py) pins that, with a junction inside the build dir, the
digest does not move when the junction appears, the digest does not move when a
file behind it changes, and newest_mtime_ns is unchanged by that edit — the
field 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.islink misreads
(islink False, isdir True), and it uses a junction on Windows (no privilege
required) and a symlink elsewhere, so on Linux CI it is a no-regression check and
only Windows exercises the fix.

The test resolves _winapi.CreateJunction through a guarded module-level import
plus getattr, mirroring platform_compat's own getattr(os.path, "isjunction", None), so mypy on Linux does not error on the win32-only attribute. The Windows
path creates a real junction and nothing else — never a symlink fallback, which is
the shape os.path.islink already refused.

The new 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 — a refusing site (both guards drop every
link/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 Dirent predicate, 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.islink guard that must refuse a Windows junction — correct on
POSIX, silently open on Windows, where islink calls 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — the corrected paragraph is the function's own docstring; no docs/ spec covers _served_signature
  • No secrets, credentials, or internal references in the diff

Supersedes #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-by trailer.

@iamwhatever iamwhatever added the drive-to-green PR claimed by drive-to-green pipeline label Sep 28, 2026
@iamwhatever
iamwhatever requested a review from a team as a code owner September 28, 2026 02:21
@iamwhatever iamwhatever added the drive-to-green PR claimed by drive-to-green pipeline label Sep 28, 2026
@iamwhatever iamwhatever self-assigned this Sep 28, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 28, 2026
@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 91785817eb1eae00712100f368340e8e533b3a5c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Confirm the windows-latest CI leg collected and passed test_served_signature_refuses_a_junctioned_directory — it is the only leg that exercises the fix.

[DESIGN-REVIEWED] 9178581

@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 91785817eb1eae00712100f368340e8e533b3a5c and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9178581

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 91785817eb1eae00712100f368340e8e533b3a5c: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 91785817eb1eae00712100f368340e8e533b3a5c — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 ships

Inventory (5 items) — 5 justified

Intent: FIX — stop the Design Critique screenshot cache from discarding good screenshots when files change behind a Windows junction the preview server never serves.

  1. On Windows, churn behind a junction inside the build dir no longer invalidates a cached screenshot (the dirs[:] prune) — justified
  2. The files-loop guard reads the same junction-aware predicate, so the whole function honors the one served-set contract — justified
  3. The signature's docstring records why the predicate must be is_link_or_junction — justified
  4. A new test pins junction refusal using a real junction on Windows, a symlink elsewhere — justified
  5. _served_signature is recorded in the generated link-screen ratchet baseline as a refusing site — justified

[FIRST-PRINCIPLES-REVIEWED] 9178581

@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 91785817eb1eae00712100f368340e8e533b3a5c — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9178581

Verdict parsed from the review's SHA-scoped output markers for commit 91785817eb1eae00712100f368340e8e533b3a5c.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 91785817eb1eae00712100f368340e8e533b3a5c: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 28, 2026
@iamwhatever
iamwhatever force-pushed the fix/design-critique-signature-junction-inrepo branch from bd274ee to 33bab24 Compare September 28, 2026 02:47
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 28, 2026
_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>
@iamwhatever
iamwhatever force-pushed the fix/design-critique-signature-junction-inrepo branch from 33bab24 to 9178581 Compare September 28, 2026 03:30
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 28, 2026
@iamwhatever
iamwhatever enabled auto-merge (squash) September 28, 2026 05:33
@chenmingwei23
chenmingwei23 merged commit f4cd862 into main Sep 28, 2026
97 checks passed
auto-merge was automatically disabled September 28, 2026 05:37

Pull Request is not mergeable

@chenmingwei23
chenmingwei23 deleted the fix/design-critique-signature-junction-inrepo branch September 28, 2026 05:37

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants