@ngockhoale/ukit 3.0.3 → 3.0.4

package/src/cli/commands/indexArgs.js

@@ -36,8 +36,10 @@ export function parseIndexArgs(argv, flagDefinitions) {
       continue;
     }
 
-    const hasEquals = arg.includes('=');
-    const [flag, valueFromEquals = null] = hasEquals ? arg.split('=', 2) : [arg, null];
+    const equalsIndex = arg.indexOf('=');
+    const [flag, valueFromEquals = null] = equalsIndex >= 0
+      ? [arg.slice(0, equalsIndex), arg.slice(equalsIndex + 1)]
+      : [arg, null];
     const definition = flagDefinitions.get(flag);
     if (!definition) {
       throw new Error(`Unknown option: ${flag}`);

package/src/cli/commands/indexTools.js

@@ -192,7 +192,14 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
     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 rawAdapter = flags.get('--adapter') ?? 'claude';
+    // Same posture as the shipped route-task.mjs helper: unknown adapters warn
+    // and fall back to claude instead of silently picking a namespace.
+    const KNOWN_ROUTE_ADAPTERS = new Set(['claude', 'codex']);
+    const adapter = KNOWN_ROUTE_ADAPTERS.has(rawAdapter) ? rawAdapter : 'claude';
+    if (adapter !== rawAdapter) {
+      console.error(`[UKit] unknown --adapter "${rawAdapter}" — falling back to claude`);
+    }
     const commandNamespace = adapter === 'codex' ? '.codex' : '.claude';
 
     if (!promptText && !commandText && !targetFile) {

package/src/cli/commands/install.js

@@ -10,6 +10,7 @@ import { removeTrackedPathsFromMetadata } from '../../core/metadata.js';
 import {
   ADAPTER_BY_KEY,
   DEFAULT_OPTIONAL_TOOL_KEYS,
+  TOOLS_FLAG_HELP,
   parseToolsArg,
   resolveOptionalToolKeys,
   toSelectedAdapterItemIds,
@@ -245,6 +246,18 @@ export async function pruneDeselectedAdapters({
 }
 
 export async function runInstall({ packageRoot, projectRoot, packageVersion, argv = [] }) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('Usage: ukit install [options]');
+    console.log('');
+    console.log('Install/update UKit assets into the current project (default command).');
+    console.log('');
+    console.log('Options:');
+    console.log(`  --tools=<list>     Adapters to enable (default: all). Values: ${TOOLS_FLAG_HELP}`);
+    console.log('  --with-codegraph   Enable CodeGraph MCP integration in CLAUDE.md');
+    console.log('  --help, -h         Show this help message');
+    return;
+  }
+
   // parseToolsArg owns only --tools and throws on anything else, so hand it the argv with
   // the flags consumed here (--with-codegraph) already removed — order-dependent parsing
   // used to make the documented `ukit install --with-codegraph` fail 100% of the time.

package/src/cli/commands/memory.js

@@ -40,8 +40,14 @@ const HELP_FLAGS = new Set(['--help', '-h', 'help']);
 function extractFlag(args, flag) {
   const index = args.indexOf(flag);
   if (index < 0) return { value: null, rest: args };
+  const value = args[index + 1];
+  // A missing value — or the next flag swallowed as the value — used to pass
+  // silently (e.g. `--project --category bug` set projectId='--category').
+  if (typeof value !== 'string' || value.startsWith('--')) {
+    throw new Error(`Missing value for ${flag}.`);
+  }
   return {
-    value: args[index + 1] ?? null,
+    value,
     rest: [...args.slice(0, index), ...args.slice(index + 2)],
   };
 }
@@ -437,8 +443,9 @@ function episodeText(ledger, sessionId) {
     ? 'not-run'
     : ledger.verificationSucceeded === true ? 'ok' : 'fail';
   const receipts = Array.isArray(ledger.receipts) ? ledger.receipts : [];
-  const lastCommand = receipts.length > 0
-    ? String(receipts[receipts.length - 1].command ?? '').split('\n')[0].trim() || 'n/a'
+  const lastReceipt = receipts.length > 0 ? receipts[receipts.length - 1] : null;
+  const lastCommand = lastReceipt
+    ? String(lastReceipt?.command ?? '').split('\n')[0].trim() || 'n/a'
     : 'n/a';
   const text = `Session ${sessionId}: ${write}, verify=${verify}, `
     + `${receipts.length} receipts, last command ${lastCommand}`;

package/src/cli/commands/status.js

@@ -1,6 +1,22 @@
 import { buildStatusReport, formatStatusReport } from '../../core/status.js';
 
-export async function runStatus({ projectRoot }) {
+const KNOWN_STATUS_FLAGS = new Set(['--help', '-h']);
+
+export async function runStatus({ projectRoot, argv = [] }) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('Usage: ukit status');
+    console.log('');
+    console.log('Show UKit runtime status for the current project.');
+    return;
+  }
+
+  const unknownArgs = argv.filter((a) => !KNOWN_STATUS_FLAGS.has(a));
+  if (unknownArgs.length > 0) {
+    throw new Error(
+      `Unknown option(s): ${unknownArgs.join(', ')}. Run \`ukit status --help\` for usage.`,
+    );
+  }
+
   const report = await buildStatusReport(projectRoot);
   for (const line of formatStatusReport(report)) {
     console.log(line);

package/src/cli/commands/update.js

@@ -20,6 +20,13 @@ export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd()
     );
   }
 
+  const positionalArgs = argv.filter((a) => !a.startsWith('-'));
+  if (positionalArgs.length > 0) {
+    throw new Error(
+      `Unexpected argument(s): ${positionalArgs.join(', ')}. Run \`ukit update --help\` for usage.`,
+    );
+  }
+
   console.log(`[UKit] Current version: ${packageVersion}`);
   console.log(`[UKit] Running: npm install -g ${UKIT_PACKAGE_NAME}`);
 

package/src/context/detectProjectContext.js

@@ -12,7 +12,9 @@ function inferProjectName(projectRoot, packageJson) {
 
 export async function detectProjectContext(projectRoot) {
   const packageJsonPath = path.join(projectRoot, 'package.json');
-  const packageJson = await readJsonIfExists(packageJsonPath);
+  // A corrupt package.json must degrade to basename naming, not crash the
+  // status/memory CLIs with a raw SyntaxError.
+  const packageJson = await readJsonIfExists(packageJsonPath).catch(() => null);
 
   return {
     project: {

package/src/core/codeintel/analogy.js

@@ -190,7 +190,7 @@ export async function findAnalogies(projectRoot, query, { limit = DEFAULT_LIMIT
   }
 
   analogies.sort((a, b) => b.score - a.score || a.ref.localeCompare(b.ref));
-  if (analogies.length === 0 && !memory.why && filesArtifact && symbolsArtifact) {
+  if (analogies.length === 0 && (memory.records !== null || filesArtifact || symbolsArtifact)) {
     omitted.push({ what: 'analogy-lane', why: 'no-match' });
   }
   return { analogies: analogies.slice(0, effectiveLimit), omitted };

package/src/core/codeintel/diagnostics.js

@@ -12,15 +12,18 @@ const SYNTAX_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']);
 const MAX_DIAGNOSTICS = 50;
 
 function parseCheckLine(stderr) {
-  const line = String(stderr ?? '')
+  const lines = String(stderr ?? '')
     .split('\n')
     .map((l) => l.trim())
-    .find((l) => l.length > 0);
-  if (!line) return { message: 'syntax check failed', line: null };
-  const match = line.match(/:(\d+)\s*$/);
+    .filter((l) => l.length > 0);
+  if (lines.length === 0) return { message: 'syntax check failed', line: null };
+  // `node --check` stderr opens with `<file>:<line>` then the offending source
+  // line and a caret; the real error is the first *Error line below that.
+  const errorLine = lines.find((l) => /\b\w*Error\b/.test(l));
+  const lineMatch = lines[0].match(/:(\d+)\s*$/);
   return {
-    message: line,
-    line: match ? Number.parseInt(match[1], 10) : null,
+    message: errorLine ?? lines[0],
+    line: lineMatch ? Number.parseInt(lineMatch[1], 10) : null,
   };
 }
 

package/src/core/codeintel/graph.js

@@ -96,8 +96,8 @@ export async function buildGraphArtifact(projectRoot) {
     }
     return id;
   };
-  const addEdge = (edge, dedupeExtra = '') => {
-    const key = `${edge.from}»${edge.to}»${edge.kind}»${dedupeExtra}`;
+  const addEdge = (edge) => {
+    const key = `${edge.from}»${edge.to}»${edge.kind}`;
     if (!edges.has(key)) edges.set(key, edge);
   };
 
@@ -132,16 +132,18 @@ export async function buildGraphArtifact(projectRoot) {
     for (const name of call.calls ?? []) {
       const target = symbolToFile.get(name);
       if (!target || target === call.filePath) continue;
+      // The callee file is a graph node even when it has no calls.json row of
+      // its own — an edge must never point at a non-existent node.
+      addFileNode(target);
       addEdge(createEdge({
         from: call.filePath,
         to: target,
         kind: 'call',
         provider: 'json-graph',
         evidence: INDEX_ARTIFACTS.calls,
-      }), name);
+      }));
     }
   }
-
   // co-change edges: pair endpoints become file nodes; count feeds confidence.
   for (const pair of cochangeArtifact?.pairs ?? []) {
     if (!pair?.a || !pair?.b) continue;
@@ -155,7 +157,7 @@ export async function buildGraphArtifact(projectRoot) {
       confidence,
       provider: 'json-graph',
       evidence: INDEX_ARTIFACTS.cochange,
-    }), String(pair.count ?? ''));
+    }));
     addEdge(createEdge({
       from: pair.b,
       to: pair.a,
@@ -163,7 +165,7 @@ export async function buildGraphArtifact(projectRoot) {
       confidence,
       provider: 'json-graph',
       evidence: INDEX_ARTIFACTS.cochange,
-    }), String(pair.count ?? ''));
+    }));
   }
 
   const artifact = {
@@ -205,11 +207,15 @@ export class JsonGraphStore {
   capabilities() {
     return { nodes: true, edges: true, queries: true };
   }
-
   async _load() {
     if (!this._artifactPromise) {
       this._artifactPromise = (async () => {
-        const artifact = await readJsonIfExists(getArtifactPath(this.rootDir, INDEX_ARTIFACTS.codegraph));
+        let artifact = null;
+        try {
+          artifact = await readJsonIfExists(getArtifactPath(this.rootDir, INDEX_ARTIFACTS.codegraph));
+        } catch {
+          return null; // corrupt JSON → empty results, never throws
+        }
         if (!artifact || typeof artifact !== 'object') return null;
         if (artifact.schemaVersion !== GRAPH_SCHEMA_VERSION) return null;
         if (!Array.isArray(artifact.nodes) || !Array.isArray(artifact.edges)) return null;

package/src/core/codeintel/impact.js

@@ -98,7 +98,6 @@ export async function impactSet(projectRoot, seeds, {
   const nodeCap = clampInt(maxNodes ?? defaults.maxNodes, 1, Number.MAX_SAFE_INTEGER);
   const requestedDepth = typeof depth === 'number' ? depth : defaults.defaultDepth;
   const depthLimit = clampInt(requestedDepth, 1, maxDepthCap);
-  const depthClamped = requestedDepth > depthLimit;
 
   const seedList = Array.isArray(seeds) ? seeds.filter((s) => typeof s === 'string' && s.length > 0) : [];
   if (seedList.length === 0) {

package/src/core/codeintel/invalidation.js

@@ -140,15 +140,17 @@ export async function readDirty(projectRoot) {
 
 /**
  * Return the accumulated dirty set and clear the file (index-refresh lane).
- * @returns {Promise<string[]>} sorted paths, `[]` on missing/corrupt.
+ * `saturated` is surfaced so callers can treat a saturated set as full
+ * invalidation — a saturated drain with few/no paths is NOT a clean state.
+ * @returns {Promise<{ paths: string[], saturated: boolean }>}
  */
 export async function drainDirty(projectRoot) {
   const { paths, saturated } = await readDirtyData(projectRoot);
-  if (paths.length === 0 && !saturated) return [];
+  if (paths.length === 0 && !saturated) return { paths: [], saturated: false };
   try {
     await writeDirtyData(projectRoot, [], false);
   } catch {
     // never throw — drained set is still returned
   }
-  return [...paths].sort();
+  return { paths: [...paths].sort(), saturated };
 }

package/src/core/codeintel/packet.js

@@ -125,6 +125,17 @@ export function packetToText(packet) {
   for (const t of packet.tests ?? []) lines.push(`- ${t}`);
   if ((packet.tests ?? []).length === 0) lines.push('(none)');
 
+  lines.push('');
+  lines.push('## Memory');
+  for (const m of packet.memory ?? []) {
+    if (m && typeof m === 'object') {
+      lines.push(`- ${m.id ?? m.ref ?? ''}${typeof m.score === 'number' ? ` (score ${m.score})` : ''}`);
+    } else {
+      lines.push(`- ${m}`);
+    }
+  }
+  if ((packet.memory ?? []).length === 0) lines.push('(none)');
+
   lines.push('');
   lines.push('## Omitted');
   for (const o of packet.omitted ?? []) lines.push(`- ${o.what ?? ''} — ${o.why ?? ''}`);

package/src/core/codeintel/router.js

@@ -36,7 +36,21 @@ const ERROR_RE = /\b(error|exception|stack ?trace|bug|crash|failing|fails|failur
 const EXPLORE_RE = /\b(where|how does|how do|find|explore|understand|what does|which file|locate|handled)\b/i;
 const DEEP_FLOW_RE = /\b(refactor|migrate|migration|flow|end[- ]?to[- ]?end|trace|across|pipeline|lifecycle)\b/i;
 const ANALOGY_RE = /\b(similar to|analogy|like\b|same as|pattern|equivalent)\b/i;
-const PATH_RE = /(?:[\w.-]+\/)+[\w.-]+|[\w.-]+\.(?:js|ts|mjs|cjs|jsx|tsx|py|rb|go|rs|java|md|json|yml|yaml|css|html|sh)\b/i;
+const PATH_RE = /(?:[\w.-]+\/)+[\w.-]+|[\w.-]+\.(?:js|ts|mjs|cjs|jsx|tsx|py|rb|go|rs|java|md|json|yml|yaml|css|html|sh)\b/gi;
+
+// English slash-words that look like paths to PATH_RE but never are —
+// "and/or", "n/a" etc. must not trigger the explicit-target rule.
+const SLASH_WORD_STOPLIST = new Set([
+  'and/or', 'n/a', 'yes/no', 'true/false', 'on/off', 'either/or', 'w/o', 'w/', 'b/c',
+]);
+
+function hasPathMention(prompt) {
+  const text = String(prompt ?? '');
+  for (const match of text.matchAll(PATH_RE)) {
+    if (!SLASH_WORD_STOPLIST.has(match[0].toLowerCase())) return true;
+  }
+  return false;
+}
 
 function resolveBudgets(options) {
   const configured = options?.config?.codeIntel?.budgets ?? options?.budgets;
@@ -63,7 +77,7 @@ function decide(prompt, { hasError = false, filesHinted } = {}) {
   }
 
   // Rule 3 — explicit path/symbol mention, clear scope, no error.
-  const hasExplicitTarget = hintedFiles.length > 0 || PATH_RE.test(prompt);
+  const hasExplicitTarget = hintedFiles.length > 0 || hasPathMention(prompt);
   const errorSignalled = hasError || ERROR_RE.test(prompt);
   if (!errorSignalled && hasExplicitTarget) {
     reasons.push('explicit path or symbol mention with clear scope');
@@ -95,7 +109,7 @@ function decide(prompt, { hasError = false, filesHinted } = {}) {
   }
 
   // Rule 8 — fallback: single-file verb (single hinted file or lone path mention).
-  if (hintedFiles.length === 1 || PATH_RE.test(prompt)) {
+  if (hintedFiles.length === 1 || hasPathMention(prompt)) {
     reasons.push('fallback: single-file hint');
     return { mode: 'peek', reasons };
   }

package/src/core/codeintel/semanticProvider.js

@@ -87,7 +87,7 @@ export class TypeScriptSemanticProvider {
     try {
       const filesPath = getArtifactPath(this.projectRoot, INDEX_ARTIFACTS.files);
       const raw = JSON.parse(fs.readFileSync(filesPath, 'utf8'));
-      const list = Array.isArray(raw) ? raw : (raw.files ?? []);
+      const list = Array.isArray(raw) ? raw : (raw.items ?? raw.files ?? []);
       return list
         .map((entry) => (typeof entry === 'string' ? entry : entry?.filePath ?? entry?.path))
         .filter(isSemanticFile)

package/src/core/codeintel/summaries.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { getSyntaxProvider } from './providers.js';
+import { getSyntaxProvider, IndexFileSyntaxProvider } from './providers.js';
 import { resolveProjectRelativePath } from '../fileOps.js';
 
 // Deterministic extractive summaries (SPEC §7/§8, CI-304) — the L3 detail tier.
@@ -118,12 +118,16 @@ function scanDeclarations(lines, maxSymbols) {
 
 async function symbolNames(rootDir, relPath, lines, maxSymbols) {
   try {
-    const provider = getSyntaxProvider(relPath);
-    if (provider) {
-      const syms = await provider.symbols(relPath);
-      if (Array.isArray(syms) && syms.length > 0) {
-        return syms.slice(0, maxSymbols).map((s) => s.name).filter(Boolean);
-      }
+    let provider = getSyntaxProvider(relPath);
+    // The registry's built-in 'index-file' provider is bound to process.cwd()
+    // at ensureBuiltins() time — rebind it to this call's rootDir so summaries
+    // read the project index even when cwd differs (or supports() failed).
+    if (!provider || provider.name === 'index-file') {
+      provider = new IndexFileSyntaxProvider({ rootDir });
+    }
+    const syms = await provider.symbols(relPath);
+    if (Array.isArray(syms) && syms.length > 0) {
+      return syms.slice(0, maxSymbols).map((s) => s.name).filter(Boolean);
     }
   } catch {
     // provider failure falls through to the regex lane — never throws

package/src/core/compact/contextBudget.js

@@ -27,6 +27,31 @@ export function deriveAutoCompactWindow(hardCapTokens, ratio) {
   return Math.round(hardCapTokens * safeRatio);
 }
 
+// A malformed hard cap must fall back to a safe ceiling, never collapse to a
+// non-positive or fractional cap that would brick every Edit/Write/Bash call or
+// invert the autoCompactWindow < hardCapTokens invariant — same operator
+// contract as positiveInteger() in compact/threshold.js.
+function positiveInteger(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}
+
+// Pure normalization of a raw `compact` config object into the budget triple.
+// Exported so the fallback rules are testable without touching the shipped file.
+export function deriveCompactBudget(compact = {}) {
+  const source = compact && typeof compact === 'object' ? compact : {};
+  const tokenThreshold = Number.isFinite(source.tokenThreshold)
+    ? source.tokenThreshold
+    : EMERGENCY_BUDGET.tokenThreshold;
+  const hardCapTokens = positiveInteger(source.hardCapTokens, EMERGENCY_BUDGET.hardCapTokens);
+  return {
+    tokenThreshold,
+    hardCapTokens,
+    autoCompactWindow: deriveAutoCompactWindow(hardCapTokens, source.autoCompactWindowRatio),
+  };
+}
+
 let cachedBudget = null;
 
 export function loadShippedCompactBudget() {
@@ -41,17 +66,6 @@ export function loadShippedCompactBudget() {
     compact = EMERGENCY_BUDGET;
   }
 
-  const tokenThreshold = Number.isFinite(compact.tokenThreshold)
-    ? compact.tokenThreshold
-    : EMERGENCY_BUDGET.tokenThreshold;
-  const hardCapTokens = Number.isFinite(compact.hardCapTokens)
-    ? compact.hardCapTokens
-    : EMERGENCY_BUDGET.hardCapTokens;
-
-  cachedBudget = {
-    tokenThreshold,
-    hardCapTokens,
-    autoCompactWindow: deriveAutoCompactWindow(hardCapTokens, compact.autoCompactWindowRatio),
-  };
+  cachedBudget = deriveCompactBudget(compact);
   return cachedBudget;
 }

package/src/core/compact/index.js

@@ -1,4 +1,4 @@
-import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
 import { buildRuntimePaths } from '../runtimePaths.js';
 import { compressLine, compressMarkdownLines, estimateTokenCount, normalizeLineForDedupe, uniqueLines } from '../token/index.js';
 
@@ -183,7 +183,10 @@ function buildCompactedContextLines(
     const forceLine = nonEmptyCount < forceFirstCount;
     const wouldExceedLines = nonEmptyCount >= maxLines;
 
-    if (wouldExceedLines || (!forceLine && selected.length > 0 && (usedTokens + tokens) > maxTokens)) {
+    // Forced lines (header + anchors) are guaranteed placement: they bypass the
+    // line cap — dropping a forced anchor would silently break the anchor
+    // contract this function exists to enforce.
+    if ((!forceLine && wouldExceedLines) || (!forceLine && selected.length > 0 && (usedTokens + tokens) > maxTokens)) {
       break;
     }
 
@@ -247,12 +250,16 @@ export async function appendCompactHistory(
   }
 
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const history = await readCompactHistory(projectRoot, { maxEntries });
-  const nextDocument = normalizeCompactHistoryDocument({
-    entries: [normalizedEntry, ...history.entries],
-  }, { maxEntries });
-  await writeJson(runtimePaths.compactHistoryPath, nextDocument);
-  return nextDocument;
+  // Same read-modify-write race as compact-pressure.json: concurrent hook
+  // processes appending history must not drop each other's entries.
+  return withFileLock(runtimePaths.compactHistoryPath, async () => {
+    const history = await readCompactHistory(projectRoot, { maxEntries });
+    const nextDocument = normalizeCompactHistoryDocument({
+      entries: [normalizedEntry, ...history.entries],
+    }, { maxEntries });
+    await writeJson(runtimePaths.compactHistoryPath, nextDocument);
+    return nextDocument;
+  });
 }
 
 export async function recordCompaction(

package/src/core/docContracts.js

@@ -367,6 +367,14 @@ async function checkCommands(rootDir, registry) {
   return makeCheck(id, label, 'error', { passed: true });
 }
 
+// Logical line count: a trailing newline terminates the last line, it does not
+// start a phantom extra one — 'a\n' is 1 line, not 2.
+function countLines(content) {
+  if (!content) return 0;
+  const n = content.split('\n').length;
+  return content.endsWith('\n') ? n - 1 : n;
+}
+
 async function checkBudgets(rootDir, registry) {
   const id = 'budgets';
   const label = 'registry line budgets obeyed (error enforcement blocks)';
@@ -377,7 +385,7 @@ async function checkBudgets(rootDir, registry) {
     if (!Number.isInteger(e.budget.max_lines)) continue;
     const content = await readText(path.join(rootDir, e.path));
     if (content === null) continue;
-    const lines = content.split('\n').length;
+    const lines = countLines(content);
     if (lines <= e.budget.max_lines) continue;
     const msg = `${e.path}: ${lines} lines > max_lines ${e.budget.max_lines}`;
     if (e.budget.enforcement === 'error') errorViolations.push(msg);
@@ -531,7 +539,7 @@ async function checkArchiveSuggestions(rootDir, registry, nowMs) {
     const signals = [];
     if ((inbound.get(e.path)?.size ?? 0) === 0) signals.push('unreferenced');
     if (e.budget && Number.isInteger(e.budget.max_lines)) {
-      const lines = content.split('\n').length;
+      const lines = countLines(content);
       if (lines > e.budget.max_lines) signals.push('over-budget');
     }
     let st = null;