@ngockhoale/ukit 2.6.7 → 2.6.9

package/src/core/codeintel/impact.js

@@ -0,0 +1,274 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION } from '../../index/paths.js';
+import { loadRuntimeConfig } from '../runtimeConfig.js';
+import { readCoChanges, coChangeEdges } from './cochange.js';
+
+// Multi-hop impact/trace engine (SPEC §4) — cycle-safe BFS over imports.json +
+// calls.json edges. `dependents` walks reverse edges (who imports the seed),
+// `dependencies` walks forward edges (what the seed imports/calls), `both`
+// unions the two with signed hops. Never throws: missing artifacts degrade to
+// an empty result with an `omitted` reason.
+
+const DEFAULT_DEPTH = 2;
+const DEFAULT_MAX_DEPTH = 4;
+const DEFAULT_MAX_NODES = 200;
+
+async function readArtifact(rootDir, name) {
+  try {
+    const raw = await fs.readFile(getArtifactPath(rootDir, name), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed?.schemaVersion !== undefined && parsed.schemaVersion !== INDEX_SCHEMA_VERSION) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// Local copy of the specifier resolver (SPEC §4 — do NOT import retriever.js,
+// a same-wave file). Resolves a relative/bare import specifier against the
+// indexed file set.
+function resolveRelativeSpecifier(fromFile, specifier, fileSet) {
+  const candidates = [];
+  if (specifier.startsWith('.')) {
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
+    candidates.push(base, `${base}.js`, `${base}.ts`, `${base}.mjs`, `${base}.jsx`, `${base}.tsx`, `${base}/index.js`, `${base}/index.ts`);
+  } else {
+    candidates.push(specifier);
+  }
+  for (const candidate of candidates) {
+    if (fileSet.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+function impactDefaults(config) {
+  const impact = config?.codeIntel?.impact;
+  return {
+    defaultDepth: typeof impact?.defaultDepth === 'number' ? impact.defaultDepth : DEFAULT_DEPTH,
+    maxDepth: typeof impact?.maxDepth === 'number' ? impact.maxDepth : DEFAULT_MAX_DEPTH,
+    maxNodes: typeof impact?.maxNodes === 'number' ? impact.maxNodes : DEFAULT_MAX_NODES,
+  };
+}
+
+function clampInt(value, min, max) {
+  const n = Math.floor(Number(value));
+  if (!Number.isFinite(n)) return min;
+  return Math.min(Math.max(n, min), max);
+}
+
+function addAdjacency(map, key, edge) {
+  let list = map.get(key);
+  if (!list) {
+    list = [];
+    map.set(key, list);
+  }
+  list.push(edge);
+}
+
+/**
+ * impactSet(projectRoot, seeds, { depth?, direction?, maxDepth?, maxNodes? })
+ *   → { nodes: [{ file, hop, via: edge[] }],
+ *       edges: [{ from, to, kind:'import'|'call', symbol? }],
+ *       truncated: boolean,
+ *       omitted: [{ what, why }] }
+ */
+export async function impactSet(projectRoot, seeds, {
+  depth,
+  direction = 'dependents',
+  maxDepth,
+  maxNodes,
+} = {}) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  const omitted = [];
+  const empty = { nodes: [], edges: [], truncated: false, omitted };
+
+  let config = null;
+  try {
+    config = await loadRuntimeConfig(rootDir);
+  } catch {
+    config = null;
+  }
+  const defaults = impactDefaults(config);
+
+  const maxDepthCap = clampInt(maxDepth ?? defaults.maxDepth, 1, Number.MAX_SAFE_INTEGER);
+  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) {
+    omitted.push({ what: 'impact', why: 'empty-seeds' });
+    return empty;
+  }
+
+  const [filesArtifact, importsArtifact, callsArtifact] = await Promise.all([
+    readArtifact(rootDir, INDEX_ARTIFACTS.files),
+    readArtifact(rootDir, INDEX_ARTIFACTS.imports),
+    readArtifact(rootDir, INDEX_ARTIFACTS.calls),
+  ]);
+
+  if (!importsArtifact && !callsArtifact) {
+    omitted.push({ what: 'impact', why: 'index-missing' });
+    return empty;
+  }
+
+  // File set for specifier resolution — files.json first, with imports' `from`
+  // endpoints as fallback so a partial index still resolves.
+  const fileSet = new Set((filesArtifact?.items ?? []).map((f) => f.filePath).filter(Boolean));
+  for (const imp of importsArtifact?.items ?? []) {
+    if (imp?.from) fileSet.add(imp.from);
+  }
+
+  // Adjacency: forward = dependencies (from → to), reverse = dependents (to → from).
+  const forward = new Map();
+  const reverse = new Map();
+  for (const imp of importsArtifact?.items ?? []) {
+    if (!imp?.from || !imp?.to) continue;
+    const target = resolveRelativeSpecifier(imp.from, imp.to, fileSet);
+    if (!target || target === imp.from) continue;
+    const edge = { from: imp.from, to: target, kind: 'import' };
+    addAdjacency(forward, edge.from, edge);
+    // Reverse edges are flipped so `from`/`to` always read seed→impacted.
+    addAdjacency(reverse, edge.to, { from: edge.to, to: edge.from, kind: 'import' });
+  }
+
+  // calls.json → symbol map; call edges are forward-only (dependencies side).
+  const symbolToFile = new Map();
+  for (const call of callsArtifact?.items ?? []) {
+    if (call?.filePath && call?.symbol && !symbolToFile.has(call.symbol)) {
+      symbolToFile.set(call.symbol, call.filePath);
+    }
+  }
+  const wantDeps = direction === 'dependencies' || direction === 'both';
+  const wantRev = direction === 'dependents' || direction === 'both';
+  if (wantDeps) {
+    for (const call of callsArtifact?.items ?? []) {
+      if (!call?.filePath) continue;
+      for (const name of call.calls ?? []) {
+        const target = symbolToFile.get(name);
+        if (!target || target === call.filePath) continue;
+        addAdjacency(forward, call.filePath, { from: call.filePath, to: target, kind: 'call', symbol: name });
+      }
+    }
+  }
+
+  // Resolve seeds → files. File seeds match indexed paths; symbol seeds match
+  // calls.json `symbol` fields (their filePath becomes the node).
+  const seedFiles = [];
+  for (const seed of seedList) {
+    if (fileSet.has(seed) || forward.has(seed) || reverse.has(seed)) {
+      seedFiles.push(seed);
+      continue;
+    }
+    const viaSymbol = symbolToFile.get(seed);
+    if (viaSymbol) {
+      seedFiles.push(viaSymbol);
+    }
+  }
+  if (seedFiles.length === 0) {
+    omitted.push({ what: 'impact', why: 'seeds-unmatched' });
+    return empty;
+  }
+
+  const nodes = new Map(); // file → { file, hop, via }
+  const edges = [];
+  const edgeKeys = new Set();
+  const visited = new Set(); // `${file}|${side}`
+  const sideHop = new Map(); // `${file}|${side}` → unsigned hop
+  let truncated = false;
+
+  const emitEdge = (edge) => {
+    const key = `${edge.from}|${edge.to}|${edge.kind}|${edge.symbol ?? ''}`;
+    if (edgeKeys.has(key)) return;
+    edgeKeys.add(key);
+    edges.push(edge);
+  };
+
+  // side: 'rev' (dependents, positive hop) | 'fwd' (dependencies, negative hop)
+  const bfs = (side) => {
+    const adjacency = side === 'rev' ? reverse : forward;
+    const sign = side === 'rev' ? 1 : -1;
+    const queue = [];
+    for (const seed of seedFiles) {
+      const key = `${seed}|${side}`;
+      if (!visited.has(key)) {
+        visited.add(key);
+        sideHop.set(key, 0);
+        queue.push({ file: seed, hop: 0 });
+      }
+    }
+    while (queue.length > 0) {
+      const { file, hop } = queue.shift();
+      if (hop >= depthLimit) continue;
+      for (const edge of adjacency.get(file) ?? []) {
+        const next = edge.to;
+        emitEdge(edge);
+        const visitKey = `${next}|${side}`;
+        if (visited.has(visitKey)) continue;
+        visited.add(visitKey);
+        const nextHop = hop + 1;
+        sideHop.set(visitKey, nextHop);
+        if (nodes.size >= nodeCap && !nodes.has(next)) {
+          truncated = true;
+          continue;
+        }
+        const existing = nodes.get(next);
+        if (!existing || Math.abs(nextHop) < Math.abs(existing.hop)) {
+          nodes.set(next, { file: next, hop: sign * nextHop, via: [edge] });
+        } else if (Math.abs(nextHop) === Math.abs(existing.hop)) {
+          existing.via.push(edge);
+        }
+        queue.push({ file: next, hop: nextHop });
+      }
+    }
+  };
+
+  if (wantRev) bfs('rev');
+  if (wantDeps) bfs('fwd');
+
+  // Detect hop-clamp truncation: any visited node at the cap whose adjacency
+  // still has unvisited neighbors would have produced more nodes.
+  const frontierCheck = (side) => {
+    const adjacency = side === 'rev' ? reverse : forward;
+    for (const [key, hop] of sideHop) {
+      if (hop !== depthLimit) continue;
+      const sep = key.lastIndexOf('|');
+      const file = key.slice(0, sep);
+      if (key.slice(sep + 1) !== side) continue;
+      for (const edge of adjacency.get(file) ?? []) {
+        if (!visited.has(`${edge.to}|${side}`)) return true;
+      }
+    }
+    return false;
+  };
+  if (frontierCheck('rev') || (wantDeps && frontierCheck('fwd'))) truncated = true;
+
+  // Co-change lane (SPEC §6): when enabled (in-code default true) and the
+  // direction touches dependents, union kind:'cochange' edges for seed peers
+  // (count ≥ minCount) as context — peers join `nodes` at hop:0 with via:[],
+  // not as graph hops. Missing artifact → omitted reason; never fatal.
+  const cochangeConfig = config?.codeIntel?.cochange;
+  const cochangeEnabled = cochangeConfig?.enabled !== false;
+  if (cochangeEnabled && wantRev) {
+    const cochangeArtifact = await readCoChanges(rootDir);
+    if (!cochangeArtifact) {
+      omitted.push({ what: 'cochange-lane', why: 'index-missing' });
+    } else {
+      const minCount = typeof cochangeConfig?.minCount === 'number' ? cochangeConfig.minCount : 2;
+      const coEdges = await coChangeEdges(rootDir, seedFiles, { minCount });
+      for (const edge of coEdges) {
+        emitEdge(edge);
+        if (!nodes.has(edge.to)) {
+          nodes.set(edge.to, { file: edge.to, hop: 0, via: [] });
+        }
+      }
+    }
+  }
+
+  return { nodes: [...nodes.values()], edges, truncated, omitted };
+}

package/src/core/codeintel/invalidation.js

@@ -0,0 +1,150 @@
+import path from 'node:path';
+import { getIndexDir } from '../../index/paths.js';
+import { ensureDir, readJsonIfExists, withFileLock, writeJson } from '../fileOps.js';
+
+/**
+ * Post-edit invalidation (SPEC §6 — CI-205).
+ *
+ * `.cache/index/dirty.json` is the shared on-disk contract between the edit
+ * lane (`notifyEdit`), the freshness lane (TASK-204 reads the file directly),
+ * the compiler (TASK-206 reads via `readDirty`, non-destructive), and the
+ * index-refresh lane (`drainDirty`).
+ *
+ * File shape: `{ schemaVersion: 1, paths: string[], saturated: boolean, updatedAt: string }`
+ * - `paths`: sorted, deduped, posix repo-relative paths.
+ * - `saturated`: true once the set hits `DIRTY_MAX_PATHS`; consumers treat a
+ *   saturated set as full invalidation (freshness falls back to full scan).
+ *
+ * Writes are atomic (tmp+rename via `writeJson`). `notifyEdit` merges via
+ * set-union inside a file lock (`withFileLock`) so concurrent callers never
+ * lose updates; read-merge-write retry (max 3) is kept as a fallback when the
+ * lock itself cannot be acquired. Missing/corrupt file → `[]`, never throws.
+ */
+
+export const DIRTY_SCHEMA_VERSION = 1;
+export const DIRTY_MAX_PATHS = 5000;
+
+const MERGE_MAX_ATTEMPTS = 3;
+
+export function getDirtyPath(projectRoot) {
+  return path.join(getIndexDir(projectRoot), 'dirty.json');
+}
+
+/**
+ * Normalize a candidate dirty path to a posix repo-relative form.
+ * Returns null for unsafe input: absolute paths, `..` escapes, empties.
+ */
+function normalizeDirtyPath(relPath) {
+  if (typeof relPath !== 'string') return null;
+  let p = relPath.trim().replace(/\\/g, '/');
+  if (!p) return null;
+  if (p.startsWith('/') || /^[A-Za-z]:\//.test(p)) return null; // absolute
+  while (p.startsWith('./')) p = p.slice(2);
+  if (!p || p === '.' ) return null;
+  const segments = p.split('/');
+  if (segments.some((s) => s === '..')) return null;
+  const normalized = path.posix.normalize(p);
+  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized === '..') {
+    return null;
+  }
+  return normalized;
+}
+
+function parseDirtyData(data) {
+  if (!data || typeof data !== 'object') return { paths: [], saturated: false };
+  const paths = Array.isArray(data.paths)
+    ? data.paths.filter((p) => typeof p === 'string')
+    : [];
+  return { paths, saturated: data.saturated === true };
+}
+
+async function readDirtyData(projectRoot) {
+  try {
+    const data = await readJsonIfExists(getDirtyPath(projectRoot));
+    return parseDirtyData(data);
+  } catch {
+    return { paths: [], saturated: false };
+  }
+}
+
+async function writeDirtyData(projectRoot, paths, saturated) {
+  const dirtyPath = getDirtyPath(projectRoot);
+  await ensureDir(path.dirname(dirtyPath));
+  await writeJson(dirtyPath, {
+    schemaVersion: DIRTY_SCHEMA_VERSION,
+    paths,
+    saturated,
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+/**
+ * Merge `relPaths` into the dirty set. Atomic, merge-safe (read-merge-write,
+ * retry max 3 on write failure), saturating at DIRTY_MAX_PATHS.
+ * @returns {Promise<{ dirty: string[] }>} sorted resulting set
+ */
+export async function notifyEdit(projectRoot, relPaths) {
+  const incoming = new Set();
+  for (const relPath of Array.isArray(relPaths) ? relPaths : []) {
+    const normalized = normalizeDirtyPath(relPath);
+    if (normalized) incoming.add(normalized);
+  }
+
+  const mergeOnce = async () => {
+    const current = await readDirtyData(projectRoot);
+    const merged = new Set(current.paths);
+    for (const p of incoming) merged.add(p);
+    const saturated = merged.size > DIRTY_MAX_PATHS;
+    const paths = [...merged].sort().slice(0, DIRTY_MAX_PATHS);
+    await writeDirtyData(projectRoot, paths, saturated);
+    return paths;
+  };
+
+  const dirtyPath = getDirtyPath(projectRoot);
+  let lastError = null;
+  for (let attempt = 0; attempt < MERGE_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      const paths = await withFileLock(dirtyPath, mergeOnce);
+      return { dirty: paths };
+    } catch (error) {
+      lastError = error;
+      // Fall back to unlocked merge if locking is unavailable on this fs.
+      if (attempt === MERGE_MAX_ATTEMPTS - 1) break;
+      try {
+        const paths = await mergeOnce();
+        return { dirty: paths };
+      } catch (error2) {
+        lastError = error2;
+      }
+    }
+  }
+  // Retry budget exhausted — surface the last write error's message without
+  // throwing past the never-throw contract boundary: return current state.
+  void lastError;
+  const current = await readDirtyData(projectRoot);
+  return { dirty: [...current.paths].sort() };
+}
+
+/**
+ * Non-destructive read of the dirty set (compiler lane uses this).
+ * @returns {Promise<string[]>} sorted paths, `[]` on missing/corrupt.
+ */
+export async function readDirty(projectRoot) {
+  const { paths } = await readDirtyData(projectRoot);
+  return [...paths].sort();
+}
+
+/**
+ * Return the accumulated dirty set and clear the file (index-refresh lane).
+ * @returns {Promise<string[]>} sorted paths, `[]` on missing/corrupt.
+ */
+export async function drainDirty(projectRoot) {
+  const { paths, saturated } = await readDirtyData(projectRoot);
+  if (paths.length === 0 && !saturated) return [];
+  try {
+    await writeDirtyData(projectRoot, [], false);
+  } catch {
+    // never throw — drained set is still returned
+  }
+  return [...paths].sort();
+}

package/src/core/codeintel/manifest.js

@@ -0,0 +1,176 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { getIndexDir } from '../../index/paths.js';
+
+// Manifest scanner (SPEC §1) — walks the project, records a sha1 per file, and
+// caches the result at `getIndexDir()/manifest.json`. The cache is validated on
+// (path, mtime, size) so an unchanged tree never re-hashes, and any mtime/size
+// drift forces a full rescan.
+
+const HARD_EXCLUDES = new Set(['.git', '.cache', 'node_modules']);
+const MANIFEST_CACHE = 'manifest.json';
+
+const IGNORED_BASENAMES = new Set(['.DS_Store']);
+
+function sha1(content) {
+  return crypto.createHash('sha1').update(content).digest('hex');
+}
+
+// Minimal .gitignore subset: blank lines and `#` comments skipped, `!` negation
+// unsupported (documented — negations are rare in-repo and the safe failure mode
+// is scanning a file that should be ignored, never dropping a needed one).
+// Supported: `name` (basename match anywhere), `dir/` (directory), `/path`
+// (root-anchored), `*` single-segment wildcard.
+function parseGitignore(content) {
+  return String(content ?? '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#') && !line.startsWith('!'));
+}
+
+function gitignorePatternToRegExp(pattern) {
+  let anchored = false;
+  let dirOnly = false;
+  let body = pattern;
+  if (body.endsWith('/')) {
+    dirOnly = true;
+    body = body.slice(0, -1);
+  }
+  if (body.startsWith('/')) {
+    anchored = true;
+    body = body.slice(1);
+  }
+  const escaped = body
+    .split('*')
+    .map((part) => part.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
+    .join('[^/]*');
+  if (anchored || body.includes('/')) {
+    return { re: new RegExp(`^${escaped}(?:/.*)?$`), dirOnly };
+  }
+  return { re: new RegExp(`(?:^|/)${escaped}(?:/.*)?$`), dirOnly };
+}
+
+function loadIgnoreMatchers(rootDir, extraIgnore) {
+  return fs.readFile(path.join(rootDir, '.gitignore'), 'utf8')
+    .then((content) => [...parseGitignore(content), ...(extraIgnore ?? [])])
+    .then((patterns) => patterns.map(gitignorePatternToRegExp))
+    .catch(() => (extraIgnore ?? []).map(gitignorePatternToRegExp));
+}
+
+function isIgnored(relPath, isDir, matchers) {
+  return matchers.some(({ re, dirOnly }) => (!dirOnly || isDir) && re.test(relPath));
+}
+
+async function walk(rootDir, matchers, options) {
+  const results = [];
+  const stack = [''];
+  while (stack.length > 0) {
+    const relDir = stack.pop();
+    const absDir = path.join(rootDir, relDir);
+    let entries;
+    try {
+      entries = await fs.readdir(absDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (HARD_EXCLUDES.has(entry.name)) {
+          continue;
+        }
+        if (isIgnored(relPath, true, matchers)) {
+          continue;
+        }
+        stack.push(relPath);
+      } else if (entry.isFile()) {
+        if (IGNORED_BASENAMES.has(entry.name)) {
+          continue;
+        }
+        if (isIgnored(relPath, false, matchers)) {
+          continue;
+        }
+        if (options?.filter && !options.filter(relPath)) {
+          continue;
+        }
+        try {
+          const stat = await fs.stat(path.join(rootDir, relPath));
+          results.push({ path: relPath, mtime: stat.mtimeMs, size: stat.size });
+        } catch {
+          // Vanished mid-walk — skip.
+        }
+      }
+    }
+  }
+  results.sort((a, b) => a.path.localeCompare(b.path));
+  return results;
+}
+
+async function readCachedManifest(rootDir) {
+  try {
+    const raw = await fs.readFile(path.join(getIndexDir(rootDir), MANIFEST_CACHE), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.files)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function snapshotMatches(cachedFiles, scannedFiles) {
+  if (!Array.isArray(cachedFiles) || cachedFiles.length !== scannedFiles.length) {
+    return false;
+  }
+  const byPath = new Map(cachedFiles.map((f) => [f.path, f]));
+  return scannedFiles.every((entry) => {
+    const cached = byPath.get(entry.path);
+    return cached && cached.mtime === entry.mtime && cached.size === entry.size
+      && typeof cached.sha1 === 'string';
+  });
+}
+
+/**
+ * scanManifest(projectRoot, { ignore, filter }) →
+ *   { files: [{ path, sha1, mtime, size }], generatedAt, fromCache }
+ *
+ * `ignore` adds .gitignore-style patterns on top of the repo .gitignore.
+ * `filter(relPath)` optionally keeps a subset of scanned files.
+ * Never throws on a missing/unreadable tree — returns an empty manifest.
+ */
+export async function scanManifest(projectRoot, { ignore, filter } = {}) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  const matchers = await loadIgnoreMatchers(rootDir, ignore);
+  const scanned = await walk(rootDir, matchers, { filter });
+
+  const cached = await readCachedManifest(rootDir);
+  if (cached && snapshotMatches(cached.files, scanned)) {
+    return { files: cached.files, generatedAt: cached.generatedAt, fromCache: true };
+  }
+
+  const files = await Promise.all(scanned.map(async (entry) => {
+    let fileSha = null;
+    try {
+      const content = await fs.readFile(path.join(rootDir, entry.path));
+      fileSha = sha1(content);
+    } catch {
+      fileSha = null;
+    }
+    return { path: entry.path, sha1: fileSha, mtime: entry.mtime, size: entry.size };
+  }));
+
+  const manifest = { files, generatedAt: new Date().toISOString() };
+  try {
+    await fs.mkdir(getIndexDir(rootDir), { recursive: true });
+    await fs.writeFile(
+      path.join(getIndexDir(rootDir), MANIFEST_CACHE),
+      JSON.stringify({ files, generatedAt: manifest.generatedAt }, null, 2),
+    );
+  } catch {
+    // Cache write failure must not fail the scan.
+  }
+  return { ...manifest, fromCache: false };
+}