Skip to content

fix(papyrus): refuse a junctioned project config, not just a symlinked one - #8873

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/papyrus-project-config-junction
Sep 6, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/papyrus-project-config-junction

Conversation

@leonlaiyc

@leonlaiyc leonlaiyc commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

store.is_reparse_link exists in this module precisely because a Windows directory junction is a reparse point is_symlink() does not report, and its docstring states the rule it was added to enforce:

every place this module refuses a link at a name KiroCrew owns has to refuse a junction too, or the refusal is POSIX-only

Shared so the project-entry guard and gitops's attributes guard cannot drift apart on which link types they cover.

It is used at gitops.py:287-289, latex.py:617, store.py:215 and store.py:503 — five sites, each carrying a comment explaining why. _config_path was the one site still asking is_symlink().

Measured on origin/main (9f3c07dc7), with a junction planted at .papyrus.json pointing at an in-project directory:

AssertionError: assert WindowsPath('.../projects/my-paper/chapters') is None

_config_path returns that resolved directory instead of None. The link guard does not fire, and safe_child cannot catch it either — an in-project link satisfies containment, which is the whole reason this guard sits ahead of containment rather than relying on it.

Why it matters

The refusal is currently POSIX-only, for the one link type an unprivileged Windows user can create — os.symlink there needs SeCreateSymbolicLinkPrivilege, a junction needs nothing. So the platform where the plant is cheapest to stage is the platform with no guard.

Scope, stated plainly: a junction is directory-only, so it cannot stand in for the .papyrus.json -> paper.tex overwrite the symlink tests cover — a write would land on a directory and fail. What it does is slip past a refusal this module documents as link-type-agnostic, and lose the logger.warning that says why, so the failure surfaces later and opaquely instead of at the guard that was written to name it.

This is a completeness fix for the module, finishing what merged #8766 started on latex.py.

What changed (motivation → approach → change)

One predicate: candidate.is_symlink() → is_reparse_link(candidate), the module's own shared helper, with a comment matching the four sites that already call it. The warning text drops "symlinked" for "linked" now that both link types reach it.

Zero unfixed siblings, checked individually rather than asserted:

  • tectonic.py:550 — also pairs is_file() with is_symlink(), but it requires is_file(), which a junction fails, so it already declines.
  • store.py:183 is is_reparse_link's own body; the remaining is_symlink() mentions in latex.py:555 and store.py:169 are prose in docstrings.

Tests

test/test_papyrus_store.py, one added test, 24 lines, no deletions. The plant is staged with test/conftest.py::make_dir_link — the repo's own seam, already imported in this file — which calls _winapi.CreateJunction unconditionally on Windows. Note the reversed argument order, (link, target).

It is deliberately not platform_compat.symlink_or_junction: that tries os.symlink FIRST and falls back to a junction only where the privilege is missing, so a runner with Developer Mode gets a SYMLINK and the junction arm is never exercised. The first head of this PR staged it that way and the Windows CI shard caught it.

The file's existing config-link tests are @pytest.mark.skipif(sys.platform == "win32") and therefore left the junction case with no coverage at all.

Two choices in the test are load-bearing, and a first draft got both wrong:

  • It asserts on _config_path, not read_project_config. Reading a directory fails anyway, so the outcome would look correct while the guard was never consulted — a green test proving nothing.
  • The junction points inside the project. An out-of-project link is refused by safe_child's containment whether or not the link guard fires, so it cannot tell the two builds apart. In-project is the case the guard exists for.

Red on origin/main: test_a_junctioned_config_is_refused — the resolved chapters/ directory in place of None.

No guard-the-guard test is added here. The first head had one; review correctly counted it as duplicate evidence, because TestIsReparseLink::test_a_directory_link_is_a_reparse_link already stages with make_dir_link and asserts is_reparse_link(link) is True. It proved no additional production contract, so it was removed rather than kept for symmetry.

Local (Windows, repo-pinned toolchain): test_papyrus_store.py 115 passed / 16 skipped. flake8, isort and scripts/check_black_formatting.py all clean in scope.

On formatting: this file is in .github/black-baseline.txt. The first head ran black over it and carried ~15 unrelated reformatting hunks, which the baselined Black gate correctly failed. That is reverted — the diff is now purely additive.

Manual verification

N/A — unit coverage sufficient: the change is a single predicate swap to an existing in-module helper, and the test stages the real plant on the affected platform through the repo's own link seam.

Related Issues

None — found by source review while completing the is_symlink()-versus-junction seam after #8766.

Pattern harvest

