explainmyrepo 0.1.1

package/kb/corpus-rules.mjs

@@ -0,0 +1,341 @@
+// corpus-rules.mjs — config-driven corpus rule-type implementations.
+//
+// Each rule type is a pure function that takes a `ctx` (the shared build context: repo root,
+// walk helper, exclusion set, chunker, addDoc collector, etc.) plus the rule's own config object
+// (from `kb.config.mjs` target.include[]) and APPENDS entries to the corpus via ctx.addDoc(...).
+//
+// The mechanics are generalized from the proven Cognitum prototype (build-ruview-kb.mjs):
+// repo-shape is now DATA (roots / exts / files / headLines) instead of hard-coded ruview/ruvector
+// paths. NO repo name is baked in here. build-kb.mjs wires these rules together per config.
+//
+// Rule types (build-plan-metaharness.md §2a [D5]):
+//   mdSweepFullText   — every *.md/.mdx/.txt under the given roots, verbatim (untruncated).
+//   componentManifests— each component's package.json / Cargo.toml summarized (name/desc/scripts/deps).
+//   componentLead     — each component's README / lead doc (full text) + lead source doc-block.
+//   sourceBodies      — full file bodies of implementing source under the roots (chunked).
+//   docCommentSweep   — leading doc comments only (//!, /** */, """...""", #-prefixed) from source.
+//   literalFiles      — an explicit list of files, full text (guarantees key docs are present).
+//   htmlText          — visible text of *.html under the roots (scripts/styles/tags stripped).
+//   templates         — scaffolding templates (.tmpl/.hbs/...): first-N-lines + path, kind:'template'.
+//
+// A `kind` is attached to every entry so the intent layer (ask-kb) can route by content kind.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---------- small shared text helpers ----------
+const read = (p) => fs.readFileSync(p, 'utf8');
+const tryRead = (p) => { try { return read(p); } catch { return null; } };
+const firstLines = (s, n) => s.split('\n').slice(0, n).join('\n');
+
+export function titleOf(text, fallback) {
+  const m = text.match(/^#\s+(.+)$/m);
+  return (m ? m[1] : fallback).slice(0, 200).trim();
+}
+
+// Visible text of an HTML document (scripts/styles/comments/tags stripped, entities decoded).
+export function htmlToText(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+    .replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+// Leading doc-comment block from the first N lines of a source file, language-aware.
+//   Rust   //!  / ///        C-style /** ... */ or // leading run
+//   Python/JS module docstring """ ... """  or  # leading run
+// Returns '' when there is no leading doc block.
+export function docBlock(text, n = 40) {
+  const head = text.split('\n').slice(0, n);
+  // Rust //! and /// runs
+  const rust = head.filter((l) => /^\s*\/\/[!/]/.test(l))
+    .map((l) => l.replace(/^\s*\/\/[!/]\s?/, '')).join('\n').trim();
+  if (rust) return rust;
+  // JSDoc / C-style /** ... */ at the very top
+  const joined = head.join('\n');
+  const block = joined.match(/^\s*\/\*\*([\s\S]*?)\*\//);
+  if (block) {
+    return block[1].split('\n').map((l) => l.replace(/^\s*\*\s?/, '')).join('\n').trim();
+  }
+  // Python / triple-quoted module docstring
+  const py = joined.match(/^\s*(?:[rRbBuU]{0,2})("""|''')([\s\S]*?)\1/);
+  if (py) return py[2].trim();
+  // leading run of #-prefixed comment lines (shell / python / toml)
+  const hash = head.filter((l) => /^\s*#/.test(l) && !/^\s*#!/.test(l))
+    .map((l) => l.replace(/^\s*#\s?/, '')).join('\n').trim();
+  return hash;
+}
+
+// Resolve a list of root-relative roots to absolute dirs that exist under the repo.
+function resolveRoots(ctx, roots) {
+  const out = [];
+  for (const r of roots || []) {
+    const abs = r === '.' ? ctx.repoDir : path.join(ctx.repoDir, r);
+    if (fs.existsSync(abs)) out.push(abs);
+  }
+  return out;
+}
+
+const hasExt = (p, exts) => !exts || !exts.length || exts.includes(path.extname(p).toLowerCase());
+
+// ============================ RULE TYPES ============================
+
+// mdSweepFullText — every prose file under the roots, full text (untruncated). De-duped by
+// absolute path so a file already ingested (e.g. by literalFiles) is not added twice.
+export function mdSweepFullText(ctx, rule) {
+  const exts = rule.ext || ['.md', '.mdx', '.txt'];
+  let n = 0;
+  for (const root of resolveRoots(ctx, rule.roots)) {
+    for (const p of ctx.walk(root)) {
+      if (!hasExt(p, exts)) continue;
+      if (ctx.alreadyIngested(p)) continue;
+      const rel = ctx.rel(p);
+      const text = read(p);
+      let kind = 'doc';
+      if (/(^|\/)adrs?\//i.test(rel) || /(^|\/)adr[-_]/i.test(rel)) kind = 'adr';
+      else if (/(^|\/)tutorials?\//i.test(rel)) kind = 'tutorial';
+      ctx.addDoc(rel, kind, titleOf(text, path.basename(p)), text, p);
+      n++;
+    }
+  }
+  return n;
+}
+
+// componentManifests — each component's package.json (or Cargo.toml) summarized so "what packages
+// make up X" and dependency questions resolve. Walks each componentRoot's immediate children.
+export function componentManifests(ctx, rule) {
+  let n = 0;
+  for (const root of resolveRoots(ctx, rule.roots)) {
+    for (const dirent of fs.readdirSync(root, { withFileTypes: true })) {
+      if (!dirent.isDirectory()) continue;
+      const cdir = path.join(root, dirent.name);
+      // npm manifest
+      const pkgPath = path.join(cdir, 'package.json');
+      const pkg = tryRead(pkgPath);
+      if (pkg) {
+        try {
+          const j = JSON.parse(pkg);
+          const scripts = j.scripts ? Object.entries(j.scripts).map(([k, v]) => `  ${k}: ${v}`).join('\n') : '';
+          const bin = j.bin ? (typeof j.bin === 'string' ? j.bin : Object.keys(j.bin).join(', ')) : '';
+          const deps = Object.keys(j.dependencies || {});
+          const dev = Object.keys(j.devDependencies || {});
+          const text =
+            `npm package: ${j.name || dirent.name}\nVersion: ${j.version || ''}\nPath: ${ctx.rel(pkgPath)}\n` +
+            `Description: ${j.description || ''}\n` +
+            (bin ? `Bin: ${bin}\n` : '') +
+            (j.type ? `Module type: ${j.type}\n` : '') +
+            (scripts ? `Scripts:\n${scripts}\n` : '') +
+            (deps.length ? `Dependencies: ${deps.join(', ')}\n` : '') +
+            (dev.length ? `DevDependencies: ${dev.join(', ')}\n` : '') +
+            (j.keywords?.length ? `Keywords: ${j.keywords.join(', ')}\n` : '');
+          ctx.addDoc(ctx.rel(pkgPath), 'npm', j.name || dirent.name, text, pkgPath);
+          n++;
+        } catch {
+          ctx.addDoc(ctx.rel(pkgPath), 'npm', dirent.name, `npm package manifest (unparseable) at ${ctx.rel(pkgPath)}`, pkgPath);
+          n++;
+        }
+      }
+      // Cargo manifest (mixed monorepos)
+      const cargoPath = path.join(cdir, 'Cargo.toml');
+      const cargo = tryRead(cargoPath);
+      if (cargo) {
+        const name = (cargo.match(/^name\s*=\s*"([^"]*)"/m) || [])[1] || dirent.name;
+        const desc = (cargo.match(/^description\s*=\s*"([^"]*)"/m) || [])[1] || '';
+        ctx.addDoc(ctx.rel(cargoPath), 'crate', name,
+          `Crate: ${name}\nDescription: ${desc}\nPath: ${ctx.rel(cargoPath)}\n\n${cargo}`, cargoPath);
+        n++;
+      }
+    }
+  }
+  return n;
+}
+
+// componentLead — each component's README (full text) + the leading doc block of its lead source
+// file (index/lib/main). Gives every component an orientation entry under componentRoots.
+export function componentLead(ctx, rule) {
+  const leadCandidates = rule.leads || [
+    'README.md', 'readme.md', 'src/index.ts', 'src/index.js', 'src/lib.rs', 'src/main.rs',
+    'index.ts', 'index.js', 'lib.rs', 'main.rs',
+  ];
+  let n = 0;
+  for (const root of resolveRoots(ctx, rule.roots)) {
+    for (const dirent of fs.readdirSync(root, { withFileTypes: true })) {
+      if (!dirent.isDirectory()) continue;
+      const cdir = path.join(root, dirent.name);
+      // README full text
+      for (const rd of ['README.md', 'readme.md', 'README.mdx']) {
+        const rp = path.join(cdir, rd);
+        if (fs.existsSync(rp) && !ctx.alreadyIngested(rp)) {
+          const text = read(rp);
+          ctx.addDoc(ctx.rel(rp), 'doc', titleOf(text, dirent.name), text, rp);
+          n++;
+          break;
+        }
+      }
+      // lead source doc-block (orientation, not full body — sourceBodies covers bodies)
+      const lead = leadCandidates.map((f) => path.join(cdir, f)).find((p) => fs.existsSync(p));
+      if (lead) {
+        const text = read(lead);
+        const doc = docBlock(text, 200);
+        if (doc) {
+          ctx.addDoc(ctx.rel(lead), 'crate-src', `${dirent.name} ${path.basename(lead)}`,
+            `Component ${dirent.name} — ${path.basename(lead)} leading doc:\n${doc}`, /*absPath*/ undefined);
+          n++;
+        }
+      }
+    }
+  }
+  return n;
+}
+
+// sourceBodies — full file bodies of implementing source under the roots, chunked like docs.
+// SCOPE: files under any `/src/` dir, or crate/module roots (lib/main/mod/index). Excludes
+// tests/benches and minified output. Tagged kind:'source'.
+export function sourceBodies(ctx, rule) {
+  const exts = (rule.ext || ['.ts', '.tsx', '.js', '.mjs', '.cjs', '.rs', '.py', '.go']).map((e) => e.toLowerCase());
+  const ROOTS_FILE = /(^|\/)(lib\.rs|main\.rs|mod\.rs|index\.ts|index\.js|index\.mjs)$/i;
+  const MINIFIED = /\.(min|bundle)\.(js|css|mjs)$/i;
+  const TESTY = /(^|\/)(tests?|benches?|__tests__|__mocks__|spec)\//i;
+  const inScope = (rel) => {
+    if (MINIFIED.test(rel)) return false;
+    if (TESTY.test(rel)) return false;
+    if (/(^|\/)src\//.test(rel)) return true;
+    return ROOTS_FILE.test(rel);
+  };
+  let n = 0;
+  for (const root of resolveRoots(ctx, rule.roots)) {
+    for (const p of ctx.walk(root)) {
+      if (!hasExt(p, exts)) continue;
+      const rel = ctx.rel(p);
+      if (!inScope(rel)) continue;
+      if (ctx.isFullBody(p)) continue;
+      const body = read(p);
+      if (!body.trim()) continue;
+      ctx.markFullBody(p);
+      ctx.addDoc(rel, 'source', path.basename(p), `Source ${rel} (full):\n${body}`, /*absPath*/ undefined);
+      n++;
+    }
+  }
+  return n;
+}
+
+// testsAndExamples — full bodies of TEST / EXAMPLE / BENCH source files under the roots. These are
+// the single best USAGE documentation a repo has (real call sites + expected results), so they are
+// ingested deliberately (sourceBodies excludes them on purpose; this rule is the complement). The
+// source_type tagger in build-kb.mjs marks each as 'test' or 'example' from its path. kind stays
+// 'source' so the existing source-routing/reranking treats them like code.
+export function testsAndExamples(ctx, rule) {
+  const exts = (rule.ext || ['.rs', '.ts', '.tsx', '.js', '.mjs']).map((e) => e.toLowerCase());
+  const IS_TEST_OR_EX = /(^|\/)(tests?|benches?|examples?|__tests__|spec)\//i;
+  const NAMED_TEST = /[._-](test|spec)\.[a-z]+$|\.test$/i;
+  let n = 0;
+  for (const root of resolveRoots(ctx, rule.roots)) {
+    for (const p of ctx.walk(root)) {
+      if (!hasExt(p, exts)) continue;
+      const rel = ctx.rel(p);
+      if (!IS_TEST_OR_EX.test(rel) && !NAMED_TEST.test(rel)) continue;
+      if (ctx.isFullBody(p)) continue;        // already ingested (shouldn't happen — sourceBodies skips these)
+      const body = read(p);
+      if (!body.trim()) continue;
+      ctx.markFullBody(p);
+      const isEx = /(^|\/)(examples?|demos?)\//i.test(rel);
+      const label = isEx ? 'Example' : 'Test';
+      ctx.addDoc(rel, 'source', path.basename(p), `${label} ${rel} (full):\n${body}`, /*absPath*/ undefined);
+      n++;
+    }
+  }
+  return n;
+}
+
+// docCommentSweep — leading doc comment ONLY from every source file under the roots that has one
+// and is NOT already indexed as a full body. Cheap orientation breadcrumbs across the whole tree.
+export function docCommentSweep(ctx, rule) {
+  const exts = (rule.ext || ['.ts', '.tsx', '.js', '.mjs', '.cjs', '.rs', '.py', '.go']).map((e) => e.toLowerCase());
+  let n = 0;
+  for (const root of resolveRoots(ctx, rule.roots)) {
+    for (const p of ctx.walk(root)) {
+      if (!hasExt(p, exts)) continue;
+      if (ctx.isFullBody(p)) continue;   // already ingested in full by sourceBodies
+      const doc = docBlock(firstLines(read(p), 40), 40);
+      if (!doc) continue;
+      const rel = ctx.rel(p);
+      ctx.addDoc(rel, 'crate-src', path.basename(p), `Module ${rel} — doc comment:\n${doc}`, /*absPath*/ undefined);
+      n++;
+    }
+  }
+  return n;
+}
+
+// literalFiles — an explicit list of root-relative files, full text. Guarantees key docs (README,
+// OVERVIEW, ARCHITECTURE, …) are in the corpus regardless of the sweep roots. De-duped by path.
+export function literalFiles(ctx, rule) {
+  let n = 0;
+  for (const f of rule.files || []) {
+    const abs = path.join(ctx.repoDir, f);
+    if (!fs.existsSync(abs) || ctx.alreadyIngested(abs)) continue;
+    const text = read(abs);
+    const rel = ctx.rel(abs);
+    let kind = 'doc';
+    if (/(^|\/)adrs?\//i.test(rel) || /(^|\/)adr[-_]/i.test(rel)) kind = 'adr';
+    ctx.addDoc(rel, kind, titleOf(text, path.basename(abs)), text, abs);
+    n++;
+  }
+  return n;
+}
+
+// htmlText — visible text content of *.html under the roots. Tagged kind:'ui'.
+export function htmlText(ctx, rule) {
+  const exts = ['.html', '.htm'];
+  let n = 0;
+  for (const root of resolveRoots(ctx, rule.roots)) {
+    for (const p of ctx.walk(root)) {
+      if (!hasExt(p, exts)) continue;
+      const text = htmlToText(read(p));
+      if (!text) continue;
+      const rel = ctx.rel(p);
+      ctx.addDoc(rel, 'ui', path.basename(p), `UI page ${rel} full text content:\n${text}`, p);
+      n++;
+    }
+  }
+  return n;
+}
+
+// templates — scaffolding templates (.tmpl/.hbs/.handlebars): path + first-N-lines, kind:'template'.
+// These are the bulk of "what does a generated harness contain" — neither prose nor runnable source,
+// so we index a head sample + the path (decided IN, not skipped — plan top risk #2).
+export function templates(ctx, rule) {
+  const exts = (rule.ext || ['.tmpl', '.hbs', '.handlebars']).map((e) => e.toLowerCase());
+  const headLines = rule.headLines || 40;
+  let n = 0;
+  for (const root of resolveRoots(ctx, rule.roots)) {
+    for (const p of ctx.walk(root)) {
+      if (!hasExt(p, exts)) continue;
+      const rel = ctx.rel(p);
+      const body = read(p);
+      const head = firstLines(body, headLines);
+      ctx.addDoc(rel, 'template', path.basename(p),
+        `Template ${rel} (first ${headLines} lines):\n${head}`, p);
+      n++;
+    }
+  }
+  return n;
+}
+
+// Registry: rule name -> implementation. build-kb.mjs dispatches config.include[] through this.
+export const RULE_IMPLS = {
+  mdSweepFullText,
+  componentManifests,
+  componentLead,
+  sourceBodies,
+  testsAndExamples,
+  docCommentSweep,
+  literalFiles,
+  htmlText,
+  templates,
+};
+
+export default RULE_IMPLS;

package/kb/dep-graph.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// dep-graph.mjs — GENERIC, config-driven dependency-graph extractor.
+//
+// Emits kb/stores/<slug>/<slug>-dep-graph.json: how the repo's components depend on each other
+// + their external deps. An AI uses this to reason about layering / blast-radius before editing.
+//
+// Strategy:
+//   Rust:  `cargo metadata --format-version 1` → workspace crate graph (internal edges between
+//          workspace members + each crate's external dependencies).
+//   TS/JS: import scan of the source tree (no madge dependency required) → module/package graph
+//          (internal edges between componentRoots packages via workspace imports + external deps
+//          from each package.json).
+//
+// Repo shape is DATA (kb.config.mjs target: repoDir, scopeExclude, componentRoots). Ships in the
+// drop-in for-ai/. NO repo name is baked in here.
+//
+// Usage: node kb/dep-graph.mjs --target ruqu  | node kb/dep-graph.mjs ruqu
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { getTarget, defaultTarget } from './kb.config.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function parseArgs(argv) {
+  const a = { target: defaultTarget };
+  for (let i = 0; i < argv.length; i++) {
+    const v = argv[i];
+    if (v === '--target') a.target = argv[++i];
+    else if (v.startsWith('--target=')) a.target = v.slice(9);
+    else if (!v.startsWith('--')) a.target = v;
+  }
+  return a;
+}
+
+const tryRead = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } };
+
+function* walk(dir, skip) {
+  let dirents;
+  try { dirents = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); }
+  catch { return; }
+  for (const e of dirents) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) { if (!skip.has(e.name)) yield* walk(p, skip); }
+    else if (e.isFile()) yield p;
+  }
+}
+
+// ---------------- Rust: cargo metadata ----------------
+function rustGraph(repoDir) {
+  let raw;
+  try {
+    raw = execFileSync('cargo', ['metadata', '--format-version', '1', '--no-deps'],
+      { cwd: repoDir, maxBuffer: 64 * 1024 * 1024, timeout: 120000 }).toString();
+  } catch (e) {
+    return { ok: false, reason: `cargo metadata failed: ${e.message?.slice(0, 80)}` };
+  }
+  const m = JSON.parse(raw);
+  const wsNames = new Set(m.packages.map((p) => p.name));
+  const nodes = [];
+  const internalEdges = [];   // { from, to }  (workspace member -> workspace member)
+  const externalDeps = {};    // pkg -> [ {name, req, kind} ] (non-workspace)
+  for (const p of m.packages) {
+    const targets = (p.targets || []).map((t) => ({ name: t.name, kinds: t.kind }));
+    nodes.push({
+      name: p.name, version: p.version, description: p.description || null,
+      manifest: path.relative(repoDir, p.manifest_path),
+      targets,
+      isLib: (p.targets || []).some((t) => t.kind.includes('lib')),
+      bins: (p.targets || []).filter((t) => t.kind.includes('bin')).map((t) => t.name),
+    });
+    const ext = [];
+    for (const d of p.dependencies || []) {
+      if (wsNames.has(d.name)) internalEdges.push({ from: p.name, to: d.name, kind: d.kind || 'normal' });
+      else ext.push({ name: d.name, req: d.req, kind: d.kind || 'normal' });
+    }
+    externalDeps[p.name] = ext;
+  }
+  // unique external deps across the workspace
+  const allExternal = [...new Set(Object.values(externalDeps).flat().map((d) => d.name))].sort();
+  return { ok: true, ecosystem: 'rust', nodes, internalEdges, externalDeps, externalDepNames: allExternal };
+}
+
+// ---------------- TS/JS: import scan + package.json ----------------
+const IMPORT_RE = /(?:import\s[^'"]*from\s*|import\s*|require\(\s*|export\s[^'"]*from\s*)['"]([^'"]+)['"]/g;
+function tsGraph(repoDir, skip, componentRoots) {
+  // discover packages under componentRoots (+ cli/apps) AND the repo root itself ('.'), so a
+  // single-package-at-root repo (e.g. ruvn: one package.json at the top, no packages/ dir) is
+  // discovered too — not just a multi-package monorepo.
+  const pkgDirs = [];
+  for (const r of [...(componentRoots || ['packages']), 'cli', 'apps', 'npm/packages', '.']) {
+    const abs = path.join(repoDir, r);
+    if (!fs.existsSync(abs)) continue;
+    if (fs.existsSync(path.join(abs, 'package.json'))) { pkgDirs.push(abs); continue; }
+    for (const d of fs.readdirSync(abs, { withFileTypes: true })) {
+      if (d.isDirectory() && !skip.has(d.name) && fs.existsSync(path.join(abs, d.name, 'package.json'))) pkgDirs.push(path.join(abs, d.name));
+    }
+  }
+  const nodes = [];
+  const nameToDir = new Map();
+  for (const dir of pkgDirs) {
+    try {
+      const j = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      nodes.push({ name: j.name || path.basename(dir), version: j.version, description: j.description || null, manifest: path.relative(repoDir, path.join(dir, 'package.json')), deps: Object.keys(j.dependencies || {}) });
+      if (j.name) nameToDir.set(j.name, dir);
+    } catch { /* skip */ }
+  }
+  const wsNames = new Set(nodes.map((n) => n.name));
+  const internalEdges = [];
+  const externalDeps = {};
+  const seenEdge = new Set();
+  for (const n of nodes) {
+    externalDeps[n.name] = (n.deps || []).filter((d) => !wsNames.has(d)).map((d) => ({ name: d, req: '*', kind: 'normal' }));
+    for (const d of n.deps || []) {
+      if (wsNames.has(d)) { const k = `${n.name}->${d}`; if (!seenEdge.has(k)) { seenEdge.add(k); internalEdges.push({ from: n.name, to: d, kind: 'normal' }); } }
+    }
+  }
+  // Also scan source imports of workspace package names (covers monorepos without explicit deps).
+  for (const [pkgName, dir] of nameToDir) {
+    for (const p of walk(dir, skip)) {
+      if (!/\.(ts|tsx|js|mjs|cjs)$/.test(p)) continue;
+      const text = tryRead(p); if (!text) continue;
+      for (const m of text.matchAll(IMPORT_RE)) {
+        const spec = m[1];
+        for (const w of wsNames) {
+          if (w !== pkgName && (spec === w || spec.startsWith(w + '/'))) {
+            const k = `${pkgName}->${w}`;
+            if (!seenEdge.has(k)) { seenEdge.add(k); internalEdges.push({ from: pkgName, to: w, kind: 'import' }); }
+          }
+        }
+      }
+    }
+  }
+  const allExternal = [...new Set(Object.values(externalDeps).flat().map((d) => d.name))].sort();
+  return { ok: true, ecosystem: 'npm', nodes, internalEdges, externalDeps, externalDepNames: allExternal };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const target = getTarget(args.target);
+  const slug = args.target;
+  const repoDir = path.resolve(__dirname, target.repoDir);
+  if (!fs.existsSync(repoDir)) { console.error(`[dep-graph] repoDir not found: ${repoDir}`); process.exit(1); }
+  const skip = new Set(target.scopeExclude || []);
+
+  const graphs = [];
+  if (tryRead(path.join(repoDir, 'Cargo.toml'))) {
+    const g = rustGraph(repoDir);
+    if (g.ok) graphs.push(g); else console.warn(`[dep-graph] ${g.reason}`);
+  }
+  // npm graph too (mixed monorepos like ruqu have BOTH a Cargo workspace + a cli/ package).
+  // Honor the target's componentRoots and the repo root ('.') so a single-package-at-root repo
+  // (ruvn: just a top-level package.json) flips hasNpm, not only the conventional monorepo dirs.
+  const npmRoots = [...new Set([...(target.componentRoots || []), 'packages', 'cli', 'apps', 'npm/packages', '.'])];
+  const hasNpm = npmRoots.some((r) => {
+    const abs = path.join(repoDir, r);
+    return fs.existsSync(abs) && (fs.existsSync(path.join(abs, 'package.json')) ||
+      (fs.statSync(abs).isDirectory() && fs.readdirSync(abs).some((d) => { try { return fs.existsSync(path.join(abs, d, 'package.json')); } catch { return false; } })));
+  });
+  if (hasNpm) { const g = tsGraph(repoDir, skip, target.componentRoots); if (g.ok && g.nodes.length) graphs.push(g); }
+
+  // Merge ecosystems into one report.
+  const nodes = graphs.flatMap((g) => g.nodes.map((n) => ({ ...n, ecosystem: g.ecosystem })));
+  const internalEdges = graphs.flatMap((g) => g.internalEdges);
+  const externalDeps = Object.assign({}, ...graphs.map((g) => g.externalDeps));
+  const externalDepNames = [...new Set(graphs.flatMap((g) => g.externalDepNames))].sort();
+
+  const out = {
+    target: slug, metaName: target.metaName, generated: new Date().toISOString(),
+    ecosystems: graphs.map((g) => g.ecosystem),
+    componentCount: nodes.length, internalEdgeCount: internalEdges.length, externalDepCount: externalDepNames.length,
+    nodes, internalEdges, externalDeps, externalDepNames,
+  };
+  const storeDir = path.join(__dirname, 'stores', slug);
+  fs.mkdirSync(storeDir, { recursive: true });
+  const outFile = path.join(storeDir, `${slug}-dep-graph.json`);
+  fs.writeFileSync(outFile, JSON.stringify(out, null, 2) + '\n');
+  console.log(`[dep-graph] ${slug}: ${nodes.length} components, ${internalEdges.length} internal edges, ${externalDepNames.length} external deps (${out.ecosystems.join('+')})`);
+  console.log(`[dep-graph] wrote ${path.relative(__dirname, outFile)}`);
+}
+
+main();