dbtour 0.4.0 → 0.5.0

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
+import type { Readable, Writable } from 'node:stream';
 import { type AddonConfig, type SourceConfig } from './config.ts';
 import { type Addon, type Source } from './plugins.ts';
 export interface Io {
@@ -9,5 +10,8 @@ export interface Io {
     load?: (source: SourceConfig) => Promise<Source>;
     /** How an add-on is loaded; tests hand in their own. */
     loadAddon?: (addon: AddonConfig) => Promise<Addon>;
+    /** Where mcp reads requests and writes answers; process.stdin and process.stdout unless a test hands in its own. */
+    stdin?: Readable;
+    stdout?: Writable;
 }
 export declare function main(argv: string[], io?: Io): Promise<number>;

package/dist/cli.js

@@ -8,13 +8,15 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 // The command. Reads dbtour.yaml in the working directory, writes under its `out`. Exit 1 for what was
 // asked and failed, 2 for what is missing, 0 otherwise.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
 import { configFile, defaultConfigText, modelFile, parseConfig, resolveConnection } from "./config.js";
 import { emptyModel, validate } from "./model.js";
 import { applyNotes, parseNotes } from "./notes.js";
+import { answerLine } from "./mcp.js";
 import { loadAddon, loadSource } from "./plugins.js";
 import { renderMarkdown } from "./render/markdown.js";
 const help = `Usage: dbtour <command>
@@ -23,6 +25,8 @@ const help = `Usage: dbtour <command>
   extract                 read every source in ${configFile}, write <out>/${modelFile}
   render                  read <out>/${modelFile} and the notes, write the Markdown and what the
                           add-ons in ${configFile} render (explorer: index.html) under <out>
+  mcp [project]           answer an agent's questions about <out>/${modelFile} and the notes over MCP,
+                          on stdin and stdout: claude mcp add dbtour -- npx dbtour mcp
 
 Set the connection string in the environment variable ${configFile} names, never in the file.`;
 export async function main(argv, io = { cwd: process.cwd(), log: console.log, error: console.error }) {
@@ -40,6 +44,8 @@ export async function main(argv, io = { cwd: process.cwd(), log: console.log, er
                 return await extract(io);
             case 'render':
                 return await render(io);
+            case 'mcp':
+                return await mcp(positionals[1] === undefined ? io : { ...io, cwd: resolve(io.cwd, positionals[1]) });
             default:
                 io.error(`"${command}" is not a dbtour command.\n\n${help}`);
                 return 1;
@@ -113,24 +119,25 @@ async function extract(io) {
 function importer(cwd) {
     return (specifier) => import(__rewriteRelativeImportExtension(specifier.startsWith('.') || specifier.startsWith('/') ? pathToFileURL(resolve(cwd, specifier)).href : specifier));
 }
-async function render(io) {
-    const config = readConfig(io);
+/** <out>/schema.json with the notes merged in, as render and mcp read it. */
+function readModel(io, config) {
     const modelPath = join(io.cwd, config.out, modelFile);
     if (!existsSync(modelPath))
         throw missing(`No ${join(config.out, modelFile)} yet. Run dbtour extract to write it.`);
     const checked = validate(JSON.parse(readFileSync(modelPath, 'utf8')));
-    if (!checked.ok) {
-        io.error(`${join(config.out, modelFile)} is not a model:\n  ${checked.errors.join('\n  ')}`);
-        return 1;
-    }
-    let model = checked.model;
+    if (!checked.ok)
+        throw new Error(`${join(config.out, modelFile)} is not a model:\n  ${checked.errors.join('\n  ')}`);
     const notesPath = join(io.cwd, config.notes);
-    if (existsSync(notesPath)) {
-        const applied = applyNotes(model, parseNotes(readFileSync(notesPath, 'utf8')));
-        for (const warning of applied.warnings)
-            io.error(warning);
-        model = applied.model;
-    }
+    if (!existsSync(notesPath))
+        return checked.model;
+    const applied = applyNotes(checked.model, parseNotes(readFileSync(notesPath, 'utf8')));
+    for (const warning of applied.warnings)
+        io.error(warning);
+    return applied.model;
+}
+async function render(io) {
+    const config = readConfig(io);
+    let model = readModel(io, config);
     // Every add-on is loaded before anything is written, so a missing one stops the run with nothing half done.
     const load = io.loadAddon ?? ((addon) => loadAddon(addon, importer(io.cwd)));
     const addons = [];
@@ -157,3 +164,31 @@ async function render(io) {
     io.log(`Wrote ${Object.keys(files).length} files to ${config.out}.`);
     return 0;
 }
+/**
+ * Serves the model to an agent until stdin closes. Read once now, so a missing model stops it with the
+ * command to run, then again whenever schema.json or the notes change, so a render while the agent is
+ * connected is seen at its next question. Everything but answers goes to stderr: stdout is the protocol.
+ */
+async function mcp(io) {
+    const config = readConfig(io);
+    const files = [join(io.cwd, config.out, modelFile), join(io.cwd, config.notes)];
+    const stamp = () => files.map((f) => (existsSync(f) ? statSync(f).mtimeMs : 0)).join();
+    let model = readModel(io, config);
+    let read = stamp();
+    const current = () => {
+        const now = stamp();
+        if (now !== read) {
+            model = readModel(io, config);
+            read = now;
+        }
+        return model;
+    };
+    const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    const output = io.stdout ?? process.stdout;
+    for await (const line of createInterface({ input: io.stdin ?? process.stdin, crlfDelay: Infinity })) {
+        const reply = answerLine(line, { model: current, version });
+        if (reply !== undefined)
+            output.write(reply + '\n');
+    }
+    return 0;
+}

package/dist/mcp.d.ts

@@ -0,0 +1,33 @@
+import { type Model } from './model.ts';
+export declare const protocolVersions: string[];
+export declare const overviewLimit = 100;
+export interface Context {
+    /** The model with its notes, read again when the files change; throws when there is none. */
+    model: () => Model;
+    version: string;
+}
+export interface ToolResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: boolean;
+}
+export declare const toolList: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+    };
+}[];
+/** One line in, at most one line out: a notification and a blank line get none. */
+export declare function answerLine(line: string, context: Context): string | undefined;
+export declare function answer(message: unknown, context: Context): object | undefined;
+export declare function callTool(model: Model, name: string, args: Record<string, unknown>): ToolResult;

package/dist/mcp.js

@@ -0,0 +1,320 @@
+// The model over the Model Context Protocol, so an agent such as Claude asks about the database (find a
+// table, read it, join two) instead of being handed all of it. JSON-RPC, one message per line; written here
+// rather than taken from the SDK, since four methods are all it needs and core keeps its one dependency.
+// Read-only and structure only, like the model: there are no rows to give.
+import { findTable, tableRef } from "./model.js";
+import { driverName, formatCount, renderTableMarkdown } from "./render/markdown.js";
+import { buildIndex, search } from "./search.js";
+// The versions this server speaks, newest first. It uses only initialize, ping, tools/list and tools/call,
+// which none of them changed, so it agrees to whichever the client asks for and offers the newest otherwise.
+export const protocolVersions = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+// Above this many tables the overview lists the largest and leaves the rest to search: a list of thousands
+// would spend the agent's context on tables the question is not about.
+export const overviewLimit = 100;
+// Enough hits to choose from without reading past the good ones; the agent can ask for up to the maximum.
+const searchDefault = 20;
+const searchMaximum = 100;
+const instructions = `dbtour knows the structure of this project's databases: tables, views, columns, keys, relations, indexes and the descriptions people wrote. It never holds rows. Start with overview for the databases and their largest tables; search finds a table or column by any part of its name or description; table gives one table's columns, keys and relations as Markdown; path gives the joins between two tables. Name tables as schema.table, and read a table before writing SQL against it.`;
+const readOnly = { readOnlyHint: true, openWorldHint: false };
+export const toolList = [
+    {
+        name: 'overview',
+        title: 'Overview',
+        description: `The databases, how many tables and relations each has, and their tables largest first by rows (all of them up to ${overviewLimit}), with the groups people defined. Call it first, to know what there is.`,
+        inputSchema: { type: 'object', properties: {}, required: [] },
+        annotations: readOnly,
+    },
+    {
+        name: 'search',
+        title: 'Search',
+        description: 'Find tables, views, columns and groups by any part of their name, type or description. Every word must match. Use it to find where something is kept before reading the table.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Words to look for, like "customer email".' },
+                limit: { type: 'integer', minimum: 1, maximum: searchMaximum, default: searchDefault },
+            },
+            required: ['query'],
+        },
+        annotations: readOnly,
+    },
+    {
+        name: 'table',
+        title: 'Table',
+        description: 'One table or view as Markdown: its columns with types, keys and descriptions, the relations both ways, indexes, constraints, a view\'s SQL and a diagram of its neighbours. Read it before writing SQL against the table.',
+        inputSchema: {
+            type: 'object',
+            properties: { ref: { type: 'string', description: 'schema.table, like dbo.Orders. A bare name works when only one schema has it.' } },
+            required: ['ref'],
+        },
+        annotations: readOnly,
+    },
+    {
+        name: 'path',
+        title: 'Join path',
+        description: 'The shortest chain of relations between two tables, written as the JOINs that follow them, through any tables between. Use it to join tables that are not related directly.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                from: { type: 'string', description: 'The table to start from, schema.table.' },
+                to: { type: 'string', description: 'The table to reach, schema.table.' },
+            },
+            required: ['from', 'to'],
+        },
+        annotations: readOnly,
+    },
+];
+const toolNames = toolList.map((t) => t.name);
+/** One line in, at most one line out: a notification and a blank line get none. */
+export function answerLine(line, context) {
+    if (line.trim() === '')
+        return undefined;
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        return JSON.stringify(failure(null, -32700, 'That line is not JSON: send one JSON-RPC message per line.'));
+    }
+    const response = answer(message, context);
+    return response === undefined ? undefined : JSON.stringify(response);
+}
+export function answer(message, context) {
+    if (typeof message !== 'object' || message === null || Array.isArray(message))
+        return failure(null, -32600, 'Send one JSON-RPC request as an object; batches are not accepted.');
+    const request = message;
+    // An id that is neither a string nor a number cannot be echoed back, so its error carries null.
+    const validId = typeof request.id === 'string' || typeof request.id === 'number';
+    const id = validId ? request.id : null;
+    if (request.jsonrpc !== '2.0')
+        return failure(id, -32600, 'A request must say "jsonrpc": "2.0".');
+    if (typeof request.method !== 'string')
+        return failure(id, -32600, 'A request needs a method.');
+    // A notification wants no answer, whatever it says.
+    if (!('id' in request))
+        return undefined;
+    if (!validId)
+        return failure(null, -32600, 'A request id must be a string or a number.');
+    const params = typeof request.params === 'object' && request.params !== null ? request.params : {};
+    switch (request.method) {
+        case 'initialize': {
+            const asked = params.protocolVersion;
+            return success(id, {
+                protocolVersion: typeof asked === 'string' && protocolVersions.includes(asked) ? asked : protocolVersions[0],
+                capabilities: { tools: {} },
+                serverInfo: { name: 'dbtour', version: context.version },
+                instructions,
+            });
+        }
+        case 'ping':
+            return success(id, {});
+        case 'tools/list':
+            return success(id, { tools: toolList });
+        case 'tools/call': {
+            const name = params.name;
+            if (typeof name !== 'string' || !toolNames.includes(name))
+                return failure(id, -32602, `There is no tool "${String(name)}": the tools are ${toolNames.join(', ')}.`);
+            const args = typeof params.arguments === 'object' && params.arguments !== null ? params.arguments : {};
+            let model;
+            try {
+                model = context.model();
+            }
+            catch (error) {
+                return success(id, problem(error instanceof Error ? error.message : String(error)));
+            }
+            return success(id, callTool(model, name, args));
+        }
+        default:
+            return failure(id, -32601, `dbtour does not answer ${request.method}: it offers tools only.`);
+    }
+}
+function success(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function failure(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+function text(value) {
+    return { content: [{ type: 'text', text: value }] };
+}
+/** A failed call goes back to the agent as text it can act on, not as a protocol error. */
+function problem(value) {
+    return { content: [{ type: 'text', text: value }], isError: true };
+}
+export function callTool(model, name, args) {
+    switch (name) {
+        case 'overview':
+            return text(overview(model));
+        case 'search': {
+            if (typeof args.query !== 'string' || args.query.trim() === '')
+                return problem('search needs a query: the words to look for, like "customer email".');
+            const limit = typeof args.limit === 'number' ? Math.min(Math.max(1, Math.floor(args.limit)), searchMaximum) : searchDefault;
+            return text(searchText(model, args.query, limit));
+        }
+        case 'table': {
+            if (typeof args.ref !== 'string')
+                return problem('table needs a ref: schema.table, like dbo.Orders.');
+            const found = resolve(model, args.ref);
+            return 'problem' in found ? problem(found.problem) : text(renderTableMarkdown(model, found.ref));
+        }
+        case 'path': {
+            if (typeof args.from !== 'string' || typeof args.to !== 'string')
+                return problem('path needs from and to: two tables as schema.table.');
+            const from = resolve(model, args.from);
+            if ('problem' in from)
+                return problem(from.problem);
+            const to = resolve(model, args.to);
+            if ('problem' in to)
+                return problem(to.problem);
+            return text(pathText(model, from.ref, to.ref));
+        }
+        default:
+            return problem(`There is no tool "${name}": the tools are ${toolNames.join(', ')}.`);
+    }
+}
+function plural(n, one, many) {
+    return `${formatCount(n)} ${n === 1 ? one : many}`;
+}
+function overview(model) {
+    const parts = [];
+    for (const database of model.databases)
+        parts.push(overviewOf(database));
+    for (const group of model.groups) {
+        parts.push(`## ${group.name}\n`);
+        if (group.description)
+            parts.push(`${group.description}\n`);
+        parts.push(`${group.tables.join(', ')}\n`);
+    }
+    parts.push('Read a table with table, find one with search, join two with path.');
+    return parts.join('\n');
+}
+function overviewOf(database) {
+    const entries = database.schemas.flatMap((s) => s.tables.map((table) => ({ ref: tableRef(s.name, table.name), table })));
+    const sized = entries.some((e) => e.table.stats);
+    // Largest first, so the tables everything hangs off come before the lookups; a view or a table the source
+    // could not count keeps its catalogue place after them. Array.sort is stable, which keeps that order.
+    const ordered = sized ? [...entries].sort((a, b) => (b.table.stats?.rows ?? -1) - (a.table.stats?.rows ?? -1)) : entries;
+    const parts = [`# ${database.name}\n`];
+    if (database.description)
+        parts.push(`${database.description}\n`);
+    const driver = database.version ? `${driverName(database.driver)} ${database.version}` : driverName(database.driver);
+    parts.push(`${driver}. ${plural(entries.length, 'table or view', 'tables and views')} in ${plural(database.schemas.length, 'schema', 'schemas')}, ${plural(database.relations.length, 'relation', 'relations')}.\n`);
+    if (sized)
+        parts.push(`Largest first, by the rows the database counted${database.statsReadAt ? ` on ${database.statsReadAt.slice(0, 10)}` : ''}; its own estimate.\n`);
+    parts.push(sized ? '| Table | Kind | Columns | Rows | Description |\n|---|---|---|---|---|' : '| Table | Kind | Columns | Description |\n|---|---|---|---|');
+    for (const { ref, table } of ordered.slice(0, overviewLimit)) {
+        const rows = !sized ? '' : ` ${table.stats ? formatCount(table.stats.rows) : ''} |`;
+        parts.push(`| ${ref} | ${table.kind} | ${table.columns.length} |${rows} ${(table.description ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ')} |`);
+    }
+    if (entries.length > overviewLimit)
+        parts.push(`\n${formatCount(entries.length - overviewLimit)} more: search finds them.`);
+    parts.push('');
+    return parts.join('\n');
+}
+const indexes = new WeakMap();
+function hitsFor(model, query, limit) {
+    let index = indexes.get(model);
+    if (!index) {
+        index = buildIndex(model);
+        indexes.set(model, index);
+    }
+    return search(index, query, limit);
+}
+function searchText(model, query, limit) {
+    const hits = hitsFor(model, query, limit);
+    if (hits.length === 0)
+        return `Nothing matches "${query}". Every word must match: try fewer words, or part of a name.`;
+    return hits.map((h) => `- ${h.kind} ${h.title}: ${h.detail}`).join('\n');
+}
+/** What an agent wrote, as the table it means: exact, then ignoring case, then a bare name in one schema. */
+function resolve(model, written) {
+    const parts = written.trim().split('.');
+    // schema.table.column is the table; a bare name is looked up by name alone.
+    const wanted = parts.length === 3 ? parts.slice(0, 2).join('.') : parts.join('.');
+    if (parts.length >= 2 && parts.length <= 3 && !parts.includes('') && findTable(model, wanted))
+        return { ref: wanted };
+    const all = model.databases.flatMap((d) => d.schemas.flatMap((s) => s.tables.map((t) => tableRef(s.name, t.name))));
+    const lower = wanted.toLowerCase();
+    const matches = [...new Set(all)].filter((ref) => ref.toLowerCase() === lower || (!lower.includes('.') && ref.slice(ref.indexOf('.') + 1).toLowerCase() === lower));
+    if (matches.length === 1)
+        return { ref: matches[0] };
+    if (matches.length > 1)
+        return { problem: `${matches.slice(0, -1).join(', ')} and ${matches.at(-1)} are ${matches.length === 2 ? 'both' : 'all'} called ${wanted}: ask for one as schema.table.` };
+    const name = wanted.slice(wanted.lastIndexOf('.') + 1);
+    const near = [...new Set(hitsFor(model, name, searchDefault).filter((h) => h.kind === 'table' || h.kind === 'view').map((h) => h.ref))].slice(0, 5);
+    return { problem: `"${written}" is not a table. ${near.length > 0 ? `Did you mean ${near.join(', ')}?` : 'overview lists them, and search finds one by any part of its name.'}` };
+}
+/** The databases that have a table of this name: refs carry no database, so two can share one. */
+function databasesWith(model, ref) {
+    return model.databases.filter((d) => d.schemas.some((s) => s.tables.some((t) => tableRef(s.name, t.name) === ref)));
+}
+// Each database quotes names its own way: brackets in SQL Server, backticks in MySQL, the standard double
+// quotes elsewhere. Every name is quoted, since a reserved word (User, Order) or a space breaks a bare one,
+// and the closing quote inside a name is doubled.
+function quote(driver, name) {
+    if (driver === 'mssql')
+        return `[${name.replace(/]/g, ']]')}]`;
+    if (driver === 'mysql')
+        return `\`${name.replace(/`/g, '``')}\``;
+    return `"${name.replace(/"/g, '""')}"`;
+}
+function quoteRef(driver, ref, column) {
+    const dot = ref.indexOf('.');
+    const names = [ref.slice(0, dot), ref.slice(dot + 1), ...(column === undefined ? [] : [column])];
+    return names.map((name) => quote(driver, name)).join('.');
+}
+function pathText(model, from, to) {
+    if (from === to)
+        return `${from} is the same table at both ends: no join is needed.`;
+    // Relations stay inside their database, so the search runs in each database that has both tables.
+    const toDatabases = databasesWith(model, to);
+    const shared = databasesWith(model, from).filter((d) => toDatabases.includes(d));
+    if (shared.length === 0) {
+        const names = (ref) => databasesWith(model, ref).map((d) => d.name).join(' and ');
+        return `${from} is in ${names(from)} and ${to} in ${names(to)}: relations do not cross databases, so no join connects them.`;
+    }
+    let best;
+    for (const database of shared) {
+        const steps = shortestPath(database.relations, from, to);
+        if (steps && (!best || steps.length < best.steps.length))
+            best = { database, steps };
+    }
+    if (!best) {
+        return `No relation connects ${from} and ${to}, declared or in the notes. If they are related all the same, add the relation to dbtour.notes.yaml so the docs and this path know it.`;
+    }
+    const { driver } = best.database;
+    const lines = [`FROM ${quoteRef(driver, from)}`];
+    let at = from;
+    for (const step of best.steps) {
+        const mine = step.forward ? step.relation.to.columns : step.relation.from.columns;
+        const theirs = step.forward ? step.relation.from.columns : step.relation.to.columns;
+        const on = mine.map((column, i) => `${quoteRef(driver, step.table, column)} = ${quoteRef(driver, at, theirs[i] ?? theirs[0])}`).join(' AND ');
+        lines.push(`JOIN ${quoteRef(driver, step.table)} ON ${on}${step.relation.virtual ? ' -- from the notes, not a declared key' : ''}`);
+        at = step.table;
+    }
+    const where = model.databases.length > 1 ? `In ${best.database.name}, ` : '';
+    return `${where}${from} to ${to}: ${plural(best.steps.length, 'join', 'joins')}.\n\n\`\`\`sql\n${lines.join('\n')}\n\`\`\`\n\nEach JOIN follows a relation as the docs record it; read the tables to choose the columns and whether a LEFT JOIN suits.`;
+}
+/** Breadth first over one database's relations both ways, so the first path found is a shortest one. */
+function shortestPath(relations, from, to) {
+    const reached = new Map([[from, []]]);
+    const queue = [from];
+    while (queue.length > 0) {
+        const at = queue.shift();
+        const path = reached.get(at);
+        for (const relation of relations) {
+            // A table that references itself leads nowhere new.
+            if (relation.from.table === relation.to.table)
+                continue;
+            const step = relation.from.table === at ? { relation, table: relation.to.table, forward: true } : relation.to.table === at ? { relation, table: relation.from.table, forward: false } : undefined;
+            if (!step || reached.has(step.table))
+                continue;
+            const next = [...path, step];
+            if (step.table === to)
+                return next;
+            reached.set(step.table, next);
+            queue.push(step.table);
+        }
+    }
+    return undefined;
+}

