@ngockhoale/ukit 2.6.7 → 2.6.9

package/src/core/codeintel/analogy.js

@@ -0,0 +1,197 @@
+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';
+
+// Analogy lane (SPEC §4, CI-302): ranks memory `procedure` records and
+// index-bound file/symbol fingerprints against the query by Jaccard overlap.
+// Read-only over both stores; every failure mode degrades into `omitted`
+// reasons — never throws, never fabricates analogies.
+//
+// fingerprint = sorted-unique normalized features:
+//   lowercase [a-z0-9_$.-] tokens (length >= 3, minus stopwords) plus
+//   camelCase/punctuation sub-splits so `routeTaskFiles` shares features with
+//   "route task files" and `src/routing.js` shares `routing`.
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'to', 'for', 'of', 'with', 'in', 'on', 'is', 'are',
+  'this', 'that', 'it', 'as', 'by', 'be', 'use', 'using', 'implement', 'fix', 'task',
+  'cần', 'và', 'là', 'cho', 'một', 'những', 'dùng',
+]);
+
+const MAX_MATCHED_FEATURES = 8;
+const DEFAULT_LIMIT = 5;
+
+function pushToken(set, raw) {
+  const token = String(raw ?? '').toLowerCase();
+  if (token.length >= 3 && !STOPWORDS.has(token)) set.add(token);
+  // Sub-split on punctuation + camelCase boundaries so compound tokens share
+  // features with their parts (e.g. `routeTaskFiles` → route/task/files).
+  const split = String(raw ?? '').replace(/([a-z0-9])([A-Z])/g, '$1 $2');
+  for (const part of split.split(/[^A-Za-z0-9_$]+/)) {
+    const sub = part.toLowerCase();
+    if (sub.length >= 3 && !STOPWORDS.has(sub)) set.add(sub);
+  }
+}
+
+/**
+ * fingerprintText(text) → string[] sorted-unique normalized features.
+ */
+export function fingerprintText(text) {
+  const features = new Set();
+  for (const token of String(text ?? '').split(/[^A-Za-z0-9_$.-]+/)) {
+    pushToken(features, token);
+  }
+  return [...features].sort();
+}
+
+/**
+ * fingerprintRecord(record) → string[] | null.
+ * Only `procedure` records carry an analogy fingerprint (SPEC §4).
+ */
+export function fingerprintRecord(record) {
+  if (!record || typeof record !== 'object') return null;
+  if (record.type !== 'procedure') return null;
+  const parts = [record.text];
+  if (record.meta && typeof record.meta === 'object') {
+    parts.push(JSON.stringify(record.meta));
+  }
+  if (record.provenance) parts.push(record.provenance);
+  return fingerprintText(parts.filter(Boolean).join(' '));
+}
+
+/**
+ * fingerprintFile({ filePath, symbols }) → string[] — path-shape tokens
+ * (incl. dir basenames) + symbol names.
+ */
+export function fingerprintFile({ filePath, symbols } = {}) {
+  const features = new Set(fingerprintText(filePath));
+  for (const sym of Array.isArray(symbols) ? symbols : []) {
+    for (const feature of fingerprintText(sym?.name)) features.add(feature);
+  }
+  return [...features].sort();
+}
+
+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;
+  }
+}
+
+// Memory lane — lazy-imported inside try/catch so a missing/disabled memory
+// v2 store degrades instead of throwing.
+async function loadProcedureCandidates(projectRoot, config) {
+  if (config?.memoryV2?.enabled === false) {
+    return { records: null, why: 'memory-unavailable' };
+  }
+  try {
+    const loader = await import('../memory/storeV2Loader.js');
+    const records = await import('../memory/records.js');
+    if (typeof loader?.loadV2Records !== 'function' || typeof records?.isRecordUsable !== 'function') {
+      return { records: null, why: 'memory-unavailable' };
+    }
+    const loaded = await loader.loadV2Records(projectRoot, { type: 'procedure' });
+    if (!Array.isArray(loaded) || loaded.length === 0) {
+      return { records: [], why: 'memory-unavailable' };
+    }
+    return { records: loaded.filter((r) => records.isRecordUsable(r)), why: null };
+  } catch {
+    return { records: null, why: 'memory-unavailable' };
+  }
+}
+
+function jaccard(querySet, candidateFeatures) {
+  let shared = 0;
+  const matched = [];
+  for (const feature of candidateFeatures) {
+    if (querySet.has(feature)) {
+      shared += 1;
+      if (matched.length < MAX_MATCHED_FEATURES) matched.push(feature);
+    }
+  }
+  if (shared === 0) return null;
+  const union = querySet.size + candidateFeatures.length - shared;
+  return { score: shared / union, matched };
+}
+
+/**
+ * findAnalogies(projectRoot, query, { limit = 5 }) →
+ *   { analogies: [{ kind:'procedure'|'code', ref, path?, score, matched:string[] }],
+ *     omitted: [{what,why}] }
+ *
+ * Jaccard over fingerprint sets; `score>0` rows only. Ties → ref localeCompare.
+ */
+export async function findAnalogies(projectRoot, query, { limit = DEFAULT_LIMIT } = {}) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  const effectiveLimit = Math.max(1, typeof limit === 'number' && Number.isFinite(limit) ? limit : DEFAULT_LIMIT);
+  const omitted = [];
+  const analogies = [];
+
+  const queryFeatures = new Set(fingerprintText(query));
+  if (queryFeatures.size === 0) {
+    omitted.push({ what: 'analogy-lane', why: 'empty-query-features' });
+    return { analogies, omitted };
+  }
+
+  let config = null;
+  try {
+    config = await loadRuntimeConfig(rootDir);
+  } catch {
+    config = null;
+  }
+
+  // Lane 1 — memory `procedure` records.
+  const memory = await loadProcedureCandidates(rootDir, config);
+  if (memory.why) {
+    omitted.push({ what: 'analogy-lane', why: memory.why });
+  }
+  for (const record of memory.records ?? []) {
+    const features = fingerprintRecord(record);
+    if (!features || features.length === 0) continue;
+    const hit = jaccard(queryFeatures, features);
+    if (!hit) continue;
+    analogies.push({ kind: 'procedure', ref: record.id, ...hit });
+  }
+
+  // Lane 2 — index files/symbols (schema-guarded artifact reads).
+  const [filesArtifact, symbolsArtifact] = await Promise.all([
+    readArtifact(rootDir, INDEX_ARTIFACTS.files),
+    readArtifact(rootDir, INDEX_ARTIFACTS.symbols),
+  ]);
+  if (!filesArtifact && !symbolsArtifact) {
+    omitted.push({ what: 'analogy-lane', why: 'index-missing' });
+  }
+  const symbolsByFile = new Map();
+  for (const sym of symbolsArtifact?.items ?? []) {
+    if (!sym?.filePath) continue;
+    const list = symbolsByFile.get(sym.filePath) ?? [];
+    list.push(sym);
+    symbolsByFile.set(sym.filePath, list);
+  }
+  const codePaths = new Set();
+  for (const item of filesArtifact?.items ?? []) {
+    if (item?.filePath) codePaths.add(item.filePath);
+  }
+  for (const filePath of symbolsByFile.keys()) codePaths.add(filePath);
+  for (const filePath of codePaths) {
+    const features = fingerprintFile({ filePath, symbols: symbolsByFile.get(filePath) ?? [] });
+    if (features.length === 0) continue;
+    const hit = jaccard(queryFeatures, features);
+    if (!hit) continue;
+    analogies.push({ kind: 'code', ref: filePath, path: filePath, ...hit });
+  }
+
+  analogies.sort((a, b) => b.score - a.score || a.ref.localeCompare(b.ref));
+  if (analogies.length === 0 && !memory.why && filesArtifact && symbolsArtifact) {
+    omitted.push({ what: 'analogy-lane', why: 'no-match' });
+  }
+  return { analogies: analogies.slice(0, effectiveLimit), omitted };
+}

