@ngockhoale/ukit 2.6.8 → 2.6.9

package/src/core/codeintel/graph.js

@@ -0,0 +1,291 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION } from '../../index/paths.js';
+import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { createEdge } from './providers.js';
+import { COCHANGE_SCHEMA_VERSION } from './cochange.js';
+
+// Graph contract + JSON store (SPEC §9 — CI-305). Builds `.cache/index/codegraph.json`
+// from existing index artifacts (imports.json + calls.json, + cochange.json when
+// present) and exposes a GraphProvider seam so SCIP/PDG/LSP backends can slot in
+// later without touching consumers. No SQLite, no new deps — providers other than
+// 'json' are contract-only NullGraphProvider stubs this cycle.
+
+export const GRAPH_SCHEMA_VERSION = 1;
+
+const VALID_GRAPH_STORES = new Set(['json', 'scip', 'pdg', 'lsp', 'null']);
+
+async function readArtifact(rootDir, name, expectedSchemaVersion) {
+  try {
+    const raw = await fs.readFile(getArtifactPath(rootDir, name), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    if (expectedSchemaVersion !== undefined && parsed.schemaVersion !== expectedSchemaVersion) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// Same specifier-resolution discipline as impact.js — local copy so this lane
+// does not import same-wave sibling internals.
+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;
+}
+
+/**
+ * buildGraphArtifact(projectRoot) → artifact | null
+ *
+ * Merges imports.json + calls.json (+ cochange.json when present) into a
+ * codegraph.json artifact: { schemaVersion, generatedAt, nodes, edges }.
+ * Node ids: files → their relative path, symbols → `symbol:<name>`.
+ * Edges use the canonical createEdge shape. Writes the artifact atomically via
+ * fileOps.writeJson; returns null when no source artifacts exist. Never throws
+ * on missing/partial sources.
+ */
+export async function buildGraphArtifact(projectRoot) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+
+  const [importsArtifact, callsArtifact, cochangeArtifact, filesArtifact] = await Promise.all([
+    readArtifact(rootDir, INDEX_ARTIFACTS.imports, INDEX_SCHEMA_VERSION),
+    readArtifact(rootDir, INDEX_ARTIFACTS.calls, INDEX_SCHEMA_VERSION),
+    readArtifact(rootDir, INDEX_ARTIFACTS.cochange, COCHANGE_SCHEMA_VERSION),
+    readArtifact(rootDir, INDEX_ARTIFACTS.files, INDEX_SCHEMA_VERSION),
+  ]);
+
+  if (!importsArtifact && !callsArtifact && !cochangeArtifact) {
+    return null;
+  }
+
+  const fileSet = new Set();
+  for (const file of filesArtifact?.items ?? []) {
+    if (file?.filePath) fileSet.add(file.filePath);
+  }
+  for (const imp of importsArtifact?.items ?? []) {
+    if (imp?.from) fileSet.add(imp.from);
+  }
+  for (const call of callsArtifact?.items ?? []) {
+    if (call?.filePath) fileSet.add(call.filePath);
+  }
+
+  const nodes = new Map(); // id → node
+  const edges = new Map(); // dedupe key → edge
+  const addFileNode = (filePath) => {
+    if (filePath && !nodes.has(filePath)) {
+      nodes.set(filePath, { id: filePath, kind: 'file', path: filePath });
+    }
+  };
+  const addSymbolNode = (name, filePath) => {
+    if (!name) return null;
+    const id = `symbol:${name}`;
+    if (!nodes.has(id)) {
+      nodes.set(id, { id, kind: 'symbol', path: filePath ?? null });
+    }
+    return id;
+  };
+  const addEdge = (edge, dedupeExtra = '') => {
+    const key = `${edge.from}»${edge.to}»${edge.kind}»${dedupeExtra}`;
+    if (!edges.has(key)) edges.set(key, edge);
+  };
+
+  // import edges: from-file → resolved target file
+  for (const imp of importsArtifact?.items ?? []) {
+    if (!imp?.from || !imp?.to) continue;
+    addFileNode(imp.from);
+    const target = resolveRelativeSpecifier(imp.from, imp.to, fileSet) ?? imp.to;
+    if (target === imp.from) continue;
+    addFileNode(target);
+    addEdge(createEdge({
+      from: imp.from,
+      to: target,
+      kind: 'import',
+      provider: 'json-graph',
+      evidence: INDEX_ARTIFACTS.imports,
+    }));
+  }
+
+  // call edges: caller file → callee file (resolved via symbol→file map);
+  // symbol nodes recorded regardless so queries can address them.
+  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);
+    }
+  }
+  for (const call of callsArtifact?.items ?? []) {
+    if (!call?.filePath) continue;
+    addFileNode(call.filePath);
+    if (call?.symbol) addSymbolNode(call.symbol, call.filePath);
+    for (const name of call.calls ?? []) {
+      const target = symbolToFile.get(name);
+      if (!target || target === call.filePath) continue;
+      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;
+    addFileNode(pair.a);
+    addFileNode(pair.b);
+    const confidence = Math.min(1, (pair.count ?? 1) / 10);
+    addEdge(createEdge({
+      from: pair.a,
+      to: pair.b,
+      kind: 'cochange',
+      confidence,
+      provider: 'json-graph',
+      evidence: INDEX_ARTIFACTS.cochange,
+    }), String(pair.count ?? ''));
+    addEdge(createEdge({
+      from: pair.b,
+      to: pair.a,
+      kind: 'cochange',
+      confidence,
+      provider: 'json-graph',
+      evidence: INDEX_ARTIFACTS.cochange,
+    }), String(pair.count ?? ''));
+  }
+
+  const artifact = {
+    schemaVersion: GRAPH_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    nodes: [...nodes.values()],
+    edges: [...edges.values()],
+  };
+
+  try {
+    // Content-gated write: unchanged graph (ignoring generatedAt) must not
+    // bump the artifact mtime — refresh's "no rewrite when nothing changed"
+    // guarantee covers derived artifacts too.
+    const graphPath = getArtifactPath(rootDir, INDEX_ARTIFACTS.codegraph);
+    const existing = await readJsonIfExists(graphPath);
+    const strip = ({ generatedAt, ...rest }) => rest;
+    if (!existing || JSON.stringify(strip(existing)) !== JSON.stringify(strip(artifact))) {
+      await writeJson(graphPath, artifact);
+    }
+  } catch {
+    // Artifact-write failure (read-only .cache, EACCES) is non-fatal — the
+    // in-memory artifact is still returned for the caller/summary.
+  }
+  return artifact;
+}
+
+/**
+ * JsonGraphStore — GraphProvider over `.cache/index/codegraph.json`.
+ * Schema-guarded (GRAPH_SCHEMA_VERSION); a missing/mismatched/corrupt artifact
+ * yields empty results per op, never throws.
+ */
+export class JsonGraphStore {
+  constructor(projectRoot) {
+    this.name = 'json';
+    this.rootDir = path.resolve(projectRoot ?? process.cwd());
+    this._artifactPromise = null;
+  }
+
+  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));
+        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;
+        return artifact;
+      })();
+    }
+    return this._artifactPromise;
+  }
+
+  async nodes() {
+    const artifact = await this._load();
+    return artifact?.nodes ?? [];
+  }
+
+  async edgesFrom(id) {
+    const artifact = await this._load();
+    if (!artifact || typeof id !== 'string') return [];
+    return artifact.edges.filter((edge) => edge?.from === id);
+  }
+
+  /**
+   * query(q) → edge[] | null. Resolves a node id (file path or `symbol:` id) to
+   * its outgoing edges; null when the node is absent or no artifact exists.
+   */
+  async query(q) {
+    const artifact = await this._load();
+    if (!artifact) return null;
+    const nodeId = typeof q === 'object' && q !== null ? q.path ?? q.id ?? null : q;
+    if (typeof nodeId !== 'string' || nodeId === '') return null;
+    const exists = artifact.nodes.some((node) => node?.id === nodeId);
+    if (!exists) return null;
+    return artifact.edges.filter((edge) => edge?.from === nodeId);
+  }
+}
+
+/**
+ * NullGraphProvider — contract-only stub for SCIP/PDG/LSP/'null' backends.
+ * All capabilities false; every op returns empty/null. Never throws.
+ */
+export class NullGraphProvider {
+  constructor(backend = 'null') {
+    this.name = backend;
+  }
+
+  capabilities() {
+    return { nodes: false, edges: false, queries: false };
+  }
+
+  async nodes() {
+    return [];
+  }
+
+  async edgesFrom() {
+    return [];
+  }
+
+  async query() {
+    return null;
+  }
+}
+
+/**
+ * createGraphProvider({ projectRoot?, config? }) → GraphProvider
+ * codeIntel.graph.store: 'json' (default/unset) → JsonGraphStore;
+ * 'scip' | 'pdg' | 'lsp' | 'null' → NullGraphProvider (contract-only seam).
+ */
+export function createGraphProvider({ projectRoot, config } = {}) {
+  if (config?.codeIntel?.graph?.enabled === false) {
+    return new NullGraphProvider('disabled');
+  }
+  const store = config?.codeIntel?.graph?.store;
+  if (store === undefined || store === 'json') {
+    return new JsonGraphStore(projectRoot);
+  }
+  if (VALID_GRAPH_STORES.has(store)) {
+    return new NullGraphProvider(store);
+  }
+  return new NullGraphProvider('null');
+}

package/src/core/codeintel/impact.js

@@ -3,6 +3,7 @@ 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),
@@ -247,5 +248,27 @@ export async function impactSet(projectRoot, seeds, {
   };
   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/packet.js

@@ -108,6 +108,7 @@ export function packetToText(packet) {
   lines.push('## Evidence');
   for (const e of packet.evidence ?? []) {
     lines.push(`- [${e.level}/${e.source}] ${e.path ?? ''} — ${e.why ?? ''}`);
+    if (e.summary) lines.push(`  summary: ${e.summary}`);
     if (e.excerpt) lines.push(`  ${e.excerpt}`);
   }
   if ((packet.evidence ?? []).length === 0) lines.push('(none)');

package/src/core/codeintel/retriever.js

@@ -5,6 +5,7 @@ import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, normalizeRelati
 import { loadRuntimeConfig } from '../runtimeConfig.js';
 import { createEdge, getSemanticProvider, IndexFileSyntaxProvider } from './providers.js';
 import { createSemanticProvider } from './semanticProvider.js';
+import { createEmbeddingProvider } from './vectorProvider.js';
 
 // Hybrid Retriever (SPEC §3): each lane produces a ranked list of file paths,
 // then lanes merge via Reciprocal Rank Fusion (k=60, per-lane weights from
@@ -15,8 +16,8 @@ import { createSemanticProvider } from './semanticProvider.js';
 const DEFAULT_LIMIT = 20;
 const DEFAULT_BM25 = { k1: 1.2, b: 0.75 };
 const DEFAULT_RRF_K = 60;
-const DEFAULT_WEIGHTS = { exact: 1.0, symbol: 1.2, bm25: 0.8, semantic: 1.0 };
-const LANE_ORDER = ['exact', 'symbol', 'bm25', 'semantic'];
+const DEFAULT_WEIGHTS = { exact: 1.0, symbol: 1.2, bm25: 0.8, vector: 0.6, semantic: 1.0 };
+const LANE_ORDER = ['exact', 'symbol', 'bm25', 'vector', 'semantic'];
 
 async function readArtifact(rootDir, name) {
   try {
@@ -56,6 +57,7 @@ function retrieverDefaults(config) {
       exact: weight('exact'),
       symbol: weight('symbol'),
       bm25: weight('bm25'),
+      vector: weight('vector'),
       semantic: weight('semantic'),
     },
   };
@@ -192,6 +194,39 @@ async function semanticLane(rootDir, normalizedQuery, config, fileSet, snapshotI
   return { lane, why: lane.length === 0 ? 'no-match' : null };
 }
 
+// Vector lane (SPEC §2/§3): dep-free hashed embedding provider; mirrors the
+// semantic lane. Edges' `to` carries "file:0" — reduce to a ranked file list.
+async function vectorLane(rootDir, normalizedQuery, config, fileSet, snapshotId) {
+  const provider = createEmbeddingProvider({ projectRoot: rootDir, config });
+  if (!provider || provider.name === 'null' || typeof provider.resolve !== 'function') {
+    return { lane: null, why: 'unavailable' };
+  }
+  let edges;
+  try {
+    edges = await provider.resolve(normalizedQuery, { limit: DEFAULT_LIMIT, snapshot: snapshotId });
+  } catch {
+    return { lane: null, why: 'provider-error' };
+  }
+  if (edges === null || edges === undefined) {
+    return { lane: null, why: 'unavailable' };
+  }
+  if (!Array.isArray(edges) || edges.length === 0) {
+    return { lane: [], why: 'no-match' };
+  }
+  const lane = [];
+  const seen = new Set();
+  for (const edge of edges) {
+    const target = typeof edge?.to === 'string' ? edge.to.split(':')[0] : null;
+    if (!target) continue;
+    const rel = path.isAbsolute(target) ? normalizeRelative(rootDir, target) : target;
+    if (seen.has(rel)) continue;
+    if (fileSet.size > 0 && !fileSet.has(rel)) continue;
+    seen.add(rel);
+    lane.push(laneEntry(rel, `vector ${edge.kind ?? 'match'} for "${normalizedQuery}"`));
+  }
+  return { lane, why: lane.length === 0 ? 'no-match' : null };
+}
+
 function rrfMerge(lanes, weights, rrfK) {
   const scores = new Map();
   const meta = new Map();
@@ -199,6 +234,7 @@ function rrfMerge(lanes, weights, rrfK) {
     const lane = lanes.get(laneName);
     if (!lane) continue;
     const w = weights[laneName] ?? 0;
+    if (w <= 0) continue;
     lane.forEach((entry, index) => {
       scores.set(entry.path, (scores.get(entry.path) ?? 0) + w / (rrfK + index + 1));
       if (!meta.has(entry.path)) meta.set(entry.path, entry);
@@ -312,7 +348,17 @@ export async function retrieve(projectRoot, query, { mode = 'search', limit, sna
     lanes.set('bm25', bm25.slice(0, Math.max(effectiveLimit, 100)));
   }
 
-  // Lane 4 — semantic provider (defensive; absent → skipped, never fatal).
+  // Lane 4 — dep-free hashed vector provider (index-bound; absent → omitted).
+  const vector = await vectorLane(rootDir, normalizedQuery, config, fileSet, snapshotId);
+  if (vector.lane === null) {
+    omitted.push({ what: 'vector-lane', why: vector.why });
+  } else if (vector.lane.length > 0) {
+    lanes.set('vector', vector.lane);
+  } else {
+    omitted.push({ what: 'vector-lane', why: vector.why });
+  }
+
+  // Lane 5 — semantic provider (defensive; absent → skipped, never fatal).
   const semantic = await semanticLane(rootDir, normalizedQuery, config, fileSet, snapshotId);
   if (semantic.lane === null) {
     omitted.push({ what: 'semantic-lane', why: semantic.why });

package/src/core/codeintel/summaries.js

@@ -0,0 +1,194 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { getSyntaxProvider } from './providers.js';
+import { resolveProjectRelativePath } from '../fileOps.js';
+
+// Deterministic extractive summaries (SPEC §7/§8, CI-304) — the L3 detail tier.
+// No model calls, no clock/random, no new deps. File reads are bounded to the
+// first MAX_READ_LINES lines; extraction is pure text scanning over docblocks,
+// declaration regexes, and the index-file symbol provider.
+
+const MAX_READ_LINES = 200;
+const DEFAULT_MAX_CHARS = 240;
+const DEFAULT_SYMBOL_MAX_CHARS = 160;
+const DEFAULT_MAX_SYMBOLS = 8;
+
+const DECL_RE = /^\s*(?:export\s+default\s+|export\s+)?(?:async\s+)?(?:function\*?|class|const|let|var)\s+([A-Za-z_$][\w$]*)/;
+
+async function readHead(rootDir, relPath) {
+  try {
+    const abs = resolveProjectRelativePath(rootDir, relPath);
+    if (!abs) return null;
+    const content = await fs.readFile(abs, 'utf8');
+    return { content, lines: content.split('\n').slice(0, MAX_READ_LINES), bytes: Buffer.byteLength(content, 'utf8') };
+  } catch {
+    return null;
+  }
+}
+
+// Extract the first sentence of a docblock: with `endIndex` omitted, reads the
+// leading file-level docblock at the top of `lines`; with `endIndex`, finds the
+// docblock ending right before a declaration line (lines above decl passed in).
+function docblockFirstSentence(lines, endIndex = lines.length) {
+  if (endIndex === lines.length) {
+    // File-level lane: the docblock must start at (or near) the top of file.
+    let start = 0;
+    while (start < lines.length && (lines[start].trim() === '' || lines[start].startsWith('#!'))) start += 1;
+    const first = (lines[start] ?? '').trim();
+    const isBlock = first.startsWith('/*');
+    const isLine = first.startsWith('//');
+    if (!isBlock && !isLine) return null;
+    const block = [];
+    if (isLine) {
+      for (let i = start; i < lines.length; i += 1) {
+        const t = lines[i].trim();
+        if (!t.startsWith('//')) break;
+        block.push(t.replace(/^\/\/+\s?/, ''));
+      }
+    } else {
+      for (let i = start; i < lines.length; i += 1) {
+        const t = lines[i].trim();
+        block.push(t.replace(/^\/\*\*?\s?/, '').replace(/\*\/\s?$/, '').replace(/^\*\s?/, ''));
+        if (t.endsWith('*/')) break;
+      }
+    }
+    const text = block.join(' ').replace(/\s+/g, ' ').trim();
+    if (!text) return null;
+    const m = text.match(/^.+?[.!?](?:\s|$)/);
+    return (m ? m[0] : text).trim();
+  }
+
+  // Find the last docblock ending at or before endIndex, scanning backwards
+  // for a '*/' terminator so decl-adjacent blocks are preferred.
+  let end = -1;
+  for (let i = Math.min(endIndex, lines.length) - 1; i >= 0; i -= 1) {
+    const t = lines[i].trim();
+    if (t === '' || t.startsWith('//') || t.startsWith('/*') || t.startsWith('*') || t.endsWith('*/')) {
+      if (t.endsWith('*/')) { end = i; break; }
+      if (t.startsWith('//')) { end = i; break; }
+      continue;
+    }
+    break;
+  }
+  if (end < 0) return null;
+
+  const block = [];
+  const tail = lines[end].trim();
+  if (tail.startsWith('//')) {
+    for (let i = end; i >= 0; i -= 1) {
+      const t = lines[i].trim();
+      if (!t.startsWith('//')) break;
+      block.unshift(t.replace(/^\/\/+\s?/, ''));
+    }
+  } else {
+    for (let i = end; i >= 0; i -= 1) {
+      const t = lines[i].trim();
+      const isBoundary = t.startsWith('/**') || t.startsWith('/*');
+      block.unshift(t.replace(/^\/\*\*?\s?/, '').replace(/\*\/\s?$/, '').replace(/^\*\s?/, ''));
+      if (isBoundary) break;
+    }
+  }
+
+  const text = block.join(' ').replace(/\s+/g, ' ').trim();
+  if (!text) return null;
+  const m = text.match(/^.+?[.!?](?:\s|$)/);
+  return (m ? m[0] : text).trim();
+}
+
+// Truncate on a word boundary — never mid-word.
+function truncateWords(text, maxChars) {
+  if (text.length <= maxChars) return text;
+  const slice = text.slice(0, maxChars);
+  const lastSpace = slice.lastIndexOf(' ');
+  const cut = lastSpace > 0 ? slice.slice(0, lastSpace) : slice;
+  return cut.trimEnd();
+}
+
+// Regex fallback when the index symbols artifact is absent — bounded, dep-free.
+function scanDeclarations(lines, maxSymbols) {
+  const names = [];
+  for (const line of lines) {
+    const m = line.match(DECL_RE);
+    if (m && !names.includes(m[1])) names.push(m[1]);
+    if (names.length >= maxSymbols) break;
+  }
+  return names;
+}
+
+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);
+      }
+    }
+  } catch {
+    // provider failure falls through to the regex lane — never throws
+  }
+  return scanDeclarations(lines, maxSymbols);
+}
+
+/**
+ * summarizeFile(rootDir, relPath, { maxSymbols=8, maxChars=240 })
+ *   → { path, summary, symbolCount, bytes } | null
+ *
+ * Extractive summary: leading docblock first sentence + top symbol names.
+ * Falls back to a path/size description for docblock-free files. Returns null
+ * only when the file cannot be read. Deterministic across calls.
+ */
+export async function summarizeFile(rootDir, relPath, opts = {}) {
+  if (!relPath || typeof relPath !== 'string') return null;
+  const maxChars = typeof opts.maxChars === 'number' ? opts.maxChars : DEFAULT_MAX_CHARS;
+  const maxSymbols = typeof opts.maxSymbols === 'number' ? opts.maxSymbols : DEFAULT_MAX_SYMBOLS;
+
+  const head = await readHead(rootDir, relPath);
+  if (!head) return null;
+
+  const parts = [];
+  const doc = docblockFirstSentence(head.lines);
+  if (doc) parts.push(doc);
+
+  const names = await symbolNames(rootDir, relPath, head.lines, maxSymbols);
+  if (names.length > 0) parts.push(`exports: ${names.join(', ')}`);
+
+  const summary = parts.length > 0
+    ? parts.join(' — ')
+    : `${relPath} (${head.bytes} bytes)`;
+
+  return {
+    path: relPath,
+    summary: truncateWords(summary, maxChars),
+    symbolCount: names.length,
+    bytes: head.bytes,
+  };
+}
+
+/**
+ * summarizeSymbol(rootDir, relPath, symbolName, { maxChars=160 })
+ *   → { path, symbol, summary } | null
+ *
+ * Docblock-above-decl + the declaration signature line. Null when the file is
+ * unreadable or the symbol is absent. Deterministic.
+ */
+export async function summarizeSymbol(rootDir, relPath, symbolName, opts = {}) {
+  if (!relPath || !symbolName) return null;
+  const maxChars = typeof opts.maxChars === 'number' ? opts.maxChars : DEFAULT_SYMBOL_MAX_CHARS;
+
+  const head = await readHead(rootDir, relPath);
+  if (!head) return null;
+
+  const declIndex = head.lines.findIndex((line) => {
+    const m = line.match(DECL_RE);
+    return m && m[1] === symbolName;
+  });
+  if (declIndex < 0) return null;
+
+  const signature = head.lines[declIndex].trim();
+  const doc = docblockFirstSentence(head.lines, declIndex);
+  const summary = doc ? `${doc} ${signature}` : signature;
+
+  return { path: relPath, symbol: symbolName, summary: truncateWords(summary, maxChars) };
+}