package/dist/search.d.ts

@@ -0,0 +1,18 @@
+import { type Model } from './model.ts';
+export interface Hit {
+    kind: 'table' | 'view' | 'column' | 'group';
+    /** schema.table for a table or column, the group's name for a group. */
+    ref: string;
+    column?: string;
+    title: string;
+    detail: string;
+    score: number;
+}
+export interface Entry extends Omit<Hit, 'score'> {
+    /** Lower-cased name, where a prefix match counts most. */
+    name: string;
+    /** Lower-cased ref and description, where any match counts. */
+    text: string;
+}
+export declare function buildIndex(model: Model): Entry[];
+export declare function search(index: Entry[], query: string, limit?: number): Hit[];

package/dist/search.js

@@ -0,0 +1,64 @@
+// Search over tables, columns and groups: built once from the model, queried on every keystroke of the page
+// and by an agent through the MCP server.
+import { tableRef } from "./model.js";
+export function buildIndex(model) {
+    const entries = [];
+    for (const database of model.databases) {
+        for (const schema of database.schemas) {
+            for (const table of schema.tables) {
+                const ref = tableRef(schema.name, table.name);
+                entries.push({
+                    kind: table.kind,
+                    ref,
+                    title: ref,
+                    detail: table.description ?? `${table.columns.length} ${table.columns.length === 1 ? 'column' : 'columns'}`,
+                    name: table.name.toLowerCase(),
+                    text: `${ref} ${table.description ?? ''}`.toLowerCase(),
+                });
+                for (const column of table.columns) {
+                    entries.push({
+                        kind: 'column',
+                        ref,
+                        column: column.name,
+                        title: `${ref}.${column.name}`,
+                        detail: column.description ?? column.type,
+                        name: column.name.toLowerCase(),
+                        text: `${ref}.${column.name} ${column.type} ${column.description ?? ''}`.toLowerCase(),
+                    });
+                }
+            }
+        }
+    }
+    for (const group of model.groups) {
+        entries.push({ kind: 'group', ref: group.name, title: group.name, detail: group.description ?? `${group.tables.length} tables`, name: group.name.toLowerCase(), text: `${group.name} ${group.description ?? ''}`.toLowerCase() });
+    }
+    return entries;
+}
+// How well the words match comes first: a name that starts with the word beats one that contains it,
+// which beats a match in the description. Among equal matches a table comes before a group, then a column,
+// so typing a table's name finds the table and typing a column's name finds the column.
+const kindWeight = { table: 3, view: 3, group: 2, column: 1 };
+const prefixScore = 3;
+const nameScore = 2;
+const textScore = 1;
+export function search(index, query, limit = 50) {
+    const words = query.toLowerCase().split(/\s+/).filter((w) => w !== '');
+    if (words.length === 0)
+        return [];
+    const hits = [];
+    for (const entry of index) {
+        let score = 0;
+        for (const word of words) {
+            const wordScore = entry.name.startsWith(word) ? prefixScore : entry.name.includes(word) ? nameScore : entry.text.includes(word) ? textScore : 0;
+            if (wordScore === 0) {
+                score = 0;
+                break;
+            }
+            score += wordScore;
+        }
+        if (score > 0)
+            hits.push({ kind: entry.kind, ref: entry.ref, column: entry.column, title: entry.title, detail: entry.detail, score });
+    }
+    hits.sort((a, b) => b.score - a.score || kindWeight[b.kind] - kindWeight[a.kind] || a.title.length - b.title.length || a.title.localeCompare(b.title));
+    return hits.slice(0, limit);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbtour",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Tour your database and its API: searchable docs, relations and diagrams, generated from the schema, kept in the repo.",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,10 @@
     "./markdown": {
       "types": "./dist/render/markdown.d.ts",
       "default": "./dist/render/markdown.js"
+    },
+    "./search": {
+      "types": "./dist/search.d.ts",
+      "default": "./dist/search.js"
     }
   },
   "files": [