@activemind/scd 1.4.0

package/lib/file-context.js

@@ -0,0 +1,380 @@
+/**
+ * file-context.js
+ * Builds a context object for a file before rules are applied.
+ *
+ * Detection is two-layer:
+ *   Layer 1 — path/filename signals (always evaluated, fast)
+ *   Layer 2 — content signals (first 50 lines, always run when content available)
+ *
+ * Vendor and generated files are classified definitively from path/filename alone.
+ * All other test/fixture classifications are tentative — content must confirm them.
+ * If content is unavailable (e.g. secrets scanner path), tentative type is used as-is.
+ *
+ * The returned context is passed to applyContextModifiers() in context-modifiers.js.
+ * Rules themselves are not modified — file context is a purely additive layer.
+ */
+
+'use strict';
+
+const path = require('path');
+
+// ── File type constants ────────────────────────────────────────────────────
+const FILE_TYPES = {
+  FIXTURE:   'fixture',
+  VENDOR:    'vendor',
+  GENERATED: 'generated',
+  TEST:      'test',
+  CONFIG:    'config',
+  DOCS:      'docs',
+  SOURCE:    'source',
+};
+
+// ── Path/filename signal patterns ──────────────────────────────────────────
+
+// TENTATIVE — requires content confirmation when content is available.
+const FIXTURE_PATH_SEGMENTS = [
+  '/fixtures/', '/fixture/', '/mocks/', '/mock/', '/stubs/', '/stub/',
+  '/__fixtures__/', '/__mocks__/',
+];
+
+// TENTATIVE — requires content confirmation when content is available.
+const TEST_PATH_SEGMENTS = [
+  '/test/', '/tests/', '/spec/', '/specs/',
+  '/__tests__/', '/__specs__/',
+  '/e2e/', '/integration-tests/', '/unit/',
+];
+
+// DEFINITIVE — never production code regardless of content.
+const VENDOR_PATH_SEGMENTS = [
+  '/vendor/', '/node_modules/', '/bower_components/', '/site-packages/',
+  '/lib/python', '/packages/', '/.venv/', '/venv/',
+];
+
+// DEFINITIVE — machine output, findings are not actionable.
+const GENERATED_PATH_SEGMENTS = [
+  '/dist/', '/build/', '/out/', '/.next/', '/.nuxt/',
+  '/generated/', '/gen/', '/auto-generated/',
+  '/coverage/', '/.nyc_output/', '/__pycache__/',
+];
+
+// TENTATIVE — requires content confirmation when content is available.
+const DOCS_PATH_SEGMENTS = [
+  '/docs/', '/doc/', '/documentation/', '/wiki/',
+];
+
+// TEST_FILENAME_RE: TENTATIVE — requires content confirmation.
+// STRONG_TEST_FILENAME_RE: DEFINITIVE — filename alone is sufficient, no content needed.
+//   Rules: suffix .test.EXT or .spec.EXT, prefix test_*.EXT, suffix _test.EXT
+//   These are language-standard test file naming conventions — ambiguity is negligible.
+//   Path-only signals (/tests/ directory without filename signal) remain tentative.
+// GENERATED_FILE_RE: DEFINITIVE.
+// CONFIG_FILE_RE: DIRECT — config modifier is 0, no suppression risk.
+const STRONG_TEST_FILENAME_RE = /(?:\.(?:test|spec)\.[a-z]+$|_test\.[a-z]+$|^test_[^/]+\.[a-z]+$)/i;
+const TEST_FILENAME_RE        = /(?:\.(?:test|spec)\.[a-z]+$|_test\.[a-z]+$|^test_.*\.[a-z]+$|Test\.[a-z]+$|\.test$|\.spec$)/i;
+const GENERATED_FILE_RE = /(?:\.min\.(?:js|css)$|package-lock\.json$|yarn\.lock$|composer\.lock$|Pipfile\.lock$|\.lock$|\.d\.ts$)/i;
+const CONFIG_FILE_RE    = /(?:\.(?:env|config|conf|ini|cfg|properties|yml|yaml|toml|json)$|^\.env(?:\.[a-z]+)?$|webpack\.config\.|vite\.config\.|babel\.config\.|jest\.config\.|karma\.conf\.|rollup\.config\.|tsconfig\.|\.eslintrc|\.prettierrc|\.stylelintrc)/i;
+
+// ── Test framework content signals ─────────────────────────────────────────
+// Checked against the first 50 lines of the file.
+// Ordered by specificity — more specific signals first.
+
+const FRAMEWORK_CONTENT_SIGNALS = [
+  // Jest
+  { framework: 'jest',      re: /\bjest\.(?:mock|fn|spyOn|setTimeout|useFakeTimers)\b/ },
+  { framework: 'jest',      re: /from\s+['"](?:@jest\/globals|jest-each)['"]/  },
+  // Vitest
+  { framework: 'vitest',    re: /from\s+['"]vitest['"]/  },
+  { framework: 'vitest',    re: /\bvi\.(?:mock|fn|spyOn)\b/ },
+  // Playwright — @playwright/test, widely used for E2E
+  { framework: 'playwright', re: /from\s+['"]@playwright\/test['"]/ },
+  { framework: 'playwright', re: /\btest\.(?:describe|beforeAll|afterAll|beforeEach|afterEach)\b/ },
+  // Mocha / Chai
+  { framework: 'mocha',     re: /\b(?:before|after|beforeEach|afterEach)\s*\(/ },
+  { framework: 'mocha',     re: /\bassert\.[a-z]+\s*\(/ },
+  // Pytest
+  { framework: 'pytest',    re: /\bimport\s+pytest\b/ },
+  { framework: 'pytest',    re: /\bdef\s+test_[a-z_]+\s*\(/ },
+  { framework: 'pytest',    re: /@pytest\.fixture\b/ },
+  // Python unittest (stdlib)
+  { framework: 'unittest',  re: /\bimport\s+unittest\b/ },
+  { framework: 'unittest',  re: /\bfrom\s+unittest\b/ },
+  { framework: 'unittest',  re: /\bclass\s+\w+\s*\(\s*unittest\.TestCase\s*\)/ },
+  // PHPUnit — direct extends
+  { framework: 'phpunit',   re: /\bextends\s+(?:TestCase|PHPUnit[\\]Framework[\\]TestCase)\b/ },
+  { framework: 'phpunit',   re: /public\s+function\s+test[A-Z]/ },
+  // PHPUnit — import/namespace signals (catches indirect inheritance chains)
+  { framework: 'phpunit',   re: /\buse\s+PHPUnit\\/ },
+  { framework: 'phpunit',   re: /\bnamespace\s+\S+\\Tests?\\/ },
+  // Pest — modern PHP testing framework
+  { framework: 'pest',      re: /\buses\s*\(\s*\w+::class\s*\)/ },
+  { framework: 'pest',      re: /\bit\s*\(\s*['"]/ },
+  // C# — NUnit, xUnit, MSTest (attribute-based, detected without imports)
+  { framework: 'nunit',     re: /\[(?:Test|TestFixture|SetUp|TearDown|OneTimeSetUp)\]/ },
+  { framework: 'xunit',     re: /\[(?:Fact|Theory|InlineData|ClassData)\]/ },
+  { framework: 'mstest',    re: /\[(?:TestMethod|TestClass|TestInitialize|TestCleanup)\]/ },
+  // RSpec
+  { framework: 'rspec',     re: /\b(?:describe|context|it)\s+['"].*['"],?\s*do\b/ },
+  { framework: 'rspec',     re: /\bexpect\s*\(.*\)\.to\s/ },
+  // Ruby Minitest
+  { framework: 'minitest',  re: /require\s+['"]minitest\/autorun['"]/ },
+  { framework: 'minitest',  re: /\bclass\s+\w+\s*<\s*Minitest::Test\b/ },
+  // Node.js built-in test runner (node:test, Node 18+)
+  { framework: 'node-test', re: /require\s*\(\s*['"]node:test['"]\s*\)/ },
+  { framework: 'node-test', re: /from\s+['"]node:test['"]/ },
+  // Bun test runner (bun:test)
+  { framework: 'bun-test',  re: /from\s+['"]bun:test['"]/ },
+  { framework: 'bun-test',  re: /require\s*\(\s*['"]bun:test['"]\s*\)/ },
+  // Generic — lower specificity, checked last
+  { framework: null,        re: /\b(?:describe|it|expect|assert|should)\s*[\.(]/ },
+];
+
+// ── Language detection from extension ─────────────────────────────────────
+const EXT_TO_LANGUAGE = {
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript',
+  jsx: 'javascript',
+  ts: 'typescript', tsx: 'typescript',
+  py: 'python',
+  php: 'php',
+  cs: 'csharp',
+  aspx: 'aspnet', ascx: 'aspnet', master: 'aspnet',
+  rb: 'ruby',
+  go: 'go',
+  java: 'java',
+  kt: 'kotlin',
+  rs: 'rust',
+  sh: 'shell', bash: 'shell',
+  ps1: 'powershell',
+  bat: 'batch', cmd: 'batch',
+  yml: 'yaml', yaml: 'yaml',
+  json: 'json',
+  xml: 'xml',
+  sql: 'sql',
+  env: 'env',
+  ini: 'ini', cfg: 'ini', conf: 'ini', properties: 'ini',
+  txt: 'text',
+  log: 'text',
+  md: 'markdown',
+  pem: 'pem', key: 'pem', pfx: 'pem', p12: 'pem',
+};
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function normalisePath(filePath) {
+  const normalised = filePath.replace(/\\/g, '/').toLowerCase();
+  return normalised.startsWith('/') ? normalised : '/' + normalised;
+}
+
+function hasPathSegment(normPath, segments) {
+  return segments.some(seg => normPath.includes(seg));
+}
+
+function firstLines(content, n = 50) {
+  if (!content) return '';
+  let count = 0;
+  let idx = 0;
+  while (idx < content.length && count < n) {
+    if (content[idx] === '\n') count++;
+    idx++;
+  }
+  return content.slice(0, idx);
+}
+
+// ── Main export ────────────────────────────────────────────────────────────
+
+/**
+ * Build a context object for a file before rules are evaluated.
+ *
+ * @param {string} filePath  - Relative or absolute path to the file.
+ * @param {string} [content] - File content (optional; used for content signals).
+ * @returns {FileContext}
+ *
+ * @typedef {Object} FileContext
+ * @property {string}      filePath       - As supplied.
+ * @property {string}      fileType       - One of: source | test | fixture | vendor | generated | config | docs
+ * @property {string|null} testFramework  - Detected test framework, or null.
+ * @property {string|null} language       - Detected language from extension, or null.
+ * @property {string[]}    signals        - Human-readable list of signals that drove classification.
+ */
+function buildFileContext(filePath, content) {
+  const normPath = normalisePath(filePath);
+  const basename = path.basename(filePath).toLowerCase();
+  const ext      = (filePath.split('.').pop() || '').toLowerCase();
+  const language = EXT_TO_LANGUAGE[ext] || null;
+
+  const signals = [];
+  let fileType      = null;
+  let testFramework = null;
+
+  // ── Layer 1: path/filename signals ────────────────────────────────────────
+  // Vendor and generated are definitive. All test/fixture signals are tentative.
+
+  // Definitive: vendor
+  if (!fileType && hasPathSegment(normPath, VENDOR_PATH_SEGMENTS)) {
+    fileType = FILE_TYPES.VENDOR;
+    signals.push(`path: vendor segment in ${normPath}`);
+  }
+
+  // Definitive: generated path
+  if (!fileType && hasPathSegment(normPath, GENERATED_PATH_SEGMENTS)) {
+    fileType = FILE_TYPES.GENERATED;
+    signals.push(`path: generated segment in ${normPath}`);
+  }
+
+  // Definitive: generated filename
+  if (!fileType && GENERATED_FILE_RE.test(basename)) {
+    fileType = FILE_TYPES.GENERATED;
+    signals.push(`filename: generated pattern (${basename})`);
+  }
+
+  // Tentative classifications — stored, not committed until content confirms.
+  // tentativeIsPathBased tracks whether the signal is path-based (reliable without
+  // content) or filename-only (unreliable — must not be committed without content).
+  let tentativeType        = null;
+  let tentativeSignal      = null;
+  let tentativeIsPathBased = false;
+
+  if (!fileType && hasPathSegment(normPath, FIXTURE_PATH_SEGMENTS)) {
+    tentativeType        = FILE_TYPES.FIXTURE;
+    tentativeSignal      = `path: fixture segment in ${normPath}`;
+    tentativeIsPathBased = true;
+  }
+
+  // Definitive: strong test filename signal AND known test path — both required.
+  // Rationale: filename alone is insufficient — kunddata.test.js in /src/ must not
+  // bypass scanning. An attacker can rename a file to evade detection.
+  if (!fileType && !tentativeType
+      && STRONG_TEST_FILENAME_RE.test(basename)
+      && hasPathSegment(normPath, TEST_PATH_SEGMENTS)) {
+    fileType = FILE_TYPES.TEST;
+    signals.push(`filename+path: strong test signal (${basename}) — definitive`);
+  }
+
+  // Tentative: strong filename without test path, or weaker filename signals.
+  // Filename-only tentative is NOT committed without content — see no-content branch.
+  if (!fileType && !tentativeType && TEST_FILENAME_RE.test(basename)) {
+    tentativeType        = FILE_TYPES.TEST;
+    tentativeSignal      = `filename: test pattern (${basename})`;
+    tentativeIsPathBased = false;
+  }
+
+  if (!fileType && !tentativeType && hasPathSegment(normPath, TEST_PATH_SEGMENTS)) {
+    tentativeType        = FILE_TYPES.TEST;
+    tentativeSignal      = `path: test segment in ${normPath}`;
+    tentativeIsPathBased = true;
+  }
+
+  // Config: direct (modifier = 0, suppression never occurs)
+  if (!fileType && !tentativeType && CONFIG_FILE_RE.test(basename)) {
+    fileType = FILE_TYPES.CONFIG;
+    signals.push(`filename: config pattern (${basename})`);
+  }
+
+  // Docs: tentative (path-based)
+  if (!fileType && !tentativeType && hasPathSegment(normPath, DOCS_PATH_SEGMENTS)) {
+    tentativeType        = FILE_TYPES.DOCS;
+    tentativeSignal      = `path: docs segment in ${normPath}`;
+    tentativeIsPathBased = true;
+  }
+
+  // ── Early commit for data/config extensions in test/fixture paths ──────────
+  // Data and config file types (.json, .yaml, .txt, .sql etc.) cannot contain
+  // test framework imports — Layer 2 content confirmation will never succeed.
+  // If such a file is in a test/fixture path, commit the tentative type directly
+  // without requiring content confirmation.
+  // Rationale: a .json file in /tests/ is test data by definition.
+  // A .yaml file in /fixtures/ is a fixture by definition.
+  // These are never "source code" that needs scanning for vulnerabilities
+  // at the same severity as production config.
+  const DATA_EXTS_NO_CONFIRM = new Set([
+    'json', 'yaml', 'yml', 'xml', 'txt', 'log', 'sql',
+    'sqlite', 'sqlite3', 'db', 'pem', 'key', 'pfx', 'p12',
+    'csv', 'tsv', 'toml', 'ini', 'cfg', 'conf', 'properties',
+  ]);
+  if (!fileType && tentativeType && DATA_EXTS_NO_CONFIRM.has(ext)) {
+    fileType = tentativeType;
+    signals.push(tentativeSignal);
+    signals.push(`data/config extension in test path — committed without content confirmation`);
+    tentativeType   = null;
+    tentativeSignal = null;
+  }
+
+  // ── Layer 1.5: framework detection for filename-confirmed test files ─────────
+  // Strong filename signals (*.test.js, *.spec.ts, test_*.py) commit fileType=TEST
+  // in Layer 1, so Layer 2's content loop never runs and testFramework stays null.
+  // Detect the framework here before Layer 2 guards on !fileType.
+  if (fileType === FILE_TYPES.TEST && !testFramework && content) {
+    const head = firstLines(content, 50);
+    for (const { framework, re } of FRAMEWORK_CONTENT_SIGNALS) {
+      if (framework && re.test(head)) {
+        testFramework = framework;
+        signals.push(`content: framework=${framework}`);
+        break;
+      }
+    }
+  }
+
+  // ── Layer 2: content signals ───────────────────────────────────────────────
+  // Run when fileType is not definitively set.
+  // With content: tentative must be confirmed, or it falls back to source.
+  // Without content: tentative is committed as-is (best available signal).
+
+  if (!fileType) {
+    if (content) {
+      const head = firstLines(content, 50);
+
+      for (const { framework, re } of FRAMEWORK_CONTENT_SIGNALS) {
+        if (re.test(head)) {
+          if (!testFramework && framework) {
+            testFramework = framework;
+            signals.push(`content: framework=${framework}`);
+          }
+
+          if (!fileType) {
+            if (tentativeType) {
+              fileType = tentativeType;
+              signals.push(tentativeSignal);
+              signals.push(`content: confirmed (${re.source.slice(0, 40)})`);
+            } else {
+              fileType = FILE_TYPES.TEST;
+              signals.push(`content: test signal (${re.source.slice(0, 40)})`);
+            }
+          }
+
+          if (fileType && testFramework) break;
+        }
+      }
+
+      // Tentative not confirmed by content → source
+      if (!fileType && tentativeType) {
+        signals.push(`path/filename: ${tentativeSignal} — not confirmed by content, treated as source`);
+        fileType = FILE_TYPES.SOURCE;
+      }
+
+    } else {
+      // No content — only path-based tentative is committed; filename-only falls to source.
+      // A path signal (/tests/, /fixtures/ etc.) is reliable without content.
+      // A filename signal alone (*.test.js in /src/) is not — commit it as source to
+      // avoid suppressing findings in misnamed production files.
+      if (tentativeType && tentativeIsPathBased) {
+        fileType = tentativeType;
+        signals.push(tentativeSignal);
+        signals.push('content: unavailable — path signal committed without confirmation');
+      }
+    }
+  }
+
+  // ── Default ───────────────────────────────────────────────────────────────
+  if (!fileType) {
+    fileType = FILE_TYPES.SOURCE;
+  }
+
+  return {
+    filePath,
+    fileType,
+    testFramework,
+    language,
+    signals,
+  };
+}
+
+module.exports = { buildFileContext, FILE_TYPES };

package/lib/file-filter.js

@@ -0,0 +1,204 @@
+'use strict';
+
+/**
+ * lib/file-filter.js
+ *
+ * Builds a file filter for use during scan file discovery.
+ * Applies .gitignore rules and scd scope.yml file_excludes patterns.
+ *
+ * Previously named gitignore-filter.js — renamed as scope.yml support
+ * extends filtering beyond git-related exclusions.
+ *
+ * Strategy:
+ *   Level 1 (git available): `git ls-files --cached --others --exclude-standard`
+ *     Returns exactly the files git tracks or would track — free and correct.
+ *   Level 2 (fallback, no git): Parse .gitignore files manually.
+ *     Handles the common case: someone downloaded a repo without git clone,
+ *     or git is not installed on the machine.
+ *
+ * Usage:
+ *   const { buildIgnoreFilter } = require('./gitignore-filter');
+ *   const shouldIgnore = buildIgnoreFilter(repoRoot);
+ *   if (shouldIgnore(filePath)) // skip this file
+ */
+
+const fs            = require('fs');
+const path          = require('path');
+const { execSync }  = require('child_process');
+
+// ── Level 1: git ls-files ────────────────────────────────────────────────
+
+/**
+ * Get the set of files tracked or untracked-but-not-ignored by git.
+ * Returns null if git is unavailable or the directory is not a git repo.
+ */
+function getGitTrackedFiles(repoRoot) {
+  try {
+    const output = execSync(
+      'git ls-files --cached --others --exclude-standard',
+      { cwd: repoRoot, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    const files = new Set(
+      output.split('\n')
+        .map(f => f.trim())
+        .filter(Boolean)
+        .map(f => path.resolve(repoRoot, f))
+    );
+    return files;
+  } catch {
+    return null;
+  }
+}
+
+// ── Level 2: manual .gitignore parsing ──────────────────────────────────
+
+/**
+ * Parse a single .gitignore file and return an array of pattern objects.
+ * Each pattern: { regex, negated, anchored }
+ */
+function parseGitignoreFile(filePath) {
+  if (!fs.existsSync(filePath)) return [];
+  const lines = fs.readFileSync(filePath, 'utf8').split('\n');
+  const patterns = [];
+
+  for (let line of lines) {
+    line = line.trim();
+    // Skip empty lines and comments
+    if (!line || line.startsWith('#')) continue;
+
+    const negated = line.startsWith('!');
+    if (negated) line = line.slice(1);
+
+    // Anchored: pattern starts with / (relative to .gitignore location)
+    const anchored = line.startsWith('/');
+    if (anchored) line = line.slice(1);
+
+    // Convert glob pattern to regex.
+    // Order matters: ** and * must be marked before regex-escaping,
+    // otherwise plain * survives the escape step and lands verbatim
+    // in the final regex (causing "nothing to repeat" errors on ^*).
+    let regexStr = line
+      .replace(/\*\*/g, '__DOUBLESTAR__')       // protect ** first
+      .replace(/\*/g,   '__STAR__')             // then protect plain *
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')    // escape regex special chars
+      .replace(/__STAR__/g,       '[^/]*')      // * = anything except /
+      .replace(/__DOUBLESTAR__/g, '.*')         // ** = anything including /
+      .replace(/\?/g, '[^/]');                  // ? = single char except /
+
+    // Directory pattern (ends with /)
+    const dirOnly = regexStr.endsWith('/');
+    if (dirOnly) regexStr = regexStr.slice(0, -1);
+
+    patterns.push({
+      regex:    new RegExp((anchored ? '^' : '(^|/)') + regexStr + (dirOnly ? '(/|$)' : '(/|$)')),
+      negated,
+      dirOnly,
+    });
+  }
+
+  return patterns;
+}
+
+/**
+ * Collect all .gitignore files from repoRoot down (including nested ones).
+ * Returns array of { dir, patterns } objects.
+ */
+function collectGitignorePatterns(repoRoot) {
+  const result = [];
+
+  function walk(dir) {
+    const gitignorePath = path.join(dir, '.gitignore');
+    const patterns = parseGitignoreFile(gitignorePath);
+    if (patterns.length > 0) {
+      result.push({ dir, patterns });
+    }
+    try {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+          walk(path.join(dir, entry.name));
+        }
+      }
+    } catch { /* permission errors etc — skip */ }
+  }
+
+  walk(repoRoot);
+  return result;
+}
+
+/**
+ * Given collected gitignore rules, check if a file path should be ignored.
+ */
+function isIgnoredByPatterns(filePath, gitignoreRules) {
+  let ignored = false;
+
+  for (const { dir, patterns } of gitignoreRules) {
+    // Only apply rules from .gitignore files at or above this file
+    if (!filePath.startsWith(dir + path.sep) && filePath !== dir) continue;
+
+    // Make path relative to the .gitignore's directory
+    const rel = path.relative(dir, filePath).split(path.sep).join('/');
+
+    for (const { regex, negated } of patterns) {
+      if (regex.test(rel)) {
+        ignored = !negated;
+      }
+    }
+  }
+
+  return ignored;
+}
+
+// ── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Build a filter function for the given repo root.
+ *
+ * Returns: shouldIgnore(absoluteFilePath) → boolean
+ *
+ * Level 1 (git available): uses git ls-files set — O(1) lookup per file.
+ * Level 2 (fallback): parses .gitignore files — pattern matching per file.
+ * Level 3 (no .gitignore): returns () => false — nothing ignored.
+ *
+ * @param {string} repoRoot  Absolute path to the repo root
+ * @param {boolean} debug    Log which strategy was used
+ */
+function buildIgnoreFilter(repoRoot, { debug = false } = {}) {
+  // Level 1: try git ls-files
+  const trackedFiles = getGitTrackedFiles(repoRoot);
+  if (trackedFiles !== null) {
+    if (debug) console.error(`[gitignore] Using git ls-files (${trackedFiles.size} files tracked)`);
+    // A file should be ignored if it is NOT in the tracked set
+    // But we only want to ignore files that git explicitly ignores —
+    // not untracked files that simply haven't been added yet.
+    // So we use a different git call to get explicitly ignored files.
+    try {
+      const ignoredOutput = execSync(
+        'git ls-files --others --ignored --exclude-standard',
+        { cwd: repoRoot, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      const ignoredFiles = new Set(
+        ignoredOutput.split('\n')
+          .map(f => f.trim())
+          .filter(Boolean)
+          .map(f => path.resolve(repoRoot, f))
+      );
+      if (debug) console.error(`[gitignore] ${ignoredFiles.size} files explicitly ignored by git`);
+      return (filePath) => ignoredFiles.has(filePath);
+    } catch {
+      // git available but ls-files --ignored failed — fall through to Level 2
+    }
+  }
+
+  // Level 2: parse .gitignore files manually
+  const gitignoreRules = collectGitignorePatterns(repoRoot);
+  if (gitignoreRules.length > 0) {
+    if (debug) console.error(`[gitignore] Using manual parser (${gitignoreRules.length} .gitignore file(s))`);
+    return (filePath) => isIgnoredByPatterns(filePath, gitignoreRules);
+  }
+
+  // Level 3: no .gitignore found — nothing to filter
+  if (debug) console.error('[gitignore] No .gitignore found — no files filtered');
+  return () => false;
+}
+
+module.exports = { buildIgnoreFilter };