@ngockhoale/ukit 2.6.6 → 2.6.8

package/src/core/codeintel/compiler.js

@@ -0,0 +1,316 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { createPacket, addEvidence, validatePacket } from './packet.js';
+import { guardLevel } from './freshness.js';
+import { routeTask } from './router.js';
+import { retrieve } from './retriever.js';
+import { impactSet } from './impact.js';
+import { readDirty } from './invalidation.js';
+import { runDiagnostics } from './diagnostics.js';
+import { createEdge } from './providers.js';
+import { loadRuntimeConfig } from '../runtimeConfig.js';
+
+// Context Compiler v1 (SPEC §5–§8) — the peek→expand→read detail ladder.
+//
+// Pipeline: routeTask (unless mode forced) → guardLevel (L0 freshness guard)
+// → retrieve → budget-fitted evidence selection (lowest-confidence first out,
+// drops recorded in `omitted`) → validatePacket.
+//
+// Depth ladder (evidence levels):
+//   peek                → L0 outline only (no excerpts, no relations)
+//   targeted | explore  → L1 + anchors + relations
+//   impact              → L2 + 1-hop reverse-import edges (retrieve mode impact)
+//   deep_flow | analogy → routed but no graph/embedding lanes in v1 →
+//                         `omitted: { what:'graph evidence', why:'provider unavailable' }`
+//   read                → L2 excerpts; emitted when depth >= 2 or `read:true`.
+//
+// Budget units are token estimates (≈ 4 chars/token over serialized evidence).
+// `budget.used` never exceeds `budget.requested` — anything that does not fit
+// lands in `omitted` with `why:'budget'`. Selective by contract: `none` mode
+// returns a valid packet with empty evidence, never fabricates context.
+
+const EXCERPT_MAX_LINES = 40;
+const EXCERPT_MAX_CHARS = 4000;
+const TOKEN_CHAR_RATIO = 4;
+
+const DEPTH_LEVEL = Object.freeze({
+  none: null,
+  peek: 'L0',
+  targeted: 'L1',
+  explore: 'L1',
+  impact: 'L2',
+  deep_flow: 'L2',
+  analogy: 'L2',
+});
+
+const UNAVAILABLE_LANES = new Set(['deep_flow', 'analogy']);
+
+function estimateTokens(value) {
+  try {
+    return Math.max(1, Math.ceil(JSON.stringify(value).length / TOKEN_CHAR_RATIO));
+  } catch {
+    return 1;
+  }
+}
+
+// Confidence proxy: retriever emits strongest lanes first, so array order is
+// the ranking. Selection walks candidates in order; whatever does not fit is
+// recorded in `omitted` with `why:'budget'` (lowest-confidence tail drops).
+// Evidence, anchors and relations all draw from the same token budget —
+// `budget.used` covers the whole emitted payload and never exceeds `requested`.
+function fitToBudget({ evidence, anchors, relations }, budgetTokens, dropped) {
+  let used = 0;
+  const fit = (items, label) => {
+    const kept = [];
+    for (const item of items) {
+      const cost = estimateTokens(item);
+      if (used + cost <= budgetTokens) {
+        kept.push(item);
+        used += cost;
+      } else {
+        dropped.push({ what: item.path ?? item.why ?? item.from ?? label, why: 'budget' });
+      }
+    }
+    return kept;
+  };
+  return {
+    evidence: fit(evidence, 'evidence'),
+    anchors: fit(anchors, 'anchor'),
+    relations: fit(relations, 'relation'),
+    used,
+  };
+}
+
+async function readExcerpt(rootDir, relPath) {
+  try {
+    const content = await fs.readFile(path.join(rootDir, relPath), 'utf8');
+    const lines = content.split('\n').slice(0, EXCERPT_MAX_LINES);
+    return lines.join('\n').slice(0, EXCERPT_MAX_CHARS);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeTask(task) {
+  if (typeof task === 'string') return { prompt: task };
+  if (task && typeof task === 'object') return { ...task };
+  return { prompt: '' };
+}
+
+/**
+ * compileContext(projectRoot, task, { mode?, budget?, depth?, read?, filesHinted?, diagnostics? })
+ *   → packet (Context Packet v1, always validatePacket-clean)
+ *
+ * `task` is a prompt string or `{ prompt, hasError?, filesHinted?, flags? }`.
+ * `mode` forces the router mode (same as `task.flags.mode`).
+ * `budget` overrides the routed token budget. `read:true` forces L2 excerpts.
+ * `depth` (>1, impact mode only) routes relations through multi-hop `impactSet`;
+ * `diagnostics` (default config.codeIntel.diagnostics.enabled) appends object
+ * `next_actions` — `{kind:'stale'}` for the dirty set + `{kind:'diagnostic'}`
+ * per `runDiagnostics` result.
+ */
+export async function compileContext(projectRoot, task, options = {}) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  const input = normalizeTask(task);
+  const opts = options && typeof options === 'object' ? options : {};
+
+  const flags = { ...(input.flags && typeof input.flags === 'object' ? input.flags : {}) };
+  if (typeof opts.mode === 'string' && opts.mode.trim() !== '') {
+    flags.mode = opts.mode.trim();
+  }
+
+  let config = null;
+  try {
+    config = await loadRuntimeConfig(rootDir);
+  } catch {
+    config = null;
+  }
+
+  const routed = routeTask(
+    { prompt: input.prompt ?? '', hasError: input.hasError === true, filesHinted: opts.filesHinted ?? input.filesHinted, flags },
+    { config },
+  );
+  const mode = routed.mode;
+  const requested = typeof opts.budget === 'number' && Number.isFinite(opts.budget) && opts.budget >= 0
+    ? opts.budget
+    : routed.budget;
+  const level = DEPTH_LEVEL[mode] ?? 'L1';
+  // `read` step of the ladder: L2 excerpts when routed depth >= 2 or --read.
+  const wantRead = opts.read === true || routed.depth >= 2;
+
+  // L0 freshness guard — never throws; staleness is reported, not repaired here.
+  let guard = null;
+  try {
+    guard = await guardLevel(rootDir, { maxLevel: 'L0' });
+  } catch {
+    guard = null;
+  }
+  const identity = guard?.identity ?? {};
+  const stale = guard?.stale === true;
+
+  const packet = createPacket({
+    repo: rootDir,
+    snapshot: typeof identity.identity === 'string' ? identity.identity : 'unknown',
+    taskType: mode,
+    budget: { requested },
+  });
+  packet.freshness = {
+    level: guard?.recommendedLevel ?? 'L0',
+    headSha: identity.headSha ?? '',
+    overlayHash: identity.overlayHash ?? '',
+    configHash: identity.configHash ?? '',
+    stale,
+  };
+  if (stale) {
+    packet.next_actions.push(`ukit index refresh — snapshot stale (repair level ${guard?.recommendedLevel ?? 'L2'})`);
+  }
+
+  // `none` mode: valid packet, empty evidence, reason recorded — never fabricate.
+  if (mode === 'none' || requested === 0) {
+    packet.omitted.push({ what: 'retrieval', why: mode === 'none' ? 'mode-none' : 'budget' });
+    return packet;
+  }
+
+  if (UNAVAILABLE_LANES.has(mode)) {
+    packet.omitted.push({ what: 'graph evidence', why: 'provider unavailable' });
+  }
+
+  const query = typeof opts.query === 'string' && opts.query.trim() !== ''
+    ? opts.query
+    : (input.prompt ?? '');
+  const retrieveMode = mode === 'impact' ? 'impact' : 'search';
+
+  // Impact-mode hop depth: explicit opt > config default. depth > 1 switches
+  // relations to the multi-hop impactSet lane; depth 1 keeps the C26 1-hop lane.
+  const impactDefaults = config?.codeIntel?.impact ?? {};
+  const configuredDepth = typeof impactDefaults.defaultDepth === 'number' ? impactDefaults.defaultDepth : 2;
+  const depth = typeof opts.depth === 'number' && Number.isFinite(opts.depth) && opts.depth > 0
+    ? opts.depth
+    : configuredDepth;
+  const multiHopImpact = mode === 'impact' && depth > 1;
+
+  let result = { anchors: [], evidence: [], relations: [], omitted: [] };
+  try {
+    result = await retrieve(rootDir, query, {
+      // Multi-hop lane handles relations itself — retriever stays in 'search'
+      // mode so its 1-hop edges do not duplicate impactSet output.
+      mode: multiHopImpact ? 'search' : retrieveMode,
+      snapshot: typeof identity.identity === 'string' ? identity.identity : null,
+    });
+  } catch {
+    packet.omitted.push({ what: 'retrieval', why: 'retriever-error' });
+  }
+
+  for (const entry of result.omitted ?? []) {
+    packet.omitted.push(entry);
+  }
+
+  // Multi-hop impact relations (SPEC §8): BFS over imports/calls artifacts at
+  // the requested depth, mapped to the canonical createEdge shape.
+  if (multiHopImpact) {
+    try {
+      const seeds = (result.anchors ?? []).map((a) => a?.path).filter(Boolean);
+      const impact = await impactSet(rootDir, seeds, { depth, direction: 'dependents' });
+      result = {
+        ...result,
+        relations: impact.edges.map((edge) => createEdge({
+          from: edge.from,
+          to: edge.to,
+          kind: edge.kind ?? 'import',
+          confidence: 1,
+          provider: 'index-file',
+          evidence: 'imports.json',
+          snapshot: typeof identity.identity === 'string' ? identity.identity : null,
+        })),
+      };
+      for (const entry of impact.omitted ?? []) packet.omitted.push(entry);
+      if (impact.truncated) {
+        packet.omitted.push({ what: 'impact-nodes', why: 'truncated' });
+      }
+    } catch {
+      packet.omitted.push({ what: 'impact-lane', why: 'impact-error' });
+    }
+  }
+
+  // L0 peek emits outline-level evidence only: same paths, no excerpts.
+  const candidates = (result.evidence ?? []).map((item) => {
+    const next = { ...item, level };
+    delete next.excerpt;
+    return next;
+  });
+
+  // L2 read lane: attach excerpts to the top candidates only.
+  if (wantRead && level !== 'L0') {
+    for (const item of candidates) {
+      if (!item.path) continue;
+      const excerpt = await readExcerpt(rootDir, item.path);
+      if (excerpt) item.excerpt = excerpt;
+    }
+  }
+
+  const dropped = [];
+  const expandLanes = level !== 'L0';
+  const fitted = fitToBudget(
+    {
+      evidence: candidates,
+      anchors: expandLanes ? (result.anchors ?? []) : [],
+      relations: expandLanes ? (result.relations ?? []) : [],
+    },
+    requested,
+    dropped,
+  );
+  for (const item of fitted.evidence) {
+    try {
+      addEvidence(packet, item);
+    } catch {
+      dropped.push({ what: item.path ?? 'evidence', why: 'invalid-evidence' });
+    }
+  }
+  if (!expandLanes) {
+    for (const rel of result.relations ?? []) {
+      dropped.push({ what: `${rel.from}→${rel.to}`, why: 'budget' });
+    }
+  }
+  packet.anchors = fitted.anchors;
+  packet.relations = fitted.relations;
+  packet.omitted.push(...dropped);
+  packet.budget.used = fitted.used;
+
+  // Diagnostics lane (SPEC §8): non-destructive dirty-set read → stale entry +
+  // cheap per-file checks → diagnostic entries. Mixed string/object
+  // next_actions is contract-legal (validatePacket only requires an array).
+  const diagnosticsEnabled = typeof opts.diagnostics === 'boolean'
+    ? opts.diagnostics
+    : config?.codeIntel?.diagnostics?.enabled === true;
+  if (diagnosticsEnabled) {
+    try {
+      const dirty = await readDirty(rootDir);
+      if (dirty.length > 0) {
+        packet.next_actions.push({ kind: 'stale', files: dirty.slice(0, 10), why: 'dirty-since-index' });
+        const timeoutMs = typeof config?.codeIntel?.diagnostics?.timeoutMs === 'number'
+          ? config.codeIntel.diagnostics.timeoutMs
+          : 8000;
+        const diags = await runDiagnostics(rootDir, dirty, { timeoutMs });
+        for (const d of diags.slice(0, 10)) {
+          packet.next_actions.push({
+            kind: 'diagnostic',
+            file: d.file,
+            message: d.message,
+            severity: d.severity,
+          });
+        }
+      }
+    } catch {
+      packet.omitted.push({ what: 'diagnostics', why: 'diagnostics-error' });
+    }
+  }
+
+  const validation = validatePacket(packet);
+  if (!validation.ok) {
+    // Contract safety net: a packet that cannot validate is still returned in
+    // minimal form rather than throwing — callers always get a packet.
+    packet.omitted.push({ what: 'packet', why: `validation: ${validation.errors.join('; ')}` });
+  }
+  return packet;
+}

package/src/core/codeintel/diagnostics.js

@@ -0,0 +1,114 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// Post-edit diagnostics (SPEC §7 — CI-206). Cheap checks over dirty paths:
+// `node --check` for .js/.mjs/.cjs, `JSON.parse` for .json. Everything else is
+// skipped silently. Never throws: missing files, spawn failures and timeouts
+// degrade to a `severity:'warning'` entry or are skipped — the caller always
+// gets a (possibly empty) normalized diagnostics list.
+
+const SYNTAX_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']);
+const MAX_DIAGNOSTICS = 50;
+
+function parseCheckLine(stderr) {
+  const line = 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*$/);
+  return {
+    message: line,
+    line: match ? Number.parseInt(match[1], 10) : null,
+  };
+}
+
+async function checkJson(rootDir, relPath) {
+  let content;
+  try {
+    content = await fs.readFile(path.join(rootDir, relPath), 'utf8');
+  } catch {
+    return null; // missing file → skip
+  }
+  try {
+    JSON.parse(content);
+    return null;
+  } catch (error) {
+    const message = error?.message ?? String(error);
+    const match = message.match(/position (\d+)/i);
+    const diag = { file: relPath, severity: 'error', message, source: 'json' };
+    if (match) {
+      const offset = Number.parseInt(match[1], 10);
+      const line = content.slice(0, offset).split('\n').length;
+      if (Number.isFinite(line) && line > 0) diag.line = line;
+    }
+    return diag;
+  }
+}
+
+async function checkSyntax(rootDir, relPath, timeoutMs, spawn) {
+  const absPath = path.join(rootDir, relPath);
+  try {
+    await fs.access(absPath);
+  } catch {
+    return null; // missing file → skip
+  }
+  let result;
+  try {
+    result = spawn(process.execPath, ['--check', absPath], {
+      timeout: timeoutMs,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+  } catch (error) {
+    return { file: relPath, severity: 'warning', message: `spawn failed: ${error?.message ?? error}`, source: 'syntax' };
+  }
+  if (!result || typeof result !== 'object') {
+    return { file: relPath, severity: 'warning', message: 'spawn failed: no result', source: 'syntax' };
+  }
+  const timedOut = result.signal === 'SIGTERM' || result.error?.code === 'ETIMEDOUT';
+  if (timedOut) {
+    return { file: relPath, severity: 'warning', message: `syntax check timed out after ${timeoutMs}ms`, source: 'syntax' };
+  }
+  if (result.error) {
+    return { file: relPath, severity: 'warning', message: `spawn failed: ${result.error.message}`, source: 'syntax' };
+  }
+  if (result.status === 0) return null;
+  const { message, line } = parseCheckLine(result.stderr || result.stdout);
+  const diag = { file: relPath, severity: 'error', message, source: 'syntax' };
+  if (line !== null) diag.line = line;
+  return diag;
+}
+
+/**
+ * runDiagnostics(projectRoot, relPaths, { timeoutMs?, maxFiles? })
+ *   → [{ file, severity:'error'|'warning', message, line?, source:'syntax'|'json' }]
+ *
+ * Deterministic order (input order preserved); capped at `maxFiles` inputs and
+ * MAX_DIAGNOSTICS total entries. `_spawn` is a test seam for timeout injection.
+ */
+export async function runDiagnostics(projectRoot, relPaths, {
+  timeoutMs = 8000,
+  maxFiles = 50,
+  _spawn = spawnSync,
+} = {}) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  const diagnostics = [];
+  const inputs = (Array.isArray(relPaths) ? relPaths : [])
+    .filter((p) => typeof p === 'string' && p.length > 0)
+    .slice(0, Math.max(0, maxFiles));
+
+  for (const relPath of inputs) {
+    if (diagnostics.length >= MAX_DIAGNOSTICS) break;
+    const ext = path.posix.extname(relPath.replace(/\\/g, '/')).toLowerCase();
+    let diag = null;
+    if (ext === '.json') {
+      diag = await checkJson(rootDir, relPath);
+    } else if (SYNTAX_EXTENSIONS.has(ext)) {
+      diag = await checkSyntax(rootDir, relPath, timeoutMs, _spawn);
+    }
+    if (diag) diagnostics.push(diag);
+  }
+  return diagnostics;
+}