@photostructure/fs-metadata 0.6.1 → 0.7.1

package/scripts/clang-tidy.ts

@@ -1,17 +1,23 @@
 #!/usr/bin/env tsx
 import { exec as execCallback, execSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, writeFileSync } from "node:fs";
 import { cpus, platform } from "node:os";
+import { join } from "node:path";
 import { promisify } from "node:util";
 
 const exec = promisify(execCallback);
 
-// Skip clang-tidy on Windows
-if (platform() === "win32") {
-  console.log("Skipping clang-tidy on Windows platform");
+// Check for environment variable to skip
+if (process.env.SKIP_CLANG_TIDY) {
+  console.log("Skipping clang-tidy (SKIP_CLANG_TIDY is set)");
   process.exit(0);
 }
 
+// Platform detection
+const isWindows = platform() === "win32";
+const isMacOS = platform() === "darwin";
+const isLinux = platform() === "linux";
+
 // Colors for output
 const colors = {
   reset: "\x1b[0m",
@@ -22,8 +28,20 @@ const colors = {
   dim: "\x1b[2m",
 } as const;
 
-// Check for required tools
+// Platform-specific warnings
+if (isMacOS) {
+  console.log(
+    "Note: clang-tidy on macOS with Homebrew LLVM may report false positives",
+  );
+  console.log(
+    "due to header path issues. Set SKIP_CLANG_TIDY=1 to skip this check.",
+  );
+}
+
+// Check for required tools (non-Windows only)
 function checkCommand(command: string, installHint: string): boolean {
+  if (isWindows) return true; // Skip on Windows
+
   try {
     execSync(`which ${command}`, { stdio: "ignore" });
     return true;
@@ -34,136 +52,606 @@ function checkCommand(command: string, installHint: string): boolean {
   }
 }
 
-const isMacOS = platform() === "darwin";
-const isLinux = platform() === "linux";
+// Find clang-tidy binary
+function findClangTidy(): string | null {
+  if (isWindows) {
+    // Windows-specific paths
+    const windowsPaths = [
+      "C:\\Program Files\\LLVM\\bin\\clang-tidy.exe",
+      "C:\\Program Files (x86)\\LLVM\\bin\\clang-tidy.exe",
+      // Visual Studio 2022
+      "C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\VC\\Tools\\Llvm\\x64\\bin\\clang-tidy.exe",
+      "C:\\Program Files\\Microsoft Visual Studio\\2022\\Professional\\VC\\Tools\\Llvm\\x64\\bin\\clang-tidy.exe",
+      "C:\\Program Files\\Microsoft Visual Studio\\2022\\Enterprise\\VC\\Tools\\Llvm\\x64\\bin\\clang-tidy.exe",
+      // Visual Studio 2019
+      "C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\Community\\VC\\Tools\\Llvm\\bin\\clang-tidy.exe",
+      "C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\Professional\\VC\\Tools\\Llvm\\bin\\clang-tidy.exe",
+      "C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\Enterprise\\VC\\Tools\\Llvm\\bin\\clang-tidy.exe",
+    ];
 
-let hasAllTools = true;
-
-if (
-  !checkCommand(
-    "bear",
-    isLinux
-      ? "sudo apt-get install bear"
-      : isMacOS
-        ? "brew install bear"
-        : "see https://github.com/rizsotto/Bear",
-  )
-) {
-  hasAllTools = false;
-}
+    for (const path of windowsPaths) {
+      if (existsSync(path)) {
+        return path;
+      }
+    }
+
+    // Try to find in PATH
+    try {
+      execSync("where clang-tidy", { stdio: "ignore" });
+      return "clang-tidy";
+    } catch {
+      return null;
+    }
+  } else {
+    // Unix-like systems
+    const versions = ["", "-18", "-17", "-16", "-15", "-14"];
+    for (const version of versions) {
+      try {
+        const result = execSync(`which clang-tidy${version}`, {
+          encoding: "utf8",
+        }).trim();
+        // On macOS, return the full path if it's in Homebrew
+        // This allows us to detect it for filtering purposes
+        if (
+          isMacOS &&
+          (result.includes("/opt/homebrew") ||
+            result.includes("/usr/local") ||
+            result.includes("/Cellar"))
+        ) {
+          return result;
+        }
+        return `clang-tidy${version}`;
+      } catch {
+        // Continue trying
+      }
+    }
+
+    // On macOS, check Homebrew locations explicitly
+    if (isMacOS) {
+      const brewPrefixes = ["/opt/homebrew", "/usr/local"];
+      for (const prefix of brewPrefixes) {
+        const paths = [
+          `${prefix}/opt/clang-tidy/bin/clang-tidy`,
+          `${prefix}/opt/llvm/bin/clang-tidy`,
+        ];
 
-if (
-  !checkCommand(
-    "clang-tidy",
-    isLinux
-      ? "sudo apt-get install clang-tidy"
-      : isMacOS
-        ? "brew install llvm && alias clang-tidy=$(brew --prefix llvm)/bin/clang-tidy"
-        : "see https://clang.llvm.org/extra/clang-tidy/",
-  )
-) {
-  hasAllTools = false;
+        for (const path of paths) {
+          if (existsSync(path)) {
+            return path;
+          }
+        }
+
+        // Try versioned LLVM formulas
+        for (let v = 18; v >= 14; v--) {
+          const versionedPath = `${prefix}/opt/llvm@${v}/bin/clang-tidy`;
+          if (existsSync(versionedPath)) {
+            return versionedPath;
+          }
+        }
+      }
+    }
+
+    return "clang-tidy"; // fallback
+  }
 }
 
-if (!hasAllTools) {
-  process.exit(1);
+// Generate compile_commands.json for Windows
+async function generateWindowsCompileCommands(): Promise<boolean> {
+  console.log("Generating compile_commands.json for Windows...");
+
+  try {
+    execSync("npm run setup:native", { stdio: "inherit" });
+
+    const nodeVersion = process.version.slice(1);
+
+    // Try multiple possible locations for node-gyp headers
+    const possibleNodeGypPaths = [
+      `${process.env.USERPROFILE}\\.node-gyp\\${nodeVersion}`,
+      `${process.env.LOCALAPPDATA}\\node-gyp\\Cache\\${nodeVersion}`,
+      `${process.env.APPDATA}\\npm\\node_modules\\node-gyp\\cache\\${nodeVersion}`,
+    ];
+
+    let nodeGyp = "";
+    for (const path of possibleNodeGypPaths) {
+      if (existsSync(join(path, "include", "node", "node.h"))) {
+        nodeGyp = path;
+        console.log("Found Node.js headers at:", nodeGyp);
+        break;
+      }
+    }
+
+    // If not found, install them
+    if (!nodeGyp) {
+      console.log("Installing Node.js headers...");
+      execSync("npx node-gyp install", { stdio: "inherit" });
+
+      // Check again
+      for (const path of possibleNodeGypPaths) {
+        if (existsSync(join(path, "include", "node", "node.h"))) {
+          nodeGyp = path;
+          break;
+        }
+      }
+
+      if (!nodeGyp) {
+        // Fallback to default
+        nodeGyp = `${process.env.USERPROFILE}\\.node-gyp\\${nodeVersion}`;
+      }
+    }
+
+    // Get all Windows sources
+    const windowsSources: string[] = [];
+    if (existsSync(join("src", "windows"))) {
+      const entries = require("fs").readdirSync(join("src", "windows"));
+      for (const entry of entries) {
+        if (entry.endsWith(".cpp") || entry.endsWith(".h")) {
+          windowsSources.push(join("src", "windows", entry));
+        }
+      }
+    }
+
+    // Add binding.cpp
+    const sources = [...windowsSources, "src/binding.cpp"];
+
+    // Find MSVC include paths
+    const msvcPaths = [
+      "C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\VC\\Tools\\MSVC",
+      "C:\\Program Files\\Microsoft Visual Studio\\2022\\Professional\\VC\\Tools\\MSVC",
+      "C:\\Program Files\\Microsoft Visual Studio\\2022\\Enterprise\\VC\\Tools\\MSVC",
+      "C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\BuildTools\\VC\\Tools\\MSVC",
+      "C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\Community\\VC\\Tools\\MSVC",
+    ];
+
+    let msvcInclude = "";
+    for (const basePath of msvcPaths) {
+      if (existsSync(basePath)) {
+        const versions = require("fs").readdirSync(basePath);
+        if (versions.length > 0) {
+          const version = versions.sort().reverse()[0];
+          msvcInclude = join(basePath, version, "include");
+          if (existsSync(msvcInclude)) {
+            console.log("Found MSVC includes at:", msvcInclude);
+            break;
+          }
+        }
+      }
+    }
+
+    // Find Windows SDK paths
+    const sdkBase = "C:\\Program Files (x86)\\Windows Kits\\10\\Include";
+    let sdkVersion = "";
+    if (existsSync(sdkBase)) {
+      const versions = require("fs")
+        .readdirSync(sdkBase)
+        .filter((v) => v.match(/^\d+\.\d+\.\d+\.\d+$/))
+        .sort()
+        .reverse();
+      if (versions.length > 0) {
+        sdkVersion = versions[0];
+        console.log("Found Windows SDK version:", sdkVersion);
+      }
+    }
+
+    // Create compile commands with absolute paths
+    const commands = sources.map((source: string) => ({
+      directory: process.cwd(),
+      file: source,
+      command: [
+        "clang++", // Use clang++ for clang-tidy compatibility
+        "-c",
+        source,
+        `-I${process.cwd()}/src/windows`,
+        `-I${process.cwd()}/node_modules/node-addon-api`,
+        `-I${nodeGyp}/include/node`,
+        msvcInclude ? `-I${msvcInclude}` : "",
+        sdkVersion ? `-I${sdkBase}\\${sdkVersion}\\ucrt` : "",
+        sdkVersion ? `-I${sdkBase}\\${sdkVersion}\\shared` : "",
+        sdkVersion ? `-I${sdkBase}\\${sdkVersion}\\um` : "",
+        sdkVersion ? `-I${sdkBase}\\${sdkVersion}\\winrt` : "",
+        "-DWIN32",
+        "-D_WINDOWS",
+        "-D_WIN64",
+        "-D_M_X64=1",
+        "-D_AMD64_=1",
+        "-DNAPI_VERSION=8",
+        "-DNODE_ADDON_API_DISABLE_DEPRECATED",
+        "-DBUILDING_NODE_EXTENSION",
+        "-std=c++17",
+        "-fms-compatibility",
+        "-fms-extensions",
+        "-Wno-microsoft-include",
+      ]
+        .filter((arg) => arg)
+        .join(" "),
+    }));
+
+    writeFileSync("compile_commands.json", JSON.stringify(commands, null, 2));
+    console.log(
+      `Created compile_commands.json with ${commands.length} entries`,
+    );
+    return true;
+  } catch (error) {
+    console.error("Failed to generate compile_commands.json:", error);
+    return false;
+  }
 }
 
-// Generate compile_commands.json if needed
-const compileCommandsPath = "compile_commands.json";
-if (existsSync(compileCommandsPath)) {
-  console.log("Using existing compile_commands.json");
-} else {
+// Generate compile_commands.json for Unix-like systems
+async function generateUnixCompileCommands(): Promise<void> {
   console.log("Generating compile_commands.json...");
 
-  // Use bear to generate compile_commands.json
-  // Bear intercepts the build commands and creates the compilation database
+  if (
+    !checkCommand(
+      "bear",
+      isLinux
+        ? "sudo apt-get install bear"
+        : isMacOS
+          ? "brew install bear"
+          : "see https://github.com/rizsotto/Bear",
+    )
+  ) {
+    process.exit(1);
+  }
+
   execSync("npm run setup:native && bear -- npm run node-gyp-rebuild", {
     stdio: "inherit",
   });
 
-  // Check if it was created successfully
-  if (!existsSync(compileCommandsPath)) {
+  if (!existsSync("compile_commands.json")) {
     console.error("Failed to generate compile_commands.json");
-    console.error("Make sure bear is installed: sudo apt-get install bear");
     process.exit(1);
   }
 }
 
-// Find clang-tidy binary (try different versions)
-function findClangTidy(): string {
-  const versions = ["", "-18", "-17", "-16", "-15", "-14"];
-  for (const version of versions) {
-    try {
-      execSync(`which clang-tidy${version}`, { stdio: "ignore" });
-      return `clang-tidy${version}`;
-    } catch {
-      // Continue trying
+// Get source files to check
+async function getSourceFiles(): Promise<string[]> {
+  if (isWindows) {
+    // Windows-specific files
+    const files: string[] = [];
+    const windowsDir = join("src", "windows");
+
+    if (existsSync(windowsDir)) {
+      const entries = require("fs").readdirSync(windowsDir);
+      for (const entry of entries) {
+        if (entry.endsWith(".cpp") || entry.endsWith(".h")) {
+          files.push(join(windowsDir, entry));
+        }
+      }
     }
+
+    // Also include binding.cpp
+    files.push(join("src", "binding.cpp"));
+    return files;
+  } else {
+    // Platform-specific exclusions for Unix-like systems
+    let excludePattern = "";
+    if (isMacOS) {
+      excludePattern = "| grep -v -E '(windows|linux)/'";
+    } else if (isLinux) {
+      excludePattern = "| grep -v -E '(windows|darwin)/'";
+    } else {
+      excludePattern = "| grep -v -E '(windows|darwin|linux)/'";
+    }
+
+    const { stdout } = await exec(
+      `find src -name '*.cpp' -o -name '*.h' | grep -E '\\.(cpp|h)$' ${excludePattern}`,
+    );
+    return stdout
+      .trim()
+      .split("\n")
+      .filter((f) => f);
   }
-  return "clang-tidy"; // fallback
 }
 
-// Get list of files to check
-async function getSourceFiles(): Promise<string[]> {
-  const { stdout } = await exec(
-    `find src -name '*.cpp' -o -name '*.h' | grep -E '\\.(cpp|h)$' | grep -v -E '(windows|darwin)/'`,
-  );
-  return stdout
-    .trim()
-    .split("\n")
-    .filter((f) => f);
+// Filter out known macOS Homebrew LLVM header issues
+function filterMacOSHeaderErrors(output: string): {
+  filteredOutput: string;
+  errors: number;
+  warnings: number;
+  filtered: number;
+} {
+  const lines = output.split("\n");
+  const filteredLines: string[] = [];
+  let errors = 0;
+  let warnings = 0;
+  let filtered = 0;
+
+  // Patterns for known Homebrew LLVM vs Apple clang header mismatches
+  const knownHeaderErrors = [
+    // Standard library headers not found
+    /'(functional|chrono|cstring|iostream|string|vector|memory|algorithm|map|set|iterator)' file not found/,
+    // Apple framework headers not found when using Homebrew clang-tidy
+    /'CoreFoundation\/CoreFoundation\.h' file not found/,
+    /'DiskArbitration\/DiskArbitration\.h' file not found/,
+    // LLVM-specific errors that don't affect actual compilation
+    /unknown type name '_LIBCPP_/,
+    /no member named '\w+' in namespace 'std'/,
+    /no template named '\w+' in namespace 'std'/,
+  ];
+
+  for (const line of lines) {
+    let isKnownError = false;
+
+    // Check if this is a known header error
+    if (line.includes(" error:")) {
+      for (const pattern of knownHeaderErrors) {
+        if (pattern.test(line)) {
+          isKnownError = true;
+          filtered++;
+          break;
+        }
+      }
+    }
+
+    if (!isKnownError) {
+      filteredLines.push(line);
+
+      // Count errors and warnings
+      if (line.includes(" error:")) {
+        errors++;
+      }
+      if (line.includes(" warning:")) {
+        warnings++;
+      }
+    }
+  }
+
+  return {
+    filteredOutput: filteredLines.join("\n"),
+    errors,
+    warnings,
+    filtered,
+  };
 }
 
-interface TidyResult {
-  file: string;
-  output: string;
+// Filter out known Windows header issues
+function filterWindowsHeaderErrors(output: string): {
+  filteredOutput: string;
   errors: number;
   warnings: number;
+} {
+  const lines = output.split("\n");
+  const filteredLines: string[] = [];
+  let errors = 0;
+  let warnings = 0;
+  let skipNextLine = false;
+  let inSystemHeader = false;
+
+  // Patterns for known header issues that we want to filter out
+  const systemHeaderPatterns = [
+    // System header paths - match the entire error line
+    /C:\\Program Files.*:\d+:\d+: (error|warning):/,
+    /C:\\Users\\.*\\AppData.*:\d+:\d+: (error|warning):/,
+    /\.node-gyp.*:\d+:\d+: (error|warning):/,
+    /Windows Kits.*:\d+:\d+: (error|warning):/,
+  ];
+
+  // Known system header error messages that appear in user files
+  const systemHeaderErrors = [
+    // File not found errors - these are the most common MSVC header issues
+    /'(chrono|functional|windows\.h|iostream|string|vector|memory|algorithm|map|set|unordered_map|iterator|utility|tuple|type_traits|cstddef|cstdint|exception|new|limits|stdexcept)' file not found/,
+    /no member named '\w+' in the global namespace/,
+    /no member named '\w+' in namespace 'std'/,
+    /no template named '\w+' in namespace 'std'/,
+    /no template named 'pointer_traits'/,
+    /unknown type name 'stream(pos|off)'/,
+    /no type named 'string' in namespace 'std'/,
+    /use of undeclared identifier '_Elem'/,
+    /use of undeclared identifier 'tuple'/,
+    /cannot initialize return object of type 'int' with an lvalue of type 'const char/,
+    /expected ';' after expression/,
+    /unknown type name 'namespace'/,
+    /expected unqualified-id/,
+    /no type named 'type' in/,
+    /declaration of anonymous struct must be a definition/,
+  ];
+
+  for (let i = 0; i < lines.length; i++) {
+    // eslint-disable-next-line security/detect-object-injection
+    const line = lines[i];
+
+    if (skipNextLine) {
+      skipNextLine = false;
+      continue;
+    }
+
+    // Check if this is a system header location
+    let isSystemHeader = false;
+    for (const pattern of systemHeaderPatterns) {
+      if (pattern.test(line)) {
+        isSystemHeader = true;
+        inSystemHeader = true;
+        break;
+      }
+    }
+
+    // Check if this is a known system header error in a user file
+    if (!isSystemHeader && line.includes(" error:")) {
+      for (const pattern of systemHeaderErrors) {
+        if (pattern.test(line)) {
+          isSystemHeader = true;
+          break;
+        }
+      }
+    }
+
+    // Reset inSystemHeader flag when we see a new file
+    if (line.match(/^[^:]+\.(cpp|h|hpp):\d+:\d+: (error|warning):/)) {
+      inSystemHeader = false;
+      for (const pattern of systemHeaderPatterns) {
+        if (pattern.test(line)) {
+          inSystemHeader = true;
+          break;
+        }
+      }
+    }
+
+    if (!isSystemHeader && !inSystemHeader) {
+      // Only add non-header errors to output
+      filteredLines.push(line);
+
+      // Count errors and warnings
+      if (line.includes(" error:")) {
+        errors++;
+      }
+      if (line.includes(" warning:")) {
+        warnings++;
+      }
+    }
+  }
+
+  return {
+    filteredOutput: filteredLines.join("\n"),
+    errors,
+    warnings,
+  };
 }
 
 // Run clang-tidy on a single file
 async function runClangTidyOnFile(
   clangTidy: string,
   file: string,
-): Promise<TidyResult> {
+): Promise<{
+  file: string;
+  output: string;
+  errors: number;
+  warnings: number;
+  filtered?: number;
+}> {
   try {
-    const { stdout, stderr } = await exec(`${clangTidy} -p . "${file}" 2>&1`);
-    const output = stdout + stderr;
+    let extraArgs = "";
+
+    // Platform-specific config and arguments
+    if (isWindows) {
+      // Always use src/windows/.clang-tidy for Windows
+      const configPath = join("src", "windows", ".clang-tidy");
+      if (existsSync(configPath)) {
+        extraArgs = `--config-file=${configPath}`;
+      }
+    } else if (isMacOS && clangTidy.includes("/opt/")) {
+      // macOS with Homebrew LLVM needs extra paths
+      // The compile_commands.json uses Apple's /usr/bin/cc, but we're running
+      // Homebrew's clang-tidy which needs Homebrew's C++ stdlib
+      const sdkPath = execSync("xcrun --show-sdk-path", {
+        encoding: "utf8",
+      }).trim();
+
+      // Extract Homebrew prefix from clang-tidy path
+      const brewPrefix = clangTidy.includes("/opt/homebrew")
+        ? "/opt/homebrew"
+        : "/usr/local";
+
+      extraArgs =
+        `--extra-arg=-nostdinc++ ` + // Ignore built-in C++ paths
+        `--extra-arg=-isystem${brewPrefix}/opt/llvm/include/c++/v1 ` +
+        `--extra-arg=-isysroot${sdkPath} ` +
+        `--extra-arg=-isystem${sdkPath}/usr/include ` +
+        `--extra-arg=-F${sdkPath}/System/Library/Frameworks`;
+    }
+
+    const { stdout, stderr } = await exec(
+      `${isWindows ? `"${clangTidy}"` : clangTidy} -p . ${extraArgs} "${file}" 2>&1`,
+    );
+    let output = stdout + stderr;
 
     let errors = 0;
     let warnings = 0;
-    const lines = output.split("\n");
+    let filteredCount = 0;
 
-    for (const line of lines) {
-      if (line.includes(" warning:")) warnings++;
-      if (line.includes(" error:")) errors++;
+    // Filter platform-specific header errors
+    if (isWindows) {
+      const filtered = filterWindowsHeaderErrors(output);
+      output = filtered.filteredOutput;
+      errors = filtered.errors;
+      warnings = filtered.warnings;
+    } else if (isMacOS && clangTidy.includes("/opt/")) {
+      // Filter Homebrew LLVM errors on macOS
+      const filtered = filterMacOSHeaderErrors(output);
+      output = filtered.filteredOutput;
+      errors = filtered.errors;
+      warnings = filtered.warnings;
+      filteredCount = filtered.filtered;
+    } else {
+      const lines = output.split("\n");
+      for (const line of lines) {
+        if (line.includes(" warning:")) warnings++;
+        if (line.includes(" error:")) errors++;
+      }
     }
 
-    return { file, output, errors, warnings };
+    return { file, output, errors, warnings, filtered: filteredCount };
   } catch (error: any) {
-    // clang-tidy returns non-zero on errors, capture output
-    const output = error.stdout || error.stderr || error.message;
+    let output = error.stdout || error.stderr || error.message;
     let errors = 0;
     let warnings = 0;
+    let filteredCount = 0;
 
-    const lines = output.split("\n");
-    for (const line of lines) {
-      if (line.includes(" warning:")) warnings++;
-      if (line.includes(" error:")) errors++;
+    // Filter platform-specific header errors
+    if (isWindows) {
+      const filtered = filterWindowsHeaderErrors(output);
+      output = filtered.filteredOutput;
+      errors = filtered.errors;
+      warnings = filtered.warnings;
+    } else if (isMacOS && clangTidy.includes("/opt/")) {
+      // Filter Homebrew LLVM errors on macOS
+      const filtered = filterMacOSHeaderErrors(output);
+      output = filtered.filteredOutput;
+      errors = filtered.errors;
+      warnings = filtered.warnings;
+      filteredCount = filtered.filtered;
+    } else {
+      const lines = output.split("\n");
+      for (const line of lines) {
+        if (line.includes(" warning:")) warnings++;
+        if (line.includes(" error:")) errors++;
+      }
     }
 
-    return { file, output, errors, warnings };
+    return { file, output, errors, warnings, filtered: filteredCount };
   }
 }
 
 // Main function
 async function main(): Promise<void> {
   const clangTidy = findClangTidy();
+
+  if (!clangTidy) {
+    console.error(`${colors.red}Error: clang-tidy not found${colors.reset}`);
+    if (isWindows) {
+      console.error("\nTo install clang-tidy on Windows:");
+      console.error(
+        "1. Install LLVM: https://github.com/llvm/llvm-project/releases",
+      );
+      console.error("2. Or install Visual Studio 2019/2022 with C++ tools");
+    } else if (isMacOS) {
+      console.error("\nTo install on macOS:");
+      console.error("  Option 1: brew install clang-tidy");
+      console.error("  Option 2: brew install llvm");
+    } else {
+      console.error("\nTo install on Linux:");
+      console.error("  sudo apt-get install clang-tidy");
+    }
+    process.exit(1);
+  }
+
   console.log(`${colors.blue}=== Running clang-tidy ===${colors.reset}`);
   console.log(`${colors.dim}Using: ${clangTidy}${colors.reset}`);
+  console.log(`${colors.dim}Platform: ${platform()}${colors.reset}`);
+
+  // Generate or check compile_commands.json
+  if (!existsSync("compile_commands.json")) {
+    if (isWindows) {
+      if (!(await generateWindowsCompileCommands())) {
+        process.exit(1);
+      }
+    } else {
+      await generateUnixCompileCommands();
+    }
+  } else {
+    console.log("Using existing compile_commands.json");
+  }
 
-  // Get files
+  // Get files to check
   const files = await getSourceFiles();
   if (files.length === 0) {
     console.log(
@@ -176,42 +664,103 @@ async function main(): Promise<void> {
     `${colors.dim}Checking ${files.length} files...${colors.reset}\n`,
   );
 
-  // Run clang-tidy on files in parallel
-  const parallelism = Math.min(cpus().length, 8);
-  const results: TidyResult[] = [];
+  // Run clang-tidy on files
+  const parallelism = isWindows ? 1 : Math.min(cpus().length, 8);
+  const results: Array<{
+    file: string;
+    output: string;
+    errors: number;
+    warnings: number;
+  }> = [];
 
-  // Process files in chunks
-  for (let i = 0; i < files.length; i += parallelism) {
-    const chunk = files.slice(i, i + parallelism);
-    const chunkResults = await Promise.all(
-      chunk.map((file) => runClangTidyOnFile(clangTidy, file)),
-    );
-    results.push(...chunkResults);
+  // Process files
+  if (isWindows) {
+    // Sequential on Windows to avoid issues
+    for (const file of files) {
+      const result = await runClangTidyOnFile(clangTidy, file);
+      results.push(result);
 
-    // Show progress
-    for (const result of chunkResults) {
-      const relPath = result.file.replace(process.cwd() + "/", "");
+      // Show progress
+      const relPath = file.replace(
+        process.cwd() + (isWindows ? "\\" : "/"),
+        "",
+      );
       if (result.errors > 0) {
         console.log(
           `${colors.red}✗${colors.reset} ${relPath} (${result.errors} errors, ${result.warnings} warnings)`,
         );
-        // Show actual errors
+        // Show first few errors (already filtered on Windows)
         const errorLines = result.output
           .split("\n")
           .filter(
             (line) => line.includes(" error:") || line.includes(" warning:"),
           );
-        errorLines.forEach((line) =>
-          console.log(`  ${colors.dim}${line}${colors.reset}`),
-        );
+        errorLines
+          .slice(0, 5)
+          .forEach((line) =>
+            console.log(`  ${colors.dim}${line}${colors.reset}`),
+          );
+        if (errorLines.length > 5) {
+          console.log(
+            `  ${colors.dim}... and ${errorLines.length - 5} more${colors.reset}`,
+          );
+        }
       } else if (result.warnings > 0) {
         console.log(
           `${colors.yellow}⚠${colors.reset} ${relPath} (${result.warnings} warnings)`,
         );
+        // Show warnings (already filtered on Windows)
+        const warningLines = result.output
+          .split("\n")
+          .filter((line) => line.includes(" warning:"));
+        warningLines.forEach((line) =>
+          console.log(`  ${colors.dim}${line}${colors.reset}`),
+        );
       } else {
         console.log(`${colors.green}✓${colors.reset} ${relPath}`);
       }
     }
+  } else {
+    // Parallel on Unix-like systems
+    for (let i = 0; i < files.length; i += parallelism) {
+      const chunk = files.slice(i, i + parallelism);
+      const chunkResults = await Promise.all(
+        chunk.map((file) => runClangTidyOnFile(clangTidy, file)),
+      );
+      results.push(...chunkResults);
+
+      // Show progress
+      for (const result of chunkResults) {
+        const relPath = result.file.replace(process.cwd() + "/", "");
+        if (result.errors > 0) {
+          console.log(
+            `${colors.red}✗${colors.reset} ${relPath} (${result.errors} errors, ${result.warnings} warnings)`,
+          );
+          // Show actual errors
+          const errorLines = result.output
+            .split("\n")
+            .filter(
+              (line) => line.includes(" error:") || line.includes(" warning:"),
+            );
+          errorLines.forEach((line) =>
+            console.log(`  ${colors.dim}${line}${colors.reset}`),
+          );
+        } else if (result.warnings > 0) {
+          console.log(
+            `${colors.yellow}⚠${colors.reset} ${relPath} (${result.warnings} warnings)`,
+          );
+          // Show warnings
+          const warningLines = result.output
+            .split("\n")
+            .filter((line) => line.includes(" warning:"));
+          warningLines.forEach((line) =>
+            console.log(`  ${colors.dim}${line}${colors.reset}`),
+          );
+        } else {
+          console.log(`${colors.green}✓${colors.reset} ${relPath}`);
+        }
+      }
+    }
   }
 
   // Summary
@@ -231,6 +780,48 @@ async function main(): Promise<void> {
     console.log(`${colors.green}✓ No issues found${colors.reset}`);
   }
 
+  if (isWindows) {
+    console.log(
+      `\n${colors.dim}Windows: Using src/windows/.clang-tidy with header error filtering${colors.reset}`,
+    );
+    console.log(
+      `${colors.dim}Note: System header errors are automatically filtered out${colors.reset}`,
+    );
+  } else if (isMacOS && clangTidy.includes("/opt/")) {
+    console.log(
+      `\n${colors.dim}macOS: Using Homebrew LLVM clang-tidy with header error filtering${colors.reset}`,
+    );
+    console.log(
+      `${colors.dim}Note: Standard library header errors from toolchain mismatch are filtered out${colors.reset}`,
+    );
+
+    // Show filtering statistics for transparency
+    const totalFilesChecked = files.length;
+    const totalFilteredErrors = results.reduce(
+      (sum, r) => sum + (r.filtered || 0),
+      0,
+    );
+
+    if (totalFilteredErrors > 0) {
+      console.log(
+        `${colors.dim}Filtered ${totalFilteredErrors} known header incompatibility error(s)${colors.reset}`,
+      );
+    }
+
+    // Sanity check: If we analyzed files and found zero issues after filtering, show validation
+    if (totalErrors === 0 && totalWarnings === 0 && totalFilesChecked > 0) {
+      if (totalFilteredErrors > 0) {
+        console.log(
+          `${colors.dim}✓ Verified: ${totalFilesChecked} files analyzed cleanly (${totalFilteredErrors} known issues filtered)${colors.reset}`,
+        );
+      } else {
+        console.log(
+          `${colors.dim}✓ Verified: ${totalFilesChecked} files analyzed with no issues${colors.reset}`,
+        );
+      }
+    }
+  }
+
   process.exit(totalErrors > 0 ? 1 : 0);
 }