@ngockhoale/ukit 3.0.3 → 3.0.5

package/template_project/.claude/hooks/session-episode.sh

@@ -64,11 +64,18 @@ if [ -e /dev/fd/0 ]; then
   exec 8<&0
   head -c 65537 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
   UKIT_HEAD_PID=$!
-  # UKIT_HOOK_STAGE_MS:-2000 — bounded wait for the staged payload.
+  # UKIT_HOOK_STAGE_MS:-2000 — bounded wait for the staged payload (same derived
+  # budget every other hook uses; a hardcoded sleep ignored the operator knob).
+  __ukit_ep_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_ep_stage_ms" in
+    ''|*[!0-9]*) __ukit_ep_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_ep_stage_ms" -gt 0 ] 2>/dev/null || __ukit_ep_stage_ms=2000
+  printf -v __ukit_ep_stage_s '%d.%03d' $((__ukit_ep_stage_ms / 1000)) $((__ukit_ep_stage_ms % 1000))
   # TASK-002: detach the watchdog's inherited stdout/stderr — otherwise a
   # captured-stdio caller (hook-chain-runner) sees the pipe held open ~2s
   # after the script exits, inflating the SessionEnd residual to ~2000ms.
-  ( sleep 2; kill "$UKIT_HEAD_PID" 2>/dev/null ) >/dev/null 2>&1 &
+  ( sleep "$__ukit_ep_stage_s"; kill "$UKIT_HEAD_PID" 2>/dev/null ) >/dev/null 2>&1 &
   UKIT_WATCH_PID=$!
   wait "$UKIT_HEAD_PID" 2>/dev/null
   kill "$UKIT_WATCH_PID" 2>/dev/null

package/template_project/.claude/skills/pdf-processing-pro/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: PDF Processing Pro
+name: pdf-processing-pro
 description: Production-ready PDF processing with forms, tables, OCR, validation, and batch operations. Use when working with complex PDF workflows in production environments, processing large volumes of PDFs, or requiring robust error handling and validation.
 ---
 

package/template_project/.claude/ukit/index/handoff-doc-validator.mjs

@@ -63,7 +63,9 @@ function planSectionPositions(sections) {
   const positions = new Map();
   for (const s of sections) {
     for (const token of PLAN_SECTIONS) {
-      if (!positions.has(token) && s.name.startsWith(token)) positions.set(token, s.pos);
+      // `## §10`/`## §12` must not satisfy `§1` — the token only matches when it
+      // is the whole heading or is followed by a non-digit boundary (space, colon…).
+      if (!positions.has(token) && new RegExp(`^${token}(?!\\d)`).test(s.name)) positions.set(token, s.pos);
     }
   }
   return positions;

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

@@ -308,7 +308,10 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     ]);
     canReuseParsedArtifacts = previousSymbolsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
       && previousImportsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
-      && previousCallsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+      && previousCallsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+      && Array.isArray(previousSymbolsArtifact.items)
+      && Array.isArray(previousImportsArtifact.items)
+      && Array.isArray(previousCallsArtifact.items);
 
     if (canReuseParsedArtifacts) {
       const previousSymbolsByPath = groupBy(previousSymbolsArtifact.items ?? [], (item) => item.filePath);
@@ -363,7 +366,8 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     ? await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.testsMap)
     : null;
   const canReuseTestsMap = canReuseTestsMapCandidate
-    && previousTestsMapArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+    && previousTestsMapArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(previousTestsMapArtifact.items);
   const testsMap = canReuseTestsMap
     ? previousTestsMapArtifact.items
     : buildTestsMap(fileRecords);
@@ -372,6 +376,7 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     ? await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.hotspots)
     : null;
   const canReuseHotspots = previousHotspotsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(previousHotspotsArtifact.items)
     && areBugIndexSnapshotsEqual(previousHotspotsArtifact?.sourceSnapshot, bugIndexSnapshot);
   const hotspots = canReuseHotspots
     ? previousHotspotsArtifact.items
@@ -386,8 +391,9 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     : null;
   const canReuseArchetypes = canReuseArchetypesCandidate
     && previousArchetypesArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
-    && previousArchetypesArtifact?.items?.length === codeFiles.length
-    && (previousArchetypesArtifact.items ?? []).every((item) => currentCodePaths.has(item.filePath));
+    && Array.isArray(previousArchetypesArtifact.items)
+    && 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
@@ -413,6 +419,7 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
   };
   const canReuseRelations = canReuseGraphArtifactsCandidate
     && previousRelationsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(previousRelationsArtifact.items)
     && areStringArraysEqual(previousRelationsArtifact?.sourceSnapshot?.styleFiles, styleFilePaths)
     && arePathSnapshotsEqual(
       previousRelationsArtifact?.sourceSnapshot?.importAliasSnapshot,
@@ -420,6 +427,7 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     );
   const canReuseAnalogs = canReuseGraphArtifactsCandidate
     && previousAnalogsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(previousAnalogsArtifact.items)
     && areStringArraysEqual(previousAnalogsArtifact?.sourceSnapshot?.styleFiles, styleFilePaths)
     && arePathSnapshotsEqual(
       previousAnalogsArtifact?.sourceSnapshot?.importAliasSnapshot,
@@ -943,13 +951,15 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
 
   // Derived artifacts are recomputed in memory from the merged inputs — the
   // expensive work being avoided is discovery and re-parsing, not these pure
-  // transformations, so their output stays identical to a clean rebuild.
   const canReuseTestsMap = haveStableTrackedFileIdentities(filesArtifact.items, mergedFileRecords)
-    && testsMapArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+    && testsMapArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(testsMapArtifact.items);
   const testsMap = canReuseTestsMap ? testsMapArtifact.items : buildTestsMap(mergedFileRecords);
 
   const bugIndexSnapshot = await readBugIndexSnapshot(absoluteRoot);
+
   const canReuseHotspots = hotspotsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(hotspotsArtifact.items)
     && areBugIndexSnapshotsEqual(hotspotsArtifact?.sourceSnapshot, bugIndexSnapshot);
   const hotspots = canReuseHotspots ? hotspotsArtifact.items : await buildHotspots(absoluteRoot, bugIndexSnapshot);
 
@@ -961,9 +971,10 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
   const canReuseArchetypes = parsedFiles.length === 0
     && !recordsChanged
     && archetypesArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(archetypesArtifact.items)
     && codeFiles.every((file) => previousCodePaths.has(file.filePath))
-    && archetypesArtifact?.items?.length === archetypes.length
-    && (archetypesArtifact.items ?? []).every((item) => currentCodePaths.has(item?.filePath));
+    && archetypesArtifact.items.length === archetypes.length
+    && archetypesArtifact.items.every((item) => currentCodePaths.has(item?.filePath));
   const archetypeItems = canReuseArchetypes ? archetypesArtifact.items : archetypes;
 
   const needsAliasContext = importsNeedAliasContext(imports);
@@ -981,7 +992,8 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
     && areStringArraysEqual(relationsArtifact?.sourceSnapshot?.styleFiles, styleFilePaths)
     && arePathSnapshotsEqual(relationsArtifact?.sourceSnapshot?.importAliasSnapshot, styleSnapshot.importAliasSnapshot);
   const canReuseAnalogs = canReuseRelations
-    && analogsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+    && analogsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(analogsArtifact.items);
 
   let relations = relationsArtifact.items;
   let analogs = analogsArtifact?.items ?? null;
@@ -1163,11 +1175,11 @@ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit
 }
 
 export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5 } = {}) {
-  if (!query || !query.trim()) return [];
+  const normalizedQuery = String(query ?? '').trim();
+  if (!normalizedQuery) 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({
@@ -1247,12 +1259,11 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
 }
 
 // ── Analog Query ──
-
 export async function queryAnalog({ rootDir = process.cwd(), filePath, limit = 5 } = {}) {
-  if (!filePath || !filePath.trim()) return [];
+  const normalizedFilePath = String(filePath ?? '').trim();
+  if (!normalizedFilePath) return [];
 
   const absoluteRoot = path.resolve(rootDir);
-  const normalizedFilePath = String(filePath).trim();
   const analogCacheKey = JSON.stringify({
     rootDir: absoluteRoot,
     filePath: normalizedFilePath,
@@ -1325,9 +1336,14 @@ function freezeQueryResults(results) {
 function freezeAnalogResults(results) {
   return Object.freeze(results.map((item) => Object.freeze({ ...item })));
 }
-
 function ensureArtifact(artifact) {
-  return artifact && typeof artifact === 'object' ? artifact : { items: [] };
+  if (!artifact || typeof artifact !== 'object') {
+    return { items: [] };
+  }
+  // A schema-current artifact whose `items` is not an array (truncated or
+  // hand-corrupted JSON) must degrade to an empty item list — callers iterate
+  // `items` unconditionally and a non-array value crashes the query path.
+  return Array.isArray(artifact.items) ? artifact : { ...artifact, items: [] };
 }
 
 function escapeJsonString(value) {
@@ -1343,11 +1359,10 @@ const TASK_TYPE_BUDGETS = {
   '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',
+  'auth', 'authentication', 'authorization', 'security', 'migration', 'uninstall',
+  'password', 'token', 'permission', 'delete all', 'drop table', 'race', 'flaky',
+  'flakiness', 'intermittent', 'timeout', 'deadlock', 'core', 'shared', 'runtime',
 ];
 const EXPANSION_SIGNALS = [
   'similar',
@@ -1368,10 +1383,23 @@ const EXPANSION_SIGNALS = [
   'project',
   'repo',
   'workspace',
-  'all ',
-  'every ',
+  'all',
+  'every',
 ];
 
+// Signals must match whole words: bare `includes` let 'score' fire 'core',
+// 'author' fire 'auth', 'context' fire 'text', and 'install ' fire 'all '.
+// Common inflections (plural/past/-ing) still count — 'timeouts', 'migrations',
+// 'deadlocked' — but 'authentication'/'authorization'/'flakiness' need explicit
+// entries since their stems diverge from the base signal.
+function escapeSignalRegExp(signal) {
+  return signal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function containsSignalWord(lower, signals) {
+  return signals.some((signal) => new RegExp(`\\b${escapeSignalRegExp(signal)}(?:s|es|ed|d|ing)?\\b`).test(lower));
+}
+
 export async function resolveContext({
   rootDir = process.cwd(),
   intent = '',
@@ -1506,12 +1534,12 @@ export async function resolveContext({
 export function classifyTask(intent) {
   const lower = intent.toLowerCase();
 
-  if (RISKY_SIGNALS.some((signal) => lower.includes(signal))) {
+  if (containsSignalWord(lower, RISKY_SIGNALS)) {
     return 'non-trivial';
   }
 
-  if (TRIVIAL_SIGNALS.some((signal) => lower.includes(signal))) {
-    if (lower.includes('all ') || lower.includes('every ') || lower.includes('multiple')) {
+  if (containsSignalWord(lower, TRIVIAL_SIGNALS)) {
+    if (/\ball\b/.test(lower) || /\bevery\b/.test(lower) || /\bmultiple\b/.test(lower)) {
       return 'simple';
     }
     return 'trivial';
@@ -1535,7 +1563,7 @@ function shouldQueryIndex({
   if (taskType === 'non-trivial') {
     return true;
   }
-  return EXPANSION_SIGNALS.some((signal) => normalizedIntent.includes(signal));
+  return containsSignalWord(normalizedIntent, EXPANSION_SIGNALS);
 }
 
 function enforceContextBudget(result, maxFiles) {
@@ -2628,7 +2656,7 @@ function extractImports(filePath, content) {
   const stripped = content
     .replace(/\/\*[\s\S]*?\*\//g, '')
     .replace(/\/\/.*$/gm, '');
-  for (const match of stripped.matchAll(/import\s+(?:[^'";]+?\s+from\s+)?['"]([^'"]+)['"]/g)) {
+  for (const match of stripped.matchAll(/(?:^|[;\n])\s*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)) {
@@ -2637,10 +2665,10 @@ function extractImports(filePath, content) {
   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)) {
+  for (const match of stripped.matchAll(/(?:^|[;\n])\s*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)) {
+  for (const match of stripped.matchAll(/(?:^|[;\n])\s*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;
@@ -3533,9 +3561,9 @@ async function loadAliasConfig(configPath, visited = new Set(), tracker = null)
 
   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);
+  if (extendsValue) {
+    const inheritedPath = await resolveExtendedConfigPath(configDir, extendsValue);
+    inherited = inheritedPath ? await loadAliasConfig(inheritedPath, visited, tracker) : null;
   }
 
   const inheritedRules = inherited?.pathRules ?? [];
@@ -3573,12 +3601,54 @@ function buildBaseUrlDirs({ rootDir, compilerOptions }) {
   if (!baseUrl) return [];
   return [path.resolve(rootDir, baseUrl)];
 }
+async function resolveExtendedConfigPath(configDir, extendsValue) {
+  if (extendsValue.startsWith('.') || extendsValue.startsWith('/')) {
+    const withExtension = extendsValue.endsWith('.json')
+      ? extendsValue
+      : `${extendsValue}.json`;
+    return path.resolve(configDir, withExtension);
+  }
+
+  // Package specifiers split on the RAW value: appending `.json` first would
+  // turn a bare `extends: "acme-base"` into the package name `acme-base.json`,
+  // which never exists under node_modules.
+  const parts = extendsValue.split('/').filter(Boolean);
+  if (parts.length === 0) {
+    return null;
+  }
 
-function resolveExtendedConfigPath(configDir, extendsValue) {
-  const withExtension = extendsValue.endsWith('.json')
-    ? extendsValue
-    : `${extendsValue}.json`;
-  return path.resolve(configDir, withExtension);
+  const packageName = extendsValue.startsWith('@')
+    ? parts.slice(0, 2).join('/')
+    : parts[0];
+  const packageRest = parts.slice(packageName.startsWith('@') ? 2 : 1).join('/');
+  const packageRoot = await findNodeModulePackageRoot(configDir, packageName);
+  if (!packageRoot) {
+    return null;
+  }
+
+  const rest = packageRest && !packageRest.endsWith('.json')
+    ? `${packageRest}.json`
+    : packageRest;
+  return path.join(packageRoot, rest || 'tsconfig.json');
+}
+
+async function findNodeModulePackageRoot(startDir, packageName) {
+  let currentDir = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(currentDir, 'node_modules', packageName);
+    try {
+      const stat = await fs.stat(candidate);
+      if (stat.isDirectory()) {
+        return candidate;
+      }
+    } catch {}
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+    currentDir = parentDir;
+  }
 }
 
 async function isAliasSnapshotValid(snapshot = []) {
@@ -4187,9 +4257,10 @@ export async function resolveImpactContext({
   const normalizedChangedFiles = uniqueImpact(changedFiles.map(normalizeImpactPath));
   const normalizedChangedSymbols = uniqueImpact(changedSymbols.map((symbol) => String(symbol ?? '').trim()));
 
-  const [callsArtifact, importsArtifact, relatedArtifacts] = await Promise.all([
+  const [callsArtifact, importsArtifact, filesArtifact, relatedArtifacts] = await Promise.all([
     readArtifact(absoluteRoot, INDEX_ARTIFACTS.calls),
     readArtifact(absoluteRoot, INDEX_ARTIFACTS.imports),
+    readArtifact(absoluteRoot, INDEX_ARTIFACTS.files),
     loadRelatedTestArtifacts({ rootDir: absoluteRoot }),
   ]);
 
@@ -4221,23 +4292,39 @@ export async function resolveImpactContext({
     for (const record of callItems) {
       const matchedSymbol = (record.calls ?? []).find((name) => callerTargets.has(name));
       if (!matchedSymbol) continue;
-      if (changedFileSet.has(normalizeImpactPath(record.filePath)) && changedSymbolSet.has(record.symbol)) continue;
+      if (changedFileSet.has(normalizeImpactPath(record.filePath))) continue;
       callers.push({ filePath: record.filePath, symbol: record.symbol, reason: `calls ${matchedSymbol}` });
     }
   }
 
   const importers = [];
   const dependencies = [];
+  // Non-relative specifiers (aliases like `@/x`, `~/x`, tsconfig paths) resolve
+  // through the same machinery the index builder uses; relative specifiers keep
+  // the candidate-list match so a changed file absent from files.json (e.g. a
+  // brand-new file) still counts.
+  const indexedFileSet = new Set((filesArtifact.items ?? []).map((item) => item.filePath));
+  const importAliasContext = importsNeedAliasContext(importItems)
+    ? await loadImportAliasContext({ rootDir: absoluteRoot }).catch(() => null)
+    : null;
   for (const imp of importItems) {
     const from = normalizeImpactPath(imp.from);
-    const matched = resolveImpactImportTargets(from, imp.to)
-      .find((candidate) => changedFileSet.has(normalizeImpactPath(candidate)));
+    const specifier = String(imp.to ?? '').trim();
+    const targets = specifier.startsWith('.')
+      ? resolveImpactImportTargets(from, specifier)
+      : [resolveImportSpecifier({
+          rootDir: absoluteRoot,
+          fromFilePath: from,
+          specifier,
+          indexedFileSet,
+          aliasContext: importAliasContext,
+        })].filter(Boolean);
+    const matched = targets.find((candidate) => changedFileSet.has(normalizeImpactPath(candidate)));
     if (matched) {
       importers.push(from);
       dependencies.push(matched);
     }
   }
-
   const candidateFiles = uniqueImpact([
     ...normalizedChangedFiles,
     ...importers,