@ngockhoale/ukit 1.1.6

package/src/index/buildIndex.js

@@ -0,0 +1,1392 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, normalizeRelative } from './paths.js';
+import { importsNeedAliasContext, loadImportAliasContextState, resolveImportSpecifier } from './importResolution.js';
+import { clearIndexArtifactCache } from './queryIndex.js';
+import { clearRelatedTestArtifactCache } from './relatedTests.js';
+
+const SOURCE_DIRS = ['src', 'tests', 'test', 'specs', 'spec', '__tests__', 'manifests'];
+const EXCLUDED_DIR_NAMES = new Set([
+  'node_modules',
+  '.git',
+  '.cache',
+  '.next',
+  '.nuxt',
+  '.output',
+  '.vercel',
+  '.turbo',
+  '.yarn',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  'tmp',
+  'temp',
+  'vendor',
+  '.venv',
+  'venv',
+]);
+const CODE_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue']);
+const STYLE_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
+const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.json', '.yaml', '.yml', '.md']);
+const DISCOVERED_EXTENSIONS = new Set([...TRACKED_EXTENSIONS, ...STYLE_EXTENSIONS]);
+export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const INDEX_PARSE_BATCH_SIZE = 8;
+
+export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
+  const absoluteRoot = path.resolve(rootDir);
+  const indexDir = getIndexDir(absoluteRoot);
+
+  const previousFilesArtifact = await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.files);
+  const canReusePrevious = previousFilesArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+  const previousCodeFileRecords = canReusePrevious
+    ? (previousFilesArtifact.items ?? []).filter((item) => CODE_EXTENSIONS.has(item?.ext))
+    : [];
+
+  const previousCodeMetaByPath = new Map(
+    previousCodeFileRecords.map((item) => [item.filePath, { mtimeMs: Number(item.mtimeMs ?? -1), size: Number(item.size ?? -1) }]),
+  );
+
+  const discoveredFiles = await collectFiles(await resolveScanRoots(absoluteRoot));
+  const sourceFingerprint = createSourceFingerprint(absoluteRoot, discoveredFiles);
+  const styleFilePaths = discoveredFiles
+    .map((entry) => {
+      const ext = path.extname(entry.absolutePath).toLowerCase();
+      if (!STYLE_EXTENSIONS.has(ext)) {
+        return null;
+      }
+      return normalizeRelative(absoluteRoot, entry.absolutePath);
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.localeCompare(b));
+
+  const fileRecords = discoveredFiles
+    .map((entry) => {
+      const ext = path.extname(entry.absolutePath).toLowerCase();
+      if (!TRACKED_EXTENSIONS.has(ext)) {
+        return null;
+      }
+
+      const filePath = normalizeRelative(absoluteRoot, entry.absolutePath);
+      const domain = filePath.split('/')[0] ?? 'other';
+
+      return {
+        filePath,
+        domain,
+        ext,
+        mtimeMs: entry.mtimeMs,
+        size: entry.size,
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.filePath.localeCompare(b.filePath));
+  const canReuseFilesArtifact = canReusePrevious
+    && areFileRecordSnapshotsEqual(previousFilesArtifact?.items ?? [], fileRecords);
+
+  const codeFiles = fileRecords.filter((record) => CODE_EXTENSIONS.has(record.ext));
+
+  const symbols = [];
+  const imports = [];
+  const reusableCodeFiles = [];
+  let filesToParse = [];
+  let reusedCodeFileCount = 0;
+  let canReuseParsedArtifacts = false;
+
+  for (const file of codeFiles) {
+    const previousMeta = previousCodeMetaByPath.get(file.filePath);
+    const isUnchanged = previousMeta
+      && previousMeta.mtimeMs === file.mtimeMs
+      && previousMeta.size === file.size;
+
+    if (isUnchanged) {
+      reusableCodeFiles.push(file.filePath);
+      continue;
+    }
+
+    filesToParse.push(file.filePath);
+  }
+
+  if (reusableCodeFiles.length > 0) {
+    const [previousSymbolsArtifact, previousImportsArtifact] = await Promise.all([
+      readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.symbols),
+      readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.imports),
+    ]);
+    canReuseParsedArtifacts = previousSymbolsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+      && previousImportsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+
+    if (canReuseParsedArtifacts) {
+      const previousSymbolsByPath = groupBy(previousSymbolsArtifact.items ?? [], (item) => item.filePath);
+      const previousImportsByPath = groupBy(previousImportsArtifact.items ?? [], (item) => item.from);
+
+      for (const filePath of reusableCodeFiles) {
+        symbols.push(...(previousSymbolsByPath.get(filePath) ?? []));
+        imports.push(...(previousImportsByPath.get(filePath) ?? []));
+        reusedCodeFileCount += 1;
+      }
+    } else {
+      filesToParse = codeFiles.map((file) => file.filePath);
+    }
+  }
+  const canReuseAllParsedArtifacts = canReuseParsedArtifacts && filesToParse.length === 0 && reusableCodeFiles.length === codeFiles.length;
+
+  for (let start = 0; start < filesToParse.length; start += INDEX_PARSE_BATCH_SIZE) {
+    const batch = filesToParse.slice(start, start + INDEX_PARSE_BATCH_SIZE);
+    const parsedBatch = (await Promise.all(batch.map(async (filePath) => {
+      try {
+        const absolutePath = path.join(absoluteRoot, filePath);
+        const content = await fs.readFile(absolutePath, 'utf8');
+        const scriptContent = extractScriptContent(filePath, content);
+        return {
+          filePath,
+          symbols: extractSymbols(filePath, scriptContent),
+          imports: [
+            ...extractImports(filePath, scriptContent),
+            ...extractSupplementalImports(filePath, content),
+          ],
+        };
+      } catch {
+        return null;
+      }
+    }))).filter(Boolean);
+
+    for (const parsedFile of parsedBatch) {
+      symbols.push(...parsedFile.symbols);
+      imports.push(...parsedFile.imports);
+    }
+  }
+
+  const canReuseTestsMapCandidate = canReusePrevious
+    && haveStableTrackedFileIdentities(previousFilesArtifact?.items ?? [], fileRecords);
+  const previousTestsMapArtifact = canReuseTestsMapCandidate
+    ? await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.testsMap)
+    : null;
+  const canReuseTestsMap = canReuseTestsMapCandidate
+    && previousTestsMapArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+  const testsMap = canReuseTestsMap
+    ? previousTestsMapArtifact.items
+    : buildTestsMap(fileRecords);
+  const bugIndexSnapshot = await readBugIndexSnapshot(absoluteRoot);
+  const previousHotspotsArtifact = canReusePrevious
+    ? await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.hotspots)
+    : null;
+  const canReuseHotspots = previousHotspotsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && areBugIndexSnapshotsEqual(previousHotspotsArtifact?.sourceSnapshot, bugIndexSnapshot);
+  const hotspots = canReuseHotspots
+    ? previousHotspotsArtifact.items
+    : await buildHotspots(absoluteRoot, bugIndexSnapshot);
+
+  const currentCodePaths = new Set(codeFiles.map((f) => f.filePath));
+  const canReuseArchetypesCandidate = canReusePrevious
+    && filesToParse.length === 0
+    && codeFiles.every((file) => previousCodeMetaByPath.has(file.filePath));
+  const previousArchetypesArtifact = canReuseArchetypesCandidate
+    ? await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.archetypes)
+    : null;
+  const canReuseArchetypes = canReuseArchetypesCandidate
+    && previousArchetypesArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && previousArchetypesArtifact?.items?.length === codeFiles.length
+    && (previousArchetypesArtifact.items ?? []).every((item) => currentCodePaths.has(item.filePath));
+
+  // Reuse cached archetypes only when every indexed code file is unchanged
+  const archetypes = canReuseArchetypes
+    ? previousArchetypesArtifact.items
+    : classifyArchetypes(fileRecords, symbols);
+  const needsAliasContext = importsNeedAliasContext(imports);
+  const canReuseGraphArtifactsCandidate = canReusePrevious
+    && filesToParse.length === 0
+    && haveStableTrackedFileIdentities(previousCodeFileRecords, codeFiles);
+  const [previousRelationsArtifact, previousAnalogsArtifact] = canReuseGraphArtifactsCandidate
+    ? await Promise.all([
+        readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.relations),
+        readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.analogs),
+      ])
+    : [null, null];
+  const importAliasState = needsAliasContext
+    ? await loadImportAliasContextState({ rootDir: absoluteRoot })
+    : null;
+  const importAliasContext = importAliasState?.context ?? null;
+  const styleSnapshot = {
+    styleFiles: styleFilePaths,
+    importAliasSnapshot: importAliasState?.snapshot ?? [],
+  };
+  const canReuseRelations = canReuseGraphArtifactsCandidate
+    && previousRelationsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && areStringArraysEqual(previousRelationsArtifact?.sourceSnapshot?.styleFiles, styleFilePaths)
+    && arePathSnapshotsEqual(
+      previousRelationsArtifact?.sourceSnapshot?.importAliasSnapshot,
+      styleSnapshot.importAliasSnapshot,
+    );
+  const canReuseAnalogs = canReuseGraphArtifactsCandidate
+    && previousAnalogsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && areStringArraysEqual(previousAnalogsArtifact?.sourceSnapshot?.styleFiles, styleFilePaths)
+    && arePathSnapshotsEqual(
+      previousAnalogsArtifact?.sourceSnapshot?.importAliasSnapshot,
+      styleSnapshot.importAliasSnapshot,
+    );
+  const indexedFileSet = new Set(codeFiles.map((file) => file.filePath));
+  const resolvedImportsBySource = canReuseRelations && canReuseAnalogs
+    ? null
+    : buildResolvedImportMap(
+        absoluteRoot,
+        imports,
+        indexedFileSet,
+        importAliasContext,
+      );
+  const resolvedStyleImportsBySource = canReuseRelations
+    ? null
+    : buildResolvedImportMap(
+        absoluteRoot,
+        imports,
+        new Set(styleFilePaths),
+        importAliasContext,
+      );
+  const relations = canReuseRelations
+    ? previousRelationsArtifact.items
+    : buildRelations(
+        fileRecords,
+        archetypes,
+        testsMap,
+        resolvedImportsBySource,
+        resolvedStyleImportsBySource,
+      );
+  const analogs = canReuseAnalogs
+    ? previousAnalogsArtifact.items
+    : buildAnalogs(fileRecords, archetypes, relations, resolvedImportsBySource);
+
+  const generatedAt = new Date().toISOString();
+
+  await fs.mkdir(indexDir, { recursive: true });
+  if (!canReuseFilesArtifact) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.files, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: fileRecords,
+    });
+  }
+  if (!canReuseAllParsedArtifacts) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.symbols, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: symbols,
+    });
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.imports, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: imports,
+    });
+  }
+  if (!canReuseTestsMap) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.testsMap, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: testsMap,
+    });
+  }
+  if (!canReuseHotspots) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.hotspots, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      sourceSnapshot: bugIndexSnapshot,
+      items: hotspots,
+    });
+  }
+  if (!canReuseArchetypes) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.archetypes, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: archetypes,
+    });
+  }
+  if (!canReuseRelations) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.relations, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      sourceSnapshot: styleSnapshot,
+      items: relations,
+    });
+  }
+  if (!canReuseAnalogs) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.analogs, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      sourceSnapshot: styleSnapshot,
+      items: analogs,
+    });
+  }
+  await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.meta, {
+    schemaVersion: INDEX_SCHEMA_VERSION,
+    generatedAt,
+    rootDir: absoluteRoot,
+    sourceFingerprint,
+  });
+  const preservedRuntimeCaches = canReuseFilesArtifact
+    && canReuseAllParsedArtifacts
+    && canReuseTestsMap
+    && canReuseHotspots
+    && canReuseArchetypes
+    && canReuseRelations
+    && canReuseAnalogs;
+  if (!preservedRuntimeCaches) {
+    clearIndexArtifactCache(absoluteRoot);
+    clearRelatedTestArtifactCache(absoluteRoot);
+  }
+
+  return {
+    indexDir,
+    generatedAt,
+    generatedAtMs: Date.parse(generatedAt),
+    fileCount: fileRecords.length,
+    symbolCount: symbols.length,
+    importCount: imports.length,
+    testsMapCount: testsMap.length,
+    hotspotCount: hotspots.length,
+    archetypeCount: archetypes.length,
+    relationCount: relations.length,
+    analogCount: analogs.length,
+    parsedCodeFileCount: filesToParse.length,
+    reusedCodeFileCount,
+    reusedTestsMap: canReuseTestsMap,
+    reusedHotspots: canReuseHotspots,
+    reusedRelations: canReuseRelations,
+    reusedAnalogs: canReuseAnalogs,
+    preservedRuntimeCaches,
+  };
+}
+
+async function collectFiles(scanRoots) {
+  const result = [];
+  const stack = [...scanRoots];
+  const visitedDirectoryRealPaths = new Set();
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let currentRealPath;
+    try {
+      currentRealPath = await fs.realpath(current);
+    } catch {
+      continue;
+    }
+
+    if (visitedDirectoryRealPaths.has(currentRealPath)) {
+      continue;
+    }
+    visitedDirectoryRealPaths.add(currentRealPath);
+
+    let entries;
+    try {
+      entries = await fs.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    const symlinkDirectories = [];
+    const directDirectories = [];
+    const symlinkFiles = [];
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (shouldSkipDirectory(entry.name)) {
+          continue;
+        }
+        directDirectories.push(fullPath);
+      } else if (entry.isSymbolicLink()) {
+        try {
+          const stat = await fs.stat(fullPath);
+          if (stat.isDirectory() && !shouldSkipDirectory(entry.name)) {
+            symlinkDirectories.push(fullPath);
+            continue;
+          }
+
+          if (stat.isFile()) {
+            const ext = path.extname(entry.name).toLowerCase();
+            if (DISCOVERED_EXTENSIONS.has(ext)) {
+              symlinkFiles.push({
+                absolutePath: fullPath,
+                mtimeMs: Math.floor(stat.mtimeMs),
+                size: stat.size,
+              });
+            }
+          }
+        } catch {
+          // broken symlink, skip
+        }
+      }
+    }
+    stack.push(...symlinkDirectories, ...directDirectories);
+
+    const fileEntries = entries.filter((entry) => {
+      if (!entry.isFile()) {
+        return false;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      return DISCOVERED_EXTENSIONS.has(ext);
+    });
+    const fileStats = (await Promise.all(fileEntries.map(async (entry) => {
+      try {
+        const fullPath = path.join(current, entry.name);
+        const stat = await fs.stat(fullPath);
+        return {
+          absolutePath: fullPath,
+          mtimeMs: Math.floor(stat.mtimeMs),
+          size: stat.size,
+        };
+      } catch {
+        return null;
+      }
+    }))).filter(Boolean);
+    result.push(...fileStats, ...symlinkFiles);
+  }
+
+  return result;
+}
+
+function extractScriptContent(filePath, content) {
+  if (!filePath.endsWith('.vue')) {
+    return content;
+  }
+
+  const allMatches = [...content.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/gi)];
+  if (allMatches.length === 0) return '';
+  return allMatches.map((m) => m[1]).join('\n');
+}
+
+function extractSymbols(filePath, content) {
+  const symbols = [];
+  const addSymbol = (name, type) => {
+    if (!name) {
+      return;
+    }
+    symbols.push({
+      name,
+      type,
+      filePath,
+    });
+  };
+  const addMatches = (regex, type, groupIndex = 1) => {
+    for (const match of content.matchAll(regex)) {
+      const symbolName = match[groupIndex];
+      if (!symbolName) {
+        continue;
+      }
+      addSymbol(symbolName, type);
+    }
+  };
+
+  addMatches(/export\s+(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)/g, 'function');
+  addMatches(/export\s+class\s+([A-Za-z_$][A-Za-z0-9_$]*)/g, 'class');
+  addMatches(/(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s*)?\(/g, 'callable');
+  addMatches(/(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][A-Za-z0-9_$]*)\s*=>/g, 'callable');
+  addMatches(/export\s+default\s+(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)/g, 'default-function');
+  addMatches(/export\s+default\s+class\s+([A-Za-z_$][A-Za-z0-9_$]*)/g, 'default-class');
+  addMatches(/export\s+default\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*(?:;|\n|$)/g, 'default-reference');
+  addMatches(/defineOptions\(\s*\{[\s\S]*?name\s*:\s*['"]([^'"]+)['"]/g, 'component-name');
+  addMatches(/defineComponent\(\s*\{[\s\S]*?name\s*:\s*['"]([^'"]+)['"]/g, 'component-name');
+  addMatches(/export\s+default\s*\{[\s\S]*?name\s*:\s*['"]([^'"]+)['"]/g, 'component-name');
+
+  if (/\bexport\s+default\b/.test(content)) {
+    addSymbol('default', 'default-export');
+  }
+
+  for (const match of content.matchAll(/export\s*\{([^}]+)\}/g)) {
+    const block = match[1] ?? '';
+    const candidates = block.split(',').map((part) => part.trim()).filter(Boolean);
+    for (const candidate of candidates) {
+      const aliasMatch = candidate.match(/^([A-Za-z_$][A-Za-z0-9_$]*)(?:\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*))?$/);
+      if (!aliasMatch) {
+        continue;
+      }
+      addSymbol(aliasMatch[2] ?? aliasMatch[1], 'named-export');
+    }
+  }
+
+  return dedupeBy(symbols, (item) => `${item.filePath}:${item.type}:${item.name}`);
+}
+
+function extractImports(filePath, content) {
+  // Strip comments to avoid false-positive imports from commented-out code
+  const stripped = content
+    .replace(/\/\*[\s\S]*?\*\//g, '')  // block comments
+    .replace(/\/\/.*$/gm, '');              // line comments
+  const imports = [];
+
+  for (const match of stripped.matchAll(/import\s+(?:[^'";]+?\s+from\s+)?['"]([^'"]+)['"]/g)) {
+    imports.push({
+      from: filePath,
+      to: match[1],
+      kind: 'import',
+    });
+  }
+
+  for (const match of stripped.matchAll(/import\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+    imports.push({
+      from: filePath,
+      to: match[1],
+      kind: 'dynamic-import',
+    });
+  }
+
+  for (const match of stripped.matchAll(/require\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+    imports.push({
+      from: filePath,
+      to: match[1],
+      kind: 'require',
+    });
+  }
+
+  for (const match of stripped.matchAll(/export\s+(?:type\s+)?\{[^}]+\}\s+from\s+['"]([^'"]+)['"]/g)) {
+    imports.push({
+      from: filePath,
+      to: match[1],
+      kind: 're-export',
+    });
+  }
+
+  for (const match of stripped.matchAll(/export\s+\*(?:\s+as\s+[A-Za-z_$][A-Za-z0-9_$]*)?\s+from\s+['"]([^'"]+)['"]/g)) {
+    imports.push({
+      from: filePath,
+      to: match[1],
+      kind: 're-export-all',
+    });
+  }
+
+  return imports;
+}
+
+function extractSupplementalImports(filePath, content) {
+  if (!filePath.endsWith('.vue')) {
+    return [];
+  }
+
+  const imports = [];
+  for (const match of content.matchAll(/<style\b[^>]*\bsrc=['"]([^'"]+)['"][^>]*>/gi)) {
+    imports.push({
+      from: filePath,
+      to: match[1],
+      kind: 'style-src',
+    });
+  }
+
+  return imports;
+}
+
+function buildTestsMap(fileRecords) {
+  const testFiles = fileRecords.filter((file) => isLikelyTestFile(file.filePath));
+  const sourceFiles = fileRecords.filter((file) => CODE_EXTENSIONS.has(file.ext) && !isLikelyTestFile(file.filePath));
+
+  return sourceFiles.map((sourceFile) => {
+    const matches = testFiles
+      .map((testFile) => ({
+        filePath: testFile.filePath,
+        score: scoreTestMatch(sourceFile.filePath, testFile.filePath),
+      }))
+      .filter((match) => match.score > 0)
+      .sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath))
+      .map((match) => match.filePath)
+      .slice(0, 10);
+
+    return {
+      sourceFile: sourceFile.filePath,
+      tests: matches,
+    };
+  });
+}
+
+async function buildHotspots(rootDir, bugIndexSnapshot = null) {
+  const snapshot = bugIndexSnapshot ?? await readBugIndexSnapshot(rootDir);
+  if (!snapshot.exists) {
+    return [];
+  }
+  const bugIndexPath = path.join(rootDir, 'docs', 'BUG_INDEX.md');
+  let content;
+  try {
+    content = await fs.readFile(bugIndexPath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const scores = new Map();
+  const filePattern = /([A-Za-z0-9_@()[\].-]+(?:\/[A-Za-z0-9_@()[\].-]+)+\.(?:tsx|jsx|ts|js|mjs|cjs|vue))/g;
+
+  for (const match of content.matchAll(filePattern)) {
+    const filePath = match[1];
+    scores.set(filePath, (scores.get(filePath) ?? 0) + 1);
+  }
+
+  return [...scores.entries()]
+    .map(([filePath, count]) => ({ filePath, count }))
+    .sort((a, b) => b.count - a.count || a.filePath.localeCompare(b.filePath));
+}
+
+async function readBugIndexSnapshot(rootDir) {
+  const bugIndexPath = path.join(rootDir, 'docs', 'BUG_INDEX.md');
+
+  try {
+    const stat = await fs.stat(bugIndexPath);
+    return {
+      exists: true,
+      mtimeMs: Math.floor(stat.mtimeMs),
+      size: stat.size,
+    };
+  } catch {
+    return { exists: false };
+  }
+}
+
+function areBugIndexSnapshotsEqual(previousSnapshot, nextSnapshot) {
+  if (!previousSnapshot || !nextSnapshot) {
+    return false;
+  }
+
+  if (previousSnapshot.exists !== nextSnapshot.exists) {
+    return false;
+  }
+
+  if (!previousSnapshot.exists) {
+    return true;
+  }
+
+  return previousSnapshot.mtimeMs === nextSnapshot.mtimeMs
+    && previousSnapshot.size === nextSnapshot.size;
+}
+
+async function resolveScanRoots(rootDir) {
+  const concreteRoots = [];
+
+  for (const relativeDir of SOURCE_DIRS) {
+    const dirPath = path.join(rootDir, relativeDir);
+    try {
+      const stat = await fs.stat(dirPath);
+      if (stat.isDirectory()) {
+        concreteRoots.push(dirPath);
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return concreteRoots.length > 0 ? concreteRoots : [rootDir];
+}
+
+function shouldSkipDirectory(name) {
+  if (EXCLUDED_DIR_NAMES.has(name)) {
+    return true;
+  }
+
+  return name.startsWith('.') && name !== '.claude' && name !== '.codex' && name !== '.antigravity';
+}
+
+function isLikelyTestFile(filePath) {
+  const lower = filePath.toLowerCase();
+  return (
+    lower.startsWith('__tests__/')
+    || lower.startsWith('test/')
+    || lower.startsWith('tests/')
+    || lower.startsWith('spec/')
+    || lower.startsWith('specs/')
+    || lower.includes('/__tests__/')
+    || lower.includes('/test/')
+    || lower.includes('/spec/')
+    || lower.includes('/specs/')
+    || lower.endsWith('.test.js')
+    || lower.endsWith('.test.ts')
+    || lower.endsWith('.test.vue')
+    || lower.endsWith('.test.tsx')
+    || lower.endsWith('.test.jsx')
+    || lower.endsWith('.test.mjs')
+    || lower.endsWith('.test.cjs')
+    || lower.endsWith('.spec.js')
+    || lower.endsWith('.spec.ts')
+    || lower.endsWith('.spec.vue')
+    || lower.endsWith('.spec.tsx')
+    || lower.endsWith('.spec.jsx')
+    || lower.endsWith('.spec.mjs')
+    || lower.endsWith('.spec.cjs')
+  );
+}
+
+function createSourceFingerprint(rootDir, discoveredFiles) {
+  const hash = crypto.createHash('sha256');
+  const normalizedEntries = discoveredFiles
+    .map((entry) => {
+      const filePath = normalizeRelative(rootDir, entry.absolutePath);
+      if (!filePath || filePath === '.' || filePath.startsWith('../') || path.isAbsolute(filePath)) {
+        return null;
+      }
+      return {
+        filePath,
+        mtimeMs: Number(entry.mtimeMs ?? -1),
+        size: Number(entry.size ?? -1),
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.filePath.localeCompare(b.filePath));
+
+  let newestMtimeMs = 0;
+  for (const entry of normalizedEntries) {
+    newestMtimeMs = Math.max(newestMtimeMs, entry.mtimeMs);
+    hash.update(entry.filePath);
+    hash.update('\0');
+    hash.update(String(entry.mtimeMs));
+    hash.update('\0');
+    hash.update(String(entry.size));
+    hash.update('\n');
+  }
+
+  return {
+    fileCount: normalizedEntries.length,
+    newestMtimeMs,
+    digest: hash.digest('base64url'),
+  };
+}
+
+function areSourceFingerprintsEqual(previousFingerprint, nextFingerprint) {
+  return previousFingerprint?.fileCount === nextFingerprint?.fileCount
+    && previousFingerprint?.newestMtimeMs === nextFingerprint?.newestMtimeMs
+    && previousFingerprint?.digest === nextFingerprint?.digest;
+}
+
+async function writeArtifact(rootDir, artifactName, payload) {
+  const artifactPath = getArtifactPath(rootDir, artifactName);
+  await fs.writeFile(artifactPath, JSON.stringify(payload, null, 2));
+}
+
+async function readArtifactIfExists(rootDir, artifactName) {
+  try {
+    const artifactPath = getArtifactPath(rootDir, artifactName);
+    const raw = await fs.readFile(artifactPath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function groupBy(items, keyFn) {
+  const map = new Map();
+  for (const item of items) {
+    const key = keyFn(item);
+    if (!map.has(key)) {
+      map.set(key, []);
+    }
+    map.get(key).push(item);
+  }
+  return map;
+}
+
+function dedupeBy(list, keyFn) {
+  const seen = new Set();
+  const result = [];
+
+  for (const item of list) {
+    const key = keyFn(item);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    result.push(item);
+  }
+
+  return result;
+}
+
+function haveStableTrackedFileIdentities(previousRecords, nextRecords) {
+  if (previousRecords.length !== nextRecords.length) {
+    return false;
+  }
+
+  return previousRecords.every((record, index) => {
+    const nextRecord = nextRecords[index];
+    return nextRecord
+      && record?.filePath === nextRecord.filePath
+      && record?.ext === nextRecord.ext;
+  });
+}
+
+function areStringArraysEqual(previousValues, nextValues) {
+  if (!Array.isArray(previousValues) || !Array.isArray(nextValues)) {
+    return false;
+  }
+
+  if (previousValues.length !== nextValues.length) {
+    return false;
+  }
+
+  return previousValues.every((value, index) => value === nextValues[index]);
+}
+
+function arePathSnapshotsEqual(previousSnapshot, nextSnapshot) {
+  if (!Array.isArray(previousSnapshot) || !Array.isArray(nextSnapshot)) {
+    return false;
+  }
+
+  if (previousSnapshot.length !== nextSnapshot.length) {
+    return false;
+  }
+
+  return previousSnapshot.every((entry, index) => {
+    const nextEntry = nextSnapshot[index];
+    return nextEntry
+      && entry?.filePath === nextEntry.filePath
+      && entry?.exists === nextEntry.exists
+      && entry?.size === nextEntry.size
+      && entry?.mtimeMs === nextEntry.mtimeMs;
+  });
+}
+
+function areFileRecordSnapshotsEqual(previousRecords, nextRecords) {
+  if (previousRecords.length !== nextRecords.length) {
+    return false;
+  }
+
+  return previousRecords.every((record, index) => {
+    const nextRecord = nextRecords[index];
+    return nextRecord
+      && record?.filePath === nextRecord.filePath
+      && record?.domain === nextRecord.domain
+      && record?.ext === nextRecord.ext
+      && Number(record?.mtimeMs ?? -1) === Number(nextRecord.mtimeMs ?? -1)
+      && Number(record?.size ?? -1) === Number(nextRecord.size ?? -1);
+  });
+}
+
+// ── Index V2: Archetype Classification ──
+
+const ARCHETYPE_RULES = [
+  // Test (check first)
+  { pattern: /(?:^|\/)(?:__tests__|test|tests|spec|specs)\//, archetype: 'test' },
+  // FE page subtypes
+  { pattern: /(?:^|\/)pages\/.*(?:List|list)\b/, archetype: 'list-page' },
+  { pattern: /(?:^|\/)pages\/.*(?:Detail|detail|View|view)\b/, archetype: 'detail-page' },
+  { pattern: /(?:^|\/)pages\/.*(?:Form|form|Edit|edit|Create|create|Add|add)\b/, archetype: 'form-page' },
+  { pattern: /(?:^|\/)pages\/|^app\.vue$|^layouts\//, archetype: 'page' },
+  // FE component subtypes
+  { pattern: /(?:^|\/)components\/.*(?:Modal|modal|Popup|popup|Dialog|dialog)\b/, archetype: 'modal' },
+  { pattern: /(?:^|\/)components\/.*(?:Grid|grid|Table|table)\b/, archetype: 'grid' },
+  { pattern: /(?:^|\/)components\//, archetype: 'component' },
+  // Composables / hooks
+  { pattern: /(?:^|\/)composables\/|^use[A-Z]/, archetype: 'composable' },
+  { pattern: /(?:^|\/)hooks\//, archetype: 'hook' },
+  // API / service layers
+  { pattern: /(?:^|\/)(?:api|apis?|services?)\//, archetype: 'api' },
+  // Store / state
+  { pattern: /(?:^|\/)store(?:s)?\//, archetype: 'store' },
+  // Utils / helpers
+  { pattern: /(?:^|\/)(?:utils?|helpers?)\//, archetype: 'util' },
+  // Middleware
+  { pattern: /(?:^|\/)middleware\//, archetype: 'middleware' },
+  // Layout
+  { pattern: /(?:^|\/)layouts?\//, archetype: 'layout' },
+  // Config
+  { pattern: /(?:^|\/)(?:config|conf|settings)\./, archetype: 'config' },
+  // Migration
+  { pattern: /(?:^|\/)migrations?\//, archetype: 'migration' },
+  // Schema / model
+  { pattern: /(?:^|\/)(?:models?|schemas?)\//, archetype: 'schema' },
+];
+
+function classifyArchetypes(fileRecords, symbols) {
+  const symbolNamesByPath = groupBy(symbols, (s) => s.filePath);
+
+  return fileRecords
+    .filter((f) => CODE_EXTENSIONS.has(f.ext))
+    .map((file) => {
+      if (isLikelyTestFile(file.filePath)) {
+        return {
+          filePath: file.filePath,
+          archetype: 'test',
+        };
+      }
+
+      let archetype = null;
+
+      for (const rule of ARCHETYPE_RULES) {
+        if (rule.pattern.test(file.filePath)) {
+          archetype = rule.archetype;
+          break;
+        }
+      }
+
+      if (!archetype) {
+        const fileSymbols = symbolNamesByPath.get(file.filePath) ?? [];
+        const hasDefaultExport = fileSymbols.some((s) => s.name === 'default');
+        const hasComponentSignal = file.ext === '.vue'
+          || fileSymbols.some((s) =>
+            s.type === 'component-name'
+            || s.name.toLowerCase().includes('component')
+            || s.name.toLowerCase().includes('page'),
+          );
+
+        if ((hasDefaultExport || file.ext === '.vue') && hasComponentSignal) {
+          archetype = 'component';
+        } else {
+          archetype = 'other';
+        }
+      }
+
+      return {
+        filePath: file.filePath,
+        archetype,
+      };
+    });
+}
+
+// ── Index V2: Feature Relations ──
+
+function buildRelations(fileRecords, archetypes, testsMap, resolvedImportsBySource, resolvedStyleImportsBySource = new Map()) {
+  const archetypeMap = new Map(archetypes.map((a) => [a.filePath, a.archetype]));
+  const testsBySource = new Map((testsMap ?? []).map((t) => [t.sourceFile, t.tests ?? []]));
+  const codeFiles = fileRecords.filter((f) => CODE_EXTENSIONS.has(f.ext));
+  const featureDirByFile = new Map(codeFiles.map((file) => [file.filePath, getFeatureDir(file.filePath)]));
+  const siblingsByKey = groupBy(
+    codeFiles,
+    (file) => `${featureDirByFile.get(file.filePath)}::${archetypeMap.get(file.filePath) ?? 'other'}`,
+  );
+
+  return codeFiles.map((file) => {
+    const filePath = file.filePath;
+    const archetype = archetypeMap.get(filePath) ?? 'other';
+    const fileImports = [...(resolvedImportsBySource.get(filePath) ?? new Set())];
+    const styleImports = [...(resolvedStyleImportsBySource.get(filePath) ?? new Set())];
+    const featureDir = featureDirByFile.get(filePath) ?? '';
+
+    const relations = {};
+
+    for (const resolved of fileImports) {
+      const targetArchetype = archetypeMap.get(resolved) ?? guessArchetypeFromPath(resolved);
+      if (!targetArchetype) {
+        continue;
+      }
+
+      if (targetArchetype === 'component' || targetArchetype === 'modal' || targetArchetype === 'grid') {
+        relations.components ??= [];
+        if (!relations.components.includes(resolved)) {
+          relations.components.push(resolved);
+        }
+      } else if (targetArchetype === 'composable' || targetArchetype === 'hook') {
+        relations.composables ??= [];
+        if (!relations.composables.includes(resolved)) {
+          relations.composables.push(resolved);
+        }
+      } else if (targetArchetype === 'api' || targetArchetype === 'service') {
+        relations.services ??= [];
+        if (!relations.services.includes(resolved)) {
+          relations.services.push(resolved);
+        }
+      } else if (targetArchetype === 'store') {
+        relations.stores ??= [];
+        if (!relations.stores.includes(resolved)) {
+          relations.stores.push(resolved);
+        }
+      } else if (targetArchetype === 'util') {
+        relations.utils ??= [];
+        if (!relations.utils.includes(resolved)) {
+          relations.utils.push(resolved);
+        }
+      }
+    }
+
+    const relatedTests = testsBySource.get(filePath) ?? [];
+    if (relatedTests.length > 0) {
+      relations.tests = relatedTests;
+    }
+
+    if (styleImports.length > 0) {
+      relations.styles = styleImports;
+    }
+
+    const siblings = (siblingsByKey.get(`${featureDir}::${archetype}`) ?? [])
+      .filter((candidate) => candidate.filePath !== filePath)
+      .map((candidate) => candidate.filePath);
+    if (siblings.length > 0) {
+      relations.siblings = siblings;
+    }
+
+    const hasAnyRelation = Object.keys(relations).length > 0;
+    return {
+      filePath,
+      archetype,
+      ...(hasAnyRelation ? { relations } : {}),
+    };
+  });
+}
+
+function getFeatureDir(filePath) {
+  const parts = filePath.split('/');
+  // e.g., "src/pages/customer/List.vue" → "src/pages/customer"
+  // or "src/components/CustomerGrid.vue" → "src/components"
+  if (parts.length >= 3) {
+    return parts.slice(0, 3).join('/');
+  }
+  if (parts.length >= 2) {
+    return parts.slice(0, 2).join('/');
+  }
+  return parts[0] ?? '';
+}
+
+function guessArchetypeFromPath(filePath) {
+  for (const rule of ARCHETYPE_RULES) {
+    if (rule.pattern.test(filePath)) {
+      return rule.archetype;
+    }
+  }
+  return null;
+}
+
+// ── Index V2: Analog Candidates ──
+
+const ANALOG_RELATION_TYPES = ['components', 'composables', 'services'];
+
+function buildAnalogs(fileRecords, archetypes, relations, resolvedImportsByFile) {
+  const archetypeMap = new Map(archetypes.map((a) => [a.filePath, a.archetype]));
+  const codeFiles = fileRecords.filter((f) => CODE_EXTENSIONS.has(f.ext));
+  const relationLookupByFile = new Map(
+    relations.map((relation) => [relation.filePath, buildAnalogRelationLookup(relation.relations ?? {})]),
+  );
+  const descriptors = codeFiles.map((file) => buildAnalogDescriptor({
+    filePath: file.filePath,
+    archetype: archetypeMap.get(file.filePath) ?? 'other',
+    imports: resolvedImportsByFile.get(file.filePath) ?? new Set(),
+    relationLookup: relationLookupByFile.get(file.filePath) ?? buildAnalogRelationLookup(),
+  }));
+  const analogIndexesByArchetype = buildAnalogIndexes(descriptors);
+
+  return descriptors.map((descriptor) => {
+    const analogIndex = analogIndexesByArchetype.get(descriptor.archetype) ?? createEmptyAnalogIndex();
+    const candidateScores = new Map();
+
+    for (const importPath of descriptor.imports) {
+      accumulateAnalogCandidates({
+        candidatePaths: analogIndex.byImport.get(importPath),
+        selfPath: descriptor.filePath,
+        candidateScores,
+        scoreDelta: 3,
+        applyReason: (candidate) => candidate.sharedImports.add(importPath),
+      });
+    }
+
+    if (descriptor.featureDir) {
+      accumulateAnalogCandidates({
+        candidatePaths: analogIndex.byFeatureDir.get(descriptor.featureDir),
+        selfPath: descriptor.filePath,
+        candidateScores,
+        scoreDelta: 2,
+        applyReason: (candidate) => {
+          candidate.sameFeatureDir = true;
+        },
+      });
+    }
+
+    for (const relType of ANALOG_RELATION_TYPES) {
+      for (const target of descriptor.relationLookup[relType]) {
+        accumulateAnalogCandidates({
+          candidatePaths: analogIndex.byRelationTarget.get(`${relType}:${target}`),
+          selfPath: descriptor.filePath,
+          candidateScores,
+          scoreDelta: 2,
+          applyReason: (candidate) => {
+            candidate.sharedRelations[relType].add(target);
+          },
+        });
+      }
+    }
+
+    if (descriptor.namePrefix3.length >= 3) {
+      accumulateAnalogCandidates({
+        candidatePaths: analogIndex.byNamePrefix.get(descriptor.namePrefix3),
+        selfPath: descriptor.filePath,
+        candidateScores,
+        scoreDelta: 1,
+        applyReason: (candidate) => {
+          candidate.namePrefix = descriptor.namePrefix3;
+        },
+      });
+    }
+
+    const analogs = [...candidateScores.entries()]
+      .map(([filePath, candidate]) => ({
+        filePath,
+        score: Math.min(candidate.score / 10, 1),
+        reason: formatAnalogReasons(candidate),
+      }))
+      .filter((candidate) => candidate.reason)
+      .sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath))
+      .slice(0, 5);
+
+    return {
+      filePath: descriptor.filePath,
+      archetype: descriptor.archetype,
+      analogs,
+    };
+  });
+}
+
+function buildAnalogDescriptor({ filePath, archetype, imports, relationLookup }) {
+  const baseName = path.basename(filePath, path.extname(filePath)).toLowerCase();
+
+  return {
+    filePath,
+    archetype,
+    featureDir: getFeatureDir(filePath),
+    imports,
+    relationLookup,
+    namePrefix3: baseName.slice(0, 3),
+  };
+}
+
+function buildAnalogIndexes(descriptors) {
+  const indexesByArchetype = new Map();
+
+  for (const descriptor of descriptors) {
+    let analogIndex = indexesByArchetype.get(descriptor.archetype);
+    if (!analogIndex) {
+      analogIndex = createEmptyAnalogIndex();
+      indexesByArchetype.set(descriptor.archetype, analogIndex);
+    }
+
+    for (const importPath of descriptor.imports) {
+      indexAnalogValue(analogIndex.byImport, importPath, descriptor.filePath);
+    }
+
+    if (descriptor.featureDir) {
+      indexAnalogValue(analogIndex.byFeatureDir, descriptor.featureDir, descriptor.filePath);
+    }
+
+    for (const relType of ANALOG_RELATION_TYPES) {
+      for (const target of descriptor.relationLookup[relType]) {
+        indexAnalogValue(analogIndex.byRelationTarget, `${relType}:${target}`, descriptor.filePath);
+      }
+    }
+
+    if (descriptor.namePrefix3.length >= 3) {
+      indexAnalogValue(analogIndex.byNamePrefix, descriptor.namePrefix3, descriptor.filePath);
+    }
+  }
+
+  return indexesByArchetype;
+}
+
+function createEmptyAnalogIndex() {
+  return {
+    byImport: new Map(),
+    byFeatureDir: new Map(),
+    byRelationTarget: new Map(),
+    byNamePrefix: new Map(),
+  };
+}
+
+function indexAnalogValue(indexMap, key, filePath) {
+  if (!key) {
+    return;
+  }
+
+  if (!indexMap.has(key)) {
+    indexMap.set(key, new Set());
+  }
+  indexMap.get(key).add(filePath);
+}
+
+function buildAnalogRelationLookup(relations = {}) {
+  return {
+    components: new Set(relations.components ?? []),
+    composables: new Set(relations.composables ?? []),
+    services: new Set(relations.services ?? []),
+  };
+}
+
+function accumulateAnalogCandidates({
+  candidatePaths,
+  selfPath,
+  candidateScores,
+  scoreDelta,
+  applyReason,
+}) {
+  if (!candidatePaths) {
+    return;
+  }
+
+  for (const candidatePath of candidatePaths) {
+    if (candidatePath === selfPath) {
+      continue;
+    }
+
+    if (!candidateScores.has(candidatePath)) {
+      candidateScores.set(candidatePath, {
+        score: 0,
+        sharedImports: new Set(),
+        sameFeatureDir: false,
+        sharedRelations: buildAnalogRelationLookup(),
+        namePrefix: '',
+      });
+    }
+
+    const candidate = candidateScores.get(candidatePath);
+    candidate.score += scoreDelta;
+    applyReason(candidate);
+  }
+}
+
+function formatAnalogReasons(candidate) {
+  const reasons = [];
+
+  if (candidate.sharedImports.size > 0) {
+    reasons.push(`shared imports: ${[...candidate.sharedImports].slice(0, 3).join(', ')}`);
+  }
+  if (candidate.sameFeatureDir) {
+    reasons.push('same feature dir');
+  }
+  for (const relType of ANALOG_RELATION_TYPES) {
+    const sharedTargets = [...candidate.sharedRelations[relType]];
+    if (sharedTargets.length > 0) {
+      reasons.push(`shared ${relType}: ${sharedTargets.join(', ')}`);
+    }
+  }
+  if (candidate.namePrefix) {
+    reasons.push(`similar name prefix: ${candidate.namePrefix}`);
+  }
+
+  return reasons.join('; ');
+}
+
+function buildResolvedImportMap(rootDir, imports, indexedFileSet, importAliasContext) {
+  const resolvedImportsBySource = new Map();
+
+  for (const imp of imports) {
+    if (!imp?.from || !imp?.to) {
+      continue;
+    }
+
+    const resolved = resolveImportSpecifier({
+      rootDir,
+      fromFilePath: imp.from,
+      specifier: imp.to,
+      indexedFileSet,
+      aliasContext: importAliasContext,
+    });
+    if (!resolved) {
+      continue;
+    }
+
+    if (!resolvedImportsBySource.has(imp.from)) {
+      resolvedImportsBySource.set(imp.from, new Set());
+    }
+    resolvedImportsBySource.get(imp.from).add(resolved);
+  }
+
+  return resolvedImportsBySource;
+}
+
+function scoreTestMatch(sourceFilePath, testFilePath) {
+  const sourcePathLower = sourceFilePath.toLowerCase();
+  const testPathLower = testFilePath.toLowerCase();
+  const sourceBase = path.basename(sourcePathLower, path.extname(sourcePathLower));
+  const sourceParentDir = path.posix.basename(path.posix.dirname(sourcePathLower));
+  const sourceStem = sourceBase === 'index' ? sourceParentDir : sourceBase;
+  const testBase = path.basename(testPathLower, path.extname(testPathLower));
+  const testStem = normalizeTestStem(testBase);
+
+  let score = 0;
+
+  if (testStem === sourceStem) {
+    score += 100;
+  }
+  if (testPathLower.includes(`/${sourceStem}.`) || testPathLower.includes(`/${sourceStem}/`)) {
+    score += 50;
+  }
+  if (sourceBase === 'index' && testStem === 'index' && testPathLower.includes(`/${sourceParentDir}/`)) {
+    score += 90;
+  }
+  if (sourceBase === 'index' && testStem === sourceParentDir) {
+    score += 80;
+  }
+  if (
+    sourceStem.length >= 4
+    && testStem !== sourceStem
+    && (testStem.includes(sourceStem) || sourceStem.includes(testStem))
+  ) {
+    score += 20;
+  }
+
+  return score;
+}
+
+function normalizeTestStem(testBase) {
+  return testBase
+    .replace(/(?:\.test|\.spec)+$/g, '')
+    .replace(/[-_.](test|spec)$/g, '')
+    .toLowerCase();
+}
+
+function parseArtifactGeneratedAt(artifact) {
+  const generatedAtRaw = String(artifact?.generatedAt ?? '').trim();
+
+  if (!generatedAtRaw) {
+    return null;
+  }
+
+  const generatedAtMs = Date.parse(generatedAtRaw);
+  if (Number.isNaN(generatedAtMs)) {
+    return null;
+  }
+
+  return generatedAtMs;
+}
+
+export async function getIndexArtifactGeneratedAt({
+  rootDir = process.cwd(),
+  artifactName = INDEX_ARTIFACTS.files,
+} = {}) {
+  const absoluteRoot = path.resolve(rootDir);
+  if (artifactName === INDEX_ARTIFACTS.files || artifactName === INDEX_ARTIFACTS.meta) {
+    const metaArtifact = await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.meta);
+    const metaGeneratedAtMs = parseArtifactGeneratedAt(metaArtifact);
+    if (metaGeneratedAtMs !== null) {
+      return metaGeneratedAtMs;
+    }
+  }
+
+  const artifact = await readArtifactIfExists(absoluteRoot, artifactName);
+  return parseArtifactGeneratedAt(artifact);
+}
+
+export async function isIndexStale({
+  rootDir = process.cwd(),
+  maxAgeMs = DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  now = Date.now(),
+  generatedAtMs = null,
+} = {}) {
+  const absoluteRoot = path.resolve(rootDir);
+  const metaArtifact = await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.meta);
+  const effectiveGeneratedAtMs = Number.isFinite(generatedAtMs)
+    ? generatedAtMs
+    : parseArtifactGeneratedAt(metaArtifact);
+  if (effectiveGeneratedAtMs === null) {
+    return true;
+  }
+
+  if (typeof maxAgeMs !== 'number' || Number.isNaN(maxAgeMs) || maxAgeMs < 0) {
+    return true;
+  }
+
+  if ((now - effectiveGeneratedAtMs) >= maxAgeMs) {
+    return true;
+  }
+
+  if (!metaArtifact?.sourceFingerprint) {
+    return true;
+  }
+
+  const currentSourceFingerprint = createSourceFingerprint(
+    absoluteRoot,
+    await collectFiles(await resolveScanRoots(absoluteRoot)),
+  );
+  return !areSourceFingerprintsEqual(metaArtifact.sourceFingerprint, currentSourceFingerprint);
+}