@ngockhoale/ukit 1.1.6

package/src/index/queryIndex.js

@@ -0,0 +1,637 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS } from './paths.js';
+import { importsNeedAliasContext, loadImportAliasContext, resolveImportSpecifier } from './importResolution.js';
+import { buildSearchDescriptor } from './languageTools.js';
+
+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 MAX_IMPORTER_HOPS = 2;
+
+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: dedupe(reasons),
+        });
+      }
+    }
+
+    if (directScores.size === 0) {
+      return Object.freeze([]);
+    }
+
+    const {
+      hotspotScores,
+      testsMapBySource,
+      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: dedupe(reasons),
+        tests: testsMapBySource.get(filePath) ?? [],
+      });
+    }
+
+    const relatedScores = applyImportGraphBoosts({
+      directScores: enrichedDirectScores,
+      resolvedImportsBySource,
+      importersByTarget,
+      testsMapBySource,
+    });
+    const finalScores = applyHotspotBoosts({
+      scores: relatedScores,
+      hotspotScores,
+    });
+
+    return freezeQueryResults(
+      [...finalScores.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;
+}
+
+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 {
+            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(([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 aliasContextPromise = importsNeedAliasContext(safeImports.items ?? [])
+            ? loadImportAliasContext({ rootDir: absoluteRoot })
+            : Promise.resolve(null);
+          return aliasContextPromise.then((importAliasContext) => {
+            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);
+}
+
+function dedupe(values) {
+  return [...new Set(values)];
+}
+
+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: dedupe(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 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);
+}
+
+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 = dedupe([...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 hotspotCount = hotspotScores.get(filePath) ?? 0;
+    if (hotspotCount <= 0) {
+      continue;
+    }
+
+    entry.score += Math.min(hotspotCount * 2, 8);
+    entry.reasons = dedupe([...entry.reasons, `hotspot:${hotspotCount}`]);
+  }
+
+  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 = dedupe([...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.tsx')
+    || lower.endsWith('.test.jsx')
+    || lower.endsWith('.test.vue')
+    || lower.endsWith('.test.mjs')
+    || lower.endsWith('.test.cjs')
+    || lower.endsWith('.spec.js')
+    || lower.endsWith('.spec.ts')
+    || lower.endsWith('.spec.tsx')
+    || lower.endsWith('.spec.jsx')
+    || lower.endsWith('.spec.vue')
+    || lower.endsWith('.spec.mjs')
+    || lower.endsWith('.spec.cjs')
+  );
+}
+
+// ── Index V2: 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();
+    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);
+    }
+  }
+}
+
+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('"', '\\"');
+}