@ngockhoale/ukit 1.1.6

package/src/cli/commands/indexTools.js

@@ -0,0 +1,509 @@
+import {
+  buildCodeIndex,
+  isIndexStale,
+  DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  getIndexArtifactGeneratedAt,
+} from '../../index/buildIndex.js';
+import { resolveContext } from '../../index/resolveContext.js';
+import { deriveVerificationPlan } from '../../index/verificationPlan.js';
+import { deriveTaskRoute } from '../../index/taskRouting.js';
+import { queryCodeIndex } from '../../index/queryIndex.js';
+import { triageBug } from '../../bug/triageBug.js';
+import { installIndexRefreshHooks, removeIndexRefreshHooks } from '../../index/gitHooks.js';
+import {
+  parseIndexArgs,
+  CONTEXT_FLAG_DEFINITIONS,
+  QUERY_FLAG_DEFINITIONS,
+  TRIAGE_FLAG_DEFINITIONS,
+  VERIFY_FLAG_DEFINITIONS,
+  ROUTE_FLAG_DEFINITIONS,
+} from './indexArgs.js';
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+const CONTEXT_DISPLAY_LIMIT = 2;
+const CONTEXT_REASON_LIMIT = 2;
+const VERIFY_COMMAND_DISPLAY_LIMIT = 2;
+const VERIFY_REASON_DISPLAY_LIMIT = 2;
+const VERIFY_NOTE_DISPLAY_LIMIT = 1;
+
+export async function runIndexTools({ projectRoot, argv = [] }) {
+  const [subcommandRaw, ...rest] = argv;
+  const subcommand = (subcommandRaw ?? '').toLowerCase();
+
+  if (!subcommand || HELP_FLAGS.has(subcommand)) {
+    printIndexHelp();
+    return;
+  }
+
+  if (subcommand === 'build' || subcommand === 'refresh') {
+    const summary = await buildCodeIndex({ rootDir: projectRoot });
+    const label = subcommand === 'build' ? 'build' : 'refresh';
+    console.log(`[UKit] Index ${label} completed.`);
+    console.log(`[UKit] files=${summary.fileCount}, symbols=${summary.symbolCount}, imports=${summary.importCount}`);
+    console.log(`[UKit] tests-map=${summary.testsMapCount}, hotspots=${summary.hotspotCount}`);
+    console.log(`[UKit] parsed=${summary.parsedCodeFileCount}, reused=${summary.reusedCodeFileCount}`);
+    console.log(`[UKit] cache=${summary.indexDir}`);
+    return;
+  }
+
+  if (subcommand === 'query') {
+    const { tokens, flags } = parseIndexArgs(rest, QUERY_FLAG_DEFINITIONS);
+    const query = tokens.join(' ').trim();
+    if (!query) {
+      throw new Error('Missing query. Usage: ukit index query "<error|symbol|path>"');
+    }
+
+    await refreshIndexIfStale(projectRoot);
+
+    const limitArg = flags.get('--limit');
+    const limit = Number.parseInt(limitArg ?? '5', 10);
+    const results = await queryCodeIndex({
+      rootDir: projectRoot,
+      query,
+      limit: Number.isNaN(limit) ? 5 : limit,
+    });
+
+    if (results.length === 0) {
+      console.log('[UKit] No index matches found.');
+      return;
+    }
+
+    console.log(`[UKit] Index query top ${results.length} for: ${query}`);
+    for (const [idx, item] of results.entries()) {
+      console.log(`${idx + 1}. ${item.filePath} (score=${item.score})`);
+      if ((item.tests ?? []).length > 0) {
+        console.log(`   tests: ${item.tests.slice(0, 2).join(', ')}`);
+      }
+      if ((item.reasons ?? []).length > 0) {
+        console.log(`   reasons: ${item.reasons.join(', ')}`);
+      }
+    }
+    return;
+  }
+
+  if (subcommand === 'triage') {
+    const { tokens: signatureTokens } = parseIndexArgs(rest, TRIAGE_FLAG_DEFINITIONS);
+    const signature = signatureTokens.join(' ').trim();
+    if (!signature) {
+      throw new Error('Missing signature. Usage: ukit index triage "<error signature>"');
+    }
+
+    await refreshIndexIfStale(projectRoot);
+
+    const result = await triageBug({ rootDir: projectRoot, signature });
+    console.log('[UKit] Bug triage result:');
+    console.log(`lane: ${result.lane}`);
+    console.log(`confidence: ${result.confidence.toFixed(2)}`);
+    console.log(`suspects: ${result.suspectFiles.join(', ') || 'none'}`);
+    console.log(`test: ${result.recommendedTestCommand}`);
+    return;
+  }
+
+  if (subcommand === 'context') {
+    const { tokens, flags } = parseIndexArgs(rest, CONTEXT_FLAG_DEFINITIONS);
+    const intent = tokens.join(' ').trim();
+    const targetFile = flags.get('--target') ?? null;
+    const taskType = flags.get('--type') ?? null;
+
+    if (!intent && !targetFile) {
+      throw new Error('Missing intent or target. Usage: ukit index context "<intent>" [--target <file>] [--type trivial|simple|non-trivial]');
+    }
+
+    await refreshIndexIfStale(projectRoot);
+
+    const result = await resolveContext({
+      rootDir: projectRoot,
+      intent,
+      targetFile,
+      taskType,
+    });
+
+    console.log('[UKit] Suggested context:');
+    console.log(`taskType: ${result.taskType}`);
+    console.log(`budget: ${result.contextBudget.minFiles}-${result.contextBudget.maxFiles} files`);
+    printContextGroup('primaryTargets', result.primaryTargets, result.explanations?.primaryTargets);
+    printContextGroup('sharedAbstractions', result.sharedAbstractions, result.explanations?.sharedAbstractions);
+    printContextGroup('analogFiles', result.analogFiles, result.explanations?.analogFiles);
+    printContextGroup('relatedTests', result.relatedTests, result.explanations?.relatedTests);
+    printContextGroup('styleFiles', result.styleFiles, result.explanations?.styleFiles);
+    return;
+  }
+
+  if (subcommand === 'verify') {
+    const { tokens, flags } = parseIndexArgs(rest, VERIFY_FLAG_DEFINITIONS);
+    const intent = tokens.join(' ').trim();
+    const targetFile = flags.get('--target') ?? null;
+    const taskType = flags.get('--type') ?? null;
+
+    if (!intent && !targetFile) {
+      throw new Error('Missing intent or target. Usage: ukit index verify "<intent>" [--target <file>] [--type trivial|simple|non-trivial]');
+    }
+
+    await refreshIndexIfStale(projectRoot);
+
+    const result = await deriveVerificationPlan({
+      rootDir: projectRoot,
+      intent,
+      targetFile,
+      taskType,
+    });
+
+    console.log('[UKit] Suggested verification:');
+    console.log(`taskType: ${result.taskType}`);
+    console.log(`mode: ${result.mode}`);
+    console.log(`commands: ${formatCompactCommandDisplayList(result.commands, VERIFY_COMMAND_DISPLAY_LIMIT)}`);
+    console.log(`fallback: ${formatCompactCommandDisplayList(result.fallbackCommands, VERIFY_COMMAND_DISPLAY_LIMIT)}`);
+    console.log(`reasons: ${formatCompactDisplayList(result.reasons, VERIFY_REASON_DISPLAY_LIMIT)}`);
+    if (result.executionPolicy) {
+      console.log(`policy: ${result.executionPolicy.policyMode}`);
+      console.log(`autoRunPrimary: ${result.executionPolicy.shouldAutoRunPrimaryCommands ? 'yes' : 'no'}`);
+      console.log(`autoRunFallbacks: ${result.executionPolicy.shouldAutoRunFallbacks ? 'yes' : 'no'}`);
+      console.log(`confirmBroad: ${result.executionPolicy.requiresHumanConfirmationForBroadOrRisky ? 'yes' : 'no'}`);
+    }
+    if ((result.notes ?? []).length > 0) {
+      console.log(`notes: ${formatCompactNoteDisplayList(result.notes, VERIFY_NOTE_DISPLAY_LIMIT)}`);
+    }
+    return;
+  }
+
+  if (subcommand === 'route') {
+    const { tokens, flags } = parseIndexArgs(rest, ROUTE_FLAG_DEFINITIONS);
+    const promptText = tokens.join(' ').trim();
+    const targetFile = flags.get('--target') ?? null;
+    const taskType = flags.get('--type') ?? null;
+    const commandText = flags.get('--tool-command') ?? '';
+    const lastExplicitUserPromptText = flags.get('--last-prompt') ?? '';
+    const adapter = flags.get('--adapter') ?? 'claude';
+    const commandNamespace = adapter === 'codex' ? '.codex' : '.claude';
+
+    if (!promptText && !commandText && !targetFile) {
+      throw new Error('Missing prompt, tool command, or target. Usage: ukit index route "<prompt>" [--tool-command <cmd>] [--target <file>] [--type trivial|simple|non-trivial] [--adapter claude|codex]');
+    }
+
+    await refreshIndexIfStale(projectRoot);
+
+    const result = await deriveTaskRoute({
+      rootDir: projectRoot,
+      promptText,
+      commandText,
+      targetFile,
+      taskType,
+      lastExplicitUserPromptText,
+      commandNamespace,
+    });
+
+    const compactSummary = formatDisplayRouteSummary(result.routeSummary, result.routingContext);
+    const nextDisplay = formatDisplayNextAction(result.routeSummary);
+    console.log('[UKit] Suggested task route:');
+    console.log(`skills: ${result.activeSkills.map((item) => item.id).join(', ') || 'none'}`);
+    console.log(`summary: ${compactSummary}`);
+    if (nextDisplay) {
+      console.log(`next: ${nextDisplay}`);
+    }
+    if (result.routeSummary?.delegateHint) {
+      console.log(`delegate: ${result.routeSummary.delegateHint}`);
+    }
+    if (result.routeSummary?.helperHint && !result.routeSummary?.nextActionCommand) {
+      console.log(`helper: ${result.routeSummary.helperHint}`);
+    }
+    return;
+  }
+
+  if (subcommand === 'hooks') {
+    const action = (rest[0] ?? 'install').toLowerCase();
+    if (action === 'help' || action === '--help' || action === '-h') {
+      printIndexHooksHelp();
+      return;
+    }
+
+    if (action === 'install') {
+      const result = await installIndexRefreshHooks({ projectRoot });
+      console.log('[UKit] Installed index auto-refresh git hooks.');
+      console.log(`[UKit] installed=${result.installed}, unchanged=${result.unchanged}`);
+      return;
+    }
+
+    if (action === 'remove' || action === 'uninstall') {
+      const result = await removeIndexRefreshHooks({ projectRoot });
+      console.log('[UKit] Removed index auto-refresh git hooks.');
+      console.log(`[UKit] removed=${result.removed}, unchanged=${result.unchanged}`);
+      return;
+    }
+
+    throw new Error(`Unknown hooks action: ${action}. Use "ukit index hooks help".`);
+  }
+
+  throw new Error(`Unknown index subcommand: ${subcommand}. Run "ukit index help".`);
+}
+
+export function printIndexHelp() {
+  console.log('UKit Index Commands');
+  console.log('Usage: ukit index <build|refresh|query|triage|context|verify|route> [args]');
+  console.log('');
+  console.log('Subcommands:');
+  console.log('  build                 Build codebase index cache');
+  console.log('  refresh               Refresh index cache (incremental hint accepted)');
+  console.log('  query "<query>"       Search indexed files/symbols/imports');
+  console.log('  triage "<signature>"  Suggest fast/deep lane + suspect files');
+  console.log('  context "<intent>"    Suggest minimal file context with reasons');
+  console.log('  verify "<intent>"     Suggest verification lane from indexed context');
+  console.log('  route "<prompt>"      Suggest skill + context + verification next step');
+  console.log('  hooks [install|remove]  Manage git-hook auto-refresh');
+  console.log('');
+  console.log('Aliases:');
+  console.log('  ukit build index      Equivalent to "ukit index build"');
+}
+
+function printIndexHooksHelp() {
+  console.log('UKit Index Hook Commands');
+  console.log('Usage: ukit index hooks [install|remove]');
+  console.log('');
+  console.log('Examples:');
+  console.log('  ukit index hooks install');
+  console.log('  ukit index hooks remove');
+}
+
+async function refreshIndexIfStale(rootDir) {
+  const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
+  const stale = await isIndexStale({
+    rootDir,
+    maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+    generatedAtMs: lastRefreshMs,
+  });
+
+  if (!stale) {
+    return false;
+  }
+
+  await buildCodeIndex({ rootDir });
+
+  if (lastRefreshMs !== null) {
+    console.log(`[UKit] stale index refreshed (last=${new Date(lastRefreshMs).toISOString()})`);
+  } else {
+    console.log('[UKit] stale index refreshed (no previous cache timestamp)');
+  }
+
+  return true;
+}
+
+function printContextGroup(label, filePaths = [], explanations = []) {
+  console.log(`${label}: ${formatCompactDisplayList(filePaths)}`);
+
+  const normalizedExplanations = uniqueContextExplanations(explanations);
+  for (const item of normalizedExplanations.slice(0, CONTEXT_REASON_LIMIT)) {
+    console.log(`  - ${item.filePath}: ${item.reason}`);
+  }
+
+  const remainingReasonCount = normalizedExplanations.length - Math.min(normalizedExplanations.length, CONTEXT_REASON_LIMIT);
+  if (remainingReasonCount > 0) {
+    console.log(`  - +${remainingReasonCount} more reasons`);
+  }
+}
+
+function formatCompactDisplayList(values = [], limit = CONTEXT_DISPLAY_LIMIT, separator = ', ') {
+  const normalized = [...new Set((values ?? []).filter(Boolean))];
+  if (normalized.length === 0) {
+    return 'none';
+  }
+
+  const shown = normalized.slice(0, limit);
+  const remaining = normalized.length - shown.length;
+  return remaining > 0
+    ? `${shown.join(separator)}${separator}+${remaining} more`
+    : shown.join(separator);
+}
+
+function formatCompactNoteDisplayList(values = [], limit = VERIFY_NOTE_DISPLAY_LIMIT) {
+  const normalized = [...new Set((values ?? []).filter(Boolean))]
+    .map(compactVerificationDisplayNote)
+    .filter(Boolean);
+
+  return formatCompactDisplayList(normalized, limit, ' | ');
+}
+
+function formatCompactCommandDisplayList(values = [], limit = VERIFY_COMMAND_DISPLAY_LIMIT) {
+  const normalized = [...new Set((values ?? []).filter(Boolean))];
+  if (normalized.length === 0) {
+    return 'none';
+  }
+
+  const sharedTargetFamily = deriveSharedTargetCommandFamily(normalized);
+  if (!sharedTargetFamily) {
+    return formatCompactDisplayList(normalized, limit);
+  }
+
+  const [firstTarget, ...remainingTargets] = sharedTargetFamily.targets;
+  const firstCommand = `${sharedTargetFamily.prefix} ${firstTarget}`;
+  const shownSiblingCount = Math.max(0, Math.min(remainingTargets.length, limit - 1));
+  const shownSiblings = remainingTargets.slice(0, shownSiblingCount);
+  const hiddenSiblingCount = remainingTargets.length - shownSiblings.length;
+
+  if (shownSiblings.length === 0) {
+    return hiddenSiblingCount > 0
+      ? `${firstCommand} | same-command: +${hiddenSiblingCount} more`
+      : firstCommand;
+  }
+
+  const siblingSummary = shownSiblings.join(', ');
+  return hiddenSiblingCount > 0
+    ? `${firstCommand} | same-command: ${siblingSummary}, +${hiddenSiblingCount} more`
+    : `${firstCommand} | same-command: ${siblingSummary}`;
+}
+
+function deriveSharedTargetCommandFamily(commands = []) {
+  if (commands.length < 2) {
+    return null;
+  }
+
+  const parsed = commands.map(parseSharedTargetCommand);
+  if (parsed.some((entry) => !entry)) {
+    return null;
+  }
+
+  const prefix = parsed[0].prefix;
+  if (!prefix || parsed.some((entry) => entry.prefix !== prefix)) {
+    return null;
+  }
+
+  return {
+    prefix,
+    targets: parsed.map((entry) => entry.target),
+  };
+}
+
+function parseSharedTargetCommand(command) {
+  const normalized = String(command || '').trim();
+  if (!normalized) {
+    return null;
+  }
+
+  const parts = normalized.split(/\s+/);
+  if (parts.length < 3) {
+    return null;
+  }
+
+  const target = parts.at(-1);
+  if (!isLikelyCommandTarget(target)) {
+    return null;
+  }
+
+  const prefix = parts.slice(0, -1).join(' ').trim();
+  return prefix
+    ? { prefix, target }
+    : null;
+}
+
+function isLikelyCommandTarget(value) {
+  if (!value) {
+    return false;
+  }
+
+  return value.startsWith('./')
+    || value.startsWith('../')
+    || value.startsWith('/')
+    || value.includes('/')
+    || /\.[a-z0-9]+$/i.test(value);
+}
+
+function compactVerificationDisplayNote(note) {
+  const normalized = String(note || '').trim();
+  if (!normalized) {
+    return '';
+  }
+
+  if (normalized.startsWith('Run related tests first:')) {
+    return `related-tests-first: ${normalized.slice('Run related tests first:'.length).trim()}`;
+  }
+
+  if (normalized.startsWith('Docs-focused change:')) {
+    return 'docs-only: prefer docs syntax/format checks; broad tests not default';
+  }
+
+  if (normalized === 'Match verification effort to scope; no project test/lint/typecheck scripts were detected.') {
+    return 'no test/lint/typecheck scripts detected; match verification effort to scope';
+  }
+
+  return normalized;
+}
+
+function uniqueContextExplanations(explanations = []) {
+  const seen = new Set();
+  const unique = [];
+
+  for (const item of explanations ?? []) {
+    const filePath = String(item?.filePath ?? '').trim();
+    const reason = String(item?.reason ?? '').trim();
+    if (!filePath && !reason) {
+      continue;
+    }
+
+    const key = `${filePath}::${reason}`;
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    unique.push({ filePath, reason });
+  }
+
+  return unique;
+}
+
+function hasRouteSummaryField(routeSummary, field) {
+  return Boolean(
+    routeSummary
+    && typeof routeSummary === 'object'
+    && Object.prototype.hasOwnProperty.call(routeSummary, field),
+  );
+}
+
+function extractRouteLineSegment(line, label) {
+  if (typeof line !== 'string' || !line.trim()) {
+    return null;
+  }
+
+  const match = line.match(new RegExp(`(?:^|\\|\\s*)${label}=([^|]+)`, 'i'));
+  return match ? `${label}=${String(match[1] || '').trim()}` : null;
+}
+
+function formatDisplayRouteSummary(routeSummary = null, routingContext = {}) {
+  const line = String(routeSummary?.line ?? '').trim();
+  const taskSegment = routingContext?.taskType
+    ? `task=${routingContext.taskType}`
+    : extractRouteLineSegment(line, 'task');
+  const policySegment = routeSummary?.policyMode
+    ? `policy=${routeSummary.policyMode}`
+    : (
+      hasRouteSummaryField(routeSummary, 'policyMode')
+        ? null
+        : extractRouteLineSegment(line, 'policy')
+    );
+
+  const segments = [
+    taskSegment,
+    extractRouteLineSegment(line, 'targets'),
+    extractRouteLineSegment(line, 'tests'),
+    extractRouteLineSegment(line, 'styles'),
+    policySegment,
+  ].filter(Boolean);
+
+  return segments.join(' | ') || 'none';
+}
+
+function formatDisplayNextAction(routeSummary = null) {
+  if (!routeSummary || typeof routeSummary !== 'object') {
+    return '';
+  }
+
+  const nextActionCommand = String(routeSummary.nextActionCommand ?? '').trim();
+  if (nextActionCommand) {
+    return nextActionCommand;
+  }
+
+  const nextActionType = String(routeSummary.nextActionType ?? '').trim();
+  if (!nextActionType || nextActionType === 'read-skill-instructions') {
+    return '';
+  }
+
+  return nextActionType;
+}