@ngockhoale/ukit 3.0.3 → 3.0.5

package/scripts/bug/triage.mjs

@@ -3,16 +3,28 @@ import path from 'node:path';
 
 import { triageBug } from '../../src/bug/triageBug.js';
 
-const args = process.argv.slice(2);
-const rootArg = readFlagValue(args, '--root');
-const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+async function main() {
+  const args = process.argv.slice(2);
+  const { value: rootArg, args: remainingArgs } = extractFlagValue(args, '--root');
+  const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
 
-const signature = args.filter((arg) => !arg.startsWith('--')).join(' ').trim();
+  // Everything after `--` is signature text; before it, only positional args
+  // are — the --root value was already consumed by extractFlagValue.
+  const separatorIndex = remainingArgs.indexOf('--');
+  const positional = separatorIndex === -1 ? remainingArgs : remainingArgs.slice(0, separatorIndex);
+  const afterSeparator = separatorIndex === -1 ? [] : remainingArgs.slice(separatorIndex + 1);
+  const unknown = positional.filter((arg) => arg.startsWith('--'));
+  if (unknown.length > 0) {
+    throw new Error(`unknown argument: ${unknown[0]}`);
+  }
+  const signature = [...positional, ...afterSeparator].join(' ').trim();
+
+  if (!signature) {
+    console.error('Usage: yarn bug:triage -- "<error signature>"');
+    process.exitCode = 1;
+    return;
+  }
 
-if (!signature) {
-  console.error('Usage: yarn bug:triage -- "<error signature>"');
-  process.exitCode = 1;
-} else {
   const result = await triageBug({ rootDir, signature });
   console.log('[bug:triage]');
   console.log(`lane: ${result.lane}`);
@@ -22,16 +34,43 @@ if (!signature) {
   console.log(`test: ${result.recommendedTestCommand}`);
 }
 
-function readFlagValue(argv, flag) {
-  const exact = argv.indexOf(flag);
-  if (exact >= 0 && argv[exact + 1]) {
-    return argv[exact + 1];
-  }
+function extractFlagValue(argv, flag) {
+  let value = null;
+  const nextArgs = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
 
-  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
-  if (withEquals) {
-    return withEquals.slice(flag.length + 1);
+    if (arg === flag) {
+      if (value !== null) {
+        nextArgs.push(arg);
+        continue;
+      }
+      const maybeValue = argv[i + 1];
+      if (!maybeValue || maybeValue.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}.`);
+      }
+      value = maybeValue;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith(`${flag}=`)) {
+      if (value === null) {
+        value = arg.slice(flag.length + 1);
+        continue;
+      }
+    }
+
+    nextArgs.push(arg);
   }
 
-  return null;
+  return { value, args: nextArgs };
+}
+
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
 }

package/scripts/index/build-index.mjs

@@ -1,36 +1,102 @@
 #!/usr/bin/env node
+import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { buildCodeIndex, buildDerivedIndexArtifacts } from '../../src/index/buildIndex.js';
-
-const args = process.argv.slice(2);
-const rootArg = readFlagValue(args, '--root');
-const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
-
-const summary = await buildCodeIndex({ rootDir });
-await buildDerivedIndexArtifacts(rootDir);
-
-console.log('[index:build] completed');
-console.log(`root: ${rootDir}`);
-console.log(`files: ${summary.fileCount}`);
-console.log(`symbols: ${summary.symbolCount}`);
-console.log(`imports: ${summary.importCount}`);
-console.log(`tests-map: ${summary.testsMapCount}`);
-console.log(`hotspots: ${summary.hotspotCount}`);
-console.log(`parsed: ${summary.parsedCodeFileCount}`);
-console.log(`reused: ${summary.reusedCodeFileCount}`);
-console.log(`indexDir: ${summary.indexDir}`);
-
-function readFlagValue(argv, flag) {
-  const exact = argv.indexOf(flag);
-  if (exact >= 0 && argv[exact + 1]) {
-    return argv[exact + 1];
+import {
+  buildCodeIndex,
+  buildDerivedIndexArtifacts,
+  inspectIndexStaleness,
+  mapLimit,
+  INDEX_IO_CONCURRENCY,
+} from '../../src/index/buildIndex.js';
+
+async function main() {
+  const args = process.argv.slice(2);
+  const { value: rootArg, args: remainingArgs } = extractFlagValue(args, '--root');
+  const unexpected = remainingArgs.filter((arg) => arg.startsWith('--'));
+  if (unexpected.length > 0) {
+    throw new Error(`unexpected argument: ${unexpected[0]}`);
+  }
+  const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+
+  // One enumeration serves both the readability check and the build: the
+  // snapshot is handed to buildCodeIndex, which reuses it instead of
+  // rediscovering the repository.
+  const { snapshot } = await inspectIndexStaleness({ rootDir, maxAgeMs: 0 });
+  const unreadable = await collectUnreadableFiles(rootDir, snapshot?.files ?? []);
+  for (const filePath of unreadable) {
+    console.error(`[index:build] skipped unreadable file: ${filePath}`);
   }
 
-  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
-  if (withEquals) {
-    return withEquals.slice(flag.length + 1);
+  const summary = await buildCodeIndex({ rootDir, discoverySnapshot: snapshot });
+  await buildDerivedIndexArtifacts(rootDir);
+
+  console.log('[index:build] completed');
+  console.log(`root: ${rootDir}`);
+  console.log(`files: ${summary.fileCount}`);
+  console.log(`symbols: ${summary.symbolCount}`);
+  console.log(`imports: ${summary.importCount}`);
+  console.log(`tests-map: ${summary.testsMapCount}`);
+  console.log(`hotspots: ${summary.hotspotCount}`);
+  console.log(`parsed: ${summary.parsedCodeFileCount}`);
+  console.log(`reused: ${summary.reusedCodeFileCount}`);
+  if (unreadable.length > 0) {
+    console.log(`skipped-unreadable: ${unreadable.length}`);
   }
+  console.log(`indexDir: ${summary.indexDir}`);
+}
+
+// The parse worker inside buildCodeIndex skips files it cannot read; the CLI
+// surfaces them so a partial index is never silent.
+async function collectUnreadableFiles(rootDir, entries) {
+  const unreadable = await mapLimit(entries, INDEX_IO_CONCURRENCY, async (entry) => {
+    try {
+      await fs.access(entry.absolutePath, fs.constants.R_OK);
+      return null;
+    } catch {
+      return path.relative(rootDir, entry.absolutePath).split(path.sep).join('/');
+    }
+  });
+  return unreadable.filter(Boolean).sort();
+}
+
+function extractFlagValue(argv, flag) {
+  let value = null;
+  const nextArgs = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === flag) {
+      if (value !== null) {
+        nextArgs.push(arg);
+        continue;
+      }
+      const maybeValue = argv[i + 1];
+      if (!maybeValue || maybeValue.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}.`);
+      }
+      value = maybeValue;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith(`${flag}=`)) {
+      if (value === null) {
+        value = arg.slice(flag.length + 1);
+        continue;
+      }
+    }
+
+    nextArgs.push(arg);
+  }
+
+  return { value, args: nextArgs };
+}
 
-  return null;
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
 }

