windows-compat

Windows compatibility (code-graph-mcp)

Three defects reached a Windows user from one root cause: two spellings of the same path compared unequal. CI already ran windows-latest and caught none of them, because nothing asserted on path spellings at all. Closing that gap is what this skill is for.

The invariant everything hangs off

indexer::merkle::normalize_rel_path stores every indexed path as a /-separated relative path, rewriting separators only under #[cfg(windows)]. So any path that becomes a lookup key, a dedup key, or stdout must land in exactly that spelling.

Almost every defect below is one producer handing over a different spelling of the same file. The producer table and the full catalogue are in references/failure-modes.md — read it before changing path-handling code. It is short and every entry is a real defect with its shipped fix.

The doctrine: platform is a parameter, not a cfg!

This is the single rule that makes everything else testable.

// NO — the Windows branch only runs on Windows, so the Linux and macOS legs
// prove nothing, and a Windows-only CI failure is expensive to debug.
fn normalize(path: &str) -> String {
    if cfg!(windows) { path.replace('\\', "/") } else { path.into() }
}

// YES — one thin cfg! entry point, all logic in a function taking the platform.
fn normalize(path: &str) -> String {
    normalize_on(path, cfg!(windows))
}
fn normalize_on(path: &str, backslash_is_sep: bool) -> String { ... }

Then assert both values from any platform:

assert_eq!(normalize_on(r"src\a.rs", true), "src/a.rs");   // Windows behaviour
assert_eq!(normalize_on(r"src\a.rs", false), r"src\a.rs"); // `\` is a legal Unix filename char

Live examples: merkle.rs::normalize_rel_str_on (the crate's single separator-rewriting implementation — everything else delegates to it), cli.rs::normalize_path_display_on, cli.rs::relativize_path_on.

Skip dunce / path-slash here. They do the right thing but decide internally on cfg(windows), forfeiting exactly the property that makes the Linux leg useful.