Rule candidate: review-prompt
Pattern: a module that introduces a shared, platform-correct predicate (here is_reparse_link) and converts most of its call sites leaves the unconverted ones strictly worse off than before — the helper's existence reads as proof the module is covered, so the remaining raw is_symlink() stops looking like a gap. When a helper's docstring says the sites "cannot drift apart", that is a claim to verify by enumeration at review time, not a guarantee. The check is cheap: grep the module for the raw call the helper replaces.

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)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

🤖 Generated with Claude Code

@leonlaiyc
leonlaiyc requested review from a team and hoang-phan98 September 6, 2026 03:37
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 6, 2026
@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 0ae612442c27768d97792618615159225c37fe8f via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Real POSIX-only refusal gap, closed with the module's own shared predicate at the exact site the docstring says must use it.

Watch

  • Phantom description item: the claimed "green on both sides" test test_the_staged_plant_is_really_a_junction_on_windows exists in neither the diff nor the base, and the plant is staged via conftest's make_dir_link (_winapi.CreateJunction), not the described platform_compat.symlink_or_junction. Substantively harmless — base test test_a_directory_link_is_a_reparse_link already pins that make_dir_link yields a reparse link on Windows — but the description should be corrected or the named test actually added.

[DESIGN-REVIEWED] 0ae6124

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed 0ae612442c27768d97792618615159225c37fe8f via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 0ae6124

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 0ae612442c27768d97792618615159225c37fe8f via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0ae6124

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of 0ae612442c27768d97792618615159225c37fe8f via the fork AI-review pipeline — 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.

