carto-md 2.0.8 → 2.1.0

package/src/mcp/validate.js

@@ -20,7 +20,7 @@
  * microseconds; the budget is for diff parsing + result aggregation.
  *
  * Persistence: `recordSideEffects` is a separate function so
- * the read-only MCP `getStore()` path stays read-only — server-v2 opens
+ * the read-only MCP `getStore()` path stays read-only — server opens
  * a brief writer connection, calls validateDiff first (read-only), then
  * recordSideEffects, then closes. Tests can pass a writer directly as
  * `opts.writer` to inspect the rows produced.

package/src/org/detect.js

@@ -0,0 +1,262 @@
+'use strict';
+
+/**
+ * Seven cross-repo edge detection methods.
+ *
+ *   1. npm scope          — `@company/*` in package.json + import statements
+ *   2. PyPI               — internal-pypi-prefix from pyproject.toml imports
+ *   3. go-mod             — `go.mod` `require` blocks (private module prefix)
+ *   4. Maven group ID     — `pom.xml` <groupId> prefix
+ *   5. gRPC               — `.proto` files importing other `.proto` files
+ *   6. OpenAPI            — `openapi.yaml` / `swagger.json` schema sharing
+ *   7. Shared DB tables   — same table names across SQL migration files
+ *
+ * Each detector returns Array<{ edge_kind, from_file?, target, to_repo?, detail }>.
+ * `to_repo` is left null when we can't resolve the producer repo from the
+ * target alone; the org-sync step does a second pass to fill it in
+ * (target → repo lookup via npm name, pypi name, and so on).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CODE_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py']);
+
+/**
+ * scanRepo({ repoRoot, scopes }) → Array<edge>
+ *
+ * `scopes` is the runtime config: known internal npm scopes, pypi
+ * prefixes, go module prefixes, maven group prefixes. The detector
+ * filters to edges that match those scopes.
+ *
+ *   scopes = {
+ *     npm: ['@mycompany'],
+ *     pypi: ['mycompany-'],
+ *     go: ['github.com/mycompany'],
+ *     maven: ['com.mycompany'],
+ *   }
+ */
+function scanRepo({ repoRoot, scopes = {} }) {
+  if (!repoRoot) return [];
+  const out = [];
+  out.push(...detectNpm(repoRoot, scopes.npm || []));
+  out.push(...detectPython(repoRoot, scopes.pypi || []));
+  out.push(...detectGo(repoRoot, scopes.go || []));
+  out.push(...detectMaven(repoRoot, scopes.maven || []));
+  out.push(...detectProto(repoRoot));
+  out.push(...detectOpenApi(repoRoot));
+  out.push(...detectSqlMigrations(repoRoot));
+  return out;
+}
+
+// ── 1. npm ────────────────────────────────────────────────────────
+function detectNpm(repoRoot, scopes) {
+  const out = [];
+  if (scopes.length === 0) return out;
+
+  // From package.json deps + devDeps.
+  const pkgPath = path.join(repoRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const all = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      for (const name of Object.keys(all)) {
+        if (scopes.some(sc => name.startsWith(sc + '/') || name === sc)) {
+          out.push({ edge_kind: 'npm', from_file: 'package.json', target: name, detail: { version: all[name] } });
+        }
+      }
+    } catch {}
+  }
+  // From import statements in source files (deeper than package.json).
+  walkSource(repoRoot, (rel, content) => {
+    const ext = path.extname(rel);
+    if (!['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext)) return;
+    // import x from '@scope/y' / require('@scope/y')
+    const re = /(?:from|require)\s*\(?\s*['"]([@\w][^'"]*)['"]/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      const spec = m[1];
+      if (scopes.some(sc => spec === sc || spec.startsWith(sc + '/'))) {
+        // Normalize target: @scope/pkg or @scope/pkg/sub → @scope/pkg
+        const parts = spec.split('/');
+        const target = parts[0].startsWith('@') ? `${parts[0]}/${parts[1] || ''}` : parts[0];
+        out.push({ edge_kind: 'npm', from_file: rel, target });
+      }
+    }
+  });
+  return dedupe(out);
+}
+
+// ── 2. PyPI ──────────────────────────────────────────────────────
+function detectPython(repoRoot, prefixes) {
+  const out = [];
+  if (prefixes.length === 0) return out;
+
+  // pyproject.toml dependencies
+  const pyproject = path.join(repoRoot, 'pyproject.toml');
+  if (fs.existsSync(pyproject)) {
+    try {
+      const text = fs.readFileSync(pyproject, 'utf-8');
+      // Match `name = "..."` lines under [tool.poetry.dependencies] or [project.dependencies]
+      const re = /^\s*([a-zA-Z][\w\-]+)\s*=\s*["']([^"']+)["']/gm;
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        if (prefixes.some(p => m[1].startsWith(p))) {
+          out.push({ edge_kind: 'pypi', from_file: 'pyproject.toml', target: m[1], detail: { version: m[2] } });
+        }
+      }
+    } catch {}
+  }
+  // Source files: from <prefix>foo import ...
+  walkSource(repoRoot, (rel, content) => {
+    if (!rel.endsWith('.py')) return;
+    const re = /^(?:import\s+|from\s+)([A-Za-z][\w.]+)/gm;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      const mod = m[1];
+      const topLevel = mod.split('.')[0];
+      if (prefixes.some(p => topLevel.startsWith(p))) {
+        out.push({ edge_kind: 'pypi', from_file: rel, target: topLevel });
+      }
+    }
+  });
+  return dedupe(out);
+}
+
+// ── 3. Go ────────────────────────────────────────────────────────
+function detectGo(repoRoot, prefixes) {
+  const out = [];
+  if (prefixes.length === 0) return out;
+  const gomod = path.join(repoRoot, 'go.mod');
+  if (fs.existsSync(gomod)) {
+    try {
+      const text = fs.readFileSync(gomod, 'utf-8');
+      const block = /require\s*\(([^)]*)\)/m.exec(text);
+      const lines = block ? block[1].split('\n') : text.split('\n');
+      for (const line of lines) {
+        const m = /^\s*([\w./\-]+)\s+(\S+)/.exec(line);
+        if (m && prefixes.some(p => m[1].startsWith(p))) {
+          out.push({ edge_kind: 'go-mod', from_file: 'go.mod', target: m[1], detail: { version: m[2] } });
+        }
+      }
+    } catch {}
+  }
+  return dedupe(out);
+}
+
+// ── 4. Maven ─────────────────────────────────────────────────────
+function detectMaven(repoRoot, prefixes) {
+  const out = [];
+  if (prefixes.length === 0) return out;
+  const pom = path.join(repoRoot, 'pom.xml');
+  if (fs.existsSync(pom)) {
+    try {
+      const text = fs.readFileSync(pom, 'utf-8');
+      const re = /<dependency>[\s\S]*?<groupId>([^<]+)<\/groupId>\s*<artifactId>([^<]+)<\/artifactId>(?:\s*<version>([^<]+)<\/version>)?/g;
+      let m;
+      while ((m = re.exec(text)) !== null) {
+        if (prefixes.some(p => m[1].startsWith(p))) {
+          out.push({
+            edge_kind: 'maven',
+            from_file: 'pom.xml',
+            target: `${m[1]}:${m[2]}`,
+            detail: { version: m[3] || null },
+          });
+        }
+      }
+    } catch {}
+  }
+  return dedupe(out);
+}
+
+// ── 5. gRPC / .proto ─────────────────────────────────────────────
+function detectProto(repoRoot) {
+  const out = [];
+  walkSource(repoRoot, (rel, content) => {
+    if (!rel.endsWith('.proto')) return;
+    const re = /^\s*import\s+["']([^"']+)["']/gm;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      out.push({ edge_kind: 'grpc', from_file: rel, target: m[1] });
+    }
+  });
+  return dedupe(out);
+}
+
+// ── 6. OpenAPI / Swagger ────────────────────────────────────────
+function detectOpenApi(repoRoot) {
+  const out = [];
+  walkSource(repoRoot, (rel, content) => {
+    const lower = rel.toLowerCase();
+    if (!/openapi\.(ya?ml|json)$|swagger\.(ya?ml|json)$/.test(lower)) return;
+    // Best-effort: capture `$ref: '...'` external refs.
+    const re = /\$ref\s*:\s*['"]([^'"#]+)(?:#[^'"]*)?['"]/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      if (m[1].startsWith('http') || m[1].startsWith('../')) {
+        out.push({ edge_kind: 'openapi', from_file: rel, target: m[1] });
+      }
+    }
+    // Also surface the file itself as a schema-producer (for cross-repo
+    // consumption detection in the second pass).
+    out.push({ edge_kind: 'openapi', from_file: rel, target: rel, detail: { kind: 'producer' } });
+  });
+  return dedupe(out);
+}
+
+// ── 7. Shared SQL tables ───────────────────────────────────────
+function detectSqlMigrations(repoRoot) {
+  const out = [];
+  walkSource(repoRoot, (rel, content) => {
+    const lower = rel.toLowerCase();
+    if (!lower.endsWith('.sql')) return;
+    if (!/migration|migrate/.test(lower)) return;
+    const re = /\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(\w+)["`]?/gi;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      out.push({ edge_kind: 'db-table', from_file: rel, target: m[1] });
+    }
+  });
+  return dedupe(out);
+}
+
+// ── helpers ────────────────────────────────────────────────────
+function walkSource(repoRoot, visit) {
+  const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'out', '.next', '.turbo', 'coverage', 'vendor']);
+  const walk = (dir) => {
+    let entries; try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith('.') && e.name !== '.proto') continue;
+      if (IGNORE_DIRS.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile()) {
+        const rel = path.relative(repoRoot, full).replace(/\\/g, '/');
+        let content;
+        try {
+          const stat = fs.statSync(full);
+          if (stat.size > 4 * 1024 * 1024) return; // skip huge files
+          content = fs.readFileSync(full, 'utf-8');
+        } catch { continue; }
+        visit(rel, content);
+      }
+    }
+  };
+  walk(repoRoot);
+}
+
+function dedupe(edges) {
+  const seen = new Set();
+  return edges.filter(e => {
+    const key = `${e.edge_kind}::${e.from_file || ''}::${e.target}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+module.exports = {
+  scanRepo,
+  detectNpm, detectPython, detectGo, detectMaven,
+  detectProto, detectOpenApi, detectSqlMigrations,
+};

package/src/org/queries.js

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * Org-wide query functions backing the 7 cross-repo MCP tools.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * orgArchitectureOverview(orgStore) → { repos, summary }
+ */
+function orgArchitectureOverview(orgStore) {
+  if (!orgStore || !orgStore.db) return { repos: [], summary: {} };
+  const repos = orgStore.listRepos();
+  const summary = {
+    total_repos: repos.length,
+    total_edges: orgStore.db.prepare('SELECT COUNT(*) as c FROM cross_repo_edges').get().c,
+    edges_by_kind: orgStore.db.prepare(`
+      SELECT edge_kind, COUNT(*) as c FROM cross_repo_edges GROUP BY edge_kind
+    `).all(),
+  };
+  return { repos, summary };
+}
+
+/**
+ * serviceDependencyGraph(orgStore) → { nodes, edges }
+ *
+ * Each repo is a node; cross-repo edges are aggregated by (from_repo, to_repo).
+ */
+function serviceDependencyGraph(orgStore) {
+  if (!orgStore || !orgStore.db) return { nodes: [], edges: [] };
+  const repos = orgStore.listRepos();
+  const edgeRows = orgStore.db.prepare(`
+    SELECT from_repo, to_repo, edge_kind, COUNT(*) as count
+    FROM cross_repo_edges
+    WHERE to_repo IS NOT NULL
+    GROUP BY from_repo, to_repo, edge_kind
+  `).all();
+  return {
+    nodes: repos.map(r => ({ name: r.name, root_path: r.root_path })),
+    edges: edgeRows,
+  };
+}
+
+/**
+ * crossRepoBlastRadius(orgStore, fromRepo) → { downstream_repos, paths }
+ *
+ * Returns the set of repos that depend on `fromRepo` (one hop). Deeper
+ * hops would need a transitive closure pass; this is direct-only.
+ */
+function crossRepoBlastRadius(orgStore, fromRepo) {
+  if (!orgStore || !orgStore.db || !fromRepo) return { downstream_repos: [], paths: [] };
+  const rows = orgStore.db.prepare(`
+    SELECT from_repo, edge_kind, target, COUNT(*) as count
+    FROM cross_repo_edges
+    WHERE to_repo = ?
+    GROUP BY from_repo, edge_kind
+  `).all(fromRepo);
+  const downstream = [...new Set(rows.map(r => r.from_repo))];
+  return { downstream_repos: downstream, paths: rows };
+}
+
+/**
+ * findConsumersOfApi(orgStore, target) → list of consuming repos
+ *
+ * "Who depends on this npm/pypi/go module?"
+ */
+function findConsumersOfApi(orgStore, target) {
+  if (!orgStore || !orgStore.db || !target) return [];
+  return orgStore.db.prepare(`
+    SELECT from_repo, edge_kind, from_file
+    FROM cross_repo_edges
+    WHERE target = ? OR target LIKE ?
+    ORDER BY from_repo, edge_kind
+  `).all(target, target + '/%');
+}
+
+/**
+ * orgDomainMapping(orgStore) — for each repo's domain (from its carto.db
+ * if present), aggregate cross-domain edges org-wide.
+ */
+function orgDomainMapping(orgStore) {
+  if (!orgStore || !orgStore.db) return { domains: [] };
+  const repos = orgStore.listRepos();
+  const domains = [];
+  for (const repo of repos) {
+    if (!repo.carto_db_path || !fs.existsSync(repo.carto_db_path)) continue;
+    try {
+      const Database = require('better-sqlite3');
+      const db = new Database(repo.carto_db_path, { readonly: true, fileMustExist: true });
+      const rows = db.prepare('SELECT name, file_count FROM domains').all();
+      for (const r of rows) domains.push({ repo: repo.name, domain: r.name, file_count: r.file_count });
+      db.close();
+    } catch {}
+  }
+  return { domains };
+}
+
+/**
+ * serviceBoundaryViolations(orgStore) → boundary-crossing edges where one
+ * repo reaches into another's private surface (heuristic: target path
+ * includes `internal`, `private`, `_lib`, etc.).
+ */
+function serviceBoundaryViolations(orgStore) {
+  if (!orgStore || !orgStore.db) return { violations: [] };
+  const rows = orgStore.db.prepare(`
+    SELECT * FROM cross_repo_edges
+    WHERE target LIKE '%internal%' OR target LIKE '%private%' OR target LIKE '%_lib%'
+       OR target LIKE '%/_%'
+  `).all();
+  return { violations: rows };
+}
+
+/**
+ * microservicesMigrationCutPoints(orgStore) → suggested order to split
+ *
+ * Heuristic: repos with the fewest outgoing edges + the most incoming
+ * edges are the most stable producers — extract those first. Repos with
+ * many outgoing edges are tightly coupled consumers — extract later.
+ */
+function microservicesMigrationCutPoints(orgStore) {
+  if (!orgStore || !orgStore.db) return { order: [] };
+  const repos = orgStore.listRepos();
+  const out = [];
+  for (const repo of repos) {
+    const outgoing = orgStore.db.prepare('SELECT COUNT(*) as c FROM cross_repo_edges WHERE from_repo = ?').get(repo.name).c;
+    const incoming = orgStore.db.prepare('SELECT COUNT(*) as c FROM cross_repo_edges WHERE to_repo = ?').get(repo.name).c;
+    const stability = incoming / Math.max(1, outgoing + incoming);
+    out.push({ repo: repo.name, outgoing, incoming, stability: Math.round(stability * 100) / 100 });
+  }
+  out.sort((a, b) => b.stability - a.stability);
+  return { order: out };
+}
+
+module.exports = {
+  orgArchitectureOverview,
+  serviceDependencyGraph,
+  crossRepoBlastRadius,
+  findConsumersOfApi,
+  orgDomainMapping,
+  serviceBoundaryViolations,
+  microservicesMigrationCutPoints,
+};

package/src/org/store.js

@@ -0,0 +1,173 @@
+'use strict';
+
+/**
+ * OrgStore — `~/.carto/org.db` for cross-repo Carto data.
+ *
+ * Shared SQLite for polyrepo / monorepo-of-monorepos setups. Lives in the
+ * user's home directory so multiple projects in `carto org` can reference
+ * the same federated dataset.
+ *
+ * Two tables:
+ *   - `repos`              registered repos (one row per `carto org add`)
+ *   - `cross_repo_edges`   detected edges (npm, pypi, go-mod, maven, grpc,
+ *                          openapi, db-table)
+ *
+ * Concurrency: WAL mode. Multiple `carto org sync` calls in parallel
+ * serialize on the SQLite busy_timeout.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const Database = require('better-sqlite3');
+
+const ORG_DB_FILENAME = 'org.db';
+const SCHEMA_VERSION = '1';
+
+function defaultOrgDbDir() {
+  return path.join(os.homedir(), '.carto');
+}
+
+class OrgStore {
+  constructor(orgDir = defaultOrgDbDir()) {
+    this._dir = orgDir;
+    this._db = null;
+  }
+
+  get dbPath() { return path.join(this._dir, ORG_DB_FILENAME); }
+
+  open() {
+    fs.mkdirSync(this._dir, { recursive: true });
+    try {
+      this._db = new Database(this.dbPath);
+    } catch {
+      try { fs.unlinkSync(this.dbPath); } catch {}
+      this._db = new Database(this.dbPath);
+    }
+    this._db.pragma('journal_mode = WAL');
+    this._db.pragma('synchronous = NORMAL');
+    this._db.pragma('busy_timeout = 5000');
+    this._ensureSchema();
+    return this;
+  }
+
+  static openIfExists(orgDir = defaultOrgDbDir()) {
+    const p = path.join(orgDir, ORG_DB_FILENAME);
+    if (!fs.existsSync(p)) return null;
+    try { return new OrgStore(orgDir).open(); } catch { return null; }
+  }
+
+  close() {
+    if (this._db) { try { this._db.close(); } catch {} this._db = null; }
+  }
+
+  get db() { return this._db; }
+
+  _ensureSchema() {
+    this._db.exec(`
+      CREATE TABLE IF NOT EXISTS org_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT
+      );
+      CREATE TABLE IF NOT EXISTS repos (
+        id INTEGER PRIMARY KEY,
+        name TEXT UNIQUE NOT NULL,
+        root_path TEXT NOT NULL,
+        carto_db_path TEXT,
+        added_at INTEGER,
+        last_sync_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_repos_name ON repos(name);
+
+      CREATE TABLE IF NOT EXISTS cross_repo_edges (
+        id INTEGER PRIMARY KEY,
+        from_repo TEXT NOT NULL,
+        to_repo TEXT,
+        edge_kind TEXT NOT NULL,
+        from_file TEXT,
+        target TEXT,
+        detail_json TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_edge_from_repo ON cross_repo_edges(from_repo);
+      CREATE INDEX IF NOT EXISTS idx_edge_to_repo ON cross_repo_edges(to_repo);
+      CREATE INDEX IF NOT EXISTS idx_edge_kind ON cross_repo_edges(edge_kind);
+      CREATE INDEX IF NOT EXISTS idx_edge_target ON cross_repo_edges(target);
+    `);
+    const row = this._db.prepare('SELECT value FROM org_meta WHERE key = ?').get('schema_version');
+    if (!row) this._db.prepare('INSERT INTO org_meta(key, value) VALUES(?, ?)').run('schema_version', SCHEMA_VERSION);
+  }
+
+  addRepo({ name, rootPath, cartoDbPath = null }) {
+    if (!name || !rootPath) throw new Error('addRepo: name and rootPath required');
+    const now = Date.now();
+    try {
+      this._db.prepare(`
+        INSERT INTO repos (name, root_path, carto_db_path, added_at)
+        VALUES (?, ?, ?, ?)
+      `).run(name, rootPath, cartoDbPath, now);
+      return { name, rootPath, added_at: now };
+    } catch (err) {
+      if (/UNIQUE/.test(err.message)) {
+        this._db.prepare(`
+          UPDATE repos SET root_path = ?, carto_db_path = ? WHERE name = ?
+        `).run(rootPath, cartoDbPath, name);
+        return { name, rootPath, updated: true };
+      }
+      throw err;
+    }
+  }
+
+  removeRepo(name) {
+    this._db.prepare('DELETE FROM repos WHERE name = ?').run(name);
+    this._db.prepare('DELETE FROM cross_repo_edges WHERE from_repo = ? OR to_repo = ?').run(name, name);
+  }
+
+  listRepos() {
+    return this._db.prepare('SELECT * FROM repos ORDER BY name ASC').all();
+  }
+
+  getRepo(name) {
+    return this._db.prepare('SELECT * FROM repos WHERE name = ?').get(name);
+  }
+
+  /**
+   * insertEdges(repoName, edges) — bulk insert. Each edge:
+   *   { edge_kind, from_file?, target, to_repo?, detail? }
+   *
+   * Replaces all existing edges where `from_repo = repoName` first so
+   * re-syncing a repo doesn't accumulate stale edges.
+   */
+  insertEdges(repoName, edges) {
+    const tx = this._db.transaction(() => {
+      this._db.prepare('DELETE FROM cross_repo_edges WHERE from_repo = ?').run(repoName);
+      const stmt = this._db.prepare(`
+        INSERT INTO cross_repo_edges (from_repo, to_repo, edge_kind, from_file, target, detail_json)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `);
+      for (const e of edges || []) {
+        stmt.run(
+          repoName,
+          e.to_repo || null,
+          e.edge_kind,
+          e.from_file || null,
+          e.target,
+          e.detail ? JSON.stringify(e.detail) : null,
+        );
+      }
+      this._db.prepare('UPDATE repos SET last_sync_at = ? WHERE name = ?').run(Date.now(), repoName);
+    });
+    tx();
+  }
+
+  getEdges({ from_repo = null, to_repo = null, edge_kind = null } = {}) {
+    const where = [];
+    const args = [];
+    if (from_repo) { where.push('from_repo = ?'); args.push(from_repo); }
+    if (to_repo)   { where.push('to_repo = ?'); args.push(to_repo); }
+    if (edge_kind) { where.push('edge_kind = ?'); args.push(edge_kind); }
+    const w = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
+    return this._db.prepare(`SELECT * FROM cross_repo_edges ${w} ORDER BY edge_kind, target`).all(...args);
+  }
+}
+
+module.exports = { OrgStore, ORG_DB_FILENAME, defaultOrgDbDir };

package/src/org/sync.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Cross-repo sync — walk every registered repo, run detection, persist edges.
+ *
+ * Second pass: target → repo resolution. We resolve `to_repo` for npm/
+ * pypi/go-mod/maven edges when the target's name matches a registered
+ * repo's package metadata. Edges remain even when unresolved (target is
+ * still useful for "find consumers of @scope/foo").
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { OrgStore, defaultOrgDbDir } = require('./store');
+const { scanRepo } = require('./detect');
+
+/**
+ * orgSync({ orgDir, scopes, dry }) → { repos, edges_inserted }
+ *
+ * `scopes`: { npm: [...], pypi: [...], go: [...], maven: [...] }
+ * `dry`: if true, don't persist; just return what would change.
+ */
+function orgSync({ orgDir = defaultOrgDbDir(), scopes = {}, dry = false } = {}) {
+  const store = new OrgStore(orgDir).open();
+  try {
+    const repos = store.listRepos();
+    let inserted = 0;
+    const allEdges = new Map();   // repo.name → edges
+
+    for (const repo of repos) {
+      const edges = scanRepo({ repoRoot: repo.root_path, scopes });
+      allEdges.set(repo.name, edges);
+    }
+
+    // Build target → producer-repo map from each repo's package metadata.
+    const targetToRepo = buildTargetToRepoMap(repos);
+
+    // Resolve to_repo + persist.
+    for (const [repoName, edges] of allEdges) {
+      for (const e of edges) {
+        if (!e.to_repo) {
+          const target = e.target;
+          const producer = targetToRepo.get(`${e.edge_kind}::${target}`);
+          if (producer && producer !== repoName) e.to_repo = producer;
+        }
+      }
+      if (!dry) store.insertEdges(repoName, edges);
+      inserted += edges.length;
+    }
+
+    return {
+      repos: repos.length,
+      edges_inserted: inserted,
+      edges_by_repo: Object.fromEntries(
+        Array.from(allEdges.entries()).map(([name, e]) => [name, e.length])
+      ),
+    };
+  } finally {
+    store.close();
+  }
+}
+
+function buildTargetToRepoMap(repos) {
+  const map = new Map();
+  for (const repo of repos) {
+    // npm: package.json `name`
+    const pkgPath = path.join(repo.root_path, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        if (pkg && pkg.name) map.set(`npm::${pkg.name}`, repo.name);
+      } catch {}
+    }
+    // pypi: pyproject.toml or setup.py
+    const pyproject = path.join(repo.root_path, 'pyproject.toml');
+    if (fs.existsSync(pyproject)) {
+      try {
+        const text = fs.readFileSync(pyproject, 'utf-8');
+        const m = /\bname\s*=\s*["']([^"']+)["']/.exec(text);
+        if (m) map.set(`pypi::${m[1]}`, repo.name);
+      } catch {}
+    }
+    // go: go.mod `module`
+    const gomod = path.join(repo.root_path, 'go.mod');
+    if (fs.existsSync(gomod)) {
+      try {
+        const text = fs.readFileSync(gomod, 'utf-8');
+        const m = /^module\s+(\S+)/m.exec(text);
+        if (m) map.set(`go-mod::${m[1]}`, repo.name);
+      } catch {}
+    }
+    // maven: pom.xml <groupId>:<artifactId>
+    const pom = path.join(repo.root_path, 'pom.xml');
+    if (fs.existsSync(pom)) {
+      try {
+        const text = fs.readFileSync(pom, 'utf-8');
+        const g = /<groupId>([^<]+)<\/groupId>/.exec(text);
+        const a = /<artifactId>([^<]+)<\/artifactId>/.exec(text);
+        if (g && a) map.set(`maven::${g[1]}:${a[1]}`, repo.name);
+      } catch {}
+    }
+  }
+  return map;
+}
+
+module.exports = { orgSync, buildTargetToRepoMap };