fix: handle shell-escaped file paths (#29)

* fix: handle shell-escaped file paths

File paths containing shell metacharacters (like $) get backslash-escaped
by git/CI tools, but normalizeFilePaths() didn't unescape them, causing
validateFilesExist() to fail with "File not found" errors.

This is common with React Router/Remix dynamic route files like
users.$id.tsx which become users.\$id.tsx when passed through shell
variables in CI.

Added filePath.replace(/\\(.)/g, '$1') in normalizeFilePaths() to strip
backslash escapes before checking if files exist.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: preserve Windows paths by only unescaping Unix-style paths

Only apply shell escape unescaping to paths containing forward slashes.
Paths using only backslashes (Windows native paths) are preserved to
avoid corrupting path separators.

This handles:
- Git Bash on Windows (uses forward slashes with backslash escaping)
- Windows CI (uses forward slashes from git)
- Native Windows cmd/PowerShell (uses backslashes, no shell escaping)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: only unescape non-alphanumeric characters

Restrict the unescape regex to /\\([^a-zA-Z0-9])/g to preserve mixed
paths like src/utils\file.ts which are valid on Windows.

Shells typically escape special characters ($, space, !), not letters
or digits. Windows separators are usually followed by alphanumeric
directory names, so this change prevents corruption while still
unescaping shell metacharacters.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: frankieyan

src/__fixtures__/sample-project/src/route.$param.tsx

@@ -0,0 +1,7 @@
+/**
+ * A dynamic route component (e.g., React Router or Remix)
+ * The $param in the filename indicates a URL parameter
+ */
+export function RouteParam({ id }: { id: string }) {
+    return <div>Route param: {id}</div>
+}

src/index.integration.test.mts

@@ -36,7 +36,7 @@ describe('CLI', () => {
     it('runs check on all files when no flag provided', () => {
         const output = runCLI()
 
-        expect(output).toContain('🔍 Checking all 4 source files for React Compiler errors…')
+        expect(output).toContain('🔍 Checking all 5 source files for React Compiler errors…')
         expect(output).toContain('⚠️  Found 4 React Compiler issues across 2 files')
         expect(() => JSON.parse(readFileSync(recordsPath, 'utf8'))).toThrow()
     })
@@ -60,11 +60,19 @@ describe('CLI', () => {
         expect(output).toContain('File not found: src/nonexistent-file.tsx')
     })
 
+    it('handles shell-escaped file paths with $ character', () => {
+        // Simulate what CI tools do when passing filenames with $ through shell variables
+        const output = runCLI(['--check-files', 'src/route.\\$param.tsx'])
+
+        expect(output).toContain('🔍 Checking 1 files for React Compiler errors…')
+        expect(output).not.toContain('File not found')
+    })
+
     it('accepts --overwrite flag', () => {
         const output = runCLI(['--overwrite'])
 
         expect(output).toContain(
-            '🔍 Checking all 4 source files for React Compiler errors and recreating records…',
+            '🔍 Checking all 5 source files for React Compiler errors and recreating records…',
         )
         expect(output).toContain(
             '✅ Records file completed. Found 4 total React Compiler issues across 2 files',
@@ -136,8 +144,8 @@ describe('CLI', () => {
 
             const output = runCLI()
 
-            // Should only find .tsx files (2 instead of 4)
-            expect(output).toContain('🔍 Checking all 2 source files for React Compiler errors…')
+            // Should only find .tsx files (3 instead of 5)
+            expect(output).toContain('🔍 Checking all 3 source files for React Compiler errors…')
         })
 
         it('uses custom recordsFile from config', () => {

src/source-files.mts

@@ -29,20 +29,30 @@ function getGitPrefix() {
 }
 
 /**
- * Normalizes file paths by converting absolute paths to cwd-relative
- * and stripping the git prefix when present.
+ * Normalizes file paths by unescaping shell-escaped characters, converting
+ * absolute paths to cwd-relative, and stripping the git prefix when present.
  *
  * When running from a package subdirectory in a monorepo, file paths from git
  * (e.g., lint-staged) are relative to the repo root. This function converts
  * those paths to cwd-relative paths.
  *
+ * Shell escapes (e.g., \$ → $) are only applied to paths containing forward
+ * slashes, which indicates Unix-style paths. Paths using only backslashes
+ * (Windows native paths) are preserved to avoid corrupting path separators.
+ *
  * @example
  * // When cwd is apps/frontend/ (prefix is "apps/frontend/")
  * normalizeFilePaths(["apps/frontend/src/file.tsx"]) // => ["src/file.tsx"]
  *
  * // Absolute paths are converted to cwd-relative
  * normalizeFilePaths(["/Users/frankie/project/src/file.tsx"]) // => ["src/file.tsx"]
  *
+ * // Shell-escaped characters are unescaped (Unix-style paths)
+ * normalizeFilePaths(["src/route.\\$id.tsx"]) // => ["src/route.$id.tsx"]
+ *
+ * // Windows-style paths are preserved (no forward slashes)
+ * normalizeFilePaths(["src\\utils\\file.ts"]) // => ["src\\utils\\file.ts"]
+ *
  * // Paths that don't start with prefix are unchanged
  * normalizeFilePaths(["src/file.tsx"]) // => ["src/file.tsx"]
  */
@@ -51,17 +61,27 @@ function normalizeFilePaths(filePaths: string[]) {
     const cwd = process.cwd()
 
     return filePaths.map((filePath) => {
+        // Only unescape shell-escaped characters for Unix-style paths (containing /).
+        // Windows paths use \ as separator, so we preserve them to avoid corruption.
+        // This handles Git Bash on Windows and Windows CI which use forward slashes.
+        // We only unescape non-alphanumeric characters since shells don't escape letters/digits,
+        // but Windows separators are typically followed by alphanumeric directory names.
+        // This preserves mixed paths like src/utils\file.ts (valid on Windows).
+        const normalized = filePath.includes('/')
+            ? filePath.replace(/\\([^a-zA-Z0-9])/g, '$1')
+            : filePath
+
         // Handle absolute paths by converting to cwd-relative
-        if (filePath.startsWith('/')) {
-            return relative(cwd, filePath)
+        if (normalized.startsWith('/')) {
+            return relative(cwd, normalized)
         }
 
         // Handle monorepo prefix stripping
-        if (prefix && filePath.startsWith(prefix)) {
-            return filePath.slice(prefix.length)
+        if (prefix && normalized.startsWith(prefix)) {
+            return normalized.slice(prefix.length)
         }
 
-        return filePath
+        return normalized
     })
 }
 

src/source-files.test.mts

@@ -127,6 +127,89 @@ describe('normalizeFilePaths', () => {
 
         expect(result).toEqual(['src/App.tsx', 'src/local.ts'])
     })
+
+    it('unescapes shell-escaped $ characters', () => {
+        vi.mocked(execSync).mockReturnValue('\n')
+
+        const result = normalizeFilePaths(['src/route.\\$id.tsx', 'src/draft.\\$slug.tsx'])
+
+        expect(result).toEqual(['src/route.$id.tsx', 'src/draft.$slug.tsx'])
+    })
+
+    it('unescapes shell-escaped spaces', () => {
+        vi.mocked(execSync).mockReturnValue('\n')
+
+        const result = normalizeFilePaths(['src/file\\ with\\ spaces.tsx'])
+
+        expect(result).toEqual(['src/file with spaces.tsx'])
+    })
+
+    it('unescapes multiple different escape characters', () => {
+        vi.mocked(execSync).mockReturnValue('\n')
+
+        const result = normalizeFilePaths(['src/route.\\$id\\ (copy).tsx'])
+
+        expect(result).toEqual(['src/route.$id (copy).tsx'])
+    })
+
+    it('handles paths with no escapes unchanged', () => {
+        vi.mocked(execSync).mockReturnValue('\n')
+
+        const result = normalizeFilePaths(['src/normal-file.tsx'])
+
+        expect(result).toEqual(['src/normal-file.tsx'])
+    })
+
+    it('unescapes before stripping prefix', () => {
+        vi.mocked(execSync).mockReturnValue('apps/frontend/\n')
+
+        const result = normalizeFilePaths(['apps/frontend/src/route.\\$id.tsx'])
+
+        expect(result).toEqual(['src/route.$id.tsx'])
+    })
+
+    it('preserves Windows-style paths with backslash separators', () => {
+        vi.mocked(execSync).mockReturnValue('\n')
+
+        const result = normalizeFilePaths(['src\\utils\\file.ts', 'src\\components\\Button.tsx'])
+
+        expect(result).toEqual(['src\\utils\\file.ts', 'src\\components\\Button.tsx'])
+    })
+
+    it('preserves Windows paths with $ in filename', () => {
+        vi.mocked(execSync).mockReturnValue('\n')
+
+        const result = normalizeFilePaths(['src\\$files.ts', 'src\\routes\\$id.tsx'])
+
+        expect(result).toEqual(['src\\$files.ts', 'src\\routes\\$id.tsx'])
+    })
+
+    it('does not unescape bare filenames without forward slashes', () => {
+        vi.mocked(execSync).mockReturnValue('\n')
+
+        // Bare filenames without / are ambiguous, so we preserve them
+        const result = normalizeFilePaths(['\\$id.tsx', 'file.tsx'])
+
+        expect(result).toEqual(['\\$id.tsx', 'file.tsx'])
+    })
+
+    it('preserves mixed paths with both forward and back slashes', () => {
+        vi.mocked(execSync).mockReturnValue('\n')
+
+        // Mixed paths are valid on Windows - backslash separators should be preserved
+        const result = normalizeFilePaths(['src/utils\\file.ts', 'src/components\\Button.tsx'])
+
+        expect(result).toEqual(['src/utils\\file.ts', 'src/components\\Button.tsx'])
+    })
+
+    it('unescapes special chars in mixed paths while preserving backslash separators', () => {
+        vi.mocked(execSync).mockReturnValue('\n')
+
+        // Should unescape \$ (non-alphanumeric) but preserve \s in utils\subdir (alphanumeric)
+        const result = normalizeFilePaths(['src/utils\\subdir/route.\\$id.tsx'])
+
+        expect(result).toEqual(['src/utils\\subdir/route.$id.tsx'])
+    })
 })
 
 describe('filterByGlob', () => {