All claims verified against the base. The fix is derived — the is_reparse_link docstring at store.py:166 documents the exact invariant, and I confirmed store.py:340 was the last raw is_symlink() guard in the module (grep for is_symlink across papyrus/backend: remaining hits are the helper's own body, tectonic.py:550 which requires is_file() a junction fails, and docstring prose). One mismatch: the description claims a second test that neither the diff nor the base contains.

First-Principles-Verdict: CONCERNS

The predicate swap is the documented cause-level fix, but the description claims a "guards the guard" test the diff never ships.

What this change ships

Intent: make the project-config link refusal fire for Windows junctions, the one link type an unprivileged Windows user can create — a FIX.

  1. A junctioned .papyrus.json is now refused instead of resolved — justified, mandated by the is_reparse_link docstring invariant (store.py:166-181)
  2. Refusal log line relabeled "symlinked" → "linked" — justified consequence, message now covers both link types
  3. New test test_a_junctioned_config_is_refused covering the previously skipped-on-Windows arm — justified
  4. Nine-line comment matching the four sibling call sites — justified, module convention

Watch

  • The Tests section claims "Green on both sides: test_the_staged_plant_is_really_a_junction_on_windows — guards the guard", but the diff adds only test_a_junctioned_config_is_refused, and grep for staged_plant|really_a_junction across test/ finds zero matches in the base. Likewise "staged with platform_compat.symlink_or_junction" — the shipped test uses conftest's make_dir_link (test/conftest.py:187), which calls _winapi.CreateJunction directly. Both read as a description written against an earlier draft; the claimed self-guarding test does not exist in what ships.
  • "Zero unfixed siblings" verified by my own grep: after this change no raw is_symlink() guard remains in the module (tectonic.py:550 already declines a junction via its is_file() requirement).

[FIRST-PRINCIPLES-REVIEWED] 0ae6124

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 6, 2026
@leonlaiyc
leonlaiyc force-pushed the fix/papyrus-project-config-junction branch from df90a84 to 3092251 Compare September 6, 2026 05:25
…d one

store.is_reparse_link exists in this module because a Windows directory
junction is a reparse point is_symlink() does not report, and its docstring
states the rule: every place this module refuses a link at a name KiroCrew owns
has to refuse a junction too, or the refusal is POSIX-only. It is used at
gitops.py:287-289, latex.py:617 and store.py:215/503 -- five sites, each with a
comment. _config_path was the one still asking is_symlink().

Measured on origin/main, with a junction at .papyrus.json pointing at an
IN-PROJECT directory, _config_path returns that resolved directory instead of
None: the link guard does not fire, and safe_child cannot catch it because an
in-project link satisfies containment -- which is why the guard sits ahead of
containment in the first place.

Scope, stated plainly: a junction is directory-only, so it CANNOT stand in for
the .papyrus.json -> paper.tex overwrite the symlink tests cover; the write
would land on a directory and fail. What it does is slip past a refusal this
module documents as link-type-agnostic, and lose the warning that says why.

Zero unfixed siblings: tectonic.py:550 also pairs is_file() with is_symlink(),
but it requires is_file(), which a junction fails, so it declines already.

The test uses test/conftest.py::make_dir_link, the repo's own seam, which calls
_winapi.CreateJunction unconditionally on Windows -- not symlink_or_junction,
which tries os.symlink first and hands a privileged runner a symlink instead of
the junction arm under test. The file is in .github/black-baseline.txt, so it is
deliberately not black-formatted here: the test delta is 24 added lines and no
deletions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@leonlaiyc
leonlaiyc force-pushed the fix/papyrus-project-config-junction branch from 3092251 to 0ae6124 Compare September 6, 2026 05:25
@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 6, 2026

@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.

Tech Lead review: APPROVE.

Verified independently rather than trusting the description:

  • The gap is real and the fix is at the right layer. store.py:340 was the last raw is_symlink() guard in papyrus/backend; swapping it for the module's own is_reparse_link is the predicate the helper's docstring at store.py:166-181 explicitly mandates for every link refusal in this module. The guard sits ahead of safe_child on purpose, and an in-project junction satisfies containment, so containment could not have caught this.
  • Enumeration of siblings confirmed by my own grep. After this change no raw is_symlink() guard remains: tectonic.py:550 pairs is_file() with is_symlink() and requires is_file(), which a directory junction fails, so it already declines; the remaining hits in store.py and latex.py are the helper's own body plus docstring/comment prose.
  • Semantics match the AGENTS.md cross-platform contract. is_reparse_link mirrors platform_compat.is_link_or_junction structurally (is_symlink() -> os.path.isjunction when available -> stat-based IO_REPARSE_TAG_MOUNT_POINT fallback), so it holds on 3.10 and 3.11 where os.path.isjunction does not exist.
  • The test stages the real plant and is valid on both platforms. make_dir_link is already imported in this file, the reversed (link, target) argument order matches test/conftest.py, it calls _winapi.CreateJunction unconditionally on Windows, and falls back to symlink_to(target_is_directory=True) on POSIX -- so the assertion holds cross-platform. Asserting on _config_path rather than read_project_config, and pointing the link inside the project, are both the load-bearing choices; either one relaxed would produce a test that passes without consulting the guard.
  • Scope is honest. The description states plainly that a junction is directory-only and cannot stand in for the .papyrus.json -> paper.tex overwrite the symlink tests cover; the claim is that it slips past a refusal documented as link-type-agnostic and loses the warning. That is exactly what the diff does, and nothing more.

CI: 69 success / 6 skipped / 0 failure on 0ae6124. All four AI lanes clear -- GPT 5.6 and Opus 4.8 no findings, Design Review PASS, First Principles CONCERNS (advisory). The single Watch item both Fable lanes raised -- a described test test_the_staged_plant_is_really_a_junction_on_windows that the diff never ships -- is already corrected in the current description, which now states outright that no guard-the-guard test is added and that the plant is deliberately staged with make_dir_link rather than platform_compat.symlink_or_junction.

One cosmetic nit, deliberately not blocking: the new test declares a tmp_path fixture argument it never uses.

Security-sensitive change reviewed as a strict tightening of an existing guard -- no trust boundary widened, no new capability, refusal path only.

@bolichen97
bolichen97 merged commit e85e60b into kirodotdev:main Sep 6, 2026
76 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 6, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…d one (kirodotdev#8873)

store.is_reparse_link exists in this module because a Windows directory
junction is a reparse point is_symlink() does not report, and its docstring
states the rule: every place this module refuses a link at a name KiroCrew owns
has to refuse a junction too, or the refusal is POSIX-only. It is used at
gitops.py:287-289, latex.py:617 and store.py:215/503 -- five sites, each with a
comment. _config_path was the one still asking is_symlink().

Measured on origin/main, with a junction at .papyrus.json pointing at an
IN-PROJECT directory, _config_path returns that resolved directory instead of
None: the link guard does not fire, and safe_child cannot catch it because an
in-project link satisfies containment -- which is why the guard sits ahead of
containment in the first place.

Scope, stated plainly: a junction is directory-only, so it CANNOT stand in for
the .papyrus.json -> paper.tex overwrite the symlink tests cover; the write
would land on a directory and fail. What it does is slip past a refusal this
module documents as link-type-agnostic, and lose the warning that says why.

Zero unfixed siblings: tectonic.py:550 also pairs is_file() with is_symlink(),
but it requires is_file(), which a junction fails, so it declines already.

The test uses test/conftest.py::make_dir_link, the repo's own seam, which calls
_winapi.CreateJunction unconditionally on Windows -- not symlink_or_junction,
which tries os.symlink first and hands a privileged runner a symlink instead of
the junction arm under test. The file is in .github/black-baseline.txt, so it is
deliberately not black-formatted here: the test delta is 24 added lines and no
deletions.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants