@ngockhoale/ukit 1.1.6

package/templates/.claude/ukit/index/verify-context.mjs

@@ -0,0 +1,689 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import * as indexCore from './lib/index-core.mjs';
+import {
+  DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+  readRecentCacheEntry,
+  writeRecentCacheEntry,
+} from './cache-utils.mjs';
+
+const {
+  resolveContext,
+  buildCodeIndex,
+  DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+  getIndexArtifactGeneratedAt,
+} = indexCore;
+const VERIFY_COMMAND_DISPLAY_LIMIT = 2;
+const VERIFY_REASON_DISPLAY_LIMIT = 2;
+const VERIFY_NOTE_DISPLAY_LIMIT = 1;
+
+const args = process.argv.slice(2);
+const rootDir = getRootDir(args);
+const targetFile = readFlagValue(args, '--target');
+const taskType = readFlagValue(args, '--type');
+const intent = collectPositionalArgs(args, ['--root', '--target', '--type']);
+const effectiveIntent = deriveHelperIntent({ intent, targetFile });
+
+if (!intent && !targetFile) {
+  console.error('Usage: node .claude/ukit/index/verify-context.mjs "<intent>" [--target <file>] [--type trivial|simple|non-trivial]');
+  process.exitCode = 1;
+} else {
+  const indexGeneratedAtMs = await ensureFreshIndex({
+    rootDir,
+    logPrefix: 'verify',
+  });
+  const projectVerification = await readProjectVerificationFingerprint(rootDir);
+  const cachePath = path.join(rootDir, '.claude', 'ukit', 'verify-context-cache.json');
+  const requestKey = buildRequestKey({
+    indexGeneratedAtMs,
+    projectFingerprint: projectVerification.fingerprint,
+    intent: effectiveIntent,
+    targetFile,
+    taskType,
+  });
+  const cached = await readRecentCacheEntry(cachePath, requestKey, {
+    maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+    touch: true,
+  });
+  const resolveContextCachePath = path.join(rootDir, '.claude', 'ukit', 'resolve-context-cache.json');
+  const cachedContext = cached
+    ? null
+    : await readRecentCacheEntry(
+        resolveContextCachePath,
+        buildResolveContextRequestKey({
+          indexGeneratedAtMs,
+          intent: effectiveIntent,
+          targetFile,
+          taskType,
+        }),
+        {
+          maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+        },
+      );
+  const plan = cached?.result
+    ?? await deriveVerificationPlan({
+      rootDir,
+      intent: effectiveIntent,
+      targetFile,
+      taskType,
+      contextResult: expandHelperContext(cachedContext?.result ?? null),
+      fingerprintEntries: projectVerification.entries,
+      pkg: projectVerification.pkg,
+    });
+
+  if (!cached) {
+    await writeRecentCacheEntry(cachePath, {
+      requestKey,
+      updatedAt: Date.now(),
+      result: plan,
+    }, {
+      maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
+    });
+  }
+
+  printVerificationPlan(plan);
+}
+
+async function ensureFreshIndex({ rootDir, logPrefix }) {
+  const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
+  const stale = lastRefreshMs === null
+    ? true
+    : typeof indexCore.isIndexStale === 'function'
+      ? await indexCore.isIndexStale({
+          rootDir,
+          maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS,
+          now: Date.now(),
+          generatedAtMs: lastRefreshMs,
+        })
+      : (Date.now() - lastRefreshMs) > DEFAULT_INDEX_CACHE_MAX_AGE_MS;
+
+  if (!stale) {
+    return lastRefreshMs;
+  }
+
+  const summary = await buildCodeIndex({ rootDir });
+  if (lastRefreshMs !== null) {
+    console.log(`[ukit:${logPrefix}] stale index refreshed (last=${new Date(lastRefreshMs).toISOString()})`);
+  } else {
+    console.log(`[ukit:${logPrefix}] stale index refreshed (no previous cache timestamp)`);
+  }
+  return Number.isFinite(summary?.generatedAtMs)
+    ? summary.generatedAtMs
+    : getIndexArtifactGeneratedAt({ rootDir });
+}
+
+async function deriveVerificationPlan({
+  rootDir = process.cwd(),
+  intent = '',
+  targetFile = null,
+  taskType = null,
+  contextResult = null,
+  fingerprintEntries = [],
+  pkg = null,
+} = {}) {
+  const absoluteRoot = path.resolve(rootDir);
+  const context = expandHelperContext(contextResult ?? await resolveContext({
+    rootDir: absoluteRoot,
+    intent,
+    targetFile,
+    taskType,
+  }));
+
+  const resolvedPkg = pkg ?? await readPackageJson(absoluteRoot);
+  const scripts = resolvedPkg?.scripts && typeof resolvedPkg.scripts === 'object' ? resolvedPkg.scripts : {};
+  const packageManager = detectPackageManager({ fingerprintEntries, pkg: resolvedPkg });
+  const primaryTargets = unique([
+    ...(context?.primaryTargets ?? []),
+    ...(targetFile ? [targetFile] : []),
+  ]);
+  const relatedTests = unique([
+    ...(context?.relatedTests ?? []),
+    ...(targetFile && /\.(test|spec)\./.test(targetFile) ? [targetFile] : []),
+  ]);
+  const commands = [];
+  const fallbackCommands = [];
+  const reasons = [];
+  const notes = [];
+  const docsOnly = primaryTargets.length > 0
+    && primaryTargets.every((filePath) => filePath.startsWith('docs/'));
+  const risky = context?.taskType === 'non-trivial';
+
+  let mode = 'minimal';
+
+  if (docsOnly) {
+    mode = 'docs-only';
+    reasons.push('docsOnly');
+    if (scripts.lint) {
+      fallbackCommands.push(buildScriptCommand(packageManager, 'lint'));
+    }
+    notes.push('Docs-focused change: prefer docs syntax/format verification if available; broad test runs are not the default.');
+  } else {
+    if (relatedTests.length > 0) {
+      mode = 'targeted-tests-first';
+      reasons.push('relatedTests');
+      if (scripts.test) {
+        for (const testFile of relatedTests.slice(0, 2)) {
+          commands.push(buildScriptCommand(packageManager, 'test', [testFile]));
+        }
+      } else {
+        notes.push(`Run related tests first: ${relatedTests.slice(0, 2).join(', ')}`);
+      }
+    }
+
+    if (risky) {
+      reasons.push('riskySkillOrTask');
+      if (scripts.test) {
+        fallbackCommands.push(buildScriptCommand(packageManager, 'test'));
+      }
+    }
+
+    if (scripts.lint) {
+      fallbackCommands.push(buildScriptCommand(packageManager, 'lint'));
+    }
+    if (scripts.typecheck) {
+      fallbackCommands.push(buildScriptCommand(packageManager, 'typecheck'));
+    }
+
+    if (commands.length === 0 && scripts.test && risky) {
+      mode = 'broader-verification';
+      reasons.push('highRiskFallback');
+      commands.push(buildScriptCommand(packageManager, 'test'));
+    }
+  }
+
+  if (commands.length === 0 && fallbackCommands.length === 0) {
+    notes.push('Match verification effort to scope; no project test/lint/typecheck scripts were detected.');
+  }
+
+  const summarizedContext = {
+    primaryTargets: context?.primaryTargets ?? [],
+    analogFiles: context?.analogFiles ?? [],
+    sharedAbstractions: context?.sharedAbstractions ?? [],
+    relatedTests: context?.relatedTests ?? [],
+    styleFiles: context?.styleFiles ?? [],
+  };
+  const primaryCommandList = unique(commands);
+  const fallbackCommandList = unique(fallbackCommands.filter((command) => !primaryCommandList.includes(command)));
+  const reasonList = unique(reasons);
+
+  return {
+    taskType: context?.taskType ?? taskType ?? 'simple',
+    packageManager,
+    mode,
+    commands: primaryCommandList,
+    fallbackCommands: fallbackCommandList,
+    reasons: reasonList,
+    notes: unique(notes),
+    executionPolicy: deriveExecutionPolicy({
+      taskType: context?.taskType ?? taskType ?? 'simple',
+      mode,
+      commands: primaryCommandList,
+      fallbackCommands: fallbackCommandList,
+      reasons: reasonList,
+      context: summarizedContext,
+    }),
+  };
+}
+
+async function readPackageJson(rootDir) {
+  try {
+    const raw = await fs.readFile(path.join(rootDir, 'package.json'), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function detectPackageManager({ fingerprintEntries = [], pkg = null } = {}) {
+  const declaredPackageManager = getDeclaredPackageManager(pkg);
+  if (declaredPackageManager) return declaredPackageManager;
+
+  const existingFiles = new Set(
+    fingerprintEntries
+      .filter((entry) => entry && entry.mtimeMs !== null)
+      .map((entry) => entry.filePath),
+  );
+
+  const checks = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lockb', 'bun'],
+    ['bun.lock', 'bun'],
+    ['package-lock.json', 'npm'],
+  ];
+
+  for (const [lockFile, pm] of checks) {
+    if (existingFiles.has(lockFile)) {
+      return pm;
+    }
+  }
+
+  return 'npm';
+}
+
+async function readProjectVerificationFingerprint(rootDir) {
+  const entries = [];
+  let pkg = null;
+
+  try {
+    const packageJsonPath = path.join(rootDir, 'package.json');
+    const [raw, stat] = await Promise.all([
+      fs.readFile(packageJsonPath, 'utf8'),
+      fs.stat(packageJsonPath),
+    ]);
+    pkg = JSON.parse(raw);
+    entries.push({
+      filePath: 'package.json',
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+    });
+  } catch {
+    entries.push({
+      filePath: 'package.json',
+      size: null,
+      mtimeMs: null,
+    });
+  }
+
+  const trackedFiles = getDeclaredPackageManager(pkg)
+    ? []
+    : [
+        'package-lock.json',
+        'pnpm-lock.yaml',
+        'yarn.lock',
+        'bun.lockb',
+        'bun.lock',
+      ];
+
+  for (const relativePath of trackedFiles) {
+    const absolutePath = path.join(rootDir, relativePath);
+    try {
+      const stat = await fs.stat(absolutePath);
+      entries.push({
+        filePath: relativePath,
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+      });
+    } catch {
+      entries.push({
+        filePath: relativePath,
+        size: null,
+        mtimeMs: null,
+      });
+    }
+  }
+
+  return {
+    pkg,
+    entries,
+    fingerprint: JSON.stringify(entries),
+  };
+}
+
+function getDeclaredPackageManager(pkg = null) {
+  const declared = String(pkg?.packageManager ?? '').toLowerCase();
+  if (declared.startsWith('pnpm')) return 'pnpm';
+  if (declared.startsWith('yarn')) return 'yarn';
+  if (declared.startsWith('bun')) return 'bun';
+  if (declared.startsWith('npm')) return 'npm';
+  return null;
+}
+
+function buildRequestKey({
+  indexGeneratedAtMs = null,
+  projectFingerprint = '',
+  intent = '',
+  targetFile = null,
+  taskType = null,
+} = {}) {
+  return buildCompactMachineKey('verify-v1', {
+    indexGeneratedAtMs,
+    projectFingerprint,
+    intent: String(intent || '').trim(),
+    targetFile: String(targetFile || '').trim(),
+    taskType: String(taskType || '').trim(),
+  });
+}
+
+function buildResolveContextRequestKey({
+  indexGeneratedAtMs = null,
+  intent = '',
+  targetFile = null,
+  taskType = null,
+} = {}) {
+  return buildCompactMachineKey('resolve-v1', {
+    indexGeneratedAtMs,
+    intent: String(intent || '').trim(),
+    targetFile: String(targetFile || '').trim(),
+    taskType: String(taskType || '').trim(),
+  });
+}
+
+function buildCompactMachineKey(prefix, payload) {
+  return `${prefix}:${stableMachineDigest(payload)}`;
+}
+
+function stableMachineDigest(payload) {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(payload))
+    .digest('base64url');
+}
+
+function deriveHelperIntent({ intent = '', targetFile = null } = {}) {
+  const normalizedIntent = String(intent || '').trim();
+  if (normalizedIntent) {
+    return normalizedIntent;
+  }
+
+  const normalizedTarget = String(targetFile || '').trim();
+  if (!normalizedTarget) {
+    return '';
+  }
+
+  if (/^docs\//i.test(normalizedTarget)) {
+    return `update docs for ${normalizedTarget}`;
+  }
+
+  return `work on ${normalizedTarget}`;
+}
+
+function expandHelperContext(contextResult) {
+  if (!contextResult) {
+    return contextResult;
+  }
+
+  const directTests = (contextResult.primaryTargets ?? []).filter(isTestLikeFile);
+  if (directTests.length === 0) {
+    return contextResult;
+  }
+
+  const relatedTests = unique([
+    ...(contextResult.relatedTests ?? []),
+    ...directTests,
+  ]);
+  const relatedTestExplanations = mergeRelatedTestExplanations(
+    contextResult.explanations?.relatedTests ?? [],
+    directTests,
+  );
+
+  return {
+    ...contextResult,
+    relatedTests,
+    explanations: {
+      ...(contextResult.explanations ?? {}),
+      relatedTests: relatedTestExplanations,
+    },
+  };
+}
+
+function mergeRelatedTestExplanations(existingExplanations = [], directTests = []) {
+  const next = [...existingExplanations];
+
+  for (const filePath of directTests) {
+    const existing = next.find((entry) => entry.filePath === filePath);
+    const reason = `direct test target ${filePath}`;
+    if (!existing) {
+      next.push({ filePath, reason });
+      continue;
+    }
+    if (!String(existing.reason || '').includes(reason)) {
+      existing.reason = existing.reason
+        ? `${existing.reason}; ${reason}`
+        : reason;
+    }
+  }
+
+  return next;
+}
+
+function isTestLikeFile(filePath) {
+  return /\.(test|spec)\.[a-z0-9]+$/i.test(filePath)
+    || /(^|\/)(?:__tests__|tests?|specs?)\//i.test(filePath);
+}
+
+function unique(values = []) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function printVerificationPlan(plan) {
+  console.log('[ukit:verify]');
+  console.log(`taskType: ${plan.taskType}`);
+  console.log(`mode: ${plan.mode}`);
+  console.log(`commands: ${formatCompactCommandDisplayList(plan.commands, VERIFY_COMMAND_DISPLAY_LIMIT)}`);
+  console.log(`fallback: ${formatCompactCommandDisplayList(plan.fallbackCommands, VERIFY_COMMAND_DISPLAY_LIMIT)}`);
+  console.log(`reasons: ${formatCompactDisplayList(plan.reasons, VERIFY_REASON_DISPLAY_LIMIT)}`);
+  if (plan.executionPolicy) {
+    console.log(`policy: ${plan.executionPolicy.policyMode}`);
+    console.log(`autoRunPrimary: ${plan.executionPolicy.shouldAutoRunPrimaryCommands ? 'yes' : 'no'}`);
+    console.log(`autoRunFallbacks: ${plan.executionPolicy.shouldAutoRunFallbacks ? 'yes' : 'no'}`);
+    console.log(`confirmBroad: ${plan.executionPolicy.requiresHumanConfirmationForBroadOrRisky ? 'yes' : 'no'}`);
+  }
+  if ((plan.notes ?? []).length > 0) {
+    console.log(`notes: ${formatCompactNoteDisplayList(plan.notes, VERIFY_NOTE_DISPLAY_LIMIT)}`);
+  }
+}
+
+function formatCompactDisplayList(values = [], limit = VERIFY_COMMAND_DISPLAY_LIMIT, separator = ', ') {
+  const normalized = unique(values);
+  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 = unique(values)
+    .map(compactVerificationDisplayNote)
+    .filter(Boolean);
+
+  return formatCompactDisplayList(normalized, limit, ' | ');
+}
+
+function formatCompactCommandDisplayList(values = [], limit = VERIFY_COMMAND_DISPLAY_LIMIT) {
+  const normalized = unique(values);
+  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 buildScriptCommand(packageManager, scriptName, args = []) {
+  const filteredArgs = args.filter(Boolean);
+  if (packageManager === 'npm') {
+    if (scriptName === 'test') {
+      return ['npm', 'test', filteredArgs.length > 0 ? '--' : '', ...filteredArgs]
+        .filter(Boolean)
+        .join(' ');
+    }
+    return ['npm', 'run', scriptName, filteredArgs.length > 0 ? '--' : '', ...filteredArgs]
+      .filter(Boolean)
+      .join(' ');
+  }
+  return [packageManager, scriptName, ...filteredArgs].join(' ');
+}
+
+function deriveExecutionPolicy({
+  taskType = 'simple',
+  mode = 'minimal',
+  commands = [],
+  fallbackCommands = [],
+  reasons = [],
+  context = {},
+} = {}) {
+  const relatedTests = context.relatedTests ?? [];
+  const sharedAbstractions = context.sharedAbstractions ?? [];
+  const docsOnly = mode === 'docs-only' || reasons.includes('docsOnly');
+  const risky = taskType === 'non-trivial'
+    || reasons.includes('riskySkillOrTask')
+    || reasons.includes('highRiskFallback');
+  const hasPrimaryCommands = commands.length > 0;
+  const hasTargetedPrimaryCommands = mode === 'targeted-tests-first' && hasPrimaryCommands;
+  const sharedScope = sharedAbstractions.length > 0;
+  const noRelatedTests = relatedTests.length === 0;
+  const broadOnlyPrimary = hasPrimaryCommands && !hasTargetedPrimaryCommands && noRelatedTests;
+  const requiresHumanConfirmationForBroadOrRisky = risky && broadOnlyPrimary;
+  const shouldAutoRunPrimaryCommands = hasPrimaryCommands && !docsOnly && !requiresHumanConfirmationForBroadOrRisky;
+  const shouldEscalateToFallbacks = !docsOnly && fallbackCommands.length > 0 && (risky || sharedScope);
+  const shouldAutoRunFallbacks = shouldEscalateToFallbacks && !requiresHumanConfirmationForBroadOrRisky;
+
+  let policyMode = 'recommend-only';
+  if (docsOnly) {
+    policyMode = 'docs-light';
+  } else if (hasTargetedPrimaryCommands && shouldEscalateToFallbacks) {
+    policyMode = 'auto-run-targeted-then-fallback';
+  } else if (hasTargetedPrimaryCommands) {
+    policyMode = 'auto-run-targeted';
+  } else if (requiresHumanConfirmationForBroadOrRisky) {
+    policyMode = 'confirm-then-broad';
+  } else if (shouldAutoRunPrimaryCommands) {
+    policyMode = 'auto-run-primary';
+  }
+
+  return {
+    policyMode,
+    shouldAutoRunPrimaryCommands,
+    shouldAutoRunTargetedVerification: hasTargetedPrimaryCommands && shouldAutoRunPrimaryCommands,
+    shouldEscalateToFallbacks,
+    shouldAutoRunFallbacks,
+    requiresHumanConfirmationForBroadOrRisky,
+    preferredOrder: [...commands, ...fallbackCommands],
+    reasons: unique([
+      ...reasons,
+      sharedScope ? 'sharedScope' : null,
+      noRelatedTests ? 'noRelatedTests' : null,
+    ]),
+  };
+}
+
+function getRootDir(argv) {
+  const value = readFlagValue(argv, '--root');
+  return value ? path.resolve(value) : process.cwd();
+}
+
+function readFlagValue(argv, flag) {
+  const exact = argv.indexOf(flag);
+  if (exact >= 0 && argv[exact + 1]) return argv[exact + 1];
+  const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
+  return withEquals ? withEquals.slice(flag.length + 1) : null;
+}
+
+function collectPositionalArgs(argv, flagsWithValues = []) {
+  return argv
+    .filter((arg, index) => !isFlagOrValue(argv, index, flagsWithValues))
+    .join(' ')
+    .trim();
+}
+
+function isFlagOrValue(argv, index, flagsWithValues = []) {
+  const arg = argv[index];
+  if (!arg.startsWith('--')) {
+    const prev = argv[index - 1];
+    return Boolean(prev && flagsWithValues.includes(prev));
+  }
+  return true;
+}