fix(checks): canonicalize source architecture root

[senthilr-nv]

Summary

Canonicalizes the repository root before the source-architecture check scans files or reports paths. This keeps macOS temporary repositories exposed through /var aliases aligned with their /private/var file identities instead of reporting paths outside the repository.

Changes

• Resolve the supplied repository root once before scanning, repository-path conversion, edge reporting, and root-file counts.
• Add a real symlink/junction-root regression that verifies repository-relative files, fan-in, fan-out, and root-file counts.
• Preserve production behavior, architecture budgets, and descendant-symlink exclusion unchanged.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: This changes an internal repository architecture check and its regression coverage only; no production implementation or supported user surface changes.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: The change canonicalizes an aliased repository root inside an internal source-architecture check so reports remain repository-relative. It changes no production implementation, public behavior, configuration, workflow, or supported product surface.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project integration test/source-architecture.test.ts: 8/8 passed on macOS; CLI typecheck, repository checks, source-shape, test-size, conditionals, loops, formatting, and lint also passed.
• Applicable broad gate passed — Automatic current-commit Linux CI and Platform Evidence are pending on this draft PR.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved source-architecture analysis when repositories are accessed through symbolic links.
  • Reports now consistently show correct repository-relative file paths and dependency metrics, including fan-in, fan-out, and root-file counts.

• Tests

  • Added coverage to verify accurate analysis results for symlinked repository locations.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f196d1e6-fc70-4cb6-bcad-8155a497362f

📥 Commits

Reviewing files that changed from the base of the PR and between 2212aa8 and 848e0f0.

📒 Files selected for processing (2)

• scripts/checks/source-architecture.mts
• test/source-architecture.test.ts

Included review availability: Your plan includes up to 12 reviews per rolling hour; 11 remain after this review.

---

📝 Walkthrough

Walkthrough

The source architecture analyzer now canonicalizes the repository root before scanning and reporting. A regression test verifies correct paths and dependency metrics when analysis runs through a symlink.

Changes

Source architecture analysis

Layer / File(s)	Summary
Canonicalize repository paths scripts/checks/source-architecture.mts	The analyzer resolves repoRoot with realpathSync. File paths, dependency mappings, and root-file counts use the canonical root.
Validate symlinked-root analysis test/source-architecture.test.ts	A test analyzes TypeScript modules through a symlink and verifies repository-relative paths, fan-in, fan-out, and root-file metrics.

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

Merge Risk: ⚪ Minimal · up to 848e0

This localized change canonicalizes repository roots for architecture-check scanning and reporting, with targeted regression coverage; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: brandonpelfrey

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: canonicalizing the source-architecture repository root.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-source-architecture-canonical-root

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 848e0f0 in the codex/fix-source-arc... branch remains at 96%, unchanged from commit fda9eb1 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 848e0f0 in the codex/fix-source-arc... branch remains at 83%, unchanged from commit 2212aa8 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 2212aa8	codex/fix-source-arc... 848e0f0	+/-
src/lib/inferen...ntext-window.ts	50%	32%	-18%
src/lib/actions...nv-isolation.ts	100%	90%	-10%
src/lib/shields...ate-mutation.ts	78%	70%	-8%
src/lib/onboard...file-builder.ts	95%	91%	-4%
src/lib/state/p...l-retirement.ts	89%	86%	-3%
src/lib/inferen...board-probes.ts	90%	92%	+2%
src/lib/onboard...nt-authority.ts	75%	79%	+4%
src/lib/cua/run...ime-manifest.ts	84%	90%	+6%
src/lib/cua/bounded-file.ts	84%	94%	+10%
src/lib/actions...re-authority.ts	79%	92%	+13%

---

_{Updated August 17, 2026 07:00 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections match; severity counts match.

3 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• aliased repository root at test/source-architecture.test.ts:140: primary classified it as justified; the second opinion classified it as define.
• repository-relative at test/source-architecture.test.ts:140: selected only by the second-opinion lane as established.
• canonicalRepoRoot at scripts/checks/source-architecture.mts:283: selected only by the second-opinion lane as define.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

1 semantic terminology decision

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• justified — aliased repository root at test/source-architecture.test.ts:140: Retain the term. The modifier distinguishes the symlink or junction case that the regression test covers.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

Manual-only E2E: managed-image-multiarch-startup
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[prekshivyas]

Reviewed commit 848e0f0. No findings.

Security review:

1. Secrets and credentials: PASS. This internal analyzer does not handle credentials.
2. Input validation and data sanitization: PASS. The code resolves the supplied repository root before all path operations.
3. Authentication and authorization: PASS. This change adds no authorization boundary.
4. Dependencies and third-party libraries: PASS. This change adds no dependency or downloaded artifact.
5. Error handling and logging: PASS. realpathSync preserves explicit failure for an invalid root.
6. Cryptography and data protection: PASS. This change adds no cryptographic or protected-data flow.
7. Configuration and security headers: PASS. This change does not alter runtime configuration.
8. Security testing: PASS. The symlink and junction regression verifies repository-relative files, fan-in, fan-out, and root-file counts.
9. System security: PASS. Canonicalization is applied once and used consistently for the complete analysis.

Cross-issue sweep: no adjacent fix or conflict found.

[cv]

Accepted scope, code review, contributor requirements, security, targeted regression coverage and documentation impact, and required checks pass on 848e0f0. GitHub reports MERGEABLE. The branch is behind main, which is advisory because required checks evaluated this unchanged commit against base commit 2212aa8.