fix(ci): preserve import cycles through macOS path aliases

[lidge-jun]

Summary

• Fix the import-cycle scanner's graph identities when the repository root contains a symlink, including macOS temporary-directory aliases. Bun resolves import targets to physical paths; the scanner previously kept lexical paths for graph keys, so valid cycle edges pointed to missing nodes.
• Canonicalize the root before scanning. Keep Bun's TS/TSX/MTS resolution and existing cycle expectations intact; add symlinked-root coverage for all three directory-index extensions and document the invariant.
• Addresses the macOS directory index.tsx imports close cycles failure in dev run 38879287332. Linux probing reproduced missing cycles through a symlink while the same physical tree passed.

Verification

• No tests or typecheck executed on the local Mac, per coordinator instruction and concurrent-worktree resource constraints. A local full suite is intentionally not run; broader coverage belongs to hosted CI.
• Remote Linux focused validation passed: ssh lidge 'OCX_LANE_SLOTS=3 ~/bin/ocx-lane-ci2.sh 2da167661cfd552d1a52aa3cfd059cb8063e41e7 f7-import-cycle-2da1676 tests/ci-workflows/import-cycle-ratchet.test.ts tests/ci-workflows/structure-ssot.test.ts tests/ci-workflows/file-size-ratchet.test.ts'. Typecheck exit 0; 76 tests passed, 0 failed across the three listed files on Bun 1.4.3. Summary: ~/ocx-lane/logs/f7-import-cycle-2da1676.summary.
• Regression sensitivity: on lidge, the new symlinked-root cases were also run against an isolated copy of the pre-fix scanner: all three failed with ../physical/src/nested/index.* targets instead of src/nested/index.*. The committed scanner passes those cases in the focused run above. Red log: ~/ocx-lane/wt/f7-import-cycle-56a09c3/.tmp/f7-red.log.
• Merged latest origin/dev (050bb444a0, fix(gui): restore keep-native-v1 qualifier placement #7237) without conflicts. Final validation head: 2da167661cfd552d1a52aa3cfd059cb8063e41e7; the inherited GUI gates fix is present and the PR diff still contains only the three scanner/test/doc files.
• Hosted macOS validation dispatched: gh workflow run ci.yml --ref codex/fix-import-cycle-tsx-macos -f lane=macos-control. This existing lane runs the macOS shards and unsharded diagnostic control; results are recorded in final-head run 38882499696, including the macos 1/3 shard containing this regression. The superseded-head dispatch was cancelled after merging dev.
• Final-head hosted macOS suite shards all passed (macos 1/3, 2/3, 3/3). Regression shard log explicitly records the original TSX/MTS cases and all three new symlink cases passing.
• Separate unsharded macos control failed in the unchanged tests/codex-integration/codex-provider-routing.test.ts:176 test, concurrent sync processes leave a complete restorable config, with concurrent sync failed: 1,0,0 (job). This is outside the scanner/test/doc patch and was not changed or retried. The manual dispatch as a whole must not be described as green.
• Hosted PR validation: final-head PR CI 38882490243, with four Linux suite shards, gates and the event-selected checks. Local static git diff --check passed. No CI policy or workflow changes.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. No authentication, credential, dependency-installation, release, or workflow changes.

Co-authored-by: lcxhh lcxhh521@gmail.com

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-16T09:38:52.833213Z	56a09c3	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: b94d6e4a-427c-49d7-93f1-486bc5638591

📥 Commits

Reviewing files that changed from the base of the PR and between 4ed45e9 and 56a09c3.

📒 Files selected for processing: 3

• scripts/import-cycles.ts
• structure/overview.md
• tests/ci-workflows/import-cycle-ratchet.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

📝 Walkthrough

The import-cycle scanner resolves its root to a physical path before scanning and generating repository-relative graph keys. Tests cover cycles beneath symlinked roots for .ts, .tsx, and .mts indexes. The invariant description records the root canonicalization.

Changes: Symlinked import-cycle roots

Layer / File(s)	Summary
Canonicalize roots and verify cycle identities scripts/import-cycles.ts, tests/ci-workflows/import-cycle-ratchet.test.ts, structure/overview.md	scanGraph uses realpathSync to canonicalize its root before resolving imports and generating graph keys. Parameterized tests check cycles under symlinked roots for .ts, .tsx, and .mts indexes. The INV-LAYER-01 description records the canonicalization.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 56a09

The scanner now canonicalizes its root, with added coverage for symlinked-root cycles across .ts, .tsx, and .mts indexes. No concrete merge-blocking issue is identified; complete the normal pending CI checks before merging.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title accurately summarizes the main change: canonicalizing the scanner root preserves import-cycle detection through macOS path aliases. This matches the implementation in scripts/import-cycles.t…

Full details: Title check

Explanation

The title accurately summarizes the main change: canonicalizing the scanner root preserves import-cycle detection through macOS path aliases. This matches the implementation in scripts/import-cycles.ts and the symlinked-root coverage in tests/ci-workflows/import-cycle-ratchet.test.ts.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

Maintainer landing note: macos 1/3, 2/3 and 3/3 pass on this head in the branch's macOS dispatch, so the directory index.tsx cycle case that failed on dev 4ed45e9 is green on macOS. The two remaining red jobs are failures already present on dev and are tracked separately. macos control is the concurrent Codex sync test (#7244), and desktop shell is the Rust 1.99 clippy manual_noop_waker lint.