Fix Android doc test path resolution

[leogdion]

Summary

• resolveFilePath in Settings.swift now prepends Sources/SyntaxKit/ on non-Android platforms
• Test methods in DocumentationExampleTests.swift use the short-form path (Documentation.docc/Tutorials/...) without the prefix
• Fixes the two failing "Documentation Code Examples" tests on all Android CI jobs

Root cause

On Android, Documentation.docc is copied flat to the test working directory — there's no Sources/SyntaxKit/ subdirectory. The two specific test methods hardcoded the full path, causing a "file doesn't exist" error. Settings.docPaths already handled this correctly; resolveFilePath now does too.

Test plan

• Verify Android CI passes (all 3 Android jobs)
• Verify macOS/Linux CI still passes

🤖 Generated with Claude Code

---

Perform an AI-assisted review on

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 312240e8-3f07-45f3-8269-67d0f39640e8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/android-doc-test-paths

---

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 and usage tips.}

[claude]

Code Review: Fix Android doc test path resolution

Summary: Focused, minimal fix for a real cross-platform CI issue. Changes are correct and well-scoped.

Code Quality

The conditional path prepending in resolveFilePath is clean and mirrors the pattern in docPaths. Removing the hardcoded prefix from call sites in DocumentationExampleTests.swift is the right call — callers no longer need platform-awareness; that logic is now centralized.

Potential Issues

1. Logic duplication between docPaths and resolveFilePath

Both independently encode Android-specific path layout knowledge. If the android-copy-files target changes, both must be updated in sync. Consider a linking comment:

// NOTE: Mirrors the Android path layout assumed by docPaths.
// Both must stay in sync if the android-copy-files target changes.

2. WASM fallthrough not documented

docPaths for WASI uses the full Sources/SyntaxKit/ prefix. The non-Android branch in resolveFilePath also prepends this prefix, so WASM falls through correctly — but a short comment noting this intent would help future readers.

Test Coverage: Validated by the two failing Android CI tests described in the PR. No additional test infrastructure needed.

Overall: Correct and appropriately minimal. Main suggestion: add a comment linking the platform path assumptions between docPaths and resolveFilePath so maintainers know to update both when the Android copy layout changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.15%. Comparing base (426285a) to head (72cbd02).
⚠️ Report is 2 commits behind head on 128-workflow-updates.

Additional details and impacted files

@@                   Coverage Diff                    @@
##           128-workflow-updates     #130      +/-   ##
========================================================
- Coverage                 78.22%   78.15%   -0.07%     
========================================================
  Files                       126      126              
  Lines                      4555     4555              
========================================================
- Hits                       3563     3560       -3     
- Misses                      992      995       +3     

Flag	Coverage Δ
spm	77.84% <ø> (-0.03%)	⬇️
swift-6.0	77.89% <ø> (-0.03%)	⬇️
swift-6.1	77.95% <ø> (-0.11%)	⬇️
swift-6.2	77.84% <ø> (-0.03%)	⬇️
swift-6.3	78.02% <ø> (+0.13%)	⬆️
ubuntu	78.15% <ø> (-0.05%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[claude]

Code Review: Fix Android doc test path resolution

The fix is correct and the root cause is well-explained. A few observations:

Settings.swift - resolveFilePath platform coupling

The non-Android branch of resolveFilePath now unconditionally prepends 'Sources/SyntaxKit/' to all relative paths. This means callers on all non-Android platforms (WASI, macOS, Linux) must pass short-form paths like 'Documentation.docc/Tutorials/...' without the prefix. The test changes do this correctly.

One latent fragility: docPaths for WASI already contains the full 'Sources/SyntaxKit/...' prefix. If any code path ever called resolveFilePath with those docPaths strings on WASI, you would get double-prefixing. Right now docPaths and resolveFilePath are used independently so this is not an active bug, but a comment clarifying the expected input contract for resolveFilePath would help future callers.

projectRoot fallback chain

The 3-strategy fallback is reasonable for cross-platform support. Strategy 1a (Sources/ in working dir) takes priority over 1b (Documentation.docc in working dir) — the ordering seems intentional and handles the Android flat-copy case correctly.

Test changes

The DocumentationExampleTests.swift changes are correct — removing the 'Sources/SyntaxKit/' prefix aligns with the new resolveFilePath contract on all non-Android platforms.

Minor: indentation in resolveFilePath

The '#if os(Android)' block inside the else branch has 0-space indentation for the 'let resolvedPath' lines vs the surrounding code. Worth a format pass to keep SwiftFormat happy.

Positives:

• Platform-specific docPaths (Android/WASI/default) are cleanly separated
• The fallback chain in projectRoot gracefully handles varied CI execution contexts
• Fix is minimal and targeted at the actual root cause

[claude]

PR Review: Fix Android doc test path resolution

Summary: This PR correctly identifies and fixes a real cross-platform path resolution issue for Android documentation tests. The core logic is sound and consistent with existing platform-conditional patterns already present in the codebase.

What the fix does: On Android, the CI workflow copies Documentation.docc as a flat top-level directory without a Sources/SyntaxKit/ prefix. The fix updates resolveFilePath() to prepend Sources/SyntaxKit/ only on non-Android platforms, and updates the two specific test methods to use short-form paths.

Code Quality - Strengths: Uses idiomatic compile-time #if os(Android) conditional (no runtime overhead). Consistent with the existing docPaths pattern in Settings.swift. Minimal, focused change with low regression risk.

Code Quality - Minor issues:

1. Missing documentation on platform behavior. The resolveFilePath() docstring does not mention the Android-specific path normalization. A brief note would help future maintainers.

2. String concatenation approach works given the existing absolute-path guard, but using URL path component APIs would be more idiomatic Swift. Not a blocker.

3. No unit test for resolveFilePath() itself. The behavior change is validated only through integration tests. A small unit test covering the path prefix logic would make this easier to verify and maintain.

Workflow File Changes: The three new workflow files (cleanup-caches.yml, cleanup-pr-caches.yml, codeql.yml) are good additions - cache cleanup prevents unbounded growth and CodeQL adds security scanning. These are unrelated to the core fix and could be separate PRs, but harmless here.

Test Coverage: The two affected test methods will now execute correctly on Android. The generic validateAllDocumentationExamples() already worked across all platforms via docPaths. Coverage is adequate for the fix.

Verdict: Approve with minor suggestions. The fix is correct and well-targeted. The issues above are non-blocking polish items. Note: the PR description has unchecked test plan boxes - worth confirming Android CI tests passed before merging.