@ngockhoale/ukit 1.1.6

package/src/index/gitHooks.js

@@ -0,0 +1,109 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const HOOK_NAMES = ['post-commit', 'post-merge', 'post-checkout'];
+const BEGIN = '# UKit index auto-refresh (begin)';
+const END = '# UKit index auto-refresh (end)';
+
+export async function installIndexRefreshHooks({ projectRoot }) {
+  const hooksDir = path.join(projectRoot, '.git', 'hooks');
+  await ensureHooksDir(hooksDir);
+
+  let installed = 0;
+  let unchanged = 0;
+
+  for (const hookName of HOOK_NAMES) {
+    const hookPath = path.join(hooksDir, hookName);
+    const existing = await readTextOrEmpty(hookPath);
+    const base = existing || '#!/bin/sh\n';
+
+    if (hasManagedBlock(base)) {
+      unchanged += 1;
+      continue;
+    }
+
+    const next = `${base.trimEnd()}\n\n${buildManagedBlock()}\n`;
+    await fs.writeFile(hookPath, next, { mode: 0o755 });
+    await fs.chmod(hookPath, 0o755);
+    installed += 1;
+  }
+
+  return {
+    hookNames: HOOK_NAMES,
+    installed,
+    unchanged,
+  };
+}
+
+export async function removeIndexRefreshHooks({ projectRoot }) {
+  const hooksDir = path.join(projectRoot, '.git', 'hooks');
+  await ensureHooksDir(hooksDir);
+
+  let removed = 0;
+  let unchanged = 0;
+
+  for (const hookName of HOOK_NAMES) {
+    const hookPath = path.join(hooksDir, hookName);
+    const existing = await readTextOrEmpty(hookPath);
+    if (!existing || !hasManagedBlock(existing)) {
+      unchanged += 1;
+      continue;
+    }
+
+    const next = removeManagedBlock(existing);
+    const cleaned = next.trim().length === 0 ? '#!/bin/sh\n' : `${next.trimEnd()}\n`;
+    await fs.writeFile(hookPath, cleaned, { mode: 0o755 });
+    await fs.chmod(hookPath, 0o755);
+    removed += 1;
+  }
+
+  return {
+    hookNames: HOOK_NAMES,
+    removed,
+    unchanged,
+  };
+}
+
+function buildManagedBlock() {
+  return [
+    BEGIN,
+    'ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0',
+    'SCRIPT="$ROOT/.claude/ukit/index/refresh-index.mjs"',
+    '[ -f "$SCRIPT" ] || exit 0',
+    'node "$SCRIPT" >/dev/null 2>&1 || true',
+    END,
+  ].join('\n');
+}
+
+function hasManagedBlock(content) {
+  return content.includes(BEGIN) && content.includes(END);
+}
+
+function removeManagedBlock(content) {
+  const pattern = new RegExp(`${escapeRegExp(BEGIN)}[\\s\\S]*?${escapeRegExp(END)}\\n?`, 'g');
+  return content.replace(pattern, '').replace(/\n{3,}/g, '\n\n');
+}
+
+function escapeRegExp(input) {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function ensureHooksDir(hooksDir) {
+  try {
+    const stat = await fs.stat(hooksDir);
+    if (!stat.isDirectory()) {
+      throw new Error();
+    }
+  } catch {
+    throw new Error('No .git/hooks directory found. Run this inside a git project.');
+  }
+}
+
+async function readTextOrEmpty(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+

package/src/index/importResolution.js

@@ -0,0 +1,377 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { normalizeRelative } from './paths.js';
+
+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'];
+
+export async function loadImportAliasContext({ rootDir }) {
+  const loaded = await loadImportAliasContextState({ rootDir });
+  return loaded.context;
+}
+
+export 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;
+}
+
+export 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,
+          rootDir,
+          baseDir: rootDir,
+        })),
+      ],
+      baseUrlDirs: dedupe(configuredBaseUrls),
+    },
+    snapshot: [...tracker.values()].sort((a, b) => a.filePath.localeCompare(b.filePath)),
+  };
+}
+
+export 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 = wildcardValue === null
+        ? targetPattern
+        : 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, rootDir, baseDir }) {
+  return {
+    pattern,
+    targets: targets.map((target) => target.replace(/\\/g, '/')),
+    rootDir,
+    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: dedupe([...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'),
+      rootDir,
+      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 dedupe(values) {
+  return [...new Set(values)];
+}

package/src/index/languageTools.js

@@ -0,0 +1,127 @@
+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']],
+]);
+
+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();
+}

package/src/index/paths.js

@@ -0,0 +1,27 @@
+import path from 'node:path';
+
+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 const INDEX_SCHEMA_VERSION = 6;
+
+export function getIndexDir(rootDir) {
+  return path.join(rootDir, '.cache', 'index');
+}
+
+export function getArtifactPath(rootDir, artifactName) {
+  return path.join(getIndexDir(rootDir), artifactName);
+}
+
+export function normalizeRelative(rootDir, absolutePath) {
+  return path.relative(rootDir, absolutePath).replace(/\\/g, '/');
+}