dbtour 0.3.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;
@@ -89,6 +95,9 @@ async function extract(io) {
             model.databases.push(result);
             const tables = result.schemas.reduce((n, s) => n + s.tables.length, 0);
             io.log(`${result.name}: ${tables} tables, ${result.relations.length} relations`);
+            // Not a failure: the rest was read, and an absence the model records is not taken for a no.
+            for (const reason of result.unread ?? [])
+                io.log(`${result.name}: not read: ${reason}. Grant it to read them, or leave them out.`);
         }
         else {
             model.apis.push(result);
@@ -110,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 = [];
@@ -154,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/model.d.ts

@@ -1,4 +1,15 @@
 export declare const MODEL_VERSION = 1;
+/**
+ * Extended properties other than MS_Description (which is `description`), by name: what a team records about
+ * an object in the database itself, such as its owner, source or retention.
+ */
+export type Properties = Record<string, string>;
+/** A column's sensitivity classification, as SQL Server's data discovery or a team set it. */
+export interface Sensitivity {
+    label?: string;
+    informationType?: string;
+    rank?: string;
+}
 export interface Column {
     name: string;
     /** As the database spells it, with its size: nvarchar(320), decimal(18,2). */
@@ -8,19 +19,62 @@ export interface Column {
     /** The expression of a computed column. */
     computed?: string;
     identity?: boolean;
+    /** An identity's seed and increment, as the database spells them. */
+    identitySeed?: string;
+    identityIncrement?: string;
     description?: string;
+    /** Only where it differs from the database's collation. */
+    collation?: string;
+    sparse?: boolean;
+    /** The dynamic data masking function: default(), email(), partial(2,"XX",0). */
+    masked?: string;
+    /** Always Encrypted: how, and under which column encryption key. */
+    encrypted?: {
+        type: 'deterministic' | 'randomized';
+        key: string;
+    };
+    sensitivity?: Sensitivity;
+    properties?: Properties;
 }
 export interface Index {
     name: string;
     columns: string[];
     unique: boolean;
     included?: string[];
+    /** As the database names the kind: nonclustered, clustered columnstore, xml, spatial. */
+    type?: string;
+    /** A filtered index's WHERE. */
+    filter?: string;
+    disabled?: boolean;
+    properties?: Properties;
 }
 export interface Constraint {
     name: string;
     kind: 'primary' | 'unique' | 'check' | 'foreign';
     columns: string[];
     definition?: string;
+    /** A foreign key or check the database no longer enforces. */
+    disabled?: boolean;
+    /** Enforced, but not checked against the rows already there, so the optimiser cannot rely on it. */
+    untrusted?: boolean;
+    properties?: Properties;
+}
+export interface Trigger {
+    name: string;
+    timing: 'after' | 'instead of';
+    /** insert, update, delete. */
+    events: string[];
+    enabled: boolean;
+    definition?: string;
+}
+/** A row-level security predicate on the table: a filter hides rows, a block refuses writes. */
+export interface SecurityPredicate {
+    policy: string;
+    kind: 'filter' | 'block';
+    /** For a block predicate: after insert, before update, and so on. */
+    operation?: string;
+    predicate: string;
+    enabled: boolean;
 }
 /**
  * How big a table is, as the database keeps it about itself: counted from its catalogue, never by reading
@@ -44,10 +98,37 @@ export interface Table {
     /** The SQL of a view. */
     definition?: string;
     stats?: TableStats;
+    properties?: Properties;
+    /** When the table was created and its definition last altered, as ISO timestamps. */
+    created?: string;
+    altered?: string;
+    /** A system-versioned table: its history table (a ref) and the columns that bound each row's period. */
+    temporal?: {
+        history: string;
+        start: string;
+        end: string;
+    };
+    /** The history table of a system-versioned table, as its ref. */
+    historyOf?: string;
+    memoryOptimised?: 'schema and data' | 'schema only';
+    ledger?: 'updatable' | 'append-only' | 'history';
+    partitioning?: {
+        scheme: string;
+        function: string;
+        column: string;
+        partitions: number;
+    };
+    /** The table's own compression, when it has any: row, page, columnstore, columnstore archive. */
+    compression?: string;
+    changeTracking?: boolean;
+    cdc?: boolean;
+    triggers?: Trigger[];
+    security?: SecurityPredicate[];
 }
 export interface Schema {
     name: string;
     tables: Table[];
+    properties?: Properties;
 }
 export interface RelationEnd {
     table: string;
@@ -61,6 +142,9 @@ export interface Relation {
     virtual?: boolean;
     onDelete?: string;
     onUpdate?: string;
+    /** As on its constraint: not enforced, or not checked against the rows already there. */
+    disabled?: boolean;
+    untrusted?: boolean;
 }
 export interface Database {
     name: string;
@@ -69,6 +153,11 @@ export interface Database {
     description?: string;
     /** When the source read its tables' stats, as an ISO timestamp: they change, so they carry their moment. */
     statsReadAt?: string;
+    /** The default collation; a column says its own only where it differs. */
+    collation?: string;
+    properties?: Properties;
+    /** What the source could not read and why, so a reader knows an absence is not a no. */
+    unread?: string[];
     schemas: Schema[];
     relations: Relation[];
 }

package/dist/model.js

@@ -114,10 +114,15 @@ function checkDatabase(check, d, p) {
     check.optionalString(d.version, `${p}.version`);
     check.optionalString(d.description, `${p}.description`);
     check.optionalString(d.statsReadAt, `${p}.statsReadAt`);
+    check.optionalString(d.collation, `${p}.collation`);
+    check.properties(d.properties, `${p}.properties`);
+    if (d.unread !== undefined)
+        check.strings(d.unread, `${p}.unread`);
     check.list(d.schemas, `${p}.schemas`, (s, sp) => {
         if (!check.object(s, sp))
             return;
         check.string(s.name, `${sp}.name`);
+        check.properties(s.properties, `${sp}.properties`);
         check.list(s.tables, `${sp}.tables`, (t, tp) => checkTable(check, t, tp));
     });
     check.list(d.relations, `${p}.relations`, (r, rp) => {
@@ -132,6 +137,8 @@ function checkDatabase(check, d, p) {
             check.strings(e.columns, `${rp}.${end}.columns`);
         }
         check.optionalBoolean(r.virtual, `${rp}.virtual`);
+        check.optionalBoolean(r.disabled, `${rp}.disabled`);
+        check.optionalBoolean(r.untrusted, `${rp}.untrusted`);
     });
 }
 function checkTable(check, t, p) {
@@ -148,6 +155,7 @@ function checkTable(check, t, p) {
     }
     if (t.primaryKey !== undefined)
         check.strings(t.primaryKey, `${p}.primaryKey`);
+    checkCatalogue(check, t, p);
     check.list(t.columns, `${p}.columns`, (c, cp) => {
         if (!check.object(c, cp))
             return;
@@ -159,6 +167,18 @@ function checkTable(check, t, p) {
         check.optionalString(c.computed, `${cp}.computed`);
         check.optionalBoolean(c.identity, `${cp}.identity`);
         check.optionalString(c.description, `${cp}.description`);
+        for (const field of ['identitySeed', 'identityIncrement', 'collation', 'masked'])
+            check.optionalString(c[field], `${cp}.${field}`);
+        check.optionalBoolean(c.sparse, `${cp}.sparse`);
+        check.properties(c.properties, `${cp}.properties`);
+        if (c.encrypted !== undefined && check.object(c.encrypted, `${cp}.encrypted`)) {
+            check.oneOf(c.encrypted.type, ['deterministic', 'randomized'], `${cp}.encrypted.type`);
+            check.string(c.encrypted.key, `${cp}.encrypted.key`);
+        }
+        if (c.sensitivity !== undefined && check.object(c.sensitivity, `${cp}.sensitivity`)) {
+            for (const field of ['label', 'informationType', 'rank'])
+                check.optionalString(c.sensitivity[field], `${cp}.sensitivity.${field}`);
+        }
     });
     check.list(t.indexes, `${p}.indexes`, (x, xp) => {
         if (!check.object(x, xp))
@@ -167,6 +187,10 @@ function checkTable(check, t, p) {
         check.strings(x.columns, `${xp}.columns`);
         if (typeof x.unique !== 'boolean')
             check.errors.push(`${xp}.unique must be true or false`);
+        check.optionalString(x.type, `${xp}.type`);
+        check.optionalString(x.filter, `${xp}.filter`);
+        check.optionalBoolean(x.disabled, `${xp}.disabled`);
+        check.properties(x.properties, `${xp}.properties`);
     });
     check.list(t.constraints, `${p}.constraints`, (c, cp) => {
         if (!check.object(c, cp))
@@ -176,8 +200,56 @@ function checkTable(check, t, p) {
             check.errors.push(`${cp}.kind is not a constraint kind`);
         check.strings(c.columns, `${cp}.columns`);
         check.optionalString(c.definition, `${cp}.definition`);
+        check.optionalBoolean(c.disabled, `${cp}.disabled`);
+        check.optionalBoolean(c.untrusted, `${cp}.untrusted`);
+        check.properties(c.properties, `${cp}.properties`);
     });
 }
+/** What the catalogue says about a table beyond its columns, keys and indexes. */
+function checkCatalogue(check, t, p) {
+    check.properties(t.properties, `${p}.properties`);
+    for (const field of ['created', 'altered', 'historyOf', 'compression'])
+        check.optionalString(t[field], `${p}.${field}`);
+    for (const field of ['changeTracking', 'cdc'])
+        check.optionalBoolean(t[field], `${p}.${field}`);
+    if (t.memoryOptimised !== undefined)
+        check.oneOf(t.memoryOptimised, ['schema and data', 'schema only'], `${p}.memoryOptimised`);
+    if (t.ledger !== undefined)
+        check.oneOf(t.ledger, ['updatable', 'append-only', 'history'], `${p}.ledger`);
+    if (t.temporal !== undefined && check.object(t.temporal, `${p}.temporal`)) {
+        for (const field of ['history', 'start', 'end'])
+            check.string(t.temporal[field], `${p}.temporal.${field}`);
+    }
+    if (t.partitioning !== undefined && check.object(t.partitioning, `${p}.partitioning`)) {
+        for (const field of ['scheme', 'function', 'column'])
+            check.string(t.partitioning[field], `${p}.partitioning.${field}`);
+        check.count(t.partitioning.partitions, `${p}.partitioning.partitions`);
+    }
+    if (t.triggers !== undefined) {
+        check.list(t.triggers, `${p}.triggers`, (g, gp) => {
+            if (!check.object(g, gp))
+                return;
+            check.string(g.name, `${gp}.name`);
+            check.oneOf(g.timing, ['after', 'instead of'], `${gp}.timing`);
+            check.strings(g.events, `${gp}.events`);
+            if (typeof g.enabled !== 'boolean')
+                check.errors.push(`${gp}.enabled must be true or false`);
+            check.optionalString(g.definition, `${gp}.definition`);
+        });
+    }
+    if (t.security !== undefined) {
+        check.list(t.security, `${p}.security`, (r, rp) => {
+            if (!check.object(r, rp))
+                return;
+            check.string(r.policy, `${rp}.policy`);
+            check.oneOf(r.kind, ['filter', 'block'], `${rp}.kind`);
+            check.optionalString(r.operation, `${rp}.operation`);
+            check.string(r.predicate, `${rp}.predicate`);
+            if (typeof r.enabled !== 'boolean')
+                check.errors.push(`${rp}.enabled must be true or false`);
+        });
+    }
+}
 class Checker {
     errors;
     constructor(errors) {
@@ -201,6 +273,18 @@ class Checker {
         if (value !== undefined && typeof value !== 'boolean')
             this.errors.push(`${path} must be true or false when given`);
     }
+    properties(value, path) {
+        if (value === undefined || !this.object(value, path))
+            return;
+        for (const [name, text] of Object.entries(value)) {
+            if (typeof text !== 'string')
+                this.errors.push(`${path}.${name} must be a string`);
+        }
+    }
+    oneOf(value, allowed, path) {
+        if (!allowed.includes(value))
+            this.errors.push(`${path} must be ${allowed.map((a) => `"${a}"`).join(' or ')}`);
+    }
     count(value, path) {
         if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
             this.errors.push(`${path} must be a number of 0 or more`);

package/dist/render/markdown.d.ts

@@ -1,8 +1,17 @@
-import { findTable, type Model, type TableStats } from '../model.ts';
+import { findTable, type Model, type Table, type TableStats } from '../model.ts';
 export declare const wholeDiagramLimit = 40;
 export declare function renderMarkdown(model: Model): Record<string, string>;
 /** The product's name for a driver: mssql is SQL Server. */
 export declare function driverName(driver: string): string;
+/** A thing the catalogue says about a table beyond its columns and keys: a name, and its particulars. */
+export interface Feature {
+    name: string;
+    detail?: string;
+    /** A table the detail names, for a link. */
+    ref?: string;
+}
+/** What the catalogue says about a table beyond its columns and keys, in the order a reader weighs it. */
+export declare function features(table: Table): Feature[];
 /** 1,204,377: thousands grouped the same way wherever it runs, so the docs do not change with the machine. */
 export declare function formatCount(n: number): string;
 /** 480 KB, 7.1 MB, 102 MB: binary units, as the database counts its pages, with one decimal below ten. */

package/dist/render/markdown.js

@@ -27,6 +27,8 @@ function renderIndex(model) {
         if (database.description)
             parts.push(`${database.description}\n`);
         parts.push(`${driverLine(database)}\n`);
+        if (database.unread?.length)
+            parts.push(`Not read: ${database.unread.join('; ')}.\n`);
         // Rows and size only when the source read them; a view, which keeps no rows of its own, leaves them blank.
         const sized = database.schemas.some((s) => s.tables.some((t) => t.stats));
         parts.push(sized ? '| Table | Kind | Columns | Rows | Size | Description |\n|---|---|---|---|---|---|' : '| Table | Kind | Columns | Description |\n|---|---|---|---|');
@@ -39,6 +41,10 @@ function renderIndex(model) {
         }
         parts.push('');
     }
+    const owned = model.databases.flatMap((d) => [[d.name, d.properties], ...d.schemas.map((s) => [s.name, s.properties])]);
+    const properties = propertiesTable(owned);
+    if (properties)
+        parts.push(`## Properties\n\n${properties}`);
     for (const group of model.groups) {
         parts.push(`## ${group.name}\n`);
         if (group.description)
@@ -63,7 +69,81 @@ export function driverName(driver) {
 }
 function driverLine(database) {
     const name = driverName(database.driver);
-    return database.version ? `${name} ${database.version}.` : `${name}.`;
+    const collation = database.collation ? `, collation ${database.collation}` : '';
+    return `${database.version ? `${name} ${database.version}` : name}${collation}.`;
+}
+/** What the catalogue says about a table beyond its columns and keys, in the order a reader weighs it. */
+export function features(table) {
+    const list = [];
+    if (table.temporal) {
+        const { history, start, end } = table.temporal;
+        list.push({ name: 'System-versioned', detail: `history in ${history}, each row valid from ${start} to ${end}`, ref: history });
+    }
+    if (table.historyOf)
+        list.push({ name: 'History', detail: `of ${table.historyOf}`, ref: table.historyOf });
+    if (table.memoryOptimised)
+        list.push({ name: 'Memory-optimised', detail: table.memoryOptimised });
+    if (table.ledger)
+        list.push({ name: 'Ledger', detail: table.ledger });
+    if (table.partitioning) {
+        const { column, scheme, function: fn, partitions } = table.partitioning;
+        list.push({ name: 'Partitioned', detail: `on ${column} by ${scheme} (function ${fn}), ${partitions} partitions` });
+    }
+    // A list is a table whose partitions are compressed differently.
+    if (table.compression)
+        list.push({ name: 'Compressed', detail: table.compression.includes(',') ? `${table.compression}, by partition` : table.compression });
+    if (table.changeTracking)
+        list.push({ name: 'Change tracking' });
+    if (table.cdc)
+        list.push({ name: 'Change data capture' });
+    if (table.triggers?.length)
+        list.push({ name: 'Triggers', detail: String(table.triggers.length) });
+    if (table.security?.length)
+        list.push({ name: 'Row-level security', detail: [...new Set(table.security.map((s) => s.policy))].join(', ') });
+    if (table.created) {
+        const altered = table.altered && table.altered.slice(0, 10) !== table.created.slice(0, 10) ? `, last altered ${table.altered.slice(0, 10)}` : '';
+        list.push({ name: 'Created', detail: `${table.created.slice(0, 10)}${altered}` });
+    }
+    return list;
+}
+/** A column's type, with its collation where it differs from the database's. */
+function columnType(column) {
+    return column.collation ? `${column.type}, collation ${column.collation}` : column.type;
+}
+/** What else the catalogue says about a column, for the Key cell: identity, sparse, masking, encryption. */
+function columnTraits(column) {
+    const traits = [];
+    if (column.identity)
+        traits.push(column.identitySeed !== undefined ? `identity(${column.identitySeed},${column.identityIncrement ?? '1'})` : 'identity');
+    if (column.computed !== undefined)
+        traits.push(`computed \`${column.computed}\``);
+    if (column.sparse)
+        traits.push('sparse');
+    if (column.masked)
+        traits.push(`masked \`${column.masked}\``);
+    if (column.encrypted)
+        traits.push(`encrypted (${column.encrypted.type}, ${column.encrypted.key})`);
+    return traits;
+}
+/** The description cell: the description, then the sensitivity classification when there is one. */
+function columnDescription(column) {
+    const parts = column.description ? [column.description] : [];
+    const s = column.sensitivity;
+    if (s)
+        parts.push(`Sensitivity: ${[s.label, s.informationType, s.rank && `rank ${s.rank}`].filter(Boolean).join(', ')}.`);
+    return parts.join(' ');
+}
+/** Not enforced, or not checked against the rows already there. */
+function enforcement(item) {
+    return [item.disabled ? 'disabled' : '', item.untrusted ? 'not trusted' : ''].filter(Boolean);
+}
+function indexKind(index) {
+    return [index.type ?? '', index.filter ? `filtered \`${index.filter}\`` : '', index.disabled ? 'disabled' : ''].filter(Boolean).join(', ');
+}
+/** Every extended property of the things listed, one row each; empty when there are none. */
+function propertiesTable(owners) {
+    const rows = owners.flatMap(([on, properties]) => Object.entries(properties ?? {}).map(([name, value]) => `| ${cell(on)} | ${cell(name)} | ${cell(value)} |`));
+    return rows.length === 0 ? '' : `| On | Name | Value |\n|---|---|---|\n${rows.join('\n')}\n`;
 }
 /** 1,204,377: thousands grouped the same way wherever it runs, so the docs do not change with the machine. */
 export function formatCount(n) {
@@ -99,6 +179,13 @@ function renderTable(model, ref, table, database) {
         parts.push(`${table.description}\n`);
     if (table.stats)
         parts.push(`${statsLine(table.stats, database.statsReadAt)}\n`);
+    const listed = features(table);
+    if (listed.length > 0) {
+        parts.push('## Features\n');
+        // A table the feature names gets a link when it is in the model, as a relation's would.
+        const linked = (f) => (f.ref && f.detail && findTable(model, f.ref) ? f.detail.replace(f.ref, `[${f.ref}](${f.ref}.md)`) : f.detail);
+        parts.push(listed.map((f) => `- **${f.name}**${f.detail ? `: ${linked(f)}` : ''}`).join('\n') + '\n');
+    }
     const relations = relationsOf(model, ref);
     parts.push('| Column | Type | Nullable | Default | Key | Description |\n|---|---|---|---|---|---|');
     for (const column of table.columns) {
@@ -110,16 +197,14 @@ function renderTable(model, ref, table, database) {
             if (i === -1)
                 continue;
             const { table: toTable, columns } = relation.to;
-            keys.push(`FK → [${toTable}](${toTable}.md).${columns[i] ?? columns.join(',')}${relation.virtual ? ' (notes)' : ''}`);
+            const state = [relation.virtual ? 'notes' : '', ...enforcement(relation)].filter(Boolean);
+            keys.push(`FK → [${toTable}](${toTable}.md).${columns[i] ?? columns.join(',')}${state.length ? ` (${state.join(', ')})` : ''}`);
         }
         if (isUniqueColumn(table, column.name))
             keys.push('unique');
-        if (column.identity)
-            keys.push('identity');
-        if (column.computed !== undefined)
-            keys.push(`computed \`${column.computed}\``);
+        keys.push(...columnTraits(column));
         const dflt = column.default === undefined ? '' : `\`${column.default}\``;
-        parts.push(`| ${cell(column.name)} | ${cell(column.type)} | ${column.nullable ? 'yes' : 'no'} | ${cell(dflt)} | ${keys.join(', ')} | ${cell(column.description)} |`);
+        parts.push(`| ${cell(column.name)} | ${cell(columnType(column))} | ${column.nullable ? 'yes' : 'no'} | ${cell(dflt)} | ${cell(keys.join(', '))} | ${cell(columnDescription(column))} |`);
     }
     parts.push('');
     if (relations.in.length > 0) {
@@ -131,10 +216,12 @@ function renderTable(model, ref, table, database) {
     }
     if (table.indexes.length > 0) {
         parts.push('## Indexes\n');
-        parts.push('| Name | Columns | Unique |\n|---|---|---|');
+        // The Kind column only when the source said what kind; a model without it renders as it always did.
+        const kinds = table.indexes.some((i) => indexKind(i) !== '');
+        parts.push(kinds ? '| Name | Columns | Unique | Kind |\n|---|---|---|---|' : '| Name | Columns | Unique |\n|---|---|---|');
         for (const index of table.indexes) {
             const columns = index.columns.join(', ') + (index.included?.length ? ` (includes ${index.included.join(', ')})` : '');
-            parts.push(`| ${cell(index.name)} | ${cell(columns)} | ${index.unique ? 'yes' : 'no'} |`);
+            parts.push(`| ${cell(index.name)} | ${cell(columns)} | ${index.unique ? 'yes' : 'no'} |${kinds ? ` ${cell(indexKind(index))} |` : ''}`);
         }
         parts.push('');
     }
@@ -143,7 +230,34 @@ function renderTable(model, ref, table, database) {
         parts.push('| Name | Kind | Columns | Definition |\n|---|---|---|---|');
         for (const constraint of table.constraints) {
             const definition = constraint.definition === undefined ? '' : `\`${constraint.definition}\``;
-            parts.push(`| ${cell(constraint.name)} | ${constraint.kind} | ${cell(constraint.columns.join(', '))} | ${cell(definition)} |`);
+            const kind = [constraint.kind, ...enforcement(constraint)].join(', ');
+            parts.push(`| ${cell(constraint.name)} | ${kind} | ${cell(constraint.columns.join(', '))} | ${cell(definition)} |`);
+        }
+        parts.push('');
+    }
+    const properties = propertiesTable([
+        [ref, table.properties],
+        ...table.columns.map((c) => [c.name, c.properties]),
+        ...table.indexes.map((i) => [i.name, i.properties]),
+        ...table.constraints.map((c) => [c.name, c.properties]),
+    ]);
+    if (properties)
+        parts.push(`## Properties\n\n${properties}`);
+    if (table.triggers?.length) {
+        parts.push('## Triggers\n');
+        for (const trigger of table.triggers) {
+            const when = `${trigger.timing === 'after' ? 'After' : 'Instead of'} ${trigger.events.join(', ')}. ${trigger.enabled ? 'Enabled' : 'Disabled'}.`;
+            parts.push(`### ${trigger.name}\n\n${when}\n`);
+            if (trigger.definition)
+                parts.push('```sql\n' + trigger.definition.trim() + '\n```\n');
+        }
+    }
+    if (table.security?.length) {
+        parts.push('## Row-level security\n');
+        parts.push('| Policy | Kind | Predicate | Enabled |\n|---|---|---|---|');
+        for (const s of table.security) {
+            const kind = s.operation ? `${s.kind}, ${s.operation}` : s.kind;
+            parts.push(`| ${cell(s.policy)} | ${kind} | ${cell(`\`${s.predicate}\``)} | ${s.enabled ? 'yes' : 'no'} |`);
         }
         parts.push('');
     }

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.3.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": [