fix(artifact-graph): normalize paths for cross-platform glob compatibility

[TabishB]

Summary

• Adds FileSystemUtils.toPosixPath() utility for cross-platform path normalization
• Fixes Windows test failures in artifact-graph glob pattern matching
• Consolidates scattered .replace(/\\/g, '/') patterns across the codebase

Root Cause

On Windows, path.join() uses backslashes (\) as separators. However, fast-glob requires forward slashes (/) for glob patterns on all platforms. When the artifact-graph state detection ran on Windows:

Input: C:\Users\...\temp\specs\*.md
Expected: Match files in specs directory
Actual: No matches (backslashes interpreted as escape characters)

Test plan

• All 575 existing tests pass
• Verified glob pattern matching works with normalized paths
• No remaining scattered path normalization patterns in src/

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• Refactor
  • Centralized file path normalization to improve cross-platform compatibility. The application now uses a unified utility for handling paths consistently across Windows, macOS, and Linux, enhancing reliability when processing file paths and glob patterns throughout the system.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

A new FileSystemUtils.toPosixPath() utility method is introduced to normalize file paths to POSIX format (replacing backslashes with forward slashes) for cross-platform compatibility. This method replaces scattered direct string normalization across four files, centralizing path handling logic.

Changes

Cohort / File(s)	Summary
New utility method src/utils/file-system.ts	Added public static method toPosixPath(p: string): string to convert Windows-style paths to POSIX format for cross-platform glob library compatibility.
Path normalization consolidation src/core/artifact-graph/state.ts, src/core/converters/json-converter.ts, src/core/update.ts, src/core/validation/validator.ts	Replaced direct backslash-to-forward-slash string replacements with centralized FileSystemUtils.toPosixPath() calls for consistent, unified path normalization across the codebase.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• fix(completions): resolve Windows compatibility issues in zsh-installer tests #373 — Modifies FileSystemUtils utility to improve cross-platform filesystem behavior through additional utility methods.

Poem

🐰 A rabbit hops through POSIX paths so clean,
Backslashes banished—no more cross-platform screams!
One utility method, unified and bright,
Four files now dancing in perfect delight. ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: introducing path normalization for cross-platform glob compatibility, which is the primary focus of all changes across multiple files.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch TabishB/windows-glob-test-fix

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between af273b8 and 31b267a.

📒 Files selected for processing (5)

• src/core/artifact-graph/state.ts
• src/core/converters/json-converter.ts
• src/core/update.ts
• src/core/validation/validator.ts
• src/utils/file-system.ts

🔇 Additional comments (8)

src/core/validation/validator.ts (2)

8-14: LGTM! Clean consolidation of imports and utilities.

The import restructuring and addition of FileSystemUtils align with the PR's objective to centralize path normalization logic.

---

363-364: LGTM! Correct use of centralized path normalization.

Replacing the inline .replace(/\\/g, '/') with FileSystemUtils.toPosixPath() ensures consistent cross-platform path handling before splitting by '/'. This is exactly the consolidation pattern described in the PR objectives.

src/core/update.ts (1)

110-111: LGTM! Improves cross-platform log consistency.

Normalizing paths before logging ensures consistent output format across Windows and Unix-like systems. This is a helpful enhancement for user experience.

src/core/artifact-graph/state.ts (2)

6-6: LGTM! Essential import for the glob compatibility fix.

---

58-63: Critical fix! Addresses the root cause of Windows glob failures.

This change directly fixes the issue described in the PR objectives: on Windows, path.join() produces backslashes (e.g., C:\...\temp\specs\*.md), but fast-glob requires forward slashes. Without normalization, backslashes were interpreted as escape characters, producing no matches.

The fix is correctly placed: normalizing the pattern immediately before passing it to fg.sync() ensures glob matching works consistently across all platforms.

src/core/converters/json-converter.ts (2)

6-6: LGTM! Consistent import pattern.

---

47-48: LGTM! Consistent with validator.ts pattern.

This change mirrors the path normalization in src/core/validation/validator.ts (line 363), ensuring consistent cross-platform behavior when extracting names from paths. The centralized utility makes the codebase more maintainable.

src/utils/file-system.ts (1)

45-51: LGTM! Well-documented utility for cross-platform path normalization.

The implementation is correct. Fast-glob treats backslashes as escape characters on Windows and expects forward slashes in glob patterns, making this utility essential for cross-platform compatibility. The JSDoc clearly explains this purpose.

---

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

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.