@ngockhoale/ukit 2.6.8 → 2.6.9

package/src/core/codeintel/vectorProvider.js

@@ -0,0 +1,213 @@
+import fs from 'node:fs/promises';
+
+import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION } from '../../index/paths.js';
+import { createEdge } from './providers.js';
+
+// Dep-free embedding lane (SPEC §2): feature hashing (FNV-1a 32-bit) over word
+// tokens + word-boundary trigrams, L2-normalized, cosine-ranked against the
+// same doc text the BM25 lane uses (file paths + symbol names). No file reads,
+// no deps — real embeddings plug in later through the injectable `loader`
+// seam (config.codeIntel.embedding.provider === 'auto'), degrading to the
+// hashed provider on ANY failure. Never throws.
+
+const DEFAULT_DIMENSIONS = 256;
+const DEFAULT_LIMIT = 20;
+
+function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i += 1) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h >>> 0;
+}
+
+function wordTokens(text) {
+  return String(text ?? '')
+    .split(/[^A-Za-z0-9_$]+/)
+    .map((t) => t.toLowerCase())
+    .filter(Boolean);
+}
+
+function trigrams(token) {
+  const padded = `#${token}#`;
+  const grams = [];
+  for (let i = 0; i + 3 <= padded.length; i += 1) {
+    grams.push(padded.slice(i, i + 3));
+  }
+  return grams;
+}
+
+/**
+ * hashVectorize(text, { dimensions }) → number[] of length `dimensions`,
+ * L2-normalized (zero vector for empty/null input). Deterministic.
+ */
+export function hashVectorize(text, { dimensions = DEFAULT_DIMENSIONS } = {}) {
+  const dims = Number.isInteger(dimensions) && dimensions > 0 ? dimensions : DEFAULT_DIMENSIONS;
+  const vec = new Array(dims).fill(0);
+  const tokens = wordTokens(text);
+  for (const token of tokens) {
+    vec[fnv1a(`w:${token}`) % dims] += 1;
+    for (const gram of trigrams(token)) {
+      vec[fnv1a(`t:${gram}`) % dims] += 0.1;
+    }
+  }
+  const norm = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0));
+  if (norm > 0) {
+    for (let i = 0; i < dims; i += 1) vec[i] /= norm;
+  }
+  return vec;
+}
+
+/** cosineSimilarity(a, b) → number in [-1, 1]; 0 on dim mismatch/empty. */
+export function cosineSimilarity(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length === 0 || a.length !== b.length) {
+    return 0;
+  }
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+
+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;
+  }
+}
+
+export class HashedEmbeddingProvider {
+  constructor({ projectRoot = process.cwd(), dimensions = DEFAULT_DIMENSIONS, embedFn = null } = {}) {
+    this.name = 'hashed-vector';
+    this.projectRoot = projectRoot;
+    this.dimensions = Number.isInteger(dimensions) && dimensions > 0 ? dimensions : DEFAULT_DIMENSIONS;
+    this._embedFn = typeof embedFn === 'function' ? embedFn : null;
+  }
+
+  async available() {
+    return true;
+  }
+
+  capabilities() {
+    return { embeddings: true, similarity: true };
+  }
+
+  async embed(text) {
+    if (this._embedFn) {
+      const vec = await this._embedFn(String(text ?? ''));
+      if (Array.isArray(vec)) return vec;
+    }
+    return hashVectorize(text, { dimensions: this.dimensions });
+  }
+
+  /**
+   * resolve(query, ctx { limit?, snapshot? }) → edge[] | null.
+   * Corpus: files.json paths + symbols.json names — index-bound, no file reads.
+   * Missing index → null (caller records 'unavailable'); empty index → [].
+   */
+  async resolve(query, ctx = {}) {
+    try {
+      const [filesArtifact, symbolsArtifact] = await Promise.all([
+        readArtifact(this.projectRoot, INDEX_ARTIFACTS.files),
+        readArtifact(this.projectRoot, INDEX_ARTIFACTS.symbols),
+      ]);
+      if (!filesArtifact && !symbolsArtifact) {
+        return null;
+      }
+      const limit = Number.isInteger(ctx?.limit) && ctx.limit > 0 ? ctx.limit : DEFAULT_LIMIT;
+      const queryVec = await this.embed(query);
+      const docs = new Map();
+      for (const item of filesArtifact?.items ?? []) {
+        if (!item?.filePath) continue;
+        docs.set(item.filePath, item.filePath);
+      }
+      for (const sym of symbolsArtifact?.items ?? []) {
+        if (!sym?.filePath || !sym?.name) continue;
+        docs.set(sym.filePath, `${docs.get(sym.filePath) ?? sym.filePath} ${sym.name}`);
+      }
+      const snapshot = ctx?.snapshot ?? null;
+      const scored = await Promise.all([...docs.entries()].map(async ([filePath, docText]) => ({
+        filePath,
+        score: cosineSimilarity(queryVec, await this.embed(docText)),
+      })));
+      return scored
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath))
+        .slice(0, limit)
+        .map((entry) => createEdge({
+          from: String(query ?? ''),
+          to: `${entry.filePath}:0`,
+          kind: 'vector',
+          confidence: entry.score,
+          provider: this.name,
+          evidence: 'hash-vectorizer',
+          snapshot,
+        }));
+    } catch {
+      return null;
+    }
+  }
+}
+
+export class NullEmbeddingProvider {
+  constructor() {
+    this.name = 'null';
+  }
+
+  async available() {
+    return false;
+  }
+
+  capabilities() {
+    return { embeddings: false, similarity: false };
+  }
+
+  async embed() {
+    return [];
+  }
+
+  async resolve() {
+    return null;
+  }
+}
+
+/**
+ * createEmbeddingProvider({ projectRoot, config, loader }) → provider.
+ * config.codeIntel.embedding.provider:
+ *   'hashed' (default) → HashedEmbeddingProvider
+ *   'auto'             → loader() module exposing embed(); ANY failure → Hashed
+ *   'null'             → NullEmbeddingProvider
+ */
+export function createEmbeddingProvider({ projectRoot = process.cwd(), config, loader } = {}) {
+  const embedding = config?.codeIntel?.embedding;
+  const setting = embedding?.provider ?? 'hashed';
+  const dimensions = embedding?.dimensions;
+  if (setting === 'null') {
+    return new NullEmbeddingProvider();
+  }
+  if (setting === 'auto' && typeof loader === 'function') {
+    try {
+      const mod = loader();
+      if (mod && typeof mod.embed === 'function') {
+        return new HashedEmbeddingProvider({ projectRoot, dimensions, embedFn: mod.embed });
+      }
+    } catch {
+      // fall through — degrade to hashed
+    }
+    return new HashedEmbeddingProvider({ projectRoot, dimensions });
+  }
+  return new HashedEmbeddingProvider({ projectRoot, dimensions });
+}

package/src/core/runtimeConfig.js

@@ -174,11 +174,17 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
         bm25: { k1: 1.2, b: 0.75 },
         merge: 'rrf',
         rrfK: 60,
-        weights: { exact: 1.0, symbol: 1.2, bm25: 0.8, semantic: 1.0 },
+        weights: { exact: 1.0, symbol: 1.2, bm25: 0.8, semantic: 1.0, vector: 0.6 },
       },
       impact: { defaultDepth: 2, maxDepth: 4, maxNodes: 200 },
       diagnostics: { enabled: true, timeoutMs: 8000 },
       providers: { semantic: 'null' },
+      // C30 additive blocks (SPEC §10 — TASK-222 single owner).
+      embedding: { provider: 'hashed', dimensions: 256 },
+      analogy: { enabled: true, limit: 5 },
+      cochange: { enabled: true, maxCommits: 500, minCount: 2, timeoutMs: 5000 },
+      summaries: { enabled: true, maxItems: 5 },
+      graph: { enabled: true, store: 'json' },
     },
     memoryV2: {
       enabled: true,
@@ -433,7 +439,7 @@ export function validateRuntimeConfig(config) {
       if (!isPlainObject(codeIntel.retriever.weights)) {
         errors.push('codeIntel.retriever.weights must be an object.');
       } else {
-        for (const lane of ['exact', 'symbol', 'bm25', 'semantic']) {
+        for (const lane of ['exact', 'symbol', 'bm25', 'semantic', 'vector']) {
           if (typeof codeIntel.retriever.weights[lane] !== 'number' || Number.isNaN(codeIntel.retriever.weights[lane])) {
             errors.push(`codeIntel.retriever.weights.${lane} must be a number.`);
           }
@@ -458,6 +464,48 @@ export function validateRuntimeConfig(config) {
     } else {
       pushNonEmptyStringError(errors, codeIntel.providers.semantic, 'codeIntel.providers.semantic');
     }
+    // C30 additive blocks (SPEC §10 — TASK-222).
+    if (!isPlainObject(codeIntel.embedding)) {
+      errors.push('codeIntel.embedding must be an object.');
+    } else {
+      const VALID_EMBEDDING_PROVIDERS = new Set(['hashed', 'auto', 'null']);
+      if (!VALID_EMBEDDING_PROVIDERS.has(codeIntel.embedding.provider)) {
+        errors.push(`codeIntel.embedding.provider must be one of: ${[...VALID_EMBEDDING_PROVIDERS].join(', ')}.`);
+      }
+      const dimensions = codeIntel.embedding.dimensions;
+      if (typeof dimensions !== 'number' || !Number.isInteger(dimensions) || dimensions <= 0 || dimensions > 4096) {
+        errors.push('codeIntel.embedding.dimensions must be a positive integer <= 4096.');
+      }
+    }
+    if (!isPlainObject(codeIntel.analogy)) {
+      errors.push('codeIntel.analogy must be an object.');
+    } else {
+      pushBooleanError(errors, codeIntel.analogy.enabled, 'codeIntel.analogy.enabled');
+      pushPositiveNumberError(errors, codeIntel.analogy.limit, 'codeIntel.analogy.limit');
+    }
+    if (!isPlainObject(codeIntel.cochange)) {
+      errors.push('codeIntel.cochange must be an object.');
+    } else {
+      pushBooleanError(errors, codeIntel.cochange.enabled, 'codeIntel.cochange.enabled');
+      pushPositiveNumberError(errors, codeIntel.cochange.maxCommits, 'codeIntel.cochange.maxCommits');
+      pushPositiveNumberError(errors, codeIntel.cochange.minCount, 'codeIntel.cochange.minCount');
+      pushPositiveNumberError(errors, codeIntel.cochange.timeoutMs, 'codeIntel.cochange.timeoutMs');
+    }
+    if (!isPlainObject(codeIntel.summaries)) {
+      errors.push('codeIntel.summaries must be an object.');
+    } else {
+      pushBooleanError(errors, codeIntel.summaries.enabled, 'codeIntel.summaries.enabled');
+      pushPositiveNumberError(errors, codeIntel.summaries.maxItems, 'codeIntel.summaries.maxItems');
+    }
+    if (!isPlainObject(codeIntel.graph)) {
+      errors.push('codeIntel.graph must be an object.');
+    } else {
+      pushBooleanError(errors, codeIntel.graph.enabled, 'codeIntel.graph.enabled');
+      const VALID_GRAPH_STORES = new Set(['json', 'scip', 'pdg', 'lsp', 'null']);
+      if (!VALID_GRAPH_STORES.has(codeIntel.graph.store)) {
+        errors.push(`codeIntel.graph.store must be one of: ${[...VALID_GRAPH_STORES].join(', ')}.`);
+      }
+    }
   }
 
   if (!isPlainObject(config.memoryV2)) {

package/src/index/buildIndex.js

@@ -1156,6 +1156,35 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
   };
 }
 
+// Derived artifacts (CI-303/CI-305): git-history co-change mining and the
+// merged code-graph store. Exported for the index CLI/install callers to run
+// after buildCodeIndex — intentionally NOT inside buildCodeIndex so the core
+// build's read/write discipline (atomic renames, no secondary artifact reads
+// on fresh builds) stays untouched. Optional, config-gated, never fatal: a
+// failure leaves the artifact absent and readers degrade to omitted/empty.
+export async function buildDerivedIndexArtifacts(absoluteRoot) {
+  const built = { cochange: null, codegraph: null };
+  try {
+    const { loadRuntimeConfig } = await import('../core/runtimeConfig.js');
+    const config = await loadRuntimeConfig(absoluteRoot);
+    const codeIntel = config?.codeIntel ?? {};
+    if (codeIntel.cochange?.enabled !== false) {
+      const { mineCoChanges } = await import('../core/codeintel/cochange.js');
+      built.cochange = await mineCoChanges(absoluteRoot, {
+        maxCommits: codeIntel.cochange?.maxCommits,
+        timeoutMs: codeIntel.cochange?.timeoutMs,
+      });
+    }
+    if (codeIntel.graph?.enabled !== false) {
+      const { buildGraphArtifact } = await import('../core/codeintel/graph.js');
+      built.codegraph = await buildGraphArtifact(absoluteRoot);
+    }
+  } catch {
+    // Derivation is best-effort; core artifacts already landed.
+  }
+  return built;
+}
+
 async function collectFiles(scanRoots, discovery = null) {
   const budget = discovery ?? createDiscoveryBudget({});
   const result = [];

package/src/index/paths.js

@@ -11,6 +11,8 @@ export const INDEX_ARTIFACTS = {
   archetypes: 'archetypes.json',
   relations: 'relations.json',
   analogs: 'analogs.json',
+  cochange: 'cochange.json',
+  codegraph: 'codegraph.json',
 };
 
 export const INDEX_SCHEMA_VERSION = 8;

package/templates/ukit/storage/config.json

@@ -192,11 +192,16 @@
       "bm25": { "k1": 1.2, "b": 0.75 },
       "merge": "rrf",
       "rrfK": 60,
-      "weights": { "exact": 1.0, "symbol": 1.2, "bm25": 0.8, "semantic": 1.0 }
+      "weights": { "exact": 1.0, "symbol": 1.2, "bm25": 0.8, "semantic": 1.0, "vector": 0.6 }
     },
     "impact": { "defaultDepth": 2, "maxDepth": 4, "maxNodes": 200 },
     "diagnostics": { "enabled": true, "timeoutMs": 8000 },
-    "providers": { "semantic": "null" }
+    "providers": { "semantic": "null" },
+    "embedding": { "provider": "hashed", "dimensions": 256 },
+    "analogy": { "enabled": true, "limit": 5 },
+    "cochange": { "enabled": true, "maxCommits": 500, "minCount": 2, "timeoutMs": 5000 },
+    "summaries": { "enabled": true, "maxItems": 5 },
+    "graph": { "enabled": true, "store": "json" }
   },
   "memoryV2": {
     "enabled": true,