graph-indexer 3.0.0 → 3.1.0

package/src/query/orm.mjs

@@ -0,0 +1,286 @@
+/**
+ * ORM models, their tables, the migrations that touch them and, for Prisma, the client calls that
+ * use them: links the compiler does not make, since a migration names its table in a string and
+ * Prisma's client is generated outside the repository (`prisma.envelope.findFirst(…)` is typed
+ * only by `node_modules/.prisma`).
+ *
+ * Models recognised:
+ *   - Prisma: `model Name { … }` in `*.prisma` files, table `@@map("…")` or the model's name;
+ *   - Django: classes deriving from `models.Model` (directly or through other models, abstract
+ *     ones left out), table `Meta.db_table` or `<app_label>_<name>`, the app label from `Meta`
+ *     (inherited from an abstract base) or the app's directory; a proxy model has its base's table;
+ *   - SQLAlchemy / SQLModel: classes with `__tablename__`, or `table=True` (SQLModel names the
+ *     table after the class, lower-cased);
+ *   - TypeORM: `@Entity('name')` / `@Entity({ name, schema })`, or `@Entity()` (the class name in
+ *     snake_case, TypeORM's default naming).
+ * Migrations: files under a directory whose name holds `migration` (or Alembic's `versions`), and
+ * code that drives TypeORM's `queryRunner` elsewhere (upgrade commands). A table is touched by SQL
+ * that names it (`CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`, `RENAME TO`, `INSERT INTO`, `UPDATE`,
+ * `DELETE FROM`, an index `ON` it, a foreign key `REFERENCES` it, a read `FROM` / `JOIN` it), by
+ * Alembic's `op.*('table', …)` and `batch_alter_table`, by TypeORM's `queryRunner.*Table` /
+ * `*Column`(…'table'…); a Django model by its app's `migrations.CreateModel(name=…)` and
+ * `model_name=…` operations and by data migrations' `apps.get_model('app', 'Model')`.
+ * Django models whose base comes from a library (auth's `AbstractUser`, treebeard, mptt,
+ * polymorphic) are recognised by name.
+ * Prisma client calls: `<client>.<model>.<operation>(` where the client is named `prisma…`, `db`,
+ * `tx`/`trx`, `client` or `…Prisma`, and the operation is one of Prisma's model methods.
+ * Test files are left out.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const PRISMA_OPS = 'findUnique|findUniqueOrThrow|findFirst|findFirstOrThrow|findMany|create|createMany|createManyAndReturn|update|updateMany|updateManyAndReturn|upsert|delete|deleteMany|count|aggregate|groupBy';
+const PRISMA_CALL = new RegExp(`\\b(prisma\\w*|\\w*Prisma|db|tx|trx|client|transaction)\\s*\\.\\s*([a-z]\\w*)\\s*\\.\\s*(${PRISMA_OPS})\\s*[(<]`, 'g');
+const MIGRATION_DIR = /(^|\/)([^/]*migrations?[^/]*|versions)\//i;
+const SQL_TABLE = /\b(CREATE\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?|ALTER\s+TABLE(?:\s+IF\s+EXISTS)?(?:\s+ONLY)?|DROP\s+TABLE(?:\s+IF\s+EXISTS)?|INSERT\s+INTO|UPDATE|DELETE\s+FROM|TRUNCATE(?:\s+TABLE)?|RENAME\s+TO|REFERENCES|FROM|JOIN|ON)\s+((?:[`"[]?\w+[`"\]]?\s*\.\s*)?[`"[]?\w+[`"\]]?)/gi;
+const ALEMBIC = /\bop\.(create_primary_key|create_table|drop_table|add_column|drop_column|alter_column|rename_table|create_index|drop_index|create_foreign_key|create_unique_constraint|create_check_constraint|drop_constraint|bulk_insert|batch_alter_table)\s*\(/g;
+const TYPEORM_RUNNER = /\bqueryRunner\.(createTable|dropTable|renameTable|addColumn|addColumns|dropColumn|dropColumns|changeColumn|renameColumn|createIndex|dropIndex|createForeignKey|createForeignKeys|dropForeignKey|createUniqueConstraint|dropUniqueConstraint|createPrimaryKey|clearTable)\s*\(\s*['"`]((?:\w+\.)?\w+)['"`]/g;
+const DJANGO_OP = /\bmigrations\.(\w+)\s*\(([^)]*?)\b(name|model_name)\s*=\s*['"](\w+)['"]/g;
+
+const EXTERNAL_MODEL_BASES = /^(?:\w+\.)*(AbstractUser|AbstractBaseUser|MP_Node|NS_Node|AL_Node|MPTTModel|PolymorphicModel|TimeStampedModel)$/;
+const snake = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2').toLowerCase();
+const unquote = (s) => s.replace(/[`"[\]\s]/g, '');
+const decorators = (s) => { try { return JSON.parse(s.decorators || '[]'); } catch { return []; } };
+
+/** Repository files matching a test, indexed or not (`*.prisma`, migration `.sql`): git's list, else a bounded walk. */
+function repoFiles(root, test) {
+    const r = spawnSync('git', ['-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8', timeout: 5000, maxBuffer: 64 << 20 });
+    if (r.status === 0 && r.stdout) return r.stdout.split('\0').filter(f => f && test(f));
+    const out = [];
+    const walk = (dir, depth) => {
+        if (depth > 8 || out.length > 5000) return;
+        let ents = [];
+        try { ents = fs.readdirSync(path.join(root, dir), { withFileTypes: true }); } catch { return; }
+        for (const e of ents) {
+            if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+            const rel = dir ? `${dir}/${e.name}` : e.name;
+            if (e.isDirectory()) walk(rel, depth + 1); else if (test(rel)) out.push(rel);
+        }
+    };
+    walk('', 0);
+    return out;
+}
+
+function readLines(intel, rel) {
+    const l = intel.fileLines(rel);
+    if (l) return l;
+    try { return fs.readFileSync(path.join(intel.root, rel), 'utf8').split(/\r?\n/); } catch { return null; }
+}
+
+/** Prisma models of every `.prisma` file. */
+function prismaModels(intel) {
+    const out = [];
+    for (const rel of repoFiles(intel.root, f => f.endsWith('.prisma') && !f.includes('node_modules/'))) {
+        const lines = readLines(intel, rel) ?? [];
+        let cur = null;
+        lines.forEach((l, i) => {
+            const m = /^\s*model\s+(\w+)\s*\{/.exec(l);
+            if (m) { cur = { orm: 'Prisma', name: m[1], sym: null, table: m[1], file: rel, line: i + 1, end: i + 1 }; out.push(cur); return; }
+            if (!cur) return;
+            const map = /^\s*@@map\(\s*(?:name\s*:\s*)?["']([^"']+)["']/.exec(l);
+            if (map) cur.table = map[1];
+            if (/^\s*\}/.test(l)) { cur.end = i + 1; cur = null; }
+        });
+    }
+    return out;
+}
+
+/** The text of a class's body (its own lines), for `class Meta`, `__tablename__`. */
+const bodyOf = (intel, s) => (intel.fileLines(s.path) ?? []).slice(s.start_line - 1, s.end_line).join('\n');
+
+/** Django, SQLAlchemy/SQLModel and TypeORM models among the indexed classes. */
+function classModels(intel) {
+    const out = [];
+    const classes = intel.store.all(`SELECT s.id, s.name, s.qname, s.kind, s.start_line, s.end_line, s.decorators, s.bases, s.sig, s.parent_id, f.path, f.lang
+        FROM symbols s JOIN files f ON f.id = s.file_id WHERE s.kind = 'class' AND f.is_test = 0 AND f.lang IN ('python', 'typescript', 'tsx', 'javascript')`);
+    const byId = new Map(classes.map(c => [c.id, c]));
+    const basesOf = new Map();
+    for (const r of intel.store.all(`SELECT src_id, dst_id FROM refs WHERE kind = 'inherit' AND dst_id IS NOT NULL AND src_id IS NOT NULL`)) (basesOf.get(r.src_id) ?? basesOf.set(r.src_id, []).get(r.src_id)).push(r.dst_id);
+    const bases = (c) => { try { return JSON.parse(c.bases || '[]'); } catch { return []; } };
+    const meta = (c) => {
+        const body = bodyOf(intel, c);
+        const m = /\n\s*class\s+Meta\b[^:]*:([\s\S]*?)(?=\n\s{0,8}(?:def|class|@)\s|\n\S|$)/.exec(body)?.[1] ?? '';
+        return {
+            abstract: /\babstract\s*=\s*True\b/.test(m),
+            proxy: /\bproxy\s*=\s*True\b/.test(m),
+            appLabel: /\bapp_label\s*=\s*['"](\w+)['"]/.exec(m)?.[1] ?? null,
+            dbTable: /\bdb_table\s*=\s*['"]([^'"]+)['"]/.exec(m)?.[1] ?? null,
+        };
+    };
+    // Django: a class is a model if a base is `models.Model` or a model, through the index
+    const djangoMemo = new Map();
+    const isDjango = (c, seen = new Set()) => {
+        if (djangoMemo.has(c.id)) return djangoMemo.get(c.id);
+        if (seen.has(c.id)) return false;
+        seen.add(c.id);
+        // a base from django or a library of models (auth's users, treebeard, mptt, polymorphic …)
+        let v = c.lang === 'python' && bases(c).some(b => (/^(models\.)?Model$/.test(String(b).trim()) || EXTERNAL_MODEL_BASES.test(String(b).trim())) && /\bmodels\b|django|treebeard|mptt|polymorphic/.test(bodyOrHead(c)));
+        if (!v) for (const b of basesOf.get(c.id) ?? []) { const bc = byId.get(b); if (bc && isDjango(bc, seen)) { v = true; break; } }
+        djangoMemo.set(c.id, v);
+        return v;
+    };
+    function bodyOrHead(c) {
+        // the module imports django's models (`from django.db import models`): read its first lines once
+        const lines = intel.fileLines(c.path) ?? [];
+        return lines.slice(0, 80).join('\n');
+    }
+    const inheritedMeta = (c, key, seen = new Set()) => {
+        if (seen.has(c.id)) return null;
+        seen.add(c.id);
+        const v = meta(c)[key];
+        if (v) return v;
+        for (const b of basesOf.get(c.id) ?? []) { const bc = byId.get(b); const x = bc && inheritedMeta(bc, key, seen); if (x) return x; }
+        return null;
+    };
+    for (const c of classes) {
+        if (c.lang === 'python') {
+            const body = bodyOf(intel, c);
+            const tn = /^\s*__tablename__\s*=\s*['"]([^'"]+)['"]/m.exec(body)?.[1];
+            if (tn) { out.push({ orm: 'SQLAlchemy', name: c.name, sym: c, table: tn, file: c.path, line: c.start_line }); continue; }
+            if (/\btable\s*=\s*True\b/.test(c.sig ?? body.split('\n')[0])) { out.push({ orm: 'SQLModel', name: c.name, sym: c, table: c.name.toLowerCase(), file: c.path, line: c.start_line }); continue; }
+            if (isDjango(c) && !meta(c).abstract) {
+                const dir = path.posix.dirname(c.path);
+                const appDir = /\/models$/.test(dir) ? path.posix.dirname(dir) : dir;
+                const label = inheritedMeta(c, 'appLabel') ?? path.posix.basename(appDir);
+                // a proxy model has no table of its own: its concrete base's
+                const proxyOf = meta(c).proxy ? (basesOf.get(c.id) ?? []).map(b => byId.get(b)).find(b => b && isDjango(b)) ?? null : null;
+                out.push({ orm: 'Django', name: c.name, sym: c, table: inheritedMeta(c, 'dbTable') ?? `${label}_${c.name.toLowerCase()}`, label, proxyOf, appDir, file: c.path, line: c.start_line });
+            }
+        } else {
+            // `@Entity(…)` right above the class (an exported class's decorators are not stored on it)
+            const lines = intel.fileLines(c.path) ?? [];
+            let top = c.start_line - 1; // the decorators: the lines above the class up to the previous statement
+            while (top > 0 && top > c.start_line - 150) {
+                const l = lines[top - 1].trim();
+                if (/;$/.test(l) || /^(import|export|class|const|let|var|function|interface|type)\b/.test(l) || l === '}') break;
+                top--;
+            }
+            const last = lines.slice(top, c.start_line - 1).join('\n');
+            if (!decorators(c).includes('Entity') && !/@Entity\(/.test(last)) continue;
+            const head = decorators(c).includes('Entity') ? (intel.fileLines(c.path) ?? []).slice(Math.max(0, c.start_line - 6), c.start_line + 1).join('\n') : last;
+            const e = /@Entity\(\s*(?:['"`]([^'"`]+)['"`]|\{([^}]*)\})?/.exec(head);
+            const name = e?.[1] ?? /\bname\s*:\s*['"`]([^'"`]+)['"`]/.exec(e?.[2] ?? '')?.[1] ?? null;
+            const schema = /\bschema\s*:\s*['"`]([^'"`]+)['"`]/.exec(e?.[2] ?? '')?.[1] ?? null;
+            out.push({ orm: 'TypeORM', name: c.name, sym: c, table: name ?? snake(c.name), schema, defaultName: !name, file: c.path, line: c.start_line });
+        }
+    }
+    // proxies take their base's table (resolved through proxies of proxies)
+    const byClass = new Map(out.filter(m => m.sym).map(m => [m.sym.id, m]));
+    for (const m of out) {
+        let base = m.proxyOf, guard = 0;
+        while (base && guard++ < 8) {
+            const bm = byClass.get(base.id);
+            if (bm && !bm.proxyOf) { m.table = bm.table; m.appDir = bm.appDir; m.proxyName = bm.name; break; }
+            base = bm?.proxyOf ?? null;
+        }
+    }
+    return out;
+}
+
+/** Every table a migration file touches: [{ table (lower case, unqualified), schema, file, line, op }], and Django operations by model. */
+function migrationRefs(intel) {
+    const tables = [], django = [];
+    const files = repoFiles(intel.root, f => MIGRATION_DIR.test(f) && /\.(sql|py|ts|js|mjs|cjs)$/.test(f) && !f.includes('node_modules/'));
+    // schema changes outside a migrations directory (upgrade commands): code that drives TypeORM's queryRunner
+    const seen = new Set(files);
+    for (const r of intel.store.all(`SELECT DISTINCT f.path FROM refs r JOIN files f ON f.id = r.file_id WHERE r.recv = 'queryRunner' AND f.is_test = 0`)) if (!seen.has(r.path)) { seen.add(r.path); files.push(r.path); }
+    for (const rel of files) {
+        const lines = readLines(intel, rel);
+        if (!lines) continue;
+        const text = lines.join('\n');
+        const lineAt = (off) => text.slice(0, off).split('\n').length;
+        const isPy = /\.py$/.test(rel);
+        const add = (raw, off, op) => {
+            const parts = unquote(raw).split('.');
+            const table = parts.pop();
+            if (!table || /^(SET|SELECT|TABLE|IF|ONLY|EXISTS|DELETE|UPDATE|NOT|CONFLICT|LATERAL|DUAL|INSERT|VALUES|WHERE)$/i.test(table)) return;
+            tables.push({ table: table.toLowerCase(), schema: parts.pop() ?? null, file: rel, line: lineAt(off), op });
+        };
+        for (const m of text.matchAll(SQL_TABLE)) {
+            const kw = m[1].replace(/\s+/g, ' ').toUpperCase();
+            // `ON` is an index's table only after CREATE [UNIQUE] INDEX …
+            if (kw === 'ON' && !/CREATE\s+(UNIQUE\s+)?INDEX\b[^;]*$/i.test(text.slice(Math.max(0, m.index - 300), m.index))) continue;
+            // `UPDATE t [AS] alias SET`: a statement, not the word in prose or a column name
+            if (kw === 'UPDATE' && !/^\s*(?:(?:AS\s+)?\w+\s+)?SET\b/i.test(text.slice(m.index + m[0].length, m.index + m[0].length + 60))) continue;
+            // reads (`FROM`, `JOIN`) in SQL only: in Python, `from x import y` is no table
+            if ((kw === 'FROM' || kw === 'JOIN') && isPy && !/^["`]/.test(m[2]) && !/(execute|RunSQL|text)\s*\(/.test(text.slice(text.lastIndexOf('\n', m.index) + 1, m.index))) continue;
+            add(m[2], m.index, kw.split(' ').slice(0, 2).join(' '));
+        }
+        for (const m of text.matchAll(ALEMBIC)) {
+            const args = text.slice(m.index + m[0].length, m.index + m[0].length + 400);
+            // the table: the first string argument (the second for create_index / create_foreign_key …), or table_name=
+            const named = /\btable_name\s*=\s*['"](\w+)['"]/.exec(args.split(')')[0] ?? '')?.[1];
+            const strs = [...args.matchAll(/['"](\w+)['"]/g)].map(x => x[1]);
+            const viaF = /^\s*op\.f\(/.test(args);
+            let table = named;
+            if (!table) table = /^(create_index|create_unique_constraint|create_check_constraint|create_primary_key|drop_constraint|drop_index)$/.test(m[1]) || viaF ? strs[1] : strs[0];
+            if (m[1] === 'create_foreign_key') {
+                // (name, source, referent, …); the name may be None
+                const [src, ref] = /^\s*None\b/.test(args) ? [strs[0], strs[1]] : [strs[1], strs[2]];
+                if (src) tables.push({ table: src.toLowerCase(), schema: null, file: rel, line: lineAt(m.index), op: m[1] });
+                if (ref) tables.push({ table: ref.toLowerCase(), schema: null, file: rel, line: lineAt(m.index), op: `${m[1]} (referenced)` });
+                continue;
+            }
+            if (table) tables.push({ table: table.toLowerCase(), schema: null, file: rel, line: lineAt(m.index), op: m[1] });
+        }
+        for (const m of text.matchAll(TYPEORM_RUNNER)) add(m[2], m.index, m[1]);
+        if (isPy) {
+            for (const m of text.matchAll(DJANGO_OP)) django.push({ model: m[4].toLowerCase(), dir: path.posix.dirname(rel), file: rel, line: lineAt(m.index), op: m[1] });
+            // data migrations: `apps.get_model("catalogue", "Option")`
+            for (const m of text.matchAll(/\bget_model\(\s*['"](\w+)['"]\s*,\s*['"](\w+)['"]/g)) django.push({ model: m[2].toLowerCase(), label: m[1], file: rel, line: lineAt(m.index), op: 'get_model (data migration)' });
+        }
+    }
+    return { tables, django };
+}
+
+/** Prisma client calls in the indexed TypeScript/JavaScript: [{ model (lower-first), op, file, line }]. */
+function prismaCalls(intel, models) {
+    const names = new Set(models.map(m => m.name[0].toLowerCase() + m.name.slice(1)));
+    const out = [];
+    for (const f of intel.store.all(`SELECT id, path FROM files WHERE lang IN ('typescript', 'tsx', 'javascript', 'vue', 'svelte') AND is_test = 0`)) {
+        const lines = intel.fileLines(f.path);
+        if (!lines) continue;
+        lines.forEach((l, i) => {
+            if (!l.includes('.')) return;
+            for (const m of l.matchAll(PRISMA_CALL)) if (names.has(m[2])) out.push({ model: m[2], op: m[3], fileId: f.id, file: f.path, line: i + 1, client: m[1] });
+        });
+    }
+    return out;
+}
+
+/**
+ * Models with their table, the migrations that touch it and (Prisma) the client calls:
+ * [{ orm, name, sym, table, file, line, migrations: [{ file, line, op }], calls: [{ file, line, op, owner }] }].
+ */
+export function collectModels(intel) {
+    if (intel._orm?.version === intel.ix?.version) return intel._orm.data;
+    const prisma = prismaModels(intel);
+    const models = [...prisma, ...classModels(intel)];
+    if (!models.length) { intel._orm = { version: intel.ix?.version, data: [] }; return []; }
+    const { tables, django } = migrationRefs(intel);
+    const byTable = new Map();
+    for (const t of tables) (byTable.get(t.table) ?? byTable.set(t.table, []).get(t.table)).push(t);
+    const calls = prisma.length ? prismaCalls(intel, prisma) : [];
+    for (const m of models) {
+        const table = m.table.toLowerCase().split('.').pop();
+        m.migrations = (byTable.get(table) ?? []).filter(t => !m.schema || !t.schema || t.schema.toLowerCase() === m.schema.toLowerCase());
+        if (m.orm === 'Django') m.migrations.push(...django.filter(d => d.model === (m.proxyName ?? m.name).toLowerCase() && (d.label ? d.label === m.label : d.dir === `${m.appDir}/migrations`)));
+        m.migrations.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+        m.calls = m.orm === 'Prisma' ? calls.filter(c => c.model === m.name[0].toLowerCase() + m.name.slice(1)) : [];
+        for (const c of m.calls) c.owner ??= intel.store.get(`SELECT qname FROM symbols WHERE file_id = ? AND start_line <= ? AND end_line >= ? AND kind IN ('function', 'method', 'variable', 'constant') ORDER BY start_line DESC LIMIT 1`, c.fileId, c.line, c.line)?.qname ?? null;
+    }
+    intel._orm = { version: intel.ix?.version, data: models };
+    return models;
+}
+
+/** The model a class symbol is, if any. */
+export function modelOf(intel, id) {
+    return collectModels(intel).find(m => m.sym?.id === id) ?? null;
+}
+
+/** Prisma models named so (case-insensitive), for a name that is no indexed symbol. */
+export function prismaModelsNamed(intel, name) {
+    const n = String(name ?? '').toLowerCase();
+    return collectModels(intel).filter(m => m.orm === 'Prisma' && m.name.toLowerCase() === n);
+}

package/src/query/read.mjs

@@ -14,6 +14,8 @@ const NAMED_KINDS = ['call', 'new', 'inherit', 'type', 'decorator'];
 // what the reader most often needs next: code it calls and types it uses; data (fields, constants,
 // enum members) comes after, its one-line definition is usually all there is to it
 const TARGET_WEIGHT = (kind) => (['field', 'property', 'variable', 'constant'].includes(kind) ? 0.35 : 1);
+// what a call or instantiation can bind to by name
+const CALLABLE_TARGETS = ['function', 'method', 'constructor', 'class', 'struct', 'macro', 'object', 'type'];
 const DEFINITION_KINDS = ['function', 'method', 'constructor', 'class', 'interface', 'struct', 'trait', 'enum', 'type', 'constant', 'macro', 'object', 'module'];
 
 /**
@@ -45,8 +47,9 @@ export function definitionsUsed(intel, file, from, to, { max = 10, skipIds = new
             const e = bound.get(r.dst_id) ?? bound.set(r.dst_id, { n: 0, score: 0, first: r.line }).get(r.dst_id);
             e.n++; e.score += w * Math.max(0.3, r.conf ?? 1);
         } else if (NAMED_KINDS.includes(r.kind)) {
-            const e = unbound.get(r.name) ?? unbound.set(r.name, { n: 0, score: 0, first: r.line }).get(r.name);
+            const e = unbound.get(r.name) ?? unbound.set(r.name, { n: 0, score: 0, first: r.line, called: false }).get(r.name);
             e.n++; e.score += w * 0.5;
+            if (r.kind === 'call' || r.kind === 'new') e.called = true;
         }
     }
     const inView = (s) => s.path === file && s.start_line >= from && s.end_line <= to;
@@ -66,6 +69,8 @@ export function definitionsUsed(intel, file, from, to, { max = 10, skipIds = new
         if (cands.length !== 1 || seen.has(cands[0].id) || skip.has(cands[0].id)) continue;
         const s = get.get(cands[0].id);
         if (!s || inView(s)) continue;
+        // `Math.max(…)` is not a call to a constant named `max`
+        if (e.called && !CALLABLE_TARGETS.includes(s.kind)) continue;
         seen.add(s.id);
         rows.push({ ...s, ...e, score: e.score * TARGET_WEIGHT(s.kind), byName: true });
     }

package/src/query/report.mjs

@@ -0,0 +1,53 @@
+/**
+ * `graph-indexer report`: what a bug report needs about an index, without anything from the code.
+ *
+ * graph-indexer sends nothing anywhere. When an answer is wrong or slow, this summary — versions,
+ * size, languages, how much of each language's references are bound, and latencies — is what the
+ * user pastes into an issue. It carries no paths, names or source text, so it is safe to share.
+ */
+import os from 'node:os';
+import { callTool } from '../mcp/tools.mjs';
+
+const pct = (a, b) => (b ? `${Math.round((1000 * a) / b) / 10}%` : '–');
+
+/** Median wall time of `fn` over `n` runs, in milliseconds. */
+async function median(fn, n = 5) {
+    const t = [];
+    for (let i = 0; i < n; i++) { const s = process.hrtime.bigint(); await fn(); t.push(Number(process.hrtime.bigint() - s) / 1e6); }
+    t.sort((a, b) => a - b);
+    return Math.round(t[n >> 1] * 10) / 10;
+}
+
+export async function reportText(intel, { version }) {
+    const st = intel.stats();
+    const sync = intel.lastSyncStats ?? {};
+    const byLang = intel.store.all(`SELECT f.lang, COUNT(DISTINCT f.id) AS files,
+            SUM(CASE WHEN r.kind IN ('call', 'new') THEN 1 ELSE 0 END) AS calls,
+            SUM(CASE WHEN r.kind IN ('call', 'new') AND r.dst_id IS NOT NULL THEN 1 ELSE 0 END) AS bound,
+            SUM(CASE WHEN r.kind IN ('call', 'new') AND r.conf >= 0.9 THEN 1 ELSE 0 END) AS exact
+        FROM files f LEFT JOIN refs r ON r.file_id = f.id GROUP BY f.lang ORDER BY files DESC`);
+    const tests = intel.store.get('SELECT COUNT(*) AS n FROM files WHERE is_test = 1')?.n ?? 0;
+    // latencies on the most referenced definition: the heaviest ordinary question
+    const top = intel.store.get(`SELECT s.id, s.qname FROM symbols s JOIN refs r ON r.dst_id = s.id GROUP BY s.id ORDER BY COUNT(*) DESC LIMIT 1`);
+    const lat = [];
+    if (top) {
+        const target = `${intel.sym(top.id).path}:${top.qname}`;
+        lat.push(`find_references ${await median(() => callTool(intel, 'find_references', { symbol: target }))} ms`);
+        lat.push(`read_code ${await median(() => callTool(intel, 'read_code', { targets: [target] }))} ms`);
+        lat.push(`explore ${await median(() => callTool(intel, 'explore', { symbols: [target] }))} ms`);
+    }
+    const out = [
+        '### graph-indexer report',
+        `- graph-indexer ${version}, Node.js ${process.versions.node}, ${os.platform()} ${os.arch()}, ${os.cpus().length} CPUs`,
+        `- index: ${st.files} files (${tests} test files), ${st.symbols} symbols, ${st.refs} references — ${pct(st.resolved, st.refs)} bound, ${pct(st.exact, st.refs)} exact`,
+        `- last sync: ${sync.added ?? 0} added, ${sync.changed ?? 0} changed, ${sync.removed ?? 0} removed in ${sync.ms ?? '?'} ms`,
+        `- warm latency (median of 5, most referenced definition): ${lat.join(', ') || 'no references indexed'}`,
+        '',
+        '| language | files | calls | bound | exact |',
+        '|---|---|---|---|---|',
+        ...byLang.map(l => `| ${l.lang} | ${l.files} | ${l.calls ?? 0} | ${pct(l.bound ?? 0, l.calls ?? 0)} | ${pct(l.exact ?? 0, l.calls ?? 0)} |`),
+        '',
+        'No paths, names or code are included. For a wrong answer, add the command you ran and what you expected.',
+    ];
+    return out.join('\n');
+}

package/src/query/routes.mjs

@@ -0,0 +1,142 @@
+/**
+ * HTTP routes and the code that handles them: the edge no compiler sees and grep finds only in
+ * pieces (a decorator here, a prefix on the class or router there, the handler named as a value).
+ *
+ * Recognised by the shape frameworks give them, from the indexed source:
+ *   - decorators: FastAPI / Flask (`@app.get("/x")`, `@router.route("/x", methods=[…])`, with the
+ *     prefix of an `APIRouter(prefix=…)` / `Blueprint(url_prefix=…)` defined in the same file),
+ *     NestJS (`@Controller('users')` + `@Get(':id')`), Spring (`@RequestMapping` on the class +
+ *     `@GetMapping("/x")`);
+ *   - registration calls: Express / Fastify / Koa / Hono (`router.post('/x', auth, handler)`), Gin /
+ *     Echo / chi (`r.GET("/x", handler)`) and net/http (`http.HandleFunc("/x", handler)`).
+ * The handler is the decorated definition, or the last argument of the registration call bound
+ * through the index (an inline function is reported by its location).
+ */
+
+const METHODS = 'get|post|put|delete|patch|head|options';
+const PY_ROUTE = new RegExp(`^\\s*@([\\w.]+)\\.(${METHODS}|route|api_route|websocket)\\(\\s*(?:path\\s*=\\s*|rule\\s*=\\s*)?[rbuf]?["']([^"']*)["']([^\\n]*)`, 'i');
+const PY_PREFIX = /^\s*(\w+)\s*=\s*(?:\w+\.)?(APIRouter|Blueprint)\(([^\n]*)/;
+const NEST_CONTROLLER = /@Controller\(\s*(?:\{[^}]*path:\s*)?['"`]([^'"`]*)['"`]/;
+const NEST_ROUTE = /^\s*@(Get|Post|Put|Delete|Patch|All|Head|Options)\(\s*(?:['"`]([^'"`]*)['"`])?\s*\)/;
+const SPRING_CLASS = /^\s*@RequestMapping\(\s*(?:(?:value|path)\s*=\s*)?\{?\s*"([^"]*)"/;
+const SPRING_ROUTE = /^\s*@(Get|Post|Put|Delete|Patch|Request)Mapping(?:\(\s*(?:(?:value|path)\s*=\s*)?\{?\s*"([^"]*)"([^\n]*))?/;
+const JS_CALL = new RegExp(`\\b([\\w$]+)\\.(${METHODS}|all)\\(\\s*['"\`]([^'"\`]+)['"\`]\\s*,([^\\n]*)`);
+const GO_CALL = /\b(\w+)\.(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS|Any|Get|Post|Put|Delete|Patch|HandleFunc|Handle)\(\s*"([^"]+)"\s*,([^\n]*)/;
+
+const HANDLER_KINDS = new Set(['function', 'method']);
+const COMMENT = /^\s*(\/\/|\/?\*|#(?!\s*@)|>>>)/;
+
+/** `/users/{id}`, `/users/:id`, `/users/<int:id>` → one comparable shape: `/users/*`. */
+export function routeShape(p) {
+    return ('/' + String(p).trim().replace(/^\/+/, ''))
+        .replace(/\{[^}]*\}|<[^>]*>|:[A-Za-z_]\w*\??|\*\w*/g, '*')
+        .replace(/\/+$/, '') || '/';
+}
+
+const join = (a, b) => ('/' + [a, b].map(x => String(x ?? '').replace(/^\/+|\/+$/g, '')).filter(Boolean).join('/')) || '/';
+
+/** Every route in the repository: { method, path, file, line, handler (symbol row or null), framework }. */
+export function collectRoutes(intel) {
+    if (intel._routes?.version === intel.ix?.version) return intel._routes.rows;
+    const files = intel.store.all(`SELECT id, path, lang FROM files WHERE is_test = 0 AND lang IN ('python', 'typescript', 'tsx', 'javascript', 'java', 'kotlin', 'go')`);
+    const out = [];
+    for (const f of files) {
+        const lines = intel.fileLines(f.path);
+        if (!lines) continue;
+        const text = lines.join('\n');
+        if (!/(route|get|post|put|delete|patch|Mapping|Controller|HandleFunc|GET|POST)\s*\(/i.test(text)) continue;
+        const defs = intel.store.all(`SELECT id, name, qname, kind, start_line, end_line, parent_id, ? AS path FROM symbols WHERE file_id = ? ORDER BY start_line`, f.path, f.id);
+        const defAfter = (line, span = 12) => defs.find(d => HANDLER_KINDS.has(d.kind) && d.start_line >= line && d.start_line <= line + span) ?? null;
+        // the prefix a class declares in an annotation just above its `class` line (`@Controller('users')`)
+        const classPrefix = (line, re) => {
+            let decl = line - 1;
+            while (decl > 0 && !/\b(class|interface)\s+\w/.test(lines[decl - 1])) decl--;
+            if (decl <= 0) return '';
+            for (let i = decl; i >= Math.max(1, decl - 8); i--) { const m = re.exec(lines[i - 1]); if (m) return m[1]; }
+            return '';
+        };
+        // an annotation is the class's own when the next line that is not an annotation declares the class
+        const onClass = (line) => { let i = line; while (i < lines.length && /^\s*@/.test(lines[i])) i++; return /\b(class|interface)\s+\w/.test(lines[i] ?? ''); };
+        // examples in comments and docstrings are not routes
+        const add = (r) => { if (!COMMENT.test(lines[r.line - 1] ?? '')) out.push({ ...r, file: f.path, shape: routeShape(r.path) }); };
+        if (f.lang === 'python') {
+            const prefixes = new Map();
+            for (const l of lines) {
+                const m = PY_PREFIX.exec(l);
+                if (m) prefixes.set(m[1], /(?:url_)?prefix\s*=\s*["']([^"']*)["']/.exec(m[3])?.[1] ?? '');
+            }
+            lines.forEach((l, i) => {
+                const m = PY_ROUTE.exec(l);
+                if (!m) return;
+                const [, obj, verb, p, rest] = m;
+                const owner = obj.split('.').pop();
+                const methods = verb.toLowerCase() === 'route' || verb.toLowerCase() === 'api_route'
+                    ? (/methods\s*=\s*[[(]([^\])]*)/.exec(rest)?.[1].match(/[A-Za-z]+/g)?.map(x => x.toUpperCase()) ?? ['GET'])
+                    : [verb.toUpperCase() === 'WEBSOCKET' ? 'WS' : verb.toUpperCase()];
+                const h = defAfter(i + 1);
+                for (const method of methods) add({ method, path: join(prefixes.get(owner) ?? '', p), line: i + 1, handler: h, framework: prefixes.has(owner) ? 'router' : 'app' });
+            });
+        } else if (f.lang === 'typescript' || f.lang === 'tsx' || f.lang === 'javascript') {
+            lines.forEach((l, i) => {
+                const n = NEST_ROUTE.exec(l);
+                if (n) {
+                    add({ method: n[1].toUpperCase(), path: join(classPrefix(i + 1, NEST_CONTROLLER), n[2] ?? ''), line: i + 1, handler: defAfter(i + 1, 8), framework: 'nestjs' });
+                    return;
+                }
+                const m = JS_CALL.exec(l);
+                if (!m || !/^\//.test(m[3])) return;
+                add({ method: m[2].toUpperCase() === 'ALL' ? 'ANY' : m[2].toUpperCase(), path: m[3], line: i + 1, handler: handlerArg(intel, f, i + 1, m[4]), framework: 'express' });
+            });
+        } else if (f.lang === 'java' || f.lang === 'kotlin') {
+            lines.forEach((l, i) => {
+                const m = SPRING_ROUTE.exec(l);
+                if (!m) return;
+                // the class-level @RequestMapping is the prefix, not a route
+                if (m[1] === 'Request' && onClass(i + 1)) return;
+                const prefix = classPrefix(i + 1, SPRING_CLASS);
+                const method = m[1] === 'Request' ? (/RequestMethod\.(\w+)/.exec(m[3] ?? '')?.[1] ?? 'ANY') : m[1].toUpperCase();
+                add({ method, path: join(prefix, m[2] ?? ''), line: i + 1, handler: defAfter(i + 1, 8), framework: 'spring' });
+            });
+        } else if (f.lang === 'go') {
+            lines.forEach((l, i) => {
+                const m = GO_CALL.exec(l);
+                if (!m || !m[3].startsWith('/')) return;
+                const verb = m[2];
+                const method = /^Handle/.test(verb) ? 'ANY' : verb.toUpperCase();
+                add({ method, path: m[3], line: i + 1, handler: handlerArg(intel, f, i + 1, m[4]), framework: 'go' });
+            });
+        }
+    }
+    intel._routes = { version: intel.ix?.version, rows: out };
+    return out;
+}
+
+/** The handler of a registration call: its last argument, bound through the index where possible. */
+function handlerArg(intel, f, line, args) {
+    const parts = args.split(',').map(x => x.trim()).filter(Boolean);
+    const last = (parts[parts.length - 1] ?? '').replace(/\)+;?\s*$/, '').trim();
+    const name = /^(?:[\w$]+\.)*([\w$]+)$/.exec(last)?.[1];
+    if (!name) return null; // an inline function: the route's own line is the handler
+    const r = intel.store.get(`SELECT dst_id FROM refs WHERE file_id = ? AND line = ? AND name = ? AND dst_id IS NOT NULL LIMIT 1`, f.id, line, name);
+    const id = r?.dst_id ?? intel.store.get(`SELECT s.id FROM symbols s JOIN files fl ON fl.id = s.file_id WHERE s.name = ? AND s.kind IN ('function', 'method') AND fl.is_test = 0 LIMIT 2`, name)?.id;
+    return id != null ? intel.store.get('SELECT s.id, s.name, s.qname, s.kind, s.start_line, s.end_line, s.parent_id, f.path FROM symbols s JOIN files f ON f.id = s.file_id WHERE s.id = ?', id) : null;
+}
+
+/** Routes in a query (`POST /api/login`, `/users/{id}`): [{ method | null, shape }]. */
+export function routesInQuery(q) {
+    const out = [];
+    const re = /(?:\b(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s+)?(\/[\w\-.{}:<>*~/]*[\w}>*])/gi;
+    for (let m; (m = re.exec(String(q))); ) if (m[2].length > 1) out.push({ method: m[1]?.toUpperCase() ?? null, shape: routeShape(m[2]) });
+    return out;
+}
+
+/** Routes matching a query route: same shape (parameters match anything), and method when given. */
+export function matchRoutes(routes, { method, shape }) {
+    const parts = shape.split('/');
+    const fits = (r) => {
+        const rp = r.shape.split('/');
+        if (rp.length !== parts.length) return false;
+        return rp.every((x, i) => x === '*' || parts[i] === '*' || x.toLowerCase() === parts[i].toLowerCase());
+    };
+    return routes.filter(r => fits(r) && (!method || r.method === method || r.method === 'ANY'));
+}

package/src/query/showcase.mjs

@@ -0,0 +1,59 @@
+/**
+ * The first answer a new user sees, on their own repository: a function or method that shares its
+ * name with other definitions, what a text search for that name returns, and the exact uses the
+ * index binds to that one definition. The contrast is the point of the tool, shown instead of told.
+ */
+import { textSearch } from './textsearch.mjs';
+import { escapeRegExp } from '../util/regex.mjs';
+
+const CALLABLE = ['function', 'method'];
+
+/**
+ * The best example in the repository, or null: a non-test callable with at least 3 bound uses whose
+ * name at least one other callable carries, ranked by its uses and how much same-name text surrounds them.
+ * @returns {Promise<{ sym: object, defs: number, uses: number, useFiles: number, grepLines: number, grepFiles: number } | null>}
+ */
+export async function pickShowcase(intel, { candidates = 8 } = {}) {
+    const ph = CALLABLE.map(() => '?').join(',');
+    const homonyms = new Map(intel.store.all(`SELECT name, COUNT(*) AS n FROM symbols WHERE kind IN (${ph}) AND length(name) >= 3 GROUP BY name HAVING COUNT(*) >= 2`, ...CALLABLE)
+        .map(r => [r.name, r.n]));
+    if (!homonyms.size) return null;
+    const byName = new Map(intel.store.all(`SELECT name, COUNT(*) AS n FROM refs WHERE kind IN ('call', 'new') GROUP BY name`).map(r => [r.name, r.n]));
+    // a class's method or an exported function: what a reader recognises, not a local helper
+    const rows = intel.store.all(`SELECT s.id, s.name, s.qname, s.kind, COUNT(r.id) AS uses, COUNT(DISTINCT r.file_id) AS files
+        FROM symbols s JOIN files f ON f.id = s.file_id JOIN refs r ON r.dst_id = s.id LEFT JOIN symbols p ON p.id = s.parent_id
+        WHERE s.kind IN (${ph}) AND f.is_test = 0 AND r.kind IN ('call', 'new') AND r.conf >= 0.9
+          AND (p.kind IN ('class', 'struct', 'interface', 'trait', 'object', 'impl') OR (s.parent_id IS NULL AND s.exported = 1))
+        GROUP BY s.id HAVING COUNT(r.id) >= 3`, ...CALLABLE)
+        .filter(r => homonyms.has(r.name))
+        .map(r => ({ ...r, others: (byName.get(r.name) ?? 0) - r.uses }))
+        .filter(r => r.others > 0)
+        // most uses drowned in the most same-name noise
+        .sort((a, b) => b.uses * Math.log1p(b.others / b.uses) - a.uses * Math.log1p(a.others / a.uses))
+        .slice(0, candidates);
+    let best = null;
+    for (const r of rows) {
+        const g = await textSearch(intel, { pattern: `\\b${escapeRegExp(r.name)}\\b`, limit: 1 });
+        if (g.error || !g.total) continue;
+        const ex = { sym: intel.sym(r.id), defs: homonyms.get(r.name), uses: r.uses, useFiles: r.files, grepLines: g.total, grepFiles: g.files };
+        const score = (x) => Math.min(x.uses, 40) * Math.log2(x.grepLines / x.uses);
+        if (ex.grepLines >= 2 * ex.uses && (!best || score(ex) > score(best))) best = ex;
+    }
+    return best;
+}
+
+/** The showcase as text, with the command that reproduces it (`cli` names the executable). */
+export async function showcaseText(intel, { cli = 'npx graph-indexer' } = {}) {
+    const st = intel.stats();
+    const ex = await pickShowcase(intel);
+    const head = `Indexed ${st.files} files, ${st.symbols} symbols, ${st.refs} references.`;
+    if (!ex) return `${head}\nNo method here shares its name with another one, so there is no grep-versus-index contrast to show; try \`${cli} explore "<a task in words>"\`.`;
+    const s = ex.sym;
+    return [
+        head,
+        `Example from this repository: ${s.qname} (${s.path}:${s.start_line}) is one of ${ex.defs} definitions named "${s.name}".`,
+        `  grep -w ${s.name}: ${ex.grepLines} lines in ${ex.grepFiles} files to read through`,
+        `  graph-indexer:   ${ex.uses} calls in ${ex.useFiles} file${ex.useFiles === 1 ? '' : 's'}, bound to this definition (scopes, imports, receiver types)`,
+        `See them: ${cli} refs ${s.qname}`,
+    ].join('\n');
+}