package/src/core/codeintel/cochange.js

@@ -0,0 +1,205 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { getArtifactPath, INDEX_ARTIFACTS } from '../../index/paths.js';
+import { writeJson } from '../fileOps.js';
+
+// Co-change mining (SPEC §6 — CI-303). Parses bounded `git log --name-only`
+// history into co-commit pair counts persisted as `.cache/index/cochange.json`.
+// The artifact feeds `impactSet` context edges (kind:'cochange') only — it does
+// NOT create edges in the structural import/call graph. Never throws: non-git
+// dirs and git failures yield null.
+
+export const COCHANGE_SCHEMA_VERSION = 1;
+
+const MAX_FILES_PER_COMMIT = 50;
+const GIT_MAX_BUFFER = 16 * 1024 * 1024;
+
+// Same discipline as freshness.js runGit: spawnSync (no shell), bounded
+// timeout/maxBuffer, null on any failure — never throws.
+function runGit(rootDir, args, timeoutMs) {
+  try {
+    const result = spawnSync('git', args, {
+      cwd: rootDir,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      maxBuffer: GIT_MAX_BUFFER,
+    });
+    if (result.error || result.status !== 0) return null;
+    return result.stdout ?? '';
+  } catch {
+    return null;
+  }
+}
+
+function getHeadSha(rootDir, timeoutMs) {
+  const out = runGit(rootDir, ['rev-parse', 'HEAD'], timeoutMs);
+  const sha = (out || '').trim();
+  return /^[0-9a-f]{40}$/i.test(sha) ? sha.toLowerCase() : null;
+}
+
+// Parses `git log --name-only --format=sha:%H` output into
+// [{ sha, files: string[] }] commits. File lines are the non-sha, non-blank
+// lines following a `sha:` header.
+function parseLog(output) {
+  const commits = [];
+  let current = null;
+  for (const line of output.split('\n')) {
+    if (line.startsWith('sha:')) {
+      const sha = line.slice(4).trim();
+      if (/^[0-9a-f]{40}$/i.test(sha)) {
+        current = { sha: sha.toLowerCase(), files: [] };
+        commits.push(current);
+      } else {
+        current = null;
+      }
+      continue;
+    }
+    if (!current) continue;
+    const rel = line.trim();
+    if (rel) current.files.push(rel);
+  }
+  return commits;
+}
+
+function pairKey(a, b) {
+  return a < b ? `${a}|${b}` : `${b}|${a}`;
+}
+
+/**
+ * mineCoChanges(projectRoot, { maxCommits?, timeoutMs? })
+ *   → artifact { schemaVersion, generatedAt, headSha,
+ *                pairs: [{a,b,count,lastSha}] sorted a|b asc,
+ *                fileCounts: {file: n}, truncated: bool }
+ *   → null when git is unavailable/fails.
+ * Writes getArtifactPath(root, 'cochange') when non-null.
+ */
+export async function mineCoChanges(projectRoot, { maxCommits = 500, timeoutMs = 5000 } = {}) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  const cap = Number.isFinite(Number(maxCommits)) && Number(maxCommits) > 0
+    ? Math.floor(Number(maxCommits))
+    : 500;
+  const timeout = Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0
+    ? Math.floor(Number(timeoutMs))
+    : 5000;
+
+  const headSha = getHeadSha(rootDir, timeout);
+  if (!headSha) return null;
+
+  // Fetch cap+1 so we can detect truncation when history runs deeper.
+  const log = runGit(
+    rootDir,
+    ['-c', 'core.quotePath=false', 'log', '--name-only', '--format=sha:%H', '-n', String(cap + 1)],
+    timeout,
+  );
+  if (log === null) return null;
+
+  let commits = parseLog(log);
+  const truncated = commits.length > cap;
+  if (truncated) commits = commits.slice(0, cap);
+
+  const fileCounts = {};
+  const pairs = new Map(); // 'a|b' → { a, b, count, lastSha }
+  for (const commit of commits) {
+    const seen = new Set(commit.files);
+    for (const rel of seen) {
+      fileCounts[rel] = (fileCounts[rel] ?? 0) + 1;
+    }
+    // Giant commits (merge/squash noise) still count for fileCounts but are
+    // skipped for pair accumulation.
+    if (seen.size > MAX_FILES_PER_COMMIT) continue;
+    const files = [...seen];
+    for (let i = 0; i < files.length; i += 1) {
+      for (let j = i + 1; j < files.length; j += 1) {
+        const a = files[i] < files[j] ? files[i] : files[j];
+        const b = files[i] < files[j] ? files[j] : files[i];
+        const key = pairKey(a, b);
+        const existing = pairs.get(key);
+        if (existing) {
+          existing.count += 1;
+          // git log is newest-first: keep the first-seen sha (latest commit).
+        } else {
+          pairs.set(key, { a, b, count: 1, lastSha: commit.sha });
+        }
+      }
+    }
+  }
+
+  const artifact = {
+    schemaVersion: COCHANGE_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    headSha,
+    pairs: [...pairs.values()].sort((x, y) => pairKey(x.a, x.b).localeCompare(pairKey(y.a, y.b))),
+    fileCounts,
+    truncated,
+  };
+
+  try {
+    await writeJson(getArtifactPath(rootDir, INDEX_ARTIFACTS.cochange), artifact);
+  } catch {
+    // Artifact write failure is non-fatal: caller still gets the data.
+  }
+  return artifact;
+}
+
+/**
+ * readCoChanges(projectRoot) → artifact | null
+ * Schema-guarded: schemaVersion !== COCHANGE_SCHEMA_VERSION → null.
+ */
+export async function readCoChanges(projectRoot) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  try {
+    const raw = await fs.readFile(getArtifactPath(rootDir, INDEX_ARTIFACTS.cochange), 'utf8');
+    const artifact = JSON.parse(raw);
+    if (!artifact || typeof artifact !== 'object') return null;
+    if (artifact.schemaVersion !== COCHANGE_SCHEMA_VERSION) return null;
+    if (!Array.isArray(artifact.pairs)) return null;
+    return artifact;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * coChangeEdges(projectRoot, seeds, { minCount? })
+ *   → edge[] { from: seed, to: peer, kind: 'cochange',
+ *              confidence: min(1, count/10), provider: 'git-cochange',
+ *              evidence: 'cochange.json', snapshot: headSha }
+ * Returns [] when the artifact is missing/stale or no pairs qualify.
+ */
+export async function coChangeEdges(projectRoot, seeds, { minCount = 2 } = {}) {
+  const artifact = await readCoChanges(projectRoot);
+  if (!artifact) return [];
+  const threshold = Number.isFinite(Number(minCount)) ? Number(minCount) : 2;
+  const seedSet = new Set(
+    Array.isArray(seeds) ? seeds.filter((s) => typeof s === 'string' && s.length > 0) : [],
+  );
+  if (seedSet.size === 0) return [];
+
+  const edges = [];
+  for (const pair of artifact.pairs) {
+    if (!pair?.a || !pair?.b || typeof pair.count !== 'number') continue;
+    if (pair.count < threshold) continue;
+    let from = null;
+    let to = null;
+    if (seedSet.has(pair.a) && !seedSet.has(pair.b)) {
+      from = pair.a;
+      to = pair.b;
+    } else if (seedSet.has(pair.b) && !seedSet.has(pair.a)) {
+      from = pair.b;
+      to = pair.a;
+    }
+    if (!from) continue;
+    edges.push({
+      from,
+      to,
+      kind: 'cochange',
+      confidence: Math.min(1, pair.count / 10),
+      provider: 'git-cochange',
+      evidence: 'cochange.json',
+      snapshot: artifact.headSha,
+    });
+  }
+  return edges;
+}