@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/code_graph/estate_cli.ts

@@ -0,0 +1,135 @@
+/**
+ * `code-graph estate …` — questions about every registered project at once,
+ * answered from the estate index alone (ADR-299, step 5.3). No project graph
+ * is opened: an estate answer is as current as each project's last refresh,
+ * and says when it was indexed.
+ *
+ *   estate where-used <package|symbol>      who declares, imports, publishes or references it
+ *   estate projects-using <package>         projects that declare or import a package
+ *   estate advisory-impact [--package P]    advisory packages × the projects that use them
+ *
+ * `--json` prints the answer as JSON.
+ */
+import { readState } from '../_lib/advisory_notice.js';
+import { type EstateReader, openEstate } from './estate_index.js';
+
+const NO_INDEX =
+    'no estate index — switch it on with `code-graph projects index on`, then build or refresh each project once';
+
+export interface WhereUsed {
+    name: string;
+    package_users: ReturnType<EstateReader['projectsUsing']>;
+    publishers: ReturnType<EstateReader['publishers']>;
+    declared_by: ReturnType<EstateReader['exporters']>;
+    referenced_by: ReturnType<EstateReader['referrers']>;
+}
+
+export interface AdvisoryImpact {
+    package: string;
+    advisories: string[];
+    projects: ReturnType<EstateReader['projectsUsing']>;
+}
+
+export function whereUsed(db: EstateReader, name: string): WhereUsed {
+    return {
+        name,
+        package_users: db.projectsUsing(name),
+        publishers: db.publishers(name),
+        declared_by: db.exporters(name),
+        referenced_by: db.referrers(name),
+    };
+}
+
+/**
+ * Advisory packages from each indexed project's own advisory cache (or the one
+ * `--package` names), joined with the index. A project that imports the
+ * package in code is the one an advisory reaches first; `imports` says so.
+ */
+export function advisoryImpact(db: EstateReader, only: string | null): AdvisoryImpact[] {
+    const ids = new Map<string, Set<string>>();
+    if (only !== null) ids.set(only, new Set());
+    else {
+        for (const p of db.projects()) {
+            for (const f of readState(p.root)?.findings ?? []) {
+                if (!ids.has(f.package)) ids.set(f.package, new Set());
+                ids.get(f.package)?.add(f.id);
+            }
+        }
+    }
+    return [...ids.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([pkg, adv]) => ({ package: pkg, advisories: [...adv].sort(), projects: db.projectsUsing(pkg) }))
+        .filter((r) => only !== null || r.projects.length > 0);
+}
+
+function flagValue(argv: string[], name: string): string | null {
+    const i = argv.indexOf(name);
+    return i >= 0 && i + 1 < argv.length ? (argv[i + 1] as string) : null;
+}
+
+function line(p: { id: string; root: string }, extra = ''): string {
+    return `  ${p.id}  ${p.root}${extra}\n`;
+}
+
+export function estateMain(argv: string[]): number {
+    const [verb, ...rest] = argv;
+    const json = rest.includes('--json');
+    const positional = rest.filter((a, i) => !a.startsWith('--') && rest[i - 1] !== '--package');
+    if (verb !== 'where-used' && verb !== 'projects-using' && verb !== 'advisory-impact') {
+        process.stderr.write('usage: code-graph estate where-used <name>|projects-using <package>|advisory-impact [--package P] [--json]\n');
+        return 2;
+    }
+    if (verb !== 'advisory-impact' && !positional[0]) {
+        process.stderr.write(`usage: code-graph estate ${verb} <name> [--json]\n`);
+        return 2;
+    }
+    const db = openEstate();
+    if (!db) {
+        process.stdout.write(`${NO_INDEX}\n`);
+        return 1;
+    }
+    try {
+        const name = positional[0] as string;
+        if (verb === 'projects-using') {
+            const rows = db.projectsUsing(name);
+            if (json) process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+            else {
+                process.stdout.write(`projects using ${name} (${rows.length}):\n`);
+                for (const r of rows) process.stdout.write(line(r, `${r.declared_in.length ? ` · declared in ${r.declared_in.join(', ')}` : ''}${r.imports ? ` · imported ${r.imports}×` : ''}`));
+            }
+            return 0;
+        }
+        if (verb === 'where-used') {
+            const w = whereUsed(db, name);
+            if (json) {
+                process.stdout.write(`${JSON.stringify(w, null, 2)}\n`);
+                return 0;
+            }
+            const section = (title: string, rows: Array<{ id: string; root: string }>): void => {
+                if (!rows.length) return;
+                process.stdout.write(`${title} (${rows.length}):\n`);
+                for (const r of rows) process.stdout.write(line(r));
+            };
+            section(`declare or import package ${name}`, w.package_users);
+            section(`publish package ${name}`, w.publishers);
+            section(`declare a top-level symbol ${name}`, w.declared_by);
+            section(`reference ${name} without resolving it (a guess)`, w.referenced_by);
+            if (!w.package_users.length && !w.publishers.length && !w.declared_by.length && !w.referenced_by.length) {
+                process.stdout.write(`no registered project uses ${name}\n`);
+            }
+            return 0;
+        }
+        const impact = advisoryImpact(db, flagValue(rest, '--package'));
+        if (json) process.stdout.write(`${JSON.stringify(impact, null, 2)}\n`);
+        else {
+            if (!impact.length) process.stdout.write('no advisory package is used by a registered project\n');
+            for (const r of impact) {
+                process.stdout.write(`${r.package}${r.advisories.length ? ` — ${r.advisories.join(', ')}` : ''}:\n`);
+                for (const p of r.projects) process.stdout.write(line(p, p.imports ? ` · imported ${p.imports}×` : ' · declared only'));
+            }
+        }
+        return 0;
+    } finally {
+        db.close();
+    }
+}

package/src/scripts/code_graph/estate_index.ts

@@ -0,0 +1,394 @@
+/**
+ * The estate index: a small, local, user-global table of what each registered
+ * project declares, publishes and exports (ADR-299, Phase 4). Never a merged
+ * graph — it stores package names, top-level symbol names and the names a
+ * project references but does not resolve, and the cross-project edges derived
+ * from them. Off by default (council O1): with the registry switch off nothing
+ * here runs and no file is written.
+ *
+ * `runtime/projects/index-v1.sqlite3`. A project's rows are replaced, never
+ * appended, on its next refresh. Edges are labelled by how they are known:
+ *
+ *   package      A declares a dependency on a package B publishes — a stated fact
+ *   unique-name  A references a name exactly one estate symbol declares — a guess
+ *   mention      A references B's name without declaring it — a guess
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { readRegistry, registryDir, type RegistryOptions, repoIdOf } from '../_lib/project_registry.js';
+import { isSqliteAvailableSync, loadSqliteSync } from '../_lib/sqlite_guard.js';
+import { isTestFile } from './build.js';
+import { type ManifestFacts, manifestFacts } from './estate_manifests.js';
+import { openGraphIndex, sqliteTwinPath, twinIsCurrent } from './sqlite_store.js';
+import type { CodeGraph } from './types.js';
+
+export type XVia = 'package' | 'unique-name' | 'mention';
+
+export interface GraphFacts {
+    exports: Array<{ name: string; kind: string }>;
+    imports: Array<{ package: string; uses: number }>;
+    refs: string[];
+}
+
+export interface XEdge {
+    source: string;
+    target: string;
+    via: XVia;
+    detail: string;
+}
+
+/** Stored as their index here: a kind name per row would be most of an export row's bytes. */
+const KINDS = ['class', 'interface', 'trait', 'function', 'constant', 'type', 'enum'] as const;
+const EXPORT_KINDS: ReadonlySet<string> = new Set(KINDS);
+
+export function indexPath(opts: RegistryOptions = {}): string {
+    return path.join(registryDir(opts), 'index-v1.sqlite3');
+}
+
+/**
+ * Top-level declarations outside test files. The graph records no
+ * exportedness (`dead` refuses for the same reason), so a top-level symbol is
+ * the closest stated fact; a member (`A::m`) never counts.
+ */
+function isTopLevel(id: string, kind: string): boolean {
+    return EXPORT_KINDS.has(kind) && !id.includes('::') && id.split('#').length === 2;
+}
+
+/** `targets` are distinct edge targets with how many edges point at each. */
+function factsFrom(
+    nodes: Iterable<{ id: string; label: string; kind: string | null; source_file: string | null }>,
+    targets: Iterable<readonly [string, number]>,
+): GraphFacts {
+    const exports = new Map<string, { name: string; kind: string }>();
+    const testFile = new Map<string, boolean>();
+    for (const n of nodes) {
+        const file = n.source_file ?? '';
+        let isTest = testFile.get(file);
+        if (isTest === undefined) testFile.set(file, (isTest = isTestFile(file)));
+        if (n.kind && !isTest && isTopLevel(n.id, n.kind)) exports.set(n.id, { name: n.label, kind: n.kind });
+    }
+    const imports = new Map<string, number>();
+    const refs = new Set<string>();
+    for (const [t, n] of targets) {
+        if (t.startsWith('external:')) {
+            const hash = t.indexOf('#');
+            const pkg = t.slice('external:'.length, hash < 0 ? undefined : hash);
+            if (pkg) imports.set(pkg, (imports.get(pkg) ?? 0) + n);
+        } else if (t.startsWith('symbol:')) {
+            refs.add(t.slice('symbol:'.length));
+        }
+    }
+    return {
+        exports: [...exports.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+        imports: [...imports.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([p, uses]) => ({ package: p, uses })),
+        refs: [...refs].sort(),
+    };
+}
+
+/**
+ * The graph facts of one cache: from the graph in hand, else from its current
+ * SQLite twin (two indexed column reads), else by parsing the JSON.
+ */
+export function graphFacts(cachePath: string, graph: CodeGraph | null = null): GraphFacts | null {
+    if (graph) {
+        const counts = new Map<string, number>();
+        for (const e of graph.edges) counts.set(e.target, (counts.get(e.target) ?? 0) + 1);
+        return factsFrom(
+            graph.nodes.map((n) => ({ id: n.id, label: n.label, kind: n.kind, source_file: n.source_file })),
+            counts,
+        );
+    }
+    if (twinIsCurrent(cachePath)) {
+        try {
+            const { DatabaseSync } = loadSqliteSync('code_graph.estate_index');
+            const db = new DatabaseSync(sqliteTwinPath(cachePath), { readOnly: true });
+            try {
+                const kinds = [...EXPORT_KINDS].map((k) => `'${k}'`).join(', ');
+                const nodes = db.prepare(`SELECT id, label, kind, source_file FROM nodes WHERE kind IN (${kinds}) AND instr(id, '::') = 0`).all() as Array<{
+                    id: string;
+                    label: string;
+                    kind: string | null;
+                    source_file: string | null;
+                }>;
+                const targets = (
+                    db
+                        // Ranges, not LIKE: they use the `edges_target` index.
+                        .prepare(
+                            'SELECT target, COUNT(*) AS n FROM edges WHERE ' +
+                                "(target >= 'external:' AND target < 'external;') OR (target >= 'symbol:' AND target < 'symbol;') GROUP BY target",
+                        )
+                        .all() as Array<{ target: string; n: number }>
+                ).map((r) => [r.target, Number(r.n)] as const);
+                return factsFrom(nodes, targets);
+            } finally {
+                db.close();
+            }
+        } catch {
+            /* fall through to the JSON */
+        }
+    }
+    try {
+        return graphFacts(cachePath, JSON.parse(fs.readFileSync(cachePath, 'utf-8')) as CodeGraph);
+    } catch {
+        return null;
+    }
+}
+
+// Rows reference a project by its integer `key`, not its 12-hex id: the id
+// repeated on every export row was a third of the file (measured on the 4.4
+// fixture estate), and the size budget is 2 % of the graphs summarised.
+const SCHEMA =
+    'CREATE TABLE IF NOT EXISTS projects (key INTEGER PRIMARY KEY, id TEXT NOT NULL UNIQUE, name TEXT NOT NULL, root TEXT NOT NULL, indexed_at TEXT NOT NULL, facts_key TEXT);' +
+    'CREATE TABLE IF NOT EXISTS declares (project INTEGER NOT NULL, ecosystem TEXT NOT NULL, package TEXT NOT NULL, manifest TEXT NOT NULL);' +
+    'CREATE TABLE IF NOT EXISTS publishes (project INTEGER NOT NULL, ecosystem TEXT NOT NULL, package TEXT NOT NULL);' +
+    'CREATE TABLE IF NOT EXISTS exports (project INTEGER NOT NULL, kind INTEGER NOT NULL, name TEXT NOT NULL);' +
+    'CREATE TABLE IF NOT EXISTS imports (project INTEGER NOT NULL, package TEXT NOT NULL, uses INTEGER NOT NULL);' +
+    'CREATE TABLE IF NOT EXISTS refs (project INTEGER NOT NULL, name TEXT NOT NULL);' +
+    'CREATE TABLE IF NOT EXISTS xedges (source INTEGER NOT NULL, target INTEGER NOT NULL, via TEXT NOT NULL, detail TEXT NOT NULL);';
+
+const PER_PROJECT = ['declares', 'publishes', 'exports', 'imports', 'refs'];
+
+/** Rebuild `xedges` from the per-project rows; a package edge suppresses both guesses for its pair. */
+const XEDGES_SQL =
+    'DELETE FROM xedges;' +
+    "INSERT INTO xedges SELECT DISTINCT d.project, p.project, 'package', d.package FROM declares d " +
+    'JOIN publishes p ON p.package = d.package AND p.ecosystem = d.ecosystem WHERE d.project <> p.project;' +
+    "INSERT INTO xedges SELECT DISTINCT r.project, e.project, 'unique-name', r.name FROM refs r JOIN exports e ON e.name = r.name " +
+    'WHERE e.project <> r.project AND r.name IN (SELECT name FROM exports GROUP BY name HAVING COUNT(*) = 1) ' +
+    "AND NOT EXISTS (SELECT 1 FROM xedges x WHERE x.source = r.project AND x.target = e.project AND x.via = 'package');" +
+    "INSERT INTO xedges SELECT DISTINCT m.project, p.key, 'mention', m.name FROM " +
+    '(SELECT project, name FROM refs UNION SELECT project, package FROM imports) m JOIN projects p ON lower(p.name) = lower(m.name) ' +
+    "WHERE p.key <> m.project AND NOT EXISTS (SELECT 1 FROM xedges x WHERE x.source = m.project AND x.target = p.key AND x.via = 'package');";
+
+type Db = InstanceType<ReturnType<typeof loadSqliteSync>['DatabaseSync']>;
+
+function openWritable(opts: RegistryOptions): Db {
+    const file = indexPath(opts);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const { DatabaseSync } = loadSqliteSync('code_graph.estate_index');
+    const fresh = !fs.existsSync(file);
+    const db = new DatabaseSync(file);
+    // Small pages: the index holds names only, and its size budget (4.4) is
+    // measured against the project graphs it summarises.
+    if (fresh) db.exec('PRAGMA page_size = 1024');
+    db.exec('PRAGMA busy_timeout = 2000');
+    db.exec(SCHEMA);
+    return db;
+}
+
+/** Replace one project's rows and re-derive the cross-project edges. */
+export function writeProjectRows(
+    id: string,
+    root: string,
+    facts: ManifestFacts & GraphFacts,
+    opts: RegistryOptions = {},
+    factsKey: string | null = null,
+): void {
+    const db = openWritable(opts);
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            db.prepare(
+                'INSERT INTO projects (id, name, root, indexed_at, facts_key) VALUES (?, ?, ?, ?, ?) ' +
+                    'ON CONFLICT(id) DO UPDATE SET name = excluded.name, root = excluded.root, indexed_at = excluded.indexed_at, facts_key = excluded.facts_key',
+            ).run(id, path.basename(root), root, (opts.now ?? new Date()).toISOString(), factsKey);
+            const key = (db.prepare('SELECT key FROM projects WHERE id = ?').get(id) as { key: number }).key;
+            for (const t of PER_PROJECT) db.prepare(`DELETE FROM ${t} WHERE project = ?`).run(key);
+            const dec = db.prepare('INSERT INTO declares VALUES (?, ?, ?, ?)');
+            for (const d of facts.declares) dec.run(key, d.ecosystem, d.package, d.manifest);
+            const pub = db.prepare('INSERT INTO publishes VALUES (?, ?, ?)');
+            for (const p of facts.publishes) pub.run(key, p.ecosystem, p.package);
+            const exp = db.prepare('INSERT INTO exports VALUES (?, ?, ?)');
+            for (const e of facts.exports) exp.run(key, KINDS.indexOf(e.kind as (typeof KINDS)[number]), e.name);
+            const imp = db.prepare('INSERT INTO imports VALUES (?, ?, ?)');
+            for (const i of facts.imports) imp.run(key, i.package, i.uses);
+            const ref = db.prepare('INSERT INTO refs VALUES (?, ?)');
+            for (const r of facts.refs) ref.run(key, r);
+            db.exec(XEDGES_SQL);
+            db.exec('COMMIT');
+        } catch (e) {
+            db.exec('ROLLBACK');
+            throw e;
+        }
+        // Replacing rows leaves free pages; compact only once they are a real share.
+        const free = (db.prepare('PRAGMA freelist_count').get() as { freelist_count: number }).freelist_count;
+        const pages = (db.prepare('PRAGMA page_count').get() as { page_count: number }).page_count;
+        if (free > 32 && free * 4 > pages) db.exec('VACUUM');
+    } finally {
+        db.close();
+    }
+}
+
+/** Remove a project from the index (a `projects remove` / `prune`). */
+export function dropProjectRows(id: string, opts: RegistryOptions = {}): void {
+    if (!fs.existsSync(indexPath(opts)) || !isSqliteAvailableSync()) return;
+    const db = openWritable(opts);
+    try {
+        const row = db.prepare('SELECT key FROM projects WHERE id = ?').get(id) as { key: number } | undefined;
+        if (row) {
+            for (const t of PER_PROJECT) db.prepare(`DELETE FROM ${t} WHERE project = ?`).run(row.key);
+            db.prepare('DELETE FROM projects WHERE key = ?').run(row.key);
+            db.exec(XEDGES_SQL);
+            db.exec('VACUUM');
+        }
+    } finally {
+        db.close();
+    }
+}
+
+/**
+ * The refresh hook: index `root` when the owner switched the index on. Returns
+ * whether rows were written. Never throws — the index is a convenience and a
+ * failure to write it never fails a refresh.
+ */
+export function indexAfterRefresh(id: string, root: string, cachePath: string, graph: CodeGraph | null, opts: RegistryOptions = {}): boolean {
+    try {
+        if (!readRegistry(opts).index || !isSqliteAvailableSync()) return false;
+        const manifests = manifestFacts(root);
+        // A refresh that changed neither the graph nor a manifest rewrites nothing:
+        // the graph's own content checksum plus the manifest rows decide.
+        const sum = graphChecksum(cachePath, graph);
+        const key = sum === null ? null : createHash('sha256').update(`${sum}\0${root}\0${JSON.stringify(manifests)}`).digest('hex');
+        if (key !== null && storedFactsKey(id, opts) === key) return true;
+        const g = graphFacts(cachePath, graph);
+        if (!g) return false;
+        writeProjectRows(id, root, { ...manifests, ...g }, opts, key);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function graphChecksum(cachePath: string, graph: CodeGraph | null): string | null {
+    if (graph) return graph.source_checksum || null;
+    const index = openGraphIndex(cachePath);
+    if (!index) return null;
+    try {
+        return index.sourceChecksum || null;
+    } finally {
+        index.close();
+    }
+}
+
+function storedFactsKey(id: string, opts: RegistryOptions): string | null {
+    const file = indexPath(opts);
+    if (!fs.existsSync(file)) return null;
+    const { DatabaseSync } = loadSqliteSync('code_graph.estate_index');
+    const db = new DatabaseSync(file, { readOnly: true });
+    try {
+        const row = db.prepare('SELECT facts_key FROM projects WHERE id = ?').get(id) as { facts_key: string | null } | undefined;
+        return row?.facts_key ?? null;
+    } catch {
+        return null;
+    } finally {
+        db.close();
+    }
+}
+
+/** A read-only view of the index; `null` when there is none. */
+export function openEstate(opts: RegistryOptions = {}): EstateReader | null {
+    const file = indexPath(opts);
+    if (!fs.existsSync(file) || !isSqliteAvailableSync()) return null;
+    const { DatabaseSync } = loadSqliteSync('code_graph.estate_index');
+    return new EstateReader(new DatabaseSync(file, { readOnly: true }));
+}
+
+type Answer = { id: string; root: string };
+
+/**
+ * One row per logical project: clones of one origin are indexed per checkout,
+ * so an answer folds them by repo id and lists every checkout root. `facet`
+ * keeps rows apart that differ in more than the project (an ecosystem, a kind).
+ */
+function byRepo<T extends Answer>(rows: T[], facet: (r: T) => string = () => '', merge: (a: T, b: T) => T = (a) => a): Array<T & { repo_id: string; roots: string[] }> {
+    const out = new Map<string, T & { repo_id: string; roots: string[] }>();
+    for (const r of rows) {
+        const repo_id = repoIdOf(r.id);
+        const k = `${repo_id}\0${facet(r)}`;
+        const prev = out.get(k);
+        if (prev === undefined) out.set(k, { ...r, repo_id, roots: [r.root] });
+        else out.set(k, { ...merge(prev, r), repo_id, roots: prev.roots.includes(r.root) ? prev.roots : [...prev.roots, r.root] });
+    }
+    return [...out.values()];
+}
+
+export class EstateReader {
+    constructor(private readonly db: Db) {}
+
+    close(): void {
+        this.db.close();
+    }
+
+    projects(): Array<{ id: string; name: string; root: string; indexed_at: string }> {
+        return this.db.prepare('SELECT id, name, root, indexed_at FROM projects ORDER BY name, id').all() as Array<{
+            id: string;
+            name: string;
+            root: string;
+            indexed_at: string;
+        }>;
+    }
+
+    xedges(): XEdge[] {
+        return this.db
+            .prepare(
+                'SELECT s.id AS source, t.id AS target, x.via, x.detail FROM xedges x JOIN projects s ON s.key = x.source ' +
+                    'JOIN projects t ON t.key = x.target ORDER BY s.id, t.id, x.via, x.detail',
+            )
+            .all() as unknown as XEdge[];
+    }
+
+    /** One project's rows of one table, with the project named by its id and an export's kind by name. */
+    rows(table: 'declares' | 'publishes' | 'exports' | 'imports' | 'refs', project: string): Array<Record<string, unknown>> {
+        const rows = this.db
+            .prepare(`SELECT r.* FROM ${table} r JOIN projects p ON p.key = r.project WHERE p.id = ? ORDER BY 2, 3`)
+            .all(project) as Array<Record<string, unknown>>;
+        return rows.map((r) => ({
+            ...r,
+            project,
+            ...(table === 'exports' ? { kind: KINDS[r['kind'] as number] ?? 'unknown' } : {}),
+        }));
+    }
+
+    /** Projects that declare `pkg` (any ecosystem) or import it in code. */
+    projectsUsing(pkg: string): Array<{ id: string; name: string; root: string; declared_in: string[]; imports: number; repo_id: string; roots: string[] }> {
+        const rows = this.db
+            .prepare(
+                'SELECT p.id, p.name, p.root, ' +
+                    "(SELECT group_concat(manifest, char(10)) FROM (SELECT DISTINCT manifest FROM declares WHERE project = p.key AND package = ?)) AS declared_in, " +
+                    '(SELECT COALESCE(SUM(uses), 0) FROM imports WHERE project = p.key AND package = ?) AS imports ' +
+                    'FROM projects p WHERE EXISTS (SELECT 1 FROM declares WHERE project = p.key AND package = ?) ' +
+                    'OR EXISTS (SELECT 1 FROM imports WHERE project = p.key AND package = ?) ORDER BY p.name, p.id',
+            )
+            .all(pkg, pkg, pkg, pkg) as Array<{ id: string; name: string; root: string; declared_in: string | null; imports: number }>;
+        return byRepo(
+            rows.map((r) => ({ ...r, declared_in: r.declared_in ? r.declared_in.split('\n').sort() : [], imports: Number(r.imports) })),
+            undefined,
+            // Two checkouts of one project count its imports once, not twice.
+            (a, b) => ({ ...a, declared_in: [...new Set([...a.declared_in, ...b.declared_in])].sort(), imports: Math.max(a.imports, b.imports) }),
+        );
+    }
+
+    /** Projects that reference `name` without resolving it — candidates for a symbol another project declares. */
+    referrers(name: string): Array<{ id: string; name: string; root: string; repo_id: string; roots: string[] }> {
+        return byRepo(this.db
+            .prepare('SELECT DISTINCT p.id, p.name, p.root FROM refs r JOIN projects p ON p.key = r.project WHERE r.name = ? ORDER BY p.name, p.id')
+            .all(name) as Array<{ id: string; name: string; root: string }>);
+    }
+
+    /** Projects that publish package `pkg`. */
+    publishers(pkg: string): Array<{ id: string; name: string; root: string; ecosystem: string; repo_id: string; roots: string[] }> {
+        return byRepo(this.db
+            .prepare('SELECT DISTINCT p.id, p.name, p.root, b.ecosystem FROM publishes b JOIN projects p ON p.key = b.project WHERE b.package = ? ORDER BY p.name, p.id')
+            .all(pkg) as Array<{ id: string; name: string; root: string; ecosystem: string }>, (r) => r.ecosystem);
+    }
+
+    /** Projects that declare a top-level symbol named `name`. */
+    exporters(name: string): Array<{ id: string; name: string; root: string; kind: string; repo_id: string; roots: string[] }> {
+        const rows = this.db
+            .prepare('SELECT p.id, p.name, p.root, e.kind FROM exports e JOIN projects p ON p.key = e.project WHERE e.name = ? ORDER BY p.name, p.id')
+            .all(name) as Array<{ id: string; name: string; root: string; kind: number }>;
+        return byRepo(rows.map((r) => ({ ...r, kind: KINDS[r.kind] ?? 'unknown' })), (r) => r.kind);
+    }
+}