@ngockhoale/ukit 1.1.6

package/templates/.claude/ukit/index/lib/index-core.mjs

@@ -0,0 +1,2800 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+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]);
+const INDEX_SCHEMA_VERSION = 6;
+export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const INDEX_PARSE_BATCH_SIZE = 8;
+const MAX_IMPORTER_HOPS = 2;
+
+export const INDEX_ARTIFACTS = {
+  meta: 'meta.json',
+  files: 'files.json',
+  symbols: 'symbols.json',
+  imports: 'imports.json',
+  testsMap: 'tests-map.json',
+  hotspots: 'hotspots.json',
+  archetypes: 'archetypes.json',
+  relations: 'relations.json',
+  analogs: 'analogs.json',
+};
+
+export function getIndexDir(rootDir) {
+  return path.join(rootDir, '.cache', 'index');
+}
+
+function getArtifactPath(rootDir, artifactName) {
+  return path.join(getIndexDir(rootDir), artifactName);
+}
+
+function normalizeRelative(rootDir, absolutePath) {
+  return path.relative(rootDir, absolutePath).replace(/\\/g, '/');
+}
+
+const ARTIFACT_CACHE = new Map();
+const QUERY_SEARCH_BUNDLE_CACHE = new Map();
+const QUERY_SUPPORT_BUNDLE_CACHE = new Map();
+const QUERY_RESULT_CACHE = new Map();
+const ANALOG_RESULT_CACHE = new Map();
+const RELATED_TEST_LOOKUP_CACHE = new Map();
+const RESOLUTION_SUFFIXES = ['', '.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs', '.vue', '/index.js', '/index.ts', '/index.jsx', '/index.tsx', '/index.mjs', '/index.cjs', '/index.vue'];
+const DEFAULT_ALIAS_RULES = [
+  { pattern: '@/*', targets: ['src/*', '*'] },
+  { pattern: '~/*', targets: ['*', 'src/*'] },
+];
+const ALIAS_CONTEXT_CACHE = new Map();
+const ROOT_ALIAS_CONFIG_FILES = ['tsconfig.json', 'jsconfig.json'];
+const GENERIC_STOPWORDS = new Set([
+  'a', 'an', 'and', 'as', 'at', 'be', 'by', 'do', 'for', 'from', 'help', 'i', 'in', 'into',
+  'is', 'it', 'me', 'my', 'of', 'on', 'or', 'please', 'the', 'this', 'that', 'to', 'with',
+  'ban', 'cho', 'cua', 'di', 'dung', 'giup', 'hay', 'khong', 'la', 'lam', 'luon', 'mot', 'nay',
+  'neu', 'nhung', 'nua', 'roi', 'toi', 'tren', 'truoc', 'va', 'voi',
+]);
+const VIETNAMESE_PHRASE_ALIASES = [
+  { regex: /\bbo nho dem\b/gu, expansions: ['cache'] },
+  { regex: /\bduong dan\b/gu, expansions: ['route', 'path'] },
+  { regex: /\bxac thuc\b/gu, expansions: ['auth', 'authentication'] },
+  { regex: /\bdang nhap\b/gu, expansions: ['login', 'signin', 'auth'] },
+  { regex: /\bquyen truy cap\b/gu, expansions: ['permission', 'access'] },
+  { regex: /\bkiem tra\b/gu, expansions: ['review', 'check', 'verify'] },
+  { regex: /\bbao mat\b/gu, expansions: ['security'] },
+  { regex: /\bco so du lieu\b/gu, expansions: ['database'] },
+  { regex: /\btai lieu\b/gu, expansions: ['docs', 'documentation'] },
+  { regex: /\bgiao dien\b/gu, expansions: ['ui', 'interface', 'frontend'] },
+  { regex: /\bthanh phan\b/gu, expansions: ['component'] },
+  { regex: /\bkiem thu\b/gu, expansions: ['test', 'testing'] },
+  { regex: /\bbo cuc\b/gu, expansions: ['layout'] },
+];
+const VIETNAMESE_TOKEN_ALIASES = new Map([
+  ['sua', ['fix']],
+  ['loi', ['bug', 'error']],
+  ['them', ['add']],
+  ['xoa', ['delete', 'remove']],
+  ['quyen', ['permission', 'access']],
+  ['token', ['token']],
+  ['cache', ['cache']],
+  ['route', ['route', 'path']],
+  ['path', ['path', 'route']],
+  ['helper', ['helper']],
+  ['docker', ['docker']],
+  ['compose', ['compose']],
+  ['page', ['page']],
+  ['component', ['component']],
+  ['test', ['test', 'testing']],
+  ['soat', ['review', 'audit']],
+  ['trien', ['implement', 'build', 'ship']],
+  ['khai', ['implement', 'build', 'ship']],
+]);
+
+// ── Build Index ──
+
+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);
+      return {
+        filePath,
+        domain: filePath.split('/')[0] ?? 'other',
+        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((f) => CODE_EXTENSIONS.has(f.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, items: fileRecords });
+  }
+  if (!canReuseAllParsedArtifacts) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.symbols, { schemaVersion: INDEX_SCHEMA_VERSION, generatedAt, items: symbols });
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.imports, { schemaVersion: INDEX_SCHEMA_VERSION, generatedAt, items: imports });
+  }
+  if (!canReuseTestsMap) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.testsMap, { schemaVersion: INDEX_SCHEMA_VERSION, generatedAt, items: testsMap });
+  }
+  if (!canReuseHotspots) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.hotspots, { schemaVersion: INDEX_SCHEMA_VERSION, generatedAt, sourceSnapshot: bugIndexSnapshot, items: hotspots });
+  }
+  if (!canReuseArchetypes) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.archetypes, { schemaVersion: INDEX_SCHEMA_VERSION, generatedAt, items: archetypes });
+  }
+  if (!canReuseRelations) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.relations, { schemaVersion: INDEX_SCHEMA_VERSION, generatedAt, sourceSnapshot: styleSnapshot, items: relations });
+  }
+  if (!canReuseAnalogs) {
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.analogs, { schemaVersion: INDEX_SCHEMA_VERSION, generatedAt, sourceSnapshot: styleSnapshot, items: analogs });
+  }
+  await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.meta, { schemaVersion: INDEX_SCHEMA_VERSION, generatedAt, sourceFingerprint });
+  const preservedRuntimeCaches = canReuseFilesArtifact
+    && canReuseAllParsedArtifacts
+    && canReuseTestsMap
+    && canReuseHotspots
+    && canReuseArchetypes
+    && canReuseRelations
+    && canReuseAnalogs;
+  if (!preservedRuntimeCaches) {
+    clearIndexArtifactCache(absoluteRoot);
+    RELATED_TEST_LOOKUP_CACHE.delete(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,
+  };
+}
+
+// ── Query Index ──
+
+export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5 } = {}) {
+  if (!query || !query.trim()) return [];
+  if (limit <= 0) return Object.freeze([]);
+
+  const absoluteRoot = path.resolve(rootDir);
+  const normalizedQuery = String(query).trim();
+  const queryDescriptor = buildSearchDescriptor(normalizedQuery, { expandVietnameseAliases: true });
+  if (queryDescriptor.tokens.size === 0) return Object.freeze([]);
+  const queryCacheKey = JSON.stringify({
+    rootDir: absoluteRoot,
+    query: normalizedQuery,
+    limit,
+  });
+  if (QUERY_RESULT_CACHE.has(queryCacheKey)) {
+    return QUERY_RESULT_CACHE.get(queryCacheKey);
+  }
+  const queryPromise = (async () => {
+    const { files, searchDescriptorsByFile } = await loadQuerySearchBundle(absoluteRoot);
+    const preferredArchetypes = inferPreferredArchetypes(queryDescriptor.tokens);
+    const includeLikelyTestFiles = shouldIncludeLikelyTestFiles(queryDescriptor);
+
+    const directScores = new Map();
+    for (const file of files.items ?? []) {
+      const filePath = file.filePath;
+      if (isLikelyTestFilePath(filePath) && !includeLikelyTestFiles) continue;
+      const searchDescriptor = searchDescriptorsByFile.get(filePath) ?? createFileSearchDescriptor({ filePath, symbols: [] });
+      const { score, reasons } = scoreDirectFileMatch({
+        queryDescriptor,
+        filePath,
+        searchDescriptor,
+      });
+
+      if (score > 0) {
+        directScores.set(filePath, { filePath, score, reasons: [...new Set(reasons)] });
+      }
+    }
+
+    if (directScores.size === 0) return Object.freeze([]);
+
+    const {
+      hotspotScores,
+      testsMapBySource: testsBySource,
+      resolvedImportsBySource,
+      importersByTarget,
+      archetypeByFile,
+    } = await loadQuerySupportBundle(absoluteRoot);
+
+    const enrichedDirectScores = new Map();
+    for (const [filePath, entry] of directScores) {
+      let score = entry.score;
+      const reasons = [...(entry.reasons ?? [])];
+      const archetype = archetypeByFile.get(filePath) ?? 'other';
+      if (preferredArchetypes.has(archetype)) {
+        score += 4;
+        reasons.push(`archetype_hint:${archetype}`);
+      }
+
+      enrichedDirectScores.set(filePath, {
+        filePath,
+        score,
+        reasons: [...new Set(reasons)],
+        tests: testsBySource.get(filePath) ?? [],
+      });
+    }
+
+    const relatedScores = applyImportGraphBoosts({
+      directScores: enrichedDirectScores,
+      resolvedImportsBySource,
+      importersByTarget,
+      testsMapBySource: testsBySource,
+    });
+    const boosted = applyHotspotBoosts({ scores: relatedScores, hotspotScores });
+    return freezeQueryResults(
+      [...boosted.values()].sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath)).slice(0, limit),
+    );
+  })().catch((error) => {
+    QUERY_RESULT_CACHE.delete(queryCacheKey);
+    throw error;
+  });
+
+  QUERY_RESULT_CACHE.set(queryCacheKey, queryPromise);
+  return queryPromise;
+}
+
+// ── Analog Query ──
+
+export async function queryAnalog({ rootDir = process.cwd(), filePath, limit = 5 } = {}) {
+  if (!filePath || !filePath.trim()) return [];
+
+  const absoluteRoot = path.resolve(rootDir);
+  const normalizedFilePath = String(filePath).trim();
+  const analogCacheKey = JSON.stringify({
+    rootDir: absoluteRoot,
+    filePath: normalizedFilePath,
+    limit,
+  });
+  if (ANALOG_RESULT_CACHE.has(analogCacheKey)) {
+    return ANALOG_RESULT_CACHE.get(analogCacheKey);
+  }
+  const analogPromise = readArtifact(absoluteRoot, INDEX_ARTIFACTS.analogs)
+    .then((analogs) => {
+      const safeAnalogs = ensureArtifact(analogs);
+      const entry = (safeAnalogs.items ?? []).find((item) => item.filePath === normalizedFilePath);
+      if (!entry) return Object.freeze([]);
+      return freezeAnalogResults(entry.analogs?.slice(0, limit) ?? []);
+    })
+    .catch((error) => {
+      ANALOG_RESULT_CACHE.delete(analogCacheKey);
+      throw error;
+    });
+
+  ANALOG_RESULT_CACHE.set(analogCacheKey, analogPromise);
+  return analogPromise;
+}
+
+export function clearIndexArtifactCache(rootDir = null) {
+  if (!rootDir) {
+    ARTIFACT_CACHE.clear();
+    QUERY_SEARCH_BUNDLE_CACHE.clear();
+    QUERY_SUPPORT_BUNDLE_CACHE.clear();
+    QUERY_RESULT_CACHE.clear();
+    ANALOG_RESULT_CACHE.clear();
+    RELATED_TEST_LOOKUP_CACHE.clear();
+    return;
+  }
+
+  const absoluteRoot = path.resolve(rootDir);
+  const indexDir = getIndexDir(absoluteRoot);
+
+  for (const artifactPath of ARTIFACT_CACHE.keys()) {
+    if (artifactPath.startsWith(indexDir)) {
+      ARTIFACT_CACHE.delete(artifactPath);
+    }
+  }
+
+  QUERY_SEARCH_BUNDLE_CACHE.delete(absoluteRoot);
+  QUERY_SUPPORT_BUNDLE_CACHE.delete(absoluteRoot);
+  for (const cacheKey of QUERY_RESULT_CACHE.keys()) {
+    if (cacheKey.includes(`"rootDir":"${escapeJsonString(absoluteRoot)}"`)) {
+      QUERY_RESULT_CACHE.delete(cacheKey);
+    }
+  }
+  for (const cacheKey of ANALOG_RESULT_CACHE.keys()) {
+    if (cacheKey.includes(`"rootDir":"${escapeJsonString(absoluteRoot)}"`)) {
+      ANALOG_RESULT_CACHE.delete(cacheKey);
+    }
+  }
+  RELATED_TEST_LOOKUP_CACHE.delete(absoluteRoot);
+}
+
+function freezeQueryResults(results) {
+  return Object.freeze(
+    results.map((item) => Object.freeze({
+      ...item,
+      reasons: Object.freeze([...(item.reasons ?? [])]),
+      tests: Object.freeze([...(item.tests ?? [])]),
+    })),
+  );
+}
+
+function freezeAnalogResults(results) {
+  return Object.freeze(results.map((item) => Object.freeze({ ...item })));
+}
+
+function ensureArtifact(artifact) {
+  return artifact && typeof artifact === 'object' ? artifact : { items: [] };
+}
+
+function escapeJsonString(value) {
+  return String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+}
+
+// ── Context Resolver ──
+
+const TASK_TYPE_BUDGETS = {
+  trivial: { minFiles: 1, maxFiles: 2 },
+  simple: { minFiles: 2, maxFiles: 5 },
+  'non-trivial': { minFiles: 4, maxFiles: 8 },
+};
+
+const TRIVIAL_SIGNALS = ['typo', 'label', 'text', 'rename', 'color', 'spacing', 'toggle', 'config', 'comment'];
+const RISKY_SIGNALS = [
+  'auth', 'security', 'migration', 'uninstall', 'password', 'token', 'permission',
+  'delete all', 'drop table', 'race', 'flaky', 'intermittent', 'timeout', 'deadlock',
+  'core', 'shared', 'runtime',
+];
+const EXPANSION_SIGNALS = [
+  'similar',
+  'same as',
+  'like',
+  'pattern',
+  'clone',
+  'analog',
+  'follow',
+  'example',
+  'search',
+  'find',
+  'where',
+  'which file',
+  'across',
+  'everywhere',
+  'multiple',
+  'project',
+  'repo',
+  'workspace',
+  'all ',
+  'every ',
+];
+
+export async function resolveContext({
+  rootDir = process.cwd(),
+  intent = '',
+  targetFile = null,
+  taskType = null,
+} = {}) {
+  const classifiedType = taskType ?? classifyTask(intent);
+  const budget = TASK_TYPE_BUDGETS[classifiedType] ?? TASK_TYPE_BUDGETS.simple;
+  const queryWasUsed = shouldQueryIndex({ intent, targetFile, taskType: classifiedType });
+
+  const result = {
+    taskType: classifiedType,
+    contextBudget: { ...budget, taskType: classifiedType },
+    primaryTargets: [],
+    analogFiles: [],
+    sharedAbstractions: [],
+    relatedTests: [],
+    styleFiles: [],
+    explanations: {
+      primaryTargets: [],
+      analogFiles: [],
+      sharedAbstractions: [],
+      relatedTests: [],
+      styleFiles: [],
+    },
+  };
+
+  if (targetFile) {
+    addExplainedFile(result, 'primaryTargets', targetFile, 'explicit target');
+  }
+
+  if (queryWasUsed) {
+    const queryResults = await queryCodeIndex({ rootDir, query: intent, limit: budget.maxFiles });
+    for (const qr of queryResults) {
+      addExplainedFile(result, 'primaryTargets', qr.filePath, buildQueryReason(qr));
+    }
+  }
+
+  if (result.primaryTargets.length === 0) {
+    return result;
+  }
+
+  const { relationsArtifact, relationsMap } = await loadRelatedTestArtifacts({
+    rootDir,
+    analogsArtifact: { items: [] },
+  });
+
+  for (const primary of result.primaryTargets) {
+    const rels = relationsMap.get(primary) ?? {};
+    for (const testPath of rels.tests ?? []) {
+      addExplainedFile(result, 'relatedTests', testPath, `test linked to ${primary}`);
+    }
+    for (const stylePath of rels.styles ?? []) {
+      addExplainedFile(result, 'styleFiles', stylePath, `style imported by ${primary}`);
+    }
+  }
+
+  const preferLocalizedDirectContext = shouldPreferLocalizedDirectTargetContext({
+    result,
+    taskType: classifiedType,
+    targetFile,
+    queryWasUsed,
+  });
+
+  if (!preferLocalizedDirectContext) {
+    for (const primary of result.primaryTargets) {
+      const rels = relationsMap.get(primary) ?? {};
+      for (const absType of ['composables', 'utils', 'services']) {
+        for (const absPath of rels[absType] ?? []) {
+          if (result.primaryTargets.includes(absPath)) continue;
+          addExplainedFile(result, 'sharedAbstractions', absPath, `related ${absType} used by ${primary}`);
+        }
+      }
+    }
+
+    const inferredTests = inferRelatedTestsFromArtifacts({
+      candidateFiles: result.primaryTargets,
+      analogsMap: new Map(),
+      relationsMap,
+      limit: budget.maxFiles,
+    });
+
+    for (const inferredTest of inferredTests) {
+      addExplainedFile(result, 'relatedTests', inferredTest.filePath, inferredTest.reason);
+    }
+  }
+
+  if (shouldLoadAnalogArtifacts({
+    result,
+    taskType: classifiedType,
+    targetFile,
+    maxFiles: budget.maxFiles,
+    queryWasUsed,
+    preferLocalizedDirectContext,
+  })) {
+    const { analogsMap } = await loadRelatedTestArtifacts({
+      rootDir,
+      relationsArtifact,
+    });
+
+    for (const primary of result.primaryTargets.slice(0, 2)) {
+      const analogs = analogsMap.get(primary) ?? [];
+      for (const analog of analogs.slice(0, 3)) {
+        if (result.primaryTargets.includes(analog.filePath)) continue;
+        addExplainedFile(
+          result,
+          'analogFiles',
+          analog.filePath,
+          `analog of ${primary}${analog.reason ? `; ${analog.reason}` : ''}`,
+        );
+      }
+    }
+
+    const inferredAnalogTests = inferRelatedTestsFromArtifacts({
+      candidateFiles: result.primaryTargets,
+      analogsMap,
+      relationsMap,
+      limit: budget.maxFiles,
+    });
+
+    for (const inferredTest of inferredAnalogTests) {
+      addExplainedFile(result, 'relatedTests', inferredTest.filePath, inferredTest.reason);
+    }
+  }
+
+  enforceContextBudget(result, budget.maxFiles);
+  includeDirectTestTargets(result);
+
+  return result;
+}
+
+export function classifyTask(intent) {
+  const lower = intent.toLowerCase();
+
+  if (RISKY_SIGNALS.some((signal) => lower.includes(signal))) {
+    return 'non-trivial';
+  }
+
+  if (TRIVIAL_SIGNALS.some((signal) => lower.includes(signal))) {
+    if (lower.includes('all ') || lower.includes('every ') || lower.includes('multiple')) {
+      return 'simple';
+    }
+    return 'trivial';
+  }
+
+  return 'simple';
+}
+
+function shouldQueryIndex({
+  intent = '',
+  targetFile = null,
+  taskType = 'simple',
+} = {}) {
+  const normalizedIntent = String(intent || '').trim().toLowerCase();
+  if (!normalizedIntent) {
+    return false;
+  }
+  if (!targetFile) {
+    return true;
+  }
+  if (taskType === 'non-trivial') {
+    return true;
+  }
+  return EXPANSION_SIGNALS.some((signal) => normalizedIntent.includes(signal));
+}
+
+function enforceContextBudget(result, maxFiles) {
+  const prioritizedGroups = [
+    'primaryTargets',
+    'relatedTests',
+    'styleFiles',
+    'sharedAbstractions',
+    'analogFiles',
+  ];
+  const kept = new Set();
+
+  for (const group of prioritizedGroups) {
+    const nextItems = [];
+    for (const item of result[group] ?? []) {
+      if (kept.size >= maxFiles) break;
+      if (kept.has(item)) continue;
+      kept.add(item);
+      nextItems.push(item);
+    }
+    result[group] = nextItems;
+    result.explanations[group] = (result.explanations[group] ?? [])
+      .filter((entry) => nextItems.includes(entry.filePath));
+  }
+}
+
+function addExplainedFile(result, group, filePath, reason) {
+  if (!result[group].includes(filePath)) {
+    result[group].push(filePath);
+  }
+
+  const explanations = result.explanations[group] ?? [];
+  const existing = explanations.find((entry) => entry.filePath === filePath);
+  if (!existing) {
+    explanations.push({ filePath, reason });
+    result.explanations[group] = explanations;
+    return;
+  }
+
+  if (!existing.reason.includes(reason)) {
+    existing.reason = `${existing.reason}; ${reason}`;
+  }
+}
+
+function shouldLoadAnalogArtifacts({
+  result,
+  taskType = 'simple',
+  targetFile = null,
+  maxFiles = 5,
+  queryWasUsed = false,
+  preferLocalizedDirectContext = false,
+} = {}) {
+  const selectedCount = countSelectedFiles(result);
+  if (selectedCount >= maxFiles) {
+    return false;
+  }
+
+  if (preferLocalizedDirectContext) {
+    return false;
+  }
+
+  if (
+    taskType === 'trivial'
+    && targetFile
+    && !queryWasUsed
+    && (result.relatedTests?.length ?? 0) > 0
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+function shouldPreferLocalizedDirectTargetContext({
+  result,
+  taskType = 'simple',
+  targetFile = null,
+  queryWasUsed = false,
+} = {}) {
+  if (queryWasUsed || !targetFile) {
+    return false;
+  }
+
+  if (taskType !== 'simple' && taskType !== 'trivial') {
+    return false;
+  }
+
+  return isTestLikeFile(targetFile)
+    || (result.relatedTests?.length ?? 0) > 0;
+}
+
+function countSelectedFiles(result) {
+  const selected = new Set();
+  for (const group of ['primaryTargets', 'relatedTests', 'styleFiles', 'sharedAbstractions', 'analogFiles']) {
+    for (const filePath of result[group] ?? []) {
+      selected.add(filePath);
+    }
+  }
+  return selected.size;
+}
+
+function buildQueryReason(queryResult) {
+  const reasons = queryResult.reasons ?? [];
+  if (reasons.length === 0) return 'query match';
+  return `query match: ${reasons.join(', ')}`;
+}
+
+function includeDirectTestTargets(result) {
+  for (const primaryTarget of result.primaryTargets ?? []) {
+    if (!isTestLikeFile(primaryTarget)) continue;
+    addExplainedFile(result, 'relatedTests', primaryTarget, `direct test target ${primaryTarget}`);
+  }
+}
+
+function isTestLikeFile(filePath) {
+  return /\.(test|spec)\.[a-z0-9]+$/i.test(filePath)
+    || /(^|\/)(?:__tests__|tests?|specs?)\//i.test(filePath);
+}
+
+const RELATED_TEST_RELATION_TYPES = [
+  { key: 'components', label: 'component' },
+  { key: 'composables', label: 'composable' },
+  { key: 'services', label: 'service' },
+  { key: 'stores', label: 'store' },
+  { key: 'utils', label: 'util' },
+];
+
+function buildRelatedTestLookups({
+  analogsArtifact = { items: [] },
+  relationsArtifact = { items: [] },
+} = {}) {
+  return {
+    analogsMap: new Map((analogsArtifact.items ?? []).map((item) => [item.filePath, item.analogs ?? []])),
+    relationsMap: new Map((relationsArtifact.items ?? []).map((item) => [item.filePath, item.relations ?? {}])),
+  };
+}
+
+function inferRelatedTestsFromArtifacts({
+  candidateFiles = [],
+  analogsMap = new Map(),
+  relationsMap = new Map(),
+  limit = 5,
+} = {}) {
+  const normalizedCandidates = [...new Set(
+    candidateFiles
+      .map((filePath) => String(filePath ?? '').trim())
+      .filter(Boolean),
+  )];
+
+  if (normalizedCandidates.length === 0) {
+    return [];
+  }
+
+  const suggestions = new Map();
+
+  for (const [candidateRank, candidateFile] of normalizedCandidates.entries()) {
+    const rankPenalty = candidateRank * 5;
+    const relations = relationsMap.get(candidateFile) ?? {};
+
+    addTestsFromSource({
+      sourceFilePath: candidateFile,
+      relationsMap,
+      suggestions,
+      score: 120 - rankPenalty,
+      reason: `direct test for ${candidateFile}`,
+    });
+
+    for (const siblingFile of (relations.siblings ?? []).slice(0, 3)) {
+      addTestsFromSource({
+        sourceFilePath: siblingFile,
+        relationsMap,
+        suggestions,
+        score: 90 - rankPenalty,
+        reason: `sibling test via ${siblingFile}`,
+      });
+    }
+
+    for (const analog of (analogsMap.get(candidateFile) ?? []).slice(0, 3)) {
+      addTestsFromSource({
+        sourceFilePath: analog.filePath,
+        relationsMap,
+        suggestions,
+        score: 80 + Math.round((Number(analog.score) || 0) * 20) - rankPenalty,
+        reason: `analog test via ${analog.filePath}${analog.reason ? `; ${analog.reason}` : ''}`,
+      });
+    }
+
+    for (const { key, label } of RELATED_TEST_RELATION_TYPES) {
+      for (const relatedFile of (relations[key] ?? []).slice(0, 2)) {
+        addTestsFromSource({
+          sourceFilePath: relatedFile,
+          relationsMap,
+          suggestions,
+          score: 60 - rankPenalty,
+          reason: `${label} test via ${relatedFile}`,
+        });
+      }
+    }
+  }
+
+  return [...suggestions.values()]
+    .sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath))
+    .slice(0, Math.max(limit, 0))
+    .map((suggestion) => ({
+      filePath: suggestion.filePath,
+      score: suggestion.score,
+      reason: suggestion.reasons.join('; '),
+    }));
+}
+
+function addTestsFromSource({
+  sourceFilePath,
+  relationsMap,
+  suggestions,
+  score,
+  reason,
+}) {
+  if (!sourceFilePath) {
+    return;
+  }
+
+  const tests = relationsMap.get(sourceFilePath)?.tests ?? [];
+  for (const testFilePath of tests) {
+    if (!suggestions.has(testFilePath)) {
+      suggestions.set(testFilePath, {
+        filePath: testFilePath,
+        score,
+        reasons: [],
+      });
+    }
+
+    const suggestion = suggestions.get(testFilePath);
+    suggestion.score = Math.max(suggestion.score, score);
+    if (!suggestion.reasons.includes(reason)) {
+      suggestion.reasons.push(reason);
+    }
+  }
+}
+
+// ── Bug Triage ──
+
+export async function triageBug({ rootDir = process.cwd(), signature } = {}) {
+  if (!signature || !signature.trim()) {
+    throw new Error('Bug signature is required. Usage: node .claude/ukit/index/triage.mjs "<error signature>"');
+  }
+
+  const deepKeywords = ['race', 'flaky', 'intermittent', 'timeout', 'deadlock'];
+  const queryResults = await queryCodeIndex({ rootDir, query: signature, limit: 3 });
+  const prioritized = [...queryResults].sort((a, b) => {
+    const as = a.filePath.startsWith('src/') ? 1 : 0;
+    const bs = b.filePath.startsWith('src/') ? 1 : 0;
+    if (as !== bs) return bs - as;
+    return b.score - a.score;
+  });
+
+  const top = prioritized[0] ?? null;
+  const lane = deepKeywords.some((k) => signature.toLowerCase().includes(k))
+    ? 'deep'
+    : (top && top.score >= 8 ? 'fast' : 'deep');
+  const directRecommendedTestFile = prioritized.flatMap((item) => item.tests ?? []).find(Boolean);
+  const shouldLoadRelatedArtifacts = Boolean(top) || !directRecommendedTestFile;
+  const relatedArtifacts = shouldLoadRelatedArtifacts
+    ? await loadRelatedTestArtifacts({ rootDir })
+    : null;
+  const inferredRecommendedTests = directRecommendedTestFile
+    ? []
+    : inferRelatedTestsFromArtifacts({
+      candidateFiles: prioritized.map((item) => item.filePath),
+      analogsMap: relatedArtifacts?.analogsMap,
+      relationsMap: relatedArtifacts?.relationsMap,
+      limit: 3,
+    });
+
+  const analogFiles = top
+    ? (relatedArtifacts?.analogsMap.get(top.filePath) ?? []).slice(0, 2)
+    : [];
+
+  return {
+    signature,
+    lane,
+    confidence: top ? Math.min(top.score / 20, 1) : 0,
+    suspectFiles: prioritized.map((x) => x.filePath),
+    analogFiles: analogFiles.map((a) => a.filePath),
+    reasons: top?.reasons ?? [],
+    recommendedTestCommand: await buildTestCommand(
+      rootDir,
+      directRecommendedTestFile
+        ?? inferredRecommendedTests[0]?.filePath
+        ?? '<target-test-file>',
+    ),
+    suggestedLoop: [
+      'Reproduce exactly once with the failing command',
+      'Open only top 1-3 suspect files from index output',
+      'If analogs found, open 1 analog file for pattern reference',
+      'Run one 15-minute loop: hypothesis -> patch -> targeted test',
+      'If two loops fail, switch to deep debugging lane',
+    ],
+  };
+}
+
+export async function inferRelatedTests({
+  rootDir = process.cwd(),
+  candidateFiles = [],
+  limit = 5,
+  analogsArtifact = null,
+  relationsArtifact = null,
+} = {}) {
+  const {
+    analogsMap,
+    relationsMap,
+  } = await loadRelatedTestArtifacts({
+    rootDir,
+    analogsArtifact,
+    relationsArtifact,
+  });
+
+  return inferRelatedTestsFromArtifacts({
+    candidateFiles,
+    limit,
+    analogsMap,
+    relationsMap,
+  });
+}
+
+async function loadRelatedTestArtifacts({
+  rootDir = process.cwd(),
+  analogsArtifact = null,
+  relationsArtifact = null,
+} = {}) {
+  const absoluteRoot = path.resolve(rootDir);
+
+  if (!analogsArtifact && !relationsArtifact) {
+    if (!RELATED_TEST_LOOKUP_CACHE.has(absoluteRoot)) {
+      RELATED_TEST_LOOKUP_CACHE.set(
+        absoluteRoot,
+        Promise.all([
+          readArtifact(absoluteRoot, INDEX_ARTIFACTS.analogs),
+          readArtifact(absoluteRoot, INDEX_ARTIFACTS.relations),
+        ])
+          .then(([resolvedAnalogsArtifact, resolvedRelationsArtifact]) => ({
+            analogsArtifact: resolvedAnalogsArtifact,
+            relationsArtifact: resolvedRelationsArtifact,
+            ...buildRelatedTestLookups({
+              analogsArtifact: resolvedAnalogsArtifact,
+              relationsArtifact: resolvedRelationsArtifact,
+            }),
+          }))
+          .catch((error) => {
+            RELATED_TEST_LOOKUP_CACHE.delete(absoluteRoot);
+            throw error;
+          }),
+      );
+    }
+
+    return RELATED_TEST_LOOKUP_CACHE.get(absoluteRoot);
+  }
+
+  const [resolvedAnalogsArtifact, resolvedRelationsArtifact] = await Promise.all([
+    analogsArtifact ?? readArtifact(absoluteRoot, INDEX_ARTIFACTS.analogs),
+    relationsArtifact ?? readArtifact(absoluteRoot, INDEX_ARTIFACTS.relations),
+  ]);
+
+  return {
+    analogsArtifact: resolvedAnalogsArtifact,
+    relationsArtifact: resolvedRelationsArtifact,
+    ...buildRelatedTestLookups({
+      analogsArtifact: resolvedAnalogsArtifact,
+      relationsArtifact: resolvedRelationsArtifact,
+    }),
+  };
+}
+
+// ── Index V2: Archetype Classification ──
+
+const ARCHETYPE_RULES = [
+  { pattern: /(?:^|\/)(?:__tests__|test|tests|spec|specs)\//, archetype: 'test' },
+  { 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' },
+  { pattern: /(?:^|\/)components\/.*(?:Modal|modal|Popup|popup|Dialog|dialog)\b/, archetype: 'modal' },
+  { pattern: /(?:^|\/)components\/.*(?:Grid|grid|Table|table)\b/, archetype: 'grid' },
+  { pattern: /(?:^|\/)components\//, archetype: 'component' },
+  { pattern: /(?:^|\/)composables\/|^use[A-Z]/, archetype: 'composable' },
+  { pattern: /(?:^|\/)hooks\//, archetype: 'hook' },
+  { pattern: /(?:^|\/)(?:api|apis?|services?)\//, archetype: 'api' },
+  { pattern: /(?:^|\/)store(?:s)?\//, archetype: 'store' },
+  { pattern: /(?:^|\/)(?:utils?|helpers?)\//, archetype: 'util' },
+  { pattern: /(?:^|\/)middleware\//, archetype: 'middleware' },
+  { pattern: /(?:^|\/)layouts?\//, archetype: 'layout' },
+  { pattern: /(?:^|\/)(?:config|conf|settings)\./, archetype: 'config' },
+  { pattern: /(?:^|\/)migrations?\//, archetype: 'migration' },
+  { 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('/');
+  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;
+}
+
+// ── Helpers ──
+
+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 out = [];
+  const addSymbol = (name, type) => {
+    if (!name) return;
+    out.push({ name, type, filePath });
+  };
+  const addMatches = (regex, type, idx = 1) => {
+    for (const match of content.matchAll(regex)) {
+      const name = match[idx];
+      if (!name) continue;
+      addSymbol(name, 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)) {
+    for (const part of (match[1] ?? '').split(',').map((x) => x.trim()).filter(Boolean)) {
+      const parsed = part.match(/^([A-Za-z_$][A-Za-z0-9_$]*)(?:\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*))?$/);
+      if (!parsed) continue;
+      addSymbol(parsed[2] ?? parsed[1], 'named-export');
+    }
+  }
+
+  const seen = new Set();
+  return out.filter((item) => {
+    const key = `${item.filePath}:${item.type}:${item.name}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function extractImports(filePath, content) {
+  const out = [];
+  const stripped = content
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/.*$/gm, '');
+  for (const match of stripped.matchAll(/import\s+(?:[^'";]+?\s+from\s+)?['"]([^'"]+)['"]/g)) {
+    out.push({ from: filePath, to: match[1], kind: 'import' });
+  }
+  for (const match of stripped.matchAll(/import\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+    out.push({ from: filePath, to: match[1], kind: 'dynamic-import' });
+  }
+  for (const match of stripped.matchAll(/require\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+    out.push({ from: filePath, to: match[1], kind: 'require' });
+  }
+  for (const match of stripped.matchAll(/export\s+(?:type\s+)?\{[^}]+\}\s+from\s+['"]([^'"]+)['"]/g)) {
+    out.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)) {
+    out.push({ from: filePath, to: match[1], kind: 're-export-all' });
+  }
+  return out;
+}
+
+function extractSupplementalImports(filePath, content) {
+  if (!filePath.endsWith('.vue')) {
+    return [];
+  }
+
+  const out = [];
+  for (const match of content.matchAll(/<style\b[^>]*\bsrc=['"]([^'"]+)['"][^>]*>/gi)) {
+    out.push({ from: filePath, to: match[1], kind: 'style-src' });
+  }
+
+  return out;
+}
+
+function buildTestsMap(fileRecords) {
+  const tests = fileRecords.filter((x) => isLikelyTestFile(x.filePath));
+  const sources = fileRecords.filter((x) => CODE_EXTENSIONS.has(x.ext) && !isLikelyTestFile(x.filePath));
+
+  return sources.map((source) => {
+    const matches = tests
+      .map((test) => ({
+        filePath: test.filePath,
+        score: scoreTestMatch(source.filePath, test.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: source.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 fp = match[1];
+    scores.set(fp, (scores.get(fp) ?? 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 writeArtifact(rootDir, artifactName, payload) {
+  await fs.writeFile(getArtifactPath(rootDir, artifactName), JSON.stringify(payload, null, 2));
+}
+
+async function readArtifact(rootDir, artifactName) {
+  const artifactPath = getArtifactPath(path.resolve(rootDir), artifactName);
+
+  if (!ARTIFACT_CACHE.has(artifactPath)) {
+    ARTIFACT_CACHE.set(
+      artifactPath,
+      fs.readFile(artifactPath, 'utf8')
+        .then((content) => {
+          try { return JSON.parse(content); } catch (e) { ARTIFACT_CACHE.delete(artifactPath); return null; }
+        })
+        .catch((error) => {
+          ARTIFACT_CACHE.delete(artifactPath);
+          return null;
+        }),
+    );
+  }
+
+  return ARTIFACT_CACHE.get(artifactPath);
+}
+
+async function loadQuerySearchBundle(rootDir) {
+  const absoluteRoot = path.resolve(rootDir);
+
+  if (!QUERY_SEARCH_BUNDLE_CACHE.has(absoluteRoot)) {
+    QUERY_SEARCH_BUNDLE_CACHE.set(
+      absoluteRoot,
+      Promise.all([
+        readArtifact(absoluteRoot, INDEX_ARTIFACTS.files),
+        readArtifact(absoluteRoot, INDEX_ARTIFACTS.symbols),
+      ])
+        .then(([files, symbols]) => {
+          const safeFiles = ensureArtifact(files);
+          const safeSymbols = ensureArtifact(symbols);
+          const symbolMap = groupBy(safeSymbols.items ?? [], (item) => item.filePath);
+          return {
+            files: safeFiles,
+            searchDescriptorsByFile: buildFileSearchDescriptors(safeFiles.items ?? [], symbolMap),
+          };
+        })
+        .catch((error) => {
+          QUERY_SEARCH_BUNDLE_CACHE.delete(absoluteRoot);
+          throw error;
+        }),
+    );
+  }
+
+  return QUERY_SEARCH_BUNDLE_CACHE.get(absoluteRoot);
+}
+
+async function loadQuerySupportBundle(rootDir) {
+  const absoluteRoot = path.resolve(rootDir);
+
+  if (!QUERY_SUPPORT_BUNDLE_CACHE.has(absoluteRoot)) {
+    QUERY_SUPPORT_BUNDLE_CACHE.set(
+      absoluteRoot,
+      loadQuerySearchBundle(absoluteRoot)
+        .then(({ files }) => Promise.all([
+          Promise.resolve(files),
+          readArtifact(absoluteRoot, INDEX_ARTIFACTS.imports),
+          readArtifact(absoluteRoot, INDEX_ARTIFACTS.testsMap),
+          readArtifact(absoluteRoot, INDEX_ARTIFACTS.hotspots),
+          readArtifact(absoluteRoot, INDEX_ARTIFACTS.archetypes),
+        ]))
+        .then(async ([files, imports, testsMap, hotspots, archetypes]) => {
+          const safeFiles = ensureArtifact(files);
+          const safeImports = ensureArtifact(imports);
+          const safeTestsMap = ensureArtifact(testsMap);
+          const safeHotspots = ensureArtifact(hotspots);
+          const safeArchetypes = ensureArtifact(archetypes);
+          const indexedFileSet = new Set((safeFiles.items ?? []).map((item) => item.filePath));
+          const importAliasContext = importsNeedAliasContext(safeImports.items ?? [])
+            ? await loadImportAliasContext({ rootDir: absoluteRoot })
+            : null;
+          const { resolvedImportsBySource, importersByTarget } = buildResolvedImportGraphs(
+            absoluteRoot,
+            safeImports.items ?? [],
+            indexedFileSet,
+            importAliasContext,
+          );
+
+          return {
+            hotspotScores: new Map((safeHotspots.items ?? []).map((item) => [item.filePath, item.count])),
+            testsMapBySource: new Map((safeTestsMap.items ?? []).map((item) => [item.sourceFile, item.tests ?? []])),
+            resolvedImportsBySource,
+            importersByTarget,
+            archetypeByFile: new Map((safeArchetypes.items ?? []).map((item) => [item.filePath, item.archetype])),
+          };
+        })
+        .catch((error) => {
+          QUERY_SUPPORT_BUNDLE_CACHE.delete(absoluteRoot);
+          throw error;
+        }),
+    );
+  }
+
+  return QUERY_SUPPORT_BUNDLE_CACHE.get(absoluteRoot);
+}
+
+async function readArtifactIfExists(rootDir, artifactName) {
+  try {
+    const artifactPath = getArtifactPath(rootDir, artifactName);
+    const content = await fs.readFile(artifactPath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function tokenize(query) {
+  return tokenizeFoldedText(foldTextForSearch(addCamelBoundaries(query)));
+}
+
+function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
+  let score = 0;
+  const reasons = [];
+
+  if (
+    queryDescriptor.compact.length >= 6
+    && searchDescriptor.path.compact.includes(queryDescriptor.compact)
+  ) {
+    score += 6;
+    reasons.push(`path_compact:${queryDescriptor.compact}`);
+  }
+
+  for (const token of queryDescriptor.tokens) {
+    if (searchDescriptor.path.tokens.has(token)) {
+      score += 3;
+      reasons.push(`path_token:${token}`);
+    } else if (searchDescriptor.path.rawLower.includes(token)) {
+      score += 1;
+      reasons.push(`path_contains:${token}`);
+    }
+  }
+
+  for (const symbolDescriptor of searchDescriptor.symbols) {
+    if (
+      queryDescriptor.compact.length >= 4
+      && symbolDescriptor.descriptor.compact === queryDescriptor.compact
+    ) {
+      score += 8;
+      reasons.push(`symbol_exact:${symbolDescriptor.name}`);
+      continue;
+    }
+
+    if (
+      queryDescriptor.compact.length >= 6
+      && symbolDescriptor.descriptor.compact.includes(queryDescriptor.compact)
+    ) {
+      score += 5;
+      reasons.push(`symbol_compact:${symbolDescriptor.name}`);
+    }
+
+    for (const token of queryDescriptor.tokens) {
+      if (symbolDescriptor.descriptor.tokens.has(token)) {
+        score += 3;
+        reasons.push(`symbol_token:${symbolDescriptor.name}:${token}`);
+      } else if (symbolDescriptor.descriptor.rawLower.includes(token)) {
+        score += 1;
+        reasons.push(`symbol_contains:${symbolDescriptor.name}`);
+      }
+    }
+  }
+
+  return { score, reasons: [...new Set(reasons)], filePath };
+}
+
+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 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);
+  });
+}
+
+function buildFileSearchDescriptors(files, symbolMap) {
+  const descriptors = new Map();
+
+  for (const file of files) {
+    const filePath = file.filePath;
+    descriptors.set(
+      filePath,
+      createFileSearchDescriptor({
+        filePath,
+        symbols: symbolMap.get(filePath) ?? [],
+      }),
+    );
+  }
+
+  return descriptors;
+}
+
+function createFileSearchDescriptor({ filePath, symbols }) {
+  return {
+    path: buildTextSearchDescriptor(filePath),
+    symbols: symbols.map((symbol) => ({
+      name: symbol.name,
+      descriptor: buildTextSearchDescriptor(symbol.name),
+    })),
+  };
+}
+
+function buildTextSearchDescriptor(value) {
+  return buildSearchDescriptor(value);
+}
+
+export function buildRouteSignalText(...values) {
+  const baseText = values
+    .map((value) => String(value || '').trim())
+    .filter(Boolean)
+    .join('\n');
+
+  if (!baseText) {
+    return '';
+  }
+
+  const withCamelBoundaries = addCamelBoundaries(baseText);
+  const foldedLower = foldTextForSearch(withCamelBoundaries);
+  const baseTokens = tokenizeFoldedText(foldedLower);
+  const aliasTokens = collectVietnameseAliasTokens(foldedLower, baseTokens);
+
+  return [
+    String(baseText).toLowerCase(),
+    foldedLower,
+    [...new Set([...baseTokens, ...aliasTokens])].join(' '),
+  ].filter(Boolean).join('\n');
+}
+
+export function buildSearchDescriptor(value, { expandVietnameseAliases = false } = {}) {
+  const withCamelBoundaries = addCamelBoundaries(value);
+  const foldedLower = foldTextForSearch(withCamelBoundaries);
+  const tokens = new Set(tokenizeFoldedText(foldedLower));
+
+  if (expandVietnameseAliases) {
+    for (const token of collectVietnameseAliasTokens(foldedLower, tokens)) {
+      tokens.add(token);
+    }
+  }
+
+  return {
+    rawLower: foldedLower,
+    tokens,
+    compact: [...tokens].join(''),
+  };
+}
+
+function addCamelBoundaries(value) {
+  return String(value || '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2');
+}
+
+function tokenizeFoldedText(value) {
+  return String(value || '')
+    .split(/[^\p{L}\p{N}]+/u)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 2 && !GENERIC_STOPWORDS.has(token));
+}
+
+function collectVietnameseAliasTokens(foldedLower, baseTokens) {
+  const aliases = [];
+
+  for (const entry of VIETNAMESE_PHRASE_ALIASES) {
+    entry.regex.lastIndex = 0;
+    if (!entry.regex.test(foldedLower)) {
+      continue;
+    }
+    aliases.push(...entry.expansions);
+  }
+
+  for (const token of baseTokens) {
+    aliases.push(...(VIETNAMESE_TOKEN_ALIASES.get(token) ?? []));
+  }
+
+  return [...new Set(
+    aliases
+      .map((token) => foldTextForSearch(token))
+      .filter((token) => token.length >= 2 && !GENERIC_STOPWORDS.has(token)),
+  )];
+}
+
+function foldTextForSearch(value) {
+  return String(value || '')
+    .replaceAll('đ', 'd')
+    .replaceAll('Đ', 'D')
+    .normalize('NFD')
+    .replace(/\p{M}+/gu, '')
+    .toLowerCase();
+}
+
+function inferPreferredArchetypes(tokens) {
+  const preferred = new Set();
+
+  const addIfAny = (signals, archetypes) => {
+    if (!signals.some((signal) => tokens.has(signal))) return;
+    for (const archetype of archetypes) preferred.add(archetype);
+  };
+
+  addIfAny(['page', 'screen', 'view', 'route'], ['page', 'detail-page', 'form-page', 'list-page']);
+  addIfAny(['list'], ['list-page', 'grid']);
+  addIfAny(['detail'], ['detail-page', 'page']);
+  addIfAny(['form', 'edit', 'create', 'add'], ['form-page']);
+  addIfAny(['component', 'widget', 'card', 'button'], ['component']);
+  addIfAny(['modal', 'dialog', 'popup'], ['modal']);
+  addIfAny(['grid', 'table'], ['grid']);
+  addIfAny(['hook', 'composable', 'use'], ['hook', 'composable']);
+  addIfAny(['service', 'api', 'client', 'request', 'fetch'], ['api']);
+  addIfAny(['store', 'state'], ['store']);
+  addIfAny(['util', 'helper', 'format'], ['util']);
+  addIfAny(['test', 'spec'], ['test']);
+
+  return preferred;
+}
+
+function shouldIncludeLikelyTestFiles(queryDescriptor) {
+  return queryDescriptor.tokens.has('test')
+    || queryDescriptor.tokens.has('tests')
+    || queryDescriptor.tokens.has('spec')
+    || queryDescriptor.tokens.has('specs')
+    || queryDescriptor.rawLower.includes('.test')
+    || queryDescriptor.rawLower.includes('.spec');
+}
+
+function applyImportGraphBoosts({
+  directScores,
+  resolvedImportsBySource,
+  importersByTarget,
+  testsMapBySource,
+}) {
+  const scores = cloneScoreMap(directScores);
+
+  for (const [sourceFilePath] of directScores) {
+    for (const targetFilePath of resolvedImportsBySource.get(sourceFilePath) ?? []) {
+      const target = ensureScoreEntry(scores, targetFilePath, testsMapBySource);
+      target.score += 1;
+      target.reasons = [...new Set([...target.reasons, `imported_by_match:${sourceFilePath}`])];
+    }
+  }
+
+  for (const [matchedFilePath] of directScores) {
+    propagateImporterMatches({
+      startFilePath: matchedFilePath,
+      scores,
+      importersByTarget,
+      testsMapBySource,
+    });
+  }
+
+  return scores;
+}
+
+function applyHotspotBoosts({ scores, hotspotScores }) {
+  const boostedScores = cloneScoreMap(scores);
+
+  for (const [filePath, entry] of boostedScores) {
+    const hotspot = hotspotScores.get(filePath) ?? 0;
+    if (hotspot <= 0) continue;
+
+    entry.score += Math.min(hotspot * 2, 8);
+    entry.reasons = [...new Set([...entry.reasons, `hotspot:${hotspot}`])];
+  }
+
+  return boostedScores;
+}
+
+function cloneScoreMap(scores) {
+  const clone = new Map();
+
+  for (const [filePath, entry] of scores) {
+    clone.set(filePath, {
+      filePath,
+      score: entry.score,
+      reasons: [...(entry.reasons ?? [])],
+      tests: [...(entry.tests ?? [])],
+    });
+  }
+
+  return clone;
+}
+
+function ensureScoreEntry(scores, filePath, testsMapBySource) {
+  if (!scores.has(filePath)) {
+    scores.set(filePath, {
+      filePath,
+      score: 0,
+      reasons: [],
+      tests: testsMapBySource.get(filePath) ?? [],
+    });
+  }
+
+  return scores.get(filePath);
+}
+
+function propagateImporterMatches({
+  startFilePath,
+  scores,
+  importersByTarget,
+  testsMapBySource,
+}) {
+  const visited = new Set([startFilePath]);
+  const queue = [{ filePath: startFilePath, depth: 0 }];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current.depth >= MAX_IMPORTER_HOPS) continue;
+
+    for (const importerFilePath of importersByTarget.get(current.filePath) ?? []) {
+      if (visited.has(importerFilePath)) continue;
+      visited.add(importerFilePath);
+
+      if (isLikelyTestFilePath(importerFilePath)) continue;
+
+      const importer = ensureScoreEntry(scores, importerFilePath, testsMapBySource);
+      const scoreDelta = current.depth === 0 ? 2 : 1;
+      const reason = current.depth === 0
+        ? `imports_match:${startFilePath}`
+        : `imports_match_via:${current.filePath}->${startFilePath}`;
+
+      importer.score += scoreDelta;
+      importer.reasons = [...new Set([...importer.reasons, reason])];
+      queue.push({ filePath: importerFilePath, depth: current.depth + 1 });
+    }
+  }
+}
+
+function buildResolvedImportGraphs(rootDir, imports, indexedFileSet, importAliasContext) {
+  const resolvedImportsBySource = new Map();
+  const importersByTarget = new Map();
+
+  for (const edge of imports) {
+    if (!edge?.from || !edge?.to) continue;
+
+    const target = resolveImportSpecifier({
+      rootDir,
+      fromFilePath: edge.from,
+      specifier: edge.to,
+      indexedFileSet,
+      aliasContext: importAliasContext,
+    });
+    if (!target) continue;
+
+    if (!resolvedImportsBySource.has(edge.from)) {
+      resolvedImportsBySource.set(edge.from, new Set());
+    }
+    resolvedImportsBySource.get(edge.from).add(target);
+
+    if (!importersByTarget.has(target)) {
+      importersByTarget.set(target, new Set());
+    }
+    importersByTarget.get(target).add(edge.from);
+  }
+
+  return { resolvedImportsBySource, importersByTarget };
+}
+
+function isLikelyTestFilePath(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')
+  );
+}
+
+async function loadImportAliasContext({ rootDir }) {
+  const loaded = await loadImportAliasContextState({ rootDir });
+  return loaded.context;
+}
+
+async function loadImportAliasContextState({ rootDir }) {
+  const absoluteRoot = path.resolve(rootDir);
+  const cached = ALIAS_CONTEXT_CACHE.get(absoluteRoot);
+  if (cached) {
+    const cachedEntry = await cached;
+    if (await isAliasSnapshotValid(cachedEntry.snapshot)) {
+      return cachedEntry;
+    }
+    ALIAS_CONTEXT_CACHE.delete(absoluteRoot);
+  }
+
+  const contextPromise = loadFreshImportAliasContext(absoluteRoot)
+    .catch((error) => {
+      ALIAS_CONTEXT_CACHE.delete(absoluteRoot);
+      throw error;
+    });
+  ALIAS_CONTEXT_CACHE.set(absoluteRoot, contextPromise);
+
+  return contextPromise;
+}
+
+function importsNeedAliasContext(imports = []) {
+  return imports.some((entry) => specifierNeedsAliasContext(entry?.to));
+}
+
+async function loadFreshImportAliasContext(rootDir) {
+  const tracker = new Map();
+  const tsconfigPath = path.join(rootDir, 'tsconfig.json');
+  const jsconfigPath = path.join(rootDir, 'jsconfig.json');
+  const config = await loadAliasConfig(tsconfigPath, new Set(), tracker)
+    ?? await loadAliasConfig(jsconfigPath, new Set(), tracker);
+
+  for (const configName of ROOT_ALIAS_CONFIG_FILES) {
+    const configPath = path.resolve(rootDir, configName);
+    if (!tracker.has(configPath)) {
+      tracker.set(configPath, await readPathSnapshot(configPath));
+    }
+  }
+
+  const configuredRules = config?.pathRules ?? [];
+  const configuredBaseUrls = config?.baseUrlDirs ?? [];
+
+  return {
+    context: {
+      rootDir,
+      pathRules: [
+        ...configuredRules,
+        ...DEFAULT_ALIAS_RULES.map((rule) => buildAliasRule({
+          pattern: rule.pattern,
+          targets: rule.targets,
+          baseDir: rootDir,
+        })),
+      ],
+      baseUrlDirs: [...new Set(configuredBaseUrls)],
+    },
+    snapshot: [...tracker.values()].sort((a, b) => a.filePath.localeCompare(b.filePath)),
+  };
+}
+
+function resolveImportSpecifier({
+  rootDir,
+  fromFilePath,
+  specifier,
+  indexedFileSet,
+  aliasContext,
+}) {
+  if (!specifier?.trim()) return null;
+
+  if (specifier.startsWith('.')) {
+    const fromDir = path.posix.dirname(fromFilePath);
+    const base = path.posix.normalize(path.posix.join(fromDir, specifier));
+    return resolveCandidateBase(base, indexedFileSet);
+  }
+
+  if (specifier.startsWith('/')) {
+    return resolveCandidateBase(specifier.slice(1), indexedFileSet);
+  }
+
+  for (const rule of aliasContext?.pathRules ?? []) {
+    const wildcardValue = matchAliasPattern(specifier, rule.pattern);
+    if (wildcardValue === null) continue;
+
+    for (const targetPattern of rule.targets) {
+      const replacedTarget = targetPattern.replaceAll('*', wildcardValue);
+      const absoluteBase = path.resolve(rule.baseDir, replacedTarget);
+      const relativeBase = normalizeRelative(rootDir, absoluteBase);
+      const resolved = resolveCandidateBase(relativeBase, indexedFileSet);
+      if (resolved) return resolved;
+    }
+  }
+
+  for (const baseUrlDir of aliasContext?.baseUrlDirs ?? []) {
+    const absoluteBase = path.resolve(baseUrlDir, specifier);
+    const relativeBase = normalizeRelative(rootDir, absoluteBase);
+    const resolved = resolveCandidateBase(relativeBase, indexedFileSet);
+    if (resolved) return resolved;
+  }
+
+  return null;
+}
+
+function resolveCandidateBase(relativeBase, indexedFileSet) {
+  const normalizedBase = relativeBase.replace(/\\/g, '/');
+
+  for (const suffix of RESOLUTION_SUFFIXES) {
+    const candidate = path.posix.normalize(`${normalizedBase}${suffix}`);
+    if (indexedFileSet.has(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+function specifierNeedsAliasContext(specifier) {
+  const normalized = String(specifier ?? '').trim();
+  if (!normalized) return false;
+  return !normalized.startsWith('.') && !normalized.startsWith('/');
+}
+
+function matchAliasPattern(specifier, pattern) {
+  if (!pattern.includes('*')) return specifier === pattern ? '' : null;
+
+  const [prefix, suffix] = pattern.split('*');
+  if (!specifier.startsWith(prefix)) return null;
+  if (suffix && !specifier.endsWith(suffix)) return null;
+
+  return specifier.slice(prefix.length, specifier.length - suffix.length);
+}
+
+function buildAliasRule({ pattern, targets, baseDir }) {
+  return {
+    pattern,
+    targets: targets.map((target) => target.replace(/\\/g, '/')),
+    baseDir,
+  };
+}
+
+async function loadAliasConfig(configPath, visited = new Set(), tracker = null) {
+  const resolvedPath = path.resolve(configPath);
+  if (visited.has(resolvedPath)) return null;
+  visited.add(resolvedPath);
+
+  const snapshot = await readPathSnapshot(resolvedPath);
+  if (tracker) {
+    tracker.set(resolvedPath, snapshot);
+  }
+  if (!snapshot.exists) {
+    return null;
+  }
+
+  let raw;
+  try {
+    raw = await fs.readFile(resolvedPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = parseJsonc(raw);
+  } catch {
+    return null;
+  }
+
+  const configDir = path.dirname(resolvedPath);
+  const compilerOptions = parsed?.compilerOptions ?? {};
+
+  let inherited = null;
+  const extendsValue = typeof parsed?.extends === 'string' ? parsed.extends.trim() : '';
+  if (extendsValue && (extendsValue.startsWith('.') || extendsValue.startsWith('/'))) {
+    const inheritedPath = resolveExtendedConfigPath(configDir, extendsValue);
+    inherited = await loadAliasConfig(inheritedPath, visited, tracker);
+  }
+
+  const inheritedRules = inherited?.pathRules ?? [];
+  const inheritedBaseUrls = inherited?.baseUrlDirs ?? [];
+  const currentRules = buildPathRules({ rootDir: configDir, compilerOptions });
+  const currentBaseUrls = buildBaseUrlDirs({ rootDir: configDir, compilerOptions });
+
+  const pathRuleMap = new Map(inheritedRules.map((rule) => [rule.pattern, rule]));
+  for (const rule of currentRules) {
+    pathRuleMap.set(rule.pattern, rule);
+  }
+
+  return {
+    pathRules: [...pathRuleMap.values()],
+    baseUrlDirs: [...new Set([...currentBaseUrls, ...inheritedBaseUrls])],
+  };
+}
+
+function buildPathRules({ rootDir, compilerOptions }) {
+  const paths = compilerOptions?.paths;
+  if (!paths || typeof paths !== 'object') return [];
+
+  const baseDir = path.resolve(rootDir, String(compilerOptions?.baseUrl ?? '.'));
+  return Object.entries(paths)
+    .filter(([pattern, targets]) => typeof pattern === 'string' && Array.isArray(targets) && targets.length > 0)
+    .map(([pattern, targets]) => buildAliasRule({
+      pattern,
+      targets: targets.filter((target) => typeof target === 'string'),
+      baseDir,
+    }));
+}
+
+function buildBaseUrlDirs({ rootDir, compilerOptions }) {
+  const baseUrl = String(compilerOptions?.baseUrl ?? '').trim();
+  if (!baseUrl) return [];
+  return [path.resolve(rootDir, baseUrl)];
+}
+
+function resolveExtendedConfigPath(configDir, extendsValue) {
+  const withExtension = extendsValue.endsWith('.json')
+    ? extendsValue
+    : `${extendsValue}.json`;
+  return path.resolve(configDir, withExtension);
+}
+
+async function isAliasSnapshotValid(snapshot = []) {
+  const current = await Promise.all(snapshot.map((entry) => readPathSnapshot(entry.filePath)));
+  return current.every((entry, index) => isSameSnapshotEntry(entry, snapshot[index]));
+}
+
+async function readPathSnapshot(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    return {
+      filePath,
+      exists: true,
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+    };
+  } catch {
+    return {
+      filePath,
+      exists: false,
+      size: null,
+      mtimeMs: null,
+    };
+  }
+}
+
+function isSameSnapshotEntry(current, previous) {
+  return current.filePath === previous.filePath
+    && current.exists === previous.exists
+    && current.size === previous.size
+    && current.mtimeMs === previous.mtimeMs;
+}
+
+function parseJsonc(raw) {
+  const withoutBom = raw.replace(/^\uFEFF/, '');
+  const withoutBlockComments = withoutBom.replace(/\/\*[\s\S]*?\*\//g, '');
+  const withoutLineComments = stripLineComments(withoutBlockComments);
+  const withoutTrailingCommas = withoutLineComments.replace(/,\s*([}\]])/g, '$1');
+  return JSON.parse(withoutTrailingCommas);
+}
+
+function stripLineComments(raw) {
+  let result = '';
+  let inString = false;
+  let stringQuote = '';
+  let isEscaped = false;
+
+  for (let index = 0; index < raw.length; index += 1) {
+    const char = raw[index];
+    const nextChar = raw[index + 1];
+
+    if (inString) {
+      result += char;
+      if (isEscaped) {
+        isEscaped = false;
+      } else if (char === '\\') {
+        isEscaped = true;
+      } else if (char === stringQuote) {
+        inString = false;
+        stringQuote = '';
+      }
+      continue;
+    }
+
+    if ((char === '"' || char === "'")) {
+      inString = true;
+      stringQuote = char;
+      result += char;
+      continue;
+    }
+
+    if (char === '/' && nextChar === '/') {
+      while (index < raw.length && raw[index] !== '\n') {
+        index += 1;
+      }
+      if (index < raw.length) result += '\n';
+      continue;
+    }
+
+    result += char;
+  }
+
+  return result;
+}
+
+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();
+}
+
+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 buildTestCommand(rootDir, testFile) {
+  const packageManager = await detectPackageManager(rootDir);
+  if (packageManager === 'pnpm') return `pnpm test ${testFile}`;
+  if (packageManager === 'yarn') return `yarn test ${testFile}`;
+  if (packageManager === 'bun') return `bun test ${testFile}`;
+  return `npm test -- ${testFile}`;
+}
+
+async function detectPackageManager(rootDir) {
+  const packageJsonPath = path.join(rootDir, 'package.json');
+  try {
+    const raw = await fs.readFile(packageJsonPath, 'utf8');
+    const pkg = JSON.parse(raw);
+    const declared = String(pkg?.packageManager ?? '').toLowerCase();
+    if (declared.startsWith('pnpm')) return 'pnpm';
+    if (declared.startsWith('yarn')) return 'yarn';
+    if (declared.startsWith('bun')) return 'bun';
+    if (declared.startsWith('npm')) return 'npm';
+  } catch {
+    // fallback below
+  }
+
+  const checks = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lockb', 'bun'],
+    ['package-lock.json', 'npm'],
+  ];
+
+  for (const [lockfile, pm] of checks) {
+    try {
+      await fs.access(path.join(rootDir, lockfile));
+      return pm;
+    } catch {
+      // continue
+    }
+  }
+
+  return 'npm';
+}
+
+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);
+}