package/scripts/index/query-index.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import fs from 'node:fs/promises';
 import path from 'node:path';
 
 import {
@@ -7,28 +8,40 @@ import {
 import {
   buildCodeIndex,
   buildDerivedIndexArtifacts,
+  inspectIndexStaleness,
   isIndexStale,
+  mapLimit,
+  INDEX_IO_CONCURRENCY,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
 } from '../../src/index/buildIndex.js';
 import { parseIndexArgs, QUERY_FLAG_DEFINITIONS } from '../../src/cli/commands/indexArgs.js';
 
-const args = process.argv.slice(2);
-const { value: rootArg, args: afterRootArgs } = extractFlagValue(args, '--root');
-const { value: changedArg, args: remainingArgs } = extractFlagValue(afterRootArgs, '--changed');
-const changedFiles = changedArg
-  ? changedArg.split(',').map((item) => item.trim()).filter(Boolean)
-  : [];
-const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+async function main() {
+  const args = process.argv.slice(2);
+  const { value: rootArg, args: afterRootArgs } = extractFlagValue(args, '--root');
+  const { value: changedArg, args: remainingArgs } = extractFlagValue(afterRootArgs, '--changed');
+  const changedFiles = changedArg
+    ? changedArg.split(',').map((item) => item.trim()).filter(Boolean)
+    : [];
+  const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+
+  const { tokens, flags } = parseIndexArgs(remainingArgs, QUERY_FLAG_DEFINITIONS);
+  const query = tokens.join(' ').trim();
+  if (!query) {
+    console.error('Usage: yarn index:query -- "<error|symbol|path>" [--limit N] [--changed fileA,fileB]');
+    process.exitCode = 1;
+    return;
+  }
 
-const { tokens, flags } = parseIndexArgs(remainingArgs, QUERY_FLAG_DEFINITIONS);
-const query = tokens.join(' ').trim();
-if (!query) {
-  console.error('Usage: yarn index:query -- "<error|symbol|path>" [--limit N] [--changed fileA,fileB]');
-  process.exitCode = 1;
-} else {
   const stale = await isIndexStale({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
   if (stale) {
-    await buildCodeIndex({ rootDir });
+    // One enumeration serves the readability check and the rebuild.
+    const { snapshot } = await inspectIndexStaleness({ rootDir, maxAgeMs: 0 });
+    const unreadable = await collectUnreadableFiles(rootDir, snapshot?.files ?? []);
+    for (const filePath of unreadable) {
+      console.error(`[index:query] skipped unreadable file: ${filePath}`);
+    }
+    await buildCodeIndex({ rootDir, discoverySnapshot: snapshot });
     await buildDerivedIndexArtifacts(rootDir);
   }
 
@@ -59,6 +72,20 @@ if (!query) {
   }
 }
 
+// The parse worker inside buildCodeIndex skips files it cannot read; the CLI
+// surfaces them so a partial index is never silent.
+async function collectUnreadableFiles(rootDir, entries) {
+  const unreadable = await mapLimit(entries, INDEX_IO_CONCURRENCY, async (entry) => {
+    try {
+      await fs.access(entry.absolutePath, fs.constants.R_OK);
+      return null;
+    } catch {
+      return path.relative(rootDir, entry.absolutePath).split(path.sep).join('/');
+    }
+  });
+  return unreadable.filter(Boolean).sort();
+}
+
 function extractFlagValue(argv, flag) {
   let value = null;
   const nextArgs = [];
@@ -92,3 +119,10 @@ function extractFlagValue(argv, flag) {
 
   return { value, args: nextArgs };
 }
+
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+}

package/scripts/index/refresh-index.mjs

@@ -5,46 +5,63 @@ import path from 'node:path';
 import {
   buildCodeIndex,
   inspectIndexStaleness,
+  mapLimit,
+  INDEX_IO_CONCURRENCY,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
 } from '../../src/index/buildIndex.js';
 
-const args = process.argv.slice(2);
-const rootArg = readFlagValue(args, '--root');
-const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+async function main() {
+  const args = process.argv.slice(2);
+  const { value: rootArg, args: afterRootArgs } = extractFlagValue(args, '--root');
+  const { value: changedArg, args: remainingArgs } = extractFlagValue(afterRootArgs, '--changed');
+  const force = remainingArgs.includes('--force');
+  const unexpected = remainingArgs.filter((arg) => arg !== '--force');
+  if (unexpected.length > 0) {
+    throw new Error(`unexpected argument: ${unexpected[0]}`);
+  }
 
-const changedArg = readFlagValue(args, '--changed');
-const changedFiles = changedArg
-  ? changedArg.split(',').map((item) => item.trim()).filter(Boolean)
-  : [];
+  const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
+  const hintedFiles = changedArg
+    ? changedArg.split(',').map((item) => item.trim()).filter(Boolean)
+    : [];
 
-const force = readBooleanFlag(args, '--force');
-const lastRefreshMs = await getLastRefreshTime(rootDir);
+  // Hints that exist but cannot be read would be silently dropped by the parse
+  // worker; surface them and keep them out of the merge set. ENOENT hints are
+  // kept — a deleted file is a legitimate removal hint.
+  const { readable: changedFiles, unreadable: unreadableHints } = await partitionReadableHints(rootDir, hintedFiles);
+  for (const filePath of unreadableHints) {
+    console.error(`[index:refresh] skipped unreadable file: ${filePath}`);
+  }
 
-if (changedFiles.length > 0 && !force) {
-  // Hints carry the change set, so no staleness enumeration is needed:
-  // buildCodeIndex merges the hinted paths into the existing artifacts and
-  // falls back to the bounded full discovery path on its own when the hints
-  // are unsafe or the previous artifacts cannot be merged (TASK-023).
-  const summary = await buildCodeIndex({ rootDir, changedFiles });
+  const lastRefreshMs = await getLastRefreshTime(rootDir);
 
-  console.log('[index:refresh] completed');
-  console.log(`mode: ${summary.mode}`);
-  if (lastRefreshMs !== null) {
-    console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
-  }
-  console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
-  console.log(`root: ${rootDir}`);
-  console.log(`files: ${summary.fileCount}`);
-  console.log(`parsed: ${summary.parsedCodeFileCount}`);
-  console.log(`reused: ${summary.reusedCodeFileCount}`);
-  if (summary.removedFiles.length > 0) {
-    console.log(`removed: ${summary.removedFiles.length}`);
+  if (changedFiles.length > 0 && !force) {
+    // Hints carry the change set, so no staleness enumeration is needed:
+    // buildCodeIndex merges the hinted paths into the existing artifacts and
+    // falls back to the bounded full discovery path on its own when the hints
+    // are unsafe or the previous artifacts cannot be merged (TASK-023).
+    const summary = await buildCodeIndex({ rootDir, changedFiles });
+
+    console.log('[index:refresh] completed');
+    console.log(`mode: ${summary.mode}`);
+    if (lastRefreshMs !== null) {
+      console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
+    }
+    console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+    console.log(`root: ${rootDir}`);
+    console.log(`files: ${summary.fileCount}`);
+    console.log(`parsed: ${summary.parsedCodeFileCount}`);
+    console.log(`reused: ${summary.reusedCodeFileCount}`);
+    if (summary.removedFiles.length > 0) {
+      console.log(`removed: ${summary.removedFiles.length}`);
+    }
+    console.log(`indexDir: ${summary.indexDir}`);
+    return;
   }
-  console.log(`indexDir: ${summary.indexDir}`);
-} else {
-  const staleness = force
-    ? null
-    : await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
+
+  // One enumeration serves the staleness check, the readability check, and the
+  // build: the snapshot is handed to buildCodeIndex, which reuses it.
+  const staleness = await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
   const stale = force || staleness.stale;
 
   if (!stale) {
@@ -56,45 +73,101 @@ if (changedFiles.length > 0 && !force) {
       console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
     }
     console.log(`root: ${rootDir}`);
-  } else {
-    // Reuse the staleness check's discovery snapshot: one enumeration per refresh.
-    const summary = await buildCodeIndex({
-      rootDir,
-      discoverySnapshot: staleness ? staleness.snapshot : null,
-    });
+    return;
+  }
 
-    console.log('[index:refresh] completed');
-    console.log(`mode: ${summary.mode}`);
-    if (lastRefreshMs !== null) {
-      console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
+  const unreadable = await collectUnreadableFiles(rootDir, staleness.snapshot?.files ?? []);
+  for (const filePath of unreadable) {
+    console.error(`[index:refresh] skipped unreadable file: ${filePath}`);
+  }
+
+  const summary = await buildCodeIndex({
+    rootDir,
+    discoverySnapshot: staleness.snapshot,
+  });
+
+  console.log('[index:refresh] completed');
+  console.log(`mode: ${summary.mode}`);
+  if (lastRefreshMs !== null) {
+    console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
+  }
+  if (changedFiles.length > 0) {
+    console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+  }
+  console.log(`root: ${rootDir}`);
+  console.log(`files: ${summary.fileCount}`);
+  console.log(`parsed: ${summary.parsedCodeFileCount}`);
+  console.log(`reused: ${summary.reusedCodeFileCount}`);
+  if (unreadable.length > 0) {
+    console.log(`skipped-unreadable: ${unreadable.length}`);
+  }
+  console.log(`indexDir: ${summary.indexDir}`);
+}
+
+// The parse worker inside buildCodeIndex skips files it cannot read; the CLI
+// surfaces them so a partial index is never silent.
+async function collectUnreadableFiles(rootDir, entries) {
+  const unreadable = await mapLimit(entries, INDEX_IO_CONCURRENCY, async (entry) => {
+    try {
+      await fs.access(entry.absolutePath, fs.constants.R_OK);
+      return null;
+    } catch {
+      return path.relative(rootDir, entry.absolutePath).split(path.sep).join('/');
     }
-    if (changedFiles.length > 0) {
-      console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
+  });
+  return unreadable.filter(Boolean).sort();
+}
+
+async function partitionReadableHints(rootDir, hints) {
+  const readable = [];
+  const unreadable = [];
+  for (const hint of hints) {
+    try {
+      await fs.access(path.resolve(rootDir, hint), fs.constants.R_OK);
+      readable.push(hint);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        readable.push(hint); // deleted file — a legitimate removal hint
+      } else {
+        unreadable.push(hint);
+      }
     }
-    console.log(`root: ${rootDir}`);
-    console.log(`files: ${summary.fileCount}`);
-    console.log(`parsed: ${summary.parsedCodeFileCount}`);
-    console.log(`reused: ${summary.reusedCodeFileCount}`);
-    console.log(`indexDir: ${summary.indexDir}`);
   }
+  return { readable, unreadable };
 }
 
-function readFlagValue(argv, flag) {
-  const exact = argv.indexOf(flag);
-  if (exact >= 0 && argv[exact + 1]) {
-    return argv[exact + 1];
-  }
+function extractFlagValue(argv, flag) {
+  let value = null;
+  const nextArgs = [];
 
-  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
-  if (withEquals) {
-    return withEquals.slice(flag.length + 1);
-  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
 
-  return null;
-}
+    if (arg === flag) {
+      if (value !== null) {
+        nextArgs.push(arg);
+        continue;
+      }
+      const maybeValue = argv[i + 1];
+      if (!maybeValue || maybeValue.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}.`);
+      }
+      value = maybeValue;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith(`${flag}=`)) {
+      if (value === null) {
+        value = arg.slice(flag.length + 1);
+        continue;
+      }
+    }
 
-function readBooleanFlag(argv, flag) {
-  return argv.includes(flag);
+    nextArgs.push(arg);
+  }
+
+  return { value, args: nextArgs };
 }
 
 async function getLastRefreshTime(rootDir) {
@@ -113,3 +186,10 @@ async function getLastRefreshTime(rootDir) {
     return null;
   }
 }
+
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+}

package/scripts/perf/audit-perf.mjs

@@ -53,6 +53,12 @@ const CLUSTER_GAP_MS = 1500;
 // is a finding in its own right, not merely a term inside a chain total.
 const HOTSPOT_P50_MS = 50;
 
+// TASK-010: every spawned child carries an explicit timeout + killSignal — a
+// wedged hook script or git child must fail the benchmark sample, not hang the
+// audit forever (same class as BUG-C22-20/21). UKIT_PERF_SPAWN_TIMEOUT_MS
+// overrides the budget for tests.
+const SPAWN_TIMEOUT_MS = Number(process.env.UKIT_PERF_SPAWN_TIMEOUT_MS) || 60 * 1000; // 1 min
+
 // A hook row costs the wrapper `bash`, its `node` runtime, and the advisory
 // telemetry `node --finish` child armed by hook-telemetry.sh.
 const PROCESSES_PER_HOOK_ROW = 3;
@@ -420,7 +426,7 @@ function benchSpawn(file, args, iterations, env) {
   const samples = [];
   for (let i = 0; i < iterations; i += 1) {
     const start = process.hrtime.bigint();
-    spawnSync(file, args, { env, input: '{}', stdio: ['pipe', 'ignore', 'ignore'] });
+    spawnSync(file, args, { env, input: '{}', stdio: ['pipe', 'ignore', 'ignore'], timeout: SPAWN_TIMEOUT_MS, killSignal: 'SIGKILL' });
     samples.push(Number(process.hrtime.bigint() - start) / 1e6);
   }
   return summarise(samples);
@@ -560,7 +566,7 @@ function recentHotPathAdditions(root, sinceDays) {
         '.claude/hooks',
         '.claude/ukit/runtime',
       ],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: SPAWN_TIMEOUT_MS, killSignal: 'SIGKILL' },
     );
     const commits = [];
     let current = null;