fix(graph): normalize Windows backslash paths to forward slashes

[giancarloerra]

Summary

Fix silent graph query failures on Windows caused by path separator mismatch. On Windows, path.relative() and path.join() return backslash separators (src\index.ts), but query inputs use forward slashes (src/index.ts). Exact string comparison fails silently, returning empty results.

Changes

• Add toForwardSlash() utility to src/constants.ts for centralized path normalization
• Normalize file walker output in code-graph.ts so all graph node keys use forward slashes at build time
• Normalize all resolution path operations in graph-resolution.ts (JVM suffix map, Rust paths, relative path resolution, fileSet lookups)
• Add defensive query-time normalization in graph-analysis.ts (getFileDependencies) and graph-impact.ts (getSymbolContext, listSymbols)
• Add unit tests for toForwardSlash() and backslash-path normalization in getFileDependencies

Type of change

• Bug fix (non-breaking change that fixes an issue)
• Test coverage improvement

Testing

• Unit tests pass (npm run test:unit)
• Integration tests pass (npm run test:integration)
• TypeScript compiles cleanly (npx tsc --noEmit)
• New tests added for new/changed functionality
• 997 tests pass (10 new tests for toForwardSlash and backslash normalization)
• Biome lint: 0 issues
• CodeRabbit local review: no findings
• Snyk: only pre-existing finding in unrelated file (provider-lmstudio.ts)

Checklist

• My code follows the existing code style and conventions
• I have added/updated JSDoc comments where appropriate
• I have updated documentation (README.md / DEVELOPER.md) if needed
• I have addressed all CodeRabbit review comments (or marked as resolved with explanation)
• I have read the Contributing Guide
• I agree to the Contributor License Agreement

Related issues

Fixes #60

Notes

• No-op on macOS/Linux where path.relative() already returns forward slashes
• Existing Windows file graph caches are handled by query-time normalization (defense-in-depth)
• Existing Windows symbol graph caches require one codebase_index rebuild (UUID hashes change due to forward-slash keys)

Summary by CodeRabbit

• Bug Fixes
  • Improved cross-platform path handling so dependency lookups, symbol queries, and import resolution work consistently with forward- or backslash separators.
• Tests
  • Added unit tests covering mixed, Windows, and POSIX path formats to ensure consistent behavior across platforms.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e2591224-c82c-4ad5-ae9d-9cd6509fbe06

📥 Commits

Reviewing files that changed from the base of the PR and between e9ee3ea and 4526ea5.

📒 Files selected for processing (2)

• src/services/graph-analysis.ts
• tests/unit/graph-analysis.test.ts

---

📝 Walkthrough

Walkthrough

Adds a toForwardSlash helper and applies forward-slash normalization across file collection, dependency lookups, symbol/cache access, and multi-language module resolution so graph keys and queries match regardless of OS path separators.

Changes

Windows Path Separator Normalization

Layer / File(s)	Summary
Path normalization helper and tests src/constants.ts, tests/unit/constants.test.ts	Exports toForwardSlash replacing \ with /; unit tests cover Windows, mixed, deep, POSIX, and empty inputs.
Graph collection and dependency lookup normalization src/services/code-graph.ts, src/services/graph-analysis.ts, tests/unit/graph-analysis.test.ts	Normalizes path.relative(...) during file discovery and normalizes the query relativePath before graph node lookup; tests validate backslash, mixed, deep, and legacy backslash-keyed graphs.
Cache and symbol context lookups src/services/graph-impact.ts	Normalizes fileHint and opts.file before filtering symbol references and loading file payloads from cache.
Multi-language module/class resolution paths src/services/graph-resolution.ts	Builds and checks JVM/Go/Java/Kotlin/Scala/Rust/SCSS/Python/relative candidate keys using forward-slash-normalized paths for consistent resolution lookups.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• giancarloerra/SocratiCode#34: Also modifies src/services/graph-resolution.ts—related changes to resolution logic and suffix-map handling.

Poem

"I nibble bytes and hop through slashes wide,
Backslashes tumble, forward ones I guide.
Across the graph I tidy every track,
So queries find nodes whether front or back.
A rabbit's cheer — paths now stride!" 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: normalizing Windows backslash paths to forward slashes in the graph module.
Description check	✅ Passed	The PR description comprehensively addresses all template sections with detailed changes, testing confirmation, and proper checklist completion.
Linked Issues check	✅ Passed	The PR directly addresses issue #60 by implementing path normalization at both build time (code-graph.ts, graph-resolution.ts) and query time (graph-analysis.ts, graph-impact.ts), meeting all stated objectives.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing Windows path separator issues in graph operations; no unrelated modifications are present.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/windows-path-separator-normalization

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/services/graph-analysis.ts`:
- Around line 16-17: The lookup currently normalizes the input path (normalized
= toForwardSlash(relativePath)) but compares it to the raw stored key
(n.relativePath), causing failures when graph nodes still have backslashes;
update the find predicate in graph.nodes.find to normalize the stored key as
well (e.g., use toForwardSlash(n.relativePath) === normalized) so both sides are
compared in forward-slash form, ensuring compatibility with legacy
Windows-cached nodes and preserving use of the existing toForwardSlash helper.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 73c32277-8eca-4392-8652-1393a541da69

📥 Commits

Reviewing files that changed from the base of the PR and between c126c52 and e9ee3ea.

📒 Files selected for processing (7)

• src/constants.ts
• src/services/code-graph.ts
• src/services/graph-analysis.ts
• src/services/graph-impact.ts
• src/services/graph-resolution.ts
• tests/unit/constants.test.ts
• tests/unit/graph-analysis.test.ts