@renzrollon/interlock 1.0.0

package/lib/graph/graph/query.mjs

@@ -0,0 +1,249 @@
+import { formatSubgraph } from '../format.mjs';
+
+/**
+ * Build adjacency maps from graph.
+ */
+export function indexGraph(graph) {
+  const nodes = new Map(graph.nodes.map((n) => [n.id, n]));
+  const out = new Map();
+  const inn = new Map();
+  for (const n of graph.nodes) {
+    out.set(n.id, []);
+    inn.set(n.id, []);
+  }
+  for (const e of graph.links) {
+    if (!out.has(e.source)) out.set(e.source, []);
+    if (!inn.has(e.target)) inn.set(e.target, []);
+    out.get(e.source).push(e);
+    inn.get(e.target).push(e);
+  }
+  return { nodes, out, inn };
+}
+
+/**
+ * Expand query tokens against node labels / ids / source_file.
+ */
+export function findSeedNodes(graph, query) {
+  const tokens = tokenize(query);
+  if (tokens.length === 0) return [];
+
+  const scored = [];
+  for (const n of graph.nodes) {
+    const hay = `${n.id} ${n.label} ${n.source_file || ''}`.toLowerCase();
+    let score = 0;
+    for (const t of tokens) {
+      if (n.label?.toLowerCase() === t) score += 10;
+      else if (n.id.toLowerCase().endsWith(`#${t}`)) score += 9;
+      else if (n.id.toLowerCase().includes(t)) score += 5;
+      else if (hay.includes(t)) score += 3;
+    }
+    if (score > 0) scored.push({ node: n, score });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, 8).map((s) => s.node);
+}
+
+function tokenize(query) {
+  return String(query)
+    .split(/[\s,|]+/)
+    .map((t) => t.trim().toLowerCase())
+    .filter((t) => t.length >= 2)
+    .map((t) => t.replace(/^file:/, '').replace(/^symbol:/, ''));
+}
+
+/**
+ * BFS or DFS neighborhood from seeds.
+ */
+export function traverse(graph, seeds, { mode = 'bfs', depth = 2, budget = 1500 } = {}) {
+  const { nodes, out, inn } = indexGraph(graph);
+  const seedIds = seeds.map((s) => s.id);
+  const visitedNodes = new Map();
+  const visitedEdges = [];
+  const queue = seedIds.map((id) => ({ id, d: 0 }));
+  const seen = new Set();
+
+  while (queue.length) {
+    const cur = mode === 'dfs' ? queue.pop() : queue.shift();
+    if (!cur || seen.has(cur.id)) continue;
+    seen.add(cur.id);
+    const node = nodes.get(cur.id);
+    if (node) visitedNodes.set(cur.id, node);
+
+    if (cur.d >= depth) continue;
+
+    const edges = [...(out.get(cur.id) || []), ...(inn.get(cur.id) || [])];
+    for (const e of edges) {
+      visitedEdges.push(e);
+      const next = e.source === cur.id ? e.target : e.source;
+      if (!seen.has(next)) {
+        if (mode === 'dfs') queue.push({ id: next, d: cur.d + 1 });
+        else queue.push({ id: next, d: cur.d + 1 });
+      }
+    }
+
+    // Early stop by rough token budget
+    const rough = visitedNodes.size * 20 + visitedEdges.length * 25;
+    if (rough > budget) break;
+  }
+
+  return formatSubgraph({
+    mode,
+    seeds: seedIds,
+    nodes: [...visitedNodes.values()],
+    edges: dedupeEdges(visitedEdges),
+    budget,
+  });
+}
+
+/**
+ * Reverse imports + references for a symbol or file.
+ */
+export function consumers(graph, target) {
+  const seeds = findSeedNodes(graph, target);
+  if (seeds.length === 0) {
+    return `No nodes matched: ${target}\n`;
+  }
+  const { nodes, inn } = indexGraph(graph);
+  const lines = [`Consumers of: ${seeds.map((s) => s.id).join(', ')}`, ''];
+
+  for (const seed of seeds) {
+    const incoming = (inn.get(seed.id) || []).filter(
+      (e) => e.relation === 'imports' || e.relation === 'references' || e.relation === 'implements_spec',
+    );
+    // Also: if seed is a symbol, include importers of its file that name the symbol
+    if (seed.type === 'symbol') {
+      const fileId = `file:${seed.source_file}`;
+      for (const e of inn.get(fileId) || []) {
+        if (e.relation === 'imports' && (e.imported === seed.label || e.local === seed.label)) {
+          incoming.push(e);
+        }
+      }
+    }
+    lines.push(`NODE ${seed.id} [${seed.source_file}:${seed.source_location}]`);
+    if (incoming.length === 0) {
+      lines.push('  (no consumers indexed)');
+    } else {
+      const seen = new Set();
+      for (const e of incoming) {
+        const key = `${e.source}|${e.relation}|${e.source_location}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const src = nodes.get(e.source);
+        lines.push(
+          `  EDGE ${short(e.source)} --${e.relation} [${e.confidence}]--> ${short(e.target)} (${e.source_file}:${e.source_location})`,
+        );
+        if (src?.type === 'file') {
+          lines.push(`    consumer_file: ${src.source_file}`);
+        }
+      }
+    }
+    lines.push('');
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Shortest path between two queries.
+ */
+export function shortestPath(graph, aQuery, bQuery) {
+  const aSeeds = findSeedNodes(graph, aQuery);
+  const bSeeds = findSeedNodes(graph, bQuery);
+  if (!aSeeds.length || !bSeeds.length) {
+    return `Could not resolve path endpoints.\n  A matches: ${aSeeds.length}\n  B matches: ${bSeeds.length}\n`;
+  }
+  const start = aSeeds[0].id;
+  const goals = new Set(bSeeds.map((s) => s.id));
+  const { nodes, out } = indexGraph(graph);
+
+  const prev = new Map();
+  const prevEdge = new Map();
+  const q = [start];
+  prev.set(start, null);
+  let found = null;
+
+  while (q.length) {
+    const cur = q.shift();
+    if (goals.has(cur)) {
+      found = cur;
+      break;
+    }
+    for (const e of out.get(cur) || []) {
+      if (!prev.has(e.target)) {
+        prev.set(e.target, cur);
+        prevEdge.set(e.target, e);
+        q.push(e.target);
+      }
+    }
+  }
+
+  if (!found) {
+    // try undirected
+    const { inn } = indexGraph(graph);
+    prev.clear();
+    prevEdge.clear();
+    q.length = 0;
+    q.push(start);
+    prev.set(start, null);
+    while (q.length) {
+      const cur = q.shift();
+      if (goals.has(cur)) {
+        found = cur;
+        break;
+      }
+      const edges = [...(out.get(cur) || []), ...(inn.get(cur) || [])];
+      for (const e of edges) {
+        const next = e.source === cur ? e.target : e.source;
+        if (!prev.has(next)) {
+          prev.set(next, cur);
+          prevEdge.set(next, e);
+          q.push(next);
+        }
+      }
+    }
+  }
+
+  if (!found) return `No path found between ${start} and ${[...goals].join('|')}\n`;
+
+  const pathNodes = [];
+  const pathEdges = [];
+  let cur = found;
+  while (cur) {
+    pathNodes.unshift(nodes.get(cur));
+    const e = prevEdge.get(cur);
+    if (e) pathEdges.unshift(e);
+    cur = prev.get(cur);
+  }
+
+  return formatSubgraph({
+    mode: 'path',
+    seeds: [start, found],
+    nodes: pathNodes.filter(Boolean),
+    edges: pathEdges,
+    budget: 5000,
+  });
+}
+
+/**
+ * Explain a single node and neighbors.
+ */
+export function explain(graph, query) {
+  const seeds = findSeedNodes(graph, query);
+  if (!seeds.length) return `No node matched: ${query}\n`;
+  return traverse(graph, seeds.slice(0, 1), { mode: 'bfs', depth: 1, budget: 2000 });
+}
+
+function dedupeEdges(edges) {
+  const seen = new Set();
+  const out = [];
+  for (const e of edges) {
+    const key = `${e.source}|${e.target}|${e.relation}|${e.source_location}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(e);
+  }
+  return out;
+}
+
+function short(id) {
+  return id.replace(/^(file|symbol|module|openspec|memory|external|unresolved):/, '');
+}

package/lib/graph/graph/report.mjs

@@ -0,0 +1,122 @@
+/**
+ * Generate GRAPH_REPORT.md content from a graph.
+ */
+export function writeReport(_root, graph, stats) {
+  const degree = new Map();
+  for (const n of graph.nodes) degree.set(n.id, { in: 0, out: 0, node: n });
+  for (const e of graph.links) {
+    if (degree.has(e.source)) degree.get(e.source).out += 1;
+    if (degree.has(e.target)) degree.get(e.target).in += 1;
+  }
+
+  const hubs = [...degree.values()]
+    .filter((d) => d.node.type === 'file' || d.node.type === 'symbol')
+    .map((d) => ({ ...d, total: d.in + d.out }))
+    .sort((a, b) => b.total - a.total)
+    .slice(0, 15);
+
+  const modules = graph.nodes
+    .filter((n) => n.type === 'module')
+    .map((m) => {
+      const members = graph.links
+        .filter((e) => e.relation === 'belongs_to' && e.target === m.id)
+        .map((e) => e.source.replace(/^file:/, ''));
+      return { ...m, members };
+    })
+    .sort((a, b) => b.members.length - a.members.length);
+
+  const surprising = graph.links
+    .filter((e) => e.confidence === 'INFERRED' && (e.relation === 'implements_spec' || e.relation === 'couples_with'))
+    .slice(0, 20);
+
+  const crossModule = [];
+  const fileModule = new Map();
+  for (const e of graph.links) {
+    if (e.relation === 'belongs_to' && e.source.startsWith('file:')) {
+      fileModule.set(e.source, e.target);
+    }
+  }
+  for (const e of graph.links) {
+    if (e.relation !== 'imports') continue;
+    if (!e.source.startsWith('file:') || !e.target.startsWith('file:')) continue;
+    const a = fileModule.get(e.source);
+    const b = fileModule.get(e.target);
+    if (a && b && a !== b) {
+      crossModule.push(e);
+    }
+  }
+
+  const lines = [];
+  lines.push('# Interlock Graph Report');
+  lines.push('');
+  lines.push(`Built: ${graph.graph?.built_at || 'unknown'}`);
+  lines.push(`Extractor: ${stats.extractor || graph.graph?.extractor || 'unknown'}`);
+  lines.push('');
+  lines.push('## Corpus stats');
+  lines.push('');
+  lines.push(`- Files: ${stats.files}`);
+  lines.push(`- Nodes: ${stats.nodes}`);
+  lines.push(`- Edges: ${stats.edges}`);
+  lines.push(`- Symbols: ${stats.symbols}`);
+  lines.push(`- Modules: ${stats.modules}`);
+  lines.push('');
+  lines.push('## God nodes (highest degree)');
+  lines.push('');
+  if (hubs.length === 0) {
+    lines.push('_None_');
+  } else {
+    for (const h of hubs) {
+      lines.push(
+        `- **${h.node.label}** (\`${h.node.source_file}${h.node.source_location ? ':' + h.node.source_location : ''}\`) — in:${h.in} out:${h.out} type:${h.node.type}`,
+      );
+    }
+  }
+  lines.push('');
+  lines.push('## Modules');
+  lines.push('');
+  for (const m of modules.slice(0, 30)) {
+    lines.push(`### ${m.label} (${m.members.length} files)`);
+    for (const f of m.members.slice(0, 12)) {
+      lines.push(`- \`${f}\``);
+    }
+    if (m.members.length > 12) lines.push(`- … +${m.members.length - 12} more`);
+    lines.push('');
+  }
+  lines.push('## Surprising / inferred connections');
+  lines.push('');
+  if (surprising.length === 0) {
+    lines.push('_None_');
+  } else {
+    for (const e of surprising) {
+      lines.push(
+        `- \`${short(e.source)}\` --${e.relation} [${e.confidence}]--> \`${short(e.target)}\` (${e.source_file}:${e.source_location})`,
+      );
+    }
+  }
+  lines.push('');
+  lines.push('## Cross-module imports (sample)');
+  lines.push('');
+  const sample = crossModule.slice(0, 25);
+  if (sample.length === 0) {
+    lines.push('_None_');
+  } else {
+    for (const e of sample) {
+      lines.push(
+        `- \`${short(e.source)}\` → \`${short(e.target)}\` (${e.source_file}:${e.source_location})`,
+      );
+    }
+  }
+  lines.push('');
+  lines.push('## Suggested questions');
+  lines.push('');
+  lines.push('- Which files import a given symbol? (`interlock-graph consumers <symbol>`)');
+  lines.push('- What is the shortest path between two modules/files? (`interlock-graph path A B`)');
+  lines.push('- What are the hub files in this repo? (see God nodes above)');
+  lines.push('- Which OpenSpec artifacts mention a symbol? (filter implements_spec edges)');
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function short(id) {
+  return id.replace(/^(file|symbol|module|openspec|memory|external|unresolved):/, '');
+}

package/lib/graph/graph/update.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import { walkSourceFiles } from '../extract/walk.mjs';
+import { loadJson, manifestPath, rel, sha256File } from '../paths.mjs';
+import { buildGraph, writeGraphArtifacts } from './build.mjs';
+
+/**
+ * Incremental update: rebuild fully if many files changed; otherwise rebuild all
+ * (v1 keeps it simple — detect staleness, then full rebuild of affected set + dependents
+ * is complex; we do full rebuild when any hash differs, which is still fast for mid-size repos).
+ *
+ * Returns { updated: boolean, stats, reason }.
+ */
+export function updateGraph(root) {
+  const manifest = loadJson(manifestPath(root), null);
+  if (!manifest?.files) {
+    const result = buildGraph(root);
+    writeGraphArtifacts(root, result);
+    return { updated: true, stats: result.stats, reason: 'no-manifest' };
+  }
+
+  const currentFiles = walkSourceFiles(root).map((f) => rel(root, f));
+  const prevFiles = new Set(Object.keys(manifest.files));
+  const changed = [];
+
+  for (const f of currentFiles) {
+    const abs = `${root}/${f}`;
+    if (!fs.existsSync(abs)) continue;
+    const hash = sha256File(abs);
+    if (manifest.files[f] !== hash) changed.push(f);
+    prevFiles.delete(f);
+  }
+  const removed = [...prevFiles];
+
+  if (changed.length === 0 && removed.length === 0) {
+    return { updated: false, stats: manifest.stats, reason: 'up-to-date' };
+  }
+
+  const result = buildGraph(root);
+  writeGraphArtifacts(root, result);
+  return {
+    updated: true,
+    stats: result.stats,
+    reason: `changed=${changed.length} removed=${removed.length}`,
+    changed,
+    removed,
+  };
+}

package/lib/graph/paths.mjs

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const GRAPH_DIR = '.claude/graph';
+export const GRAPH_FILE = 'graph.json';
+export const REPORT_FILE = 'GRAPH_REPORT.md';
+export const MANIFEST_FILE = 'manifest.json';
+export const DOCS_INDEX_FILE = 'docs-index.json';
+export const DOCS_DIGEST_FILE = 'DOCS_DIGEST.md';
+
+export function resolveRoot(cwd = process.cwd()) {
+  return path.resolve(cwd);
+}
+
+export function graphDir(root) {
+  return path.join(root, GRAPH_DIR);
+}
+
+export function graphPath(root) {
+  return path.join(graphDir(root), GRAPH_FILE);
+}
+
+export function reportPath(root) {
+  return path.join(graphDir(root), REPORT_FILE);
+}
+
+export function manifestPath(root) {
+  return path.join(graphDir(root), MANIFEST_FILE);
+}
+
+export function docsIndexPath(root) {
+  return path.join(graphDir(root), DOCS_INDEX_FILE);
+}
+
+export function docsDigestPath(root) {
+  return path.join(graphDir(root), DOCS_DIGEST_FILE);
+}
+
+export function ensureGraphDir(root) {
+  fs.mkdirSync(graphDir(root), { recursive: true });
+}
+
+export function rel(root, abs) {
+  return path.relative(root, abs).split(path.sep).join('/');
+}
+
+export function abs(root, relPath) {
+  return path.join(root, ...relPath.split('/'));
+}
+
+export function sha256File(filePath) {
+  const hash = createHash('sha256');
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest('hex');
+}
+
+export function loadJson(filePath, fallback = null) {
+  if (!fs.existsSync(filePath)) return fallback;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}

package/lib/graph/retrieve/context.mjs

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import { graphPath } from '../paths.mjs';
+import { loadGraph } from '../graph/build.mjs';
+import { findSeedNodes, traverse } from '../graph/query.mjs';
+import { deriveTerms, retrieveMarkdownSections } from './markdown.mjs';
+import { estimateTokens } from '../format.mjs';
+
+/**
+ * Build a combined context bundle: structural graph subgraph + ranked doc sections.
+ */
+export function retrieveContext(root, {
+  query = '',
+  changedFiles = [],
+  commitSubject = '',
+  budget = 2000,
+  graphBudget = null,
+  docsBudget = null,
+  docsDirs = null,
+} = {}) {
+  const terms = deriveTerms({ query, changedFiles, commitSubject });
+  const searchQuery = query || terms.slice(0, 8).join(' ');
+  const graphShare = graphBudget ?? Math.floor(budget * 0.45);
+  const docsShare = docsBudget ?? budget - graphShare;
+
+  const parts = [];
+  parts.push(`# Context bundle`);
+  parts.push(`Query: ${searchQuery || '(derived from changed files)'}`);
+  parts.push(`Terms: [${terms.join(', ')}] | total budget=${budget}`);
+  parts.push('');
+
+  let graphText = '';
+  let graphPresent = false;
+
+  if (fs.existsSync(graphPath(root))) {
+    try {
+      const graph = loadGraph(root);
+      const seeds = findSeedNodes(graph, searchQuery);
+      if (seeds.length > 0) {
+        graphText = traverse(graph, seeds, { mode: 'bfs', depth: 2, budget: graphShare });
+        graphPresent = true;
+      } else {
+        graphText = `Structural: no graph nodes matched "${searchQuery}" — using documentation retrieval only.\n`;
+      }
+    } catch (err) {
+      graphText = `Structural: graph load failed (${err.message}) — documentation retrieval only.\n`;
+    }
+  } else {
+    graphText =
+      `Structural: no graph at ${graphPath(root)} — run \`interlock-graph build .\` for import/symbol navigation.\n`;
+  }
+
+  parts.push('## Structural (graph)');
+  parts.push(graphText.trimEnd());
+  parts.push('');
+
+  const docsResult = retrieveMarkdownSections(root, {
+    query: searchQuery,
+    terms,
+    changedFiles,
+    dirs: docsDirs ?? undefined,
+    budget: docsShare,
+  });
+
+  parts.push(docsResult.text.trimEnd());
+
+  const text = `${parts.join('\n')}\n`;
+  return {
+    text,
+    terms,
+    graphPresent,
+    docsEmpty: docsResult.empty,
+    docsSectionCount: docsResult.sectionCount,
+    tokens: estimateTokens(text),
+    empty: !graphPresent && docsResult.empty,
+  };
+}
+
+export function formatContextResult(result) {
+  if (result.empty) {
+    return (
+      `${result.text}\n` +
+      `(empty bundle — no graph match and no documentation sections; try broader terms or build the graph)\n`
+    );
+  }
+  return result.text;
+}

package/lib/graph/retrieve/docs-index.mjs

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import {
+  docsDigestPath,
+  docsIndexPath,
+  ensureGraphDir,
+  rel,
+  sha256File,
+  writeJson,
+} from '../paths.mjs';
+import { walkMarkdown, resolveDocsDirs } from '../extract/walk.mjs';
+import { estimateTokens } from '../format.mjs';
+import { parseMarkdownSections } from './markdown.mjs';
+
+/** Preferred markdown roots for the docs digest index (never openspec/changes/). */
+export const DOCS_INDEX_DEFAULT_DIRS = ['docs', 'openspec/specs'];
+
+const DEFAULT_BLURB_TOKENS = 40;
+
+export { docsDigestPath, docsIndexPath, resolveDocsDirs };
+
+/**
+ * Extract a short extractive blurb (~blurbTokens) from section content.
+ * Strips the heading line when present; prefers non-empty prose/bullet lines.
+ */
+export function extractBlurb(content, blurbTokens = DEFAULT_BLURB_TOKENS) {
+  const lines = String(content || '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !/^#{1,6}\s/.test(l) && !/^```/.test(l));
+  const joined = lines.join(' ').replace(/\s+/g, ' ').trim();
+  if (!joined) return '';
+  const charLimit = blurbTokens * 4;
+  if (joined.length <= charLimit) return joined;
+  return `${joined.slice(0, charLimit).trimEnd()}…`;
+}
+
+/**
+ * Build a deterministic TOC index over markdown under dirs
+ * (default: docs/ + openspec/specs/; never openspec/changes/).
+ */
+export function buildDocsIndex(root, {
+  dirs: requestedDirs,
+  blurbTokens = DEFAULT_BLURB_TOKENS,
+} = {}) {
+  const dirs = resolveDocsDirs(root, requestedDirs);
+  const files = [];
+  let totalSections = 0;
+  let totalTokens = 0;
+
+  for (const absPath of walkMarkdown(root, dirs)) {
+    const filePath = rel(root, absPath);
+    let text;
+    try {
+      text = fs.readFileSync(absPath, 'utf8');
+    } catch {
+      continue;
+    }
+    const sha256 = sha256File(absPath);
+    const sections = parseMarkdownSections(filePath, text).map((s) => {
+      const tokens_est = estimateTokens(s.content);
+      return {
+        heading: s.heading,
+        level: s.level,
+        startLine: s.startLine,
+        endLine: s.endLine,
+        tokens_est,
+        blurb: extractBlurb(s.content, blurbTokens),
+      };
+    });
+    const tokens_est = estimateTokens(text);
+    totalSections += sections.length;
+    totalTokens += tokens_est;
+    files.push({
+      path: filePath,
+      sha256,
+      tokens_est,
+      sections,
+    });
+  }
+
+  files.sort((a, b) => a.path.localeCompare(b.path));
+
+  return {
+    generated_at: new Date().toISOString(),
+    dirs: [...dirs],
+    files,
+    totals: {
+      files: files.length,
+      sections: totalSections,
+      tokens_est: totalTokens,
+    },
+  };
+}
+
+/**
+ * Build index and optionally write to .claude/graph/docs-index.json.
+ * Returns { index, path, written }.
+ */
+export function writeDocsIndex(root, options = {}) {
+  const { write = true, dirs, blurbTokens } = options;
+  const index = buildDocsIndex(root, { dirs, blurbTokens });
+  const outPath = docsIndexPath(root);
+  if (write) {
+    ensureGraphDir(root);
+    writeJson(outPath, index);
+  }
+  return { index, path: outPath, written: write };
+}
+
+export function formatDocsIndexSummary(index, outPath, written) {
+  const lines = [
+    written ? `Wrote docs index → ${outPath}` : `Docs index (not written)`,
+    `dirs=${index.dirs.join(',')} files=${index.totals.files} sections=${index.totals.sections} tokens_est=${index.totals.tokens_est}`,
+  ];
+  return `${lines.join('\n')}\n`;
+}