Two Cross-Platform Bugs in Our Go CLI (And How We Fixed Them)

Go's cross-platform story is genuinely good. Write code once, compile for any target, mostly just works. But "mostly" hides a couple of sharp edges that bit us while building TestSmith. Both bugs were invisible on macOS and Linux, only surfaced on Windows CI, and had the same root cause: assumptions about path separators and filesystem traversal boundaries.

Bug 1: The Detector Boundary Escape

TestSmith has five language drivers, each responsible for detecting whether a directory is a project of its type. The Python driver walks upward from the starting directory, looking for pyproject.toml or setup.py. The Go driver looks for go.mod. And so on.

The bug: every driver would happily walk past a .git directory belonging to a different project and claim files in an ancestor project.

Here's what happened in practice. Our example projects live at:

testsmith/                  ← Go repo root (.git here)
  examples/
    python-service/          ← Python example project
      pyproject.toml

When you ran testsmith generate from inside examples/python-service/, the Python driver would detect it correctly. But when you ran it from examples/go-service/ and the Python driver was tried first during registry detection, it would walk upward, find no Python markers in go-service/, then continue upward, find no markers in examples/, then continue upward... find conftest.py at the testsmith repo root (left over from a previous test run), and claim the entire testsmith repo as a Python project.

The naive fix is "stop when you see .git." But that's wrong too — a legitimate project root can have both pyproject.toml and a .git directory. If you stop at the first .git you see, you'd refuse to detect projects that are also VCS roots.

The correct rule: check VCS stop markers only at ancestor directories, not at the starting directory.

func findRoot(startDir string) (string, error) {
    dir := startDir
    for {
        // Only check VCS boundaries at ancestor dirs — the starting dir
        // may legitimately have both a project marker and a .git directory.
        if dir != startDir {
            for _, stop := range stopMarkers {
                if _, err := os.Stat(filepath.Join(dir, stop)); err == nil {
                    return "", domain.ErrProjectNotFound
                }
            }
        }
        for _, marker := range rootMarkers {
            if _, err := os.Stat(filepath.Join(dir, marker)); err == nil {
                return dir, nil
            }
        }
        parent := filepath.Dir(dir)
        if parent == dir {
            break
        }
        dir = parent
    }
    return "", domain.ErrProjectNotFound
}

We applied this pattern to all five drivers. The key insight: .git is a traversal-stopping sentinel when found in an ancestor, but it's perfectly normal at the project root itself.

Bug 2: Hardcoded Path Separators

The Windows test failure was more direct:

    analyzer_test.go:179: DeriveTestPath("/proj/src/services/payment.py"):
        got "\\proj\\tests\\src\\services\\test_payment.py",
        want "/proj/tests/services/test_payment.py"

Two things wrong in that output: backslashes (expected on Windows, handled by the test via filepath.ToSlash), and src appearing in the output path when it should have been stripped.

The code:

func deriveTestPath(sourcePath string, ctx *domain.ProjectContext) (string, error) {
    rel, err := filepath.Rel(ctx.Root, sourcePath)
    if err != nil {
        return "", err
    }

    // Strip src/ prefix if present.
    if len(rel) > 4 && rel[:4] == "src/" {  // ← BUG
        rel = rel[4:]
    }
    // ...
}

filepath.Rel on Windows returns src\services\payment.py. The prefix check looks for src/ with a forward slash. On Windows, it never matches. The src component stays in the path, so the output becomes tests\src\services\test_payment.py instead of tests\services\test_payment.py.

The fix normalises to forward slashes before the check:

// Normalise to forward slashes for the prefix check so this works on
// Windows (where filepath.Rel returns backslash-separated paths).
slashed := filepath.ToSlash(rel)
if strings.HasPrefix(slashed, "src/") {
    slashed = slashed[4:]
}
rel = filepath.FromSlash(slashed)

filepath.ToSlash converts \ to /. strings.HasPrefix(slashed, "src/") works correctly on all platforms. filepath.FromSlash converts back to the OS-native separator for the subsequent filepath.Join call.

The same pattern applied to deriveModulePath, which had the identical bug.

The Pattern

Both bugs share a structure: an algorithm that works correctly on the development platform (macOS/Linux) but silently produces wrong results on Windows because it makes assumptions about the filesystem:

• Bug 1: assumes .git presence implies "not a project root" (wrong at the starting dir)
• Bug 2: assumes filepath.Rel uses forward slashes (wrong on Windows)

The remedies are similarly structured:

• Bug 1: be explicit about which directories the invariant applies to
• Bug 2: normalise to a known format before string operations, then convert back for OS operations

Go's filepath package is excellent — filepath.Rel, filepath.Join, filepath.Dir, filepath.Base all do the right thing. The problems arise when you mix filepath results with hardcoded string literals (like "src/") that embed platform assumptions. The rule: use filepath functions for path operations, filepath.ToSlash to convert before any string matching, and filepath.FromSlash to convert back before passing to OS calls.

CI as the Detector

Neither bug would have been caught by running tests locally on macOS. The Windows CI job was the only place they surfaced.

This is the case for a real cross-platform test matrix. It's not just about supporting Windows users — it's about finding any code that makes implicit platform assumptions. If your tests only run on one platform, that class of bug is invisible until a user reports it.

TestSmith is open source at github.com/orieken/testsmith. The full CI matrix runs on Ubuntu, macOS, and Windows with -race enabled on all three.