path-quirk-audit — sweep a tree for Windows path/file landmines

The engine is path-quirk-audit.js (portable Node, zero deps). It enumerates a tree (git ls-files in a repo, else a recursive walk skipping node_modules/.git) and flags file-shaped corruption classes that fail silently on Windows: a single non-ASCII byte that kills a .bat parse, a shell script that arrived with CRLFs, a JSON file a PowerShell rewrite left with a BOM or mangled UTF-8, a stray root file whose name shadows a cmd builtin, and two paths that collide by case on NTFS. It is strictly read-only — it never writes, moves, or edits anything. When it finds an offender, pair the finding with your own symptom-side runbook for the actual fix.

Commands

node path-quirk-audit.js scan [dir]   audit dir (default cwd)
node path-quirk-audit.js --canary

• scan enumerates and reports one block per finding: CLASS<tab>file, then a detail line, then a fix: hint. Exit 1 if anything is flagged, 0 if clean.
• Enumeration uses git ls-files when dir is inside a repo (tracked files only, respects .gitignore), otherwise a recursive walk skipping node_modules/.git.

Classes flagged

Examples

• Before a scheduled .bat runs (a monthly job that runs as a Windows scheduled task): node path-quirk-audit.js scan /path/to/project — a BAT-NONASCII hit is exactly the "one non-ASCII byte silently corrupts the whole batch parse" failure, caught before the task fires and dies with garbled errors.
• After a PowerShell edit touched JSON (PS Set-Content defaults to the ANSI codepage and can leave a BOM / corrupt emoji): scan the tree — JSON-BADUTF8 flags the BOM or the mangled multibyte sequence and points you at a Node writer.
• Cross-checking this repo before a Windows checkout: CASE-COLLIDE catches a Case.txt/case.txt pair that would clobber on NTFS, and SH-CRLF catches a helper script that picked up CRLFs.

Windows notes

• Runs the same in PowerShell 5.1 and Git Bash — no &&/|| chaining, ternary, or ?? used; it's a single Node process.
• scan is read-only. It reads content only for .bat/.cmd/.sh/.bash/.json; all other files are inspected by name only (root-shadow, case-collision).
• The BOM/invalid-UTF-8 detector is deliberately hand-rolled on raw bytes so the tool never itself re-encodes a file — it reports, it does not touch.

Exit codes

0 clean · 1 one or more findings · 2 usage error (missing/not-a-directory).

Verification (the done-check)

node path-quirk-audit.js --canary

Plants one instance of every class in a throwaway temp dir and asserts all are flagged (the bad direction), plus a clean dir with the same file types — a pure -ASCII .bat, an LF .sh, a BOM-free valid-UTF-8 .json (emoji included), a shadow-named file that is NOT in root — yields zero findings (the good direction). MUST print CANARY PASS 25/25 before you trust a result.