dbtour 0.0.0-stage → 0.2.0

package/bin/dbtour.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Node 22.18+ runs the TypeScript as it is; an older Node fails here with a syntax error, so say why first.
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 22 || (major === 22 && minor < 18)) {
+  console.error(`dbtour needs Node 22.18 or newer (this is ${process.versions.node}). Upgrade Node, then run it again.`);
+  process.exit(2);
+}
+const { main } = await import('../src/cli.ts');
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "dbtour",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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",
+  "author": "Victor Saly",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/victorsaly/dbtour.git",
+    "directory": "packages/core"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "bin": {
+    "dbtour": "bin/dbtour.mjs"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./model": "./src/model.ts",
+    "./markdown": "./src/render/markdown.ts"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "database",
+    "documentation",
+    "schema",
+    "erd",
+    "mssql",
+    "markdown",
+    "mermaid"
+  ],
+  "dependencies": {
+    "yaml": "^2.8.1"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,156 @@
+// 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 { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { configFile, defaultConfigText, modelFile, parseConfig, resolveConnection, type AddonConfig, type Config, type SourceConfig } from './config.ts';
+import { emptyModel, validate, type Api, type Database, type Model } from './model.ts';
+import { applyNotes, parseNotes } from './notes.ts';
+import { loadAddon, loadSource, type Addon, type Importer, type Source } from './plugins.ts';
+import { renderMarkdown } from './render/markdown.ts';
+
+export interface Io {
+  cwd: string;
+  log: (line: string) => void;
+  error: (line: string) => void;
+  env?: Record<string, string | undefined>;
+  /** How a source is loaded; tests hand in their own. */
+  load?: (source: SourceConfig) => Promise<Source>;
+  /** How an add-on is loaded; tests hand in their own. */
+  loadAddon?: (addon: AddonConfig) => Promise<Addon>;
+}
+
+const help = `Usage: dbtour <command>
+
+  init [--source mssql]   write ${configFile} here
+  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>
+
+Set the connection string in the environment variable ${configFile} names, never in the file.`;
+
+export async function main(argv: string[], io: Io = { cwd: process.cwd(), log: console.log, error: console.error }): Promise<number> {
+  const { values, positionals } = parseArgs({ args: argv, options: { help: { type: 'boolean', short: 'h' }, source: { type: 'string' } }, allowPositionals: true, strict: false });
+  const command = positionals[0];
+  if (values.help || command === undefined) {
+    io.log(help);
+    return 0;
+  }
+  try {
+    switch (command) {
+      case 'init':
+        return init(io, typeof values.source === 'string' ? values.source : 'mssql');
+      case 'extract':
+        return await extract(io);
+      case 'render':
+        return await render(io);
+      default:
+        io.error(`"${command}" is not a dbtour command.\n\n${help}`);
+        return 1;
+    }
+  } catch (error) {
+    io.error(error instanceof Error ? error.message : String(error));
+    return (error as { exitCode?: number }).exitCode ?? 1;
+  }
+}
+
+function missing(message: string): Error {
+  return Object.assign(new Error(message), { exitCode: 2 });
+}
+
+function init(io: Io, source: string): number {
+  const path = join(io.cwd, configFile);
+  if (existsSync(path)) {
+    io.error(`${configFile} already exists here. Edit it, or delete it and run dbtour init again.`);
+    return 1;
+  }
+  writeFileSync(path, defaultConfigText(source));
+  io.log(`Wrote ${configFile}. Set the connection string in DBTOUR_${source.toUpperCase()}, then run dbtour extract.`);
+  return 0;
+}
+
+function readConfig(io: Io): Config {
+  const path = join(io.cwd, configFile);
+  if (!existsSync(path)) throw missing(`No ${configFile} here. Run dbtour init to write one.`);
+  return parseConfig(readFileSync(path, 'utf8'));
+}
+
+async function extract(io: Io): Promise<number> {
+  const config = readConfig(io);
+  const env = io.env ?? process.env;
+  const load = io.load ?? ((source: SourceConfig) => loadSource(source, importer(io.cwd)));
+  const model: Model = { ...emptyModel(), generatedAt: new Date().toISOString() };
+  for (const source of config.sources) {
+    const connection = resolveConnection(source.connection, env);
+    const { extract } = await load(source);
+    let result: Database | Api;
+    try {
+      result = await extract({ ...source, connection });
+    } catch (error) {
+      io.error(`${source.name} (${source.type}): ${error instanceof Error ? error.message : String(error)}`);
+      return 1;
+    }
+    if ('schemas' in result) {
+      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`);
+    } else {
+      model.apis.push(result);
+      io.log(`${result.name}: ${result.endpoints.length} endpoints`);
+    }
+  }
+  const checked = validate(model);
+  if (!checked.ok) {
+    io.error(`A source returned something that is not a model:\n  ${checked.errors.join('\n  ')}`);
+    return 1;
+  }
+  const path = join(io.cwd, config.out, modelFile);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(model, null, 2) + '\n');
+  io.log(`Wrote ${join(config.out, modelFile)}. Run dbtour render to write the docs.`);
+  return 0;
+}
+
+/** A module given as a path is relative to the project, not to dbtour. */
+function importer(cwd: string): Importer {
+  return (specifier) => import(specifier.startsWith('.') || specifier.startsWith('/') ? pathToFileURL(resolve(cwd, specifier)).href : specifier);
+}
+
+async function render(io: Io): Promise<number> {
+  const config = readConfig(io);
+  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;
+  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;
+  }
+  // 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: AddonConfig) => loadAddon(addon, importer(io.cwd)));
+  const addons: Addon[] = [];
+  for (const addon of config.addons) {
+    try {
+      addons.push(await load(addon));
+    } catch (error) {
+      throw missing(error instanceof Error ? error.message : String(error));
+    }
+  }
+  for (const addon of addons) if (addon.enrich) model = await addon.enrich(model);
+  const files = renderMarkdown(model);
+  for (const addon of addons) if (addon.render) Object.assign(files, await addon.render(model));
+  for (const [name, text] of Object.entries(files)) {
+    const path = join(io.cwd, config.out, name);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+  }
+  io.log(`Wrote ${Object.keys(files).length} files to ${config.out}.`);
+  return 0;
+}

package/src/config.ts

@@ -0,0 +1,93 @@
+// dbtour.yaml: where the model goes, where it comes from, where the notes are.
+import { parse } from 'yaml';
+
+export interface SourceConfig {
+  type: string;
+  name: string;
+  /** `${NAME}`: the environment variable holding the connection string. Never the string itself. */
+  connection?: string;
+  /** A module to import instead of dbtour-source-<type>. */
+  module?: string;
+  [option: string]: unknown;
+}
+
+export interface AddonConfig {
+  type: string;
+  /** A module to import instead of dbtour-addon-<type>. */
+  module?: string;
+  [option: string]: unknown;
+}
+
+export interface Config {
+  out: string;
+  notes: string;
+  sources: SourceConfig[];
+  addons: AddonConfig[];
+}
+
+export const configFile = 'dbtour.yaml';
+export const modelFile = 'schema.json';
+
+export function parseConfig(text: string): Config {
+  const raw: unknown = parse(text) ?? {};
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) throw new Error(`${configFile} must be a map with out, notes and sources`);
+  const doc = raw as Record<string, unknown>;
+  if (!Array.isArray(doc.sources) || doc.sources.length === 0) throw new Error(`${configFile} needs a sources list with at least one source`);
+  const sources = doc.sources.map((value, i): SourceConfig => {
+    if (typeof value !== 'object' || value === null) throw new Error(`sources[${i}] must be a map with type and name`);
+    const entry = value as Record<string, unknown>;
+    if (typeof entry.type !== 'string' || entry.type === '') throw new Error(`sources[${i}].type is required: mssql, for instance`);
+    if (typeof entry.name !== 'string' || entry.name === '') throw new Error(`sources[${i}].name is required: the name the docs call this database`);
+    return { ...entry, type: entry.type, name: entry.name };
+  });
+  return {
+    out: typeof doc.out === 'string' ? doc.out : 'docs/dbtour',
+    notes: typeof doc.notes === 'string' ? doc.notes : 'dbtour.notes.yaml',
+    sources,
+    addons: parseAddons(doc.addons),
+  };
+}
+
+/** `addons: [explorer]` or `addons: [{ type: explorer, module: ./page.ts }]`; none when absent. */
+function parseAddons(value: unknown): AddonConfig[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error('addons must be a list of add-on names, like [explorer]');
+  return value.map((entry, i): AddonConfig => {
+    if (typeof entry === 'string' && entry !== '') return { type: entry };
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) throw new Error(`addons[${i}] must be a name or a map with type`);
+    const map = entry as Record<string, unknown>;
+    if (typeof map.type !== 'string' || map.type === '') throw new Error(`addons[${i}].type is required: explorer, for instance`);
+    return { ...map, type: map.type };
+  });
+}
+
+export function defaultConfigText(type: string): string {
+  const variable = `DBTOUR_${type.toUpperCase()}`;
+  return `# dbtour: see https://github.com/victorsaly/dbtour
+out: docs/dbtour
+sources:
+  - type: ${type}
+    name: ${type === 'mssql' ? 'MyDatabase' : 'my-database'}
+    # The name of the environment variable holding the connection string. Never the string itself.
+    connection: \${${variable}}
+# Descriptions, relations and groups the database cannot say. Optional.
+notes: dbtour.notes.yaml
+# What else render writes. explorer is the page: npm install --save-dev dbtour-addon-explorer
+addons:
+  - explorer
+`;
+}
+
+const variablePattern = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+
+export function resolveConnection(value: string | undefined, env: Record<string, string | undefined>): string | undefined {
+  if (value === undefined) return undefined;
+  const match = variablePattern.exec(value);
+  if (!match) throw new Error(`connection must name an environment variable, like \${DBTOUR_MSSQL}: never write the connection string into ${configFile}`);
+  const resolved = env[match[1]];
+  if (resolved === undefined || resolved === '') {
+    // Exit 2: what is missing, not what failed.
+    throw Object.assign(new Error(`Set ${match[1]} to the connection string, then run it again`), { exitCode: 2 });
+  }
+  return resolved;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './model.ts';
+export { parseNotes, applyNotes, type Notes, type TableNotes, type RelationNote, type Applied } from './notes.ts';
+export { parseConfig, defaultConfigText, resolveConnection, configFile, modelFile, type Config, type SourceConfig, type AddonConfig } from './config.ts';
+export { loadSource, sourceModuleName, loadAddon, addonModuleName, type Source, type Extract, type Importer, type Addon, type Files } from './plugins.ts';
+export { renderMarkdown, renderTableMarkdown, driverName, wholeDiagramLimit } from './render/markdown.ts';
+export { erDiagram, neighbourhood, entityName } from './render/mermaid.ts';

package/src/model.ts

@@ -0,0 +1,318 @@
+// The model: what every source writes and everything else reads. Kept to plain JSON so it can be committed,
+// diffed and handed to a page or an agent. Refs name tables as `schema.table` and columns as
+// `schema.table.column`.
+
+export const MODEL_VERSION = 1;
+
+export interface Column {
+  name: string;
+  /** As the database spells it, with its size: nvarchar(320), decimal(18,2). */
+  type: string;
+  nullable: boolean;
+  default?: string;
+  /** The expression of a computed column. */
+  computed?: string;
+  identity?: boolean;
+  description?: string;
+}
+
+export interface Index {
+  name: string;
+  columns: string[];
+  unique: boolean;
+  included?: string[];
+}
+
+export interface Constraint {
+  name: string;
+  kind: 'primary' | 'unique' | 'check' | 'foreign';
+  columns: string[];
+  definition?: string;
+}
+
+export interface Table {
+  name: string;
+  kind: 'table' | 'view';
+  description?: string;
+  columns: Column[];
+  primaryKey?: string[];
+  indexes: Index[];
+  constraints: Constraint[];
+  /** The SQL of a view. */
+  definition?: string;
+}
+
+export interface Schema {
+  name: string;
+  tables: Table[];
+}
+
+export interface RelationEnd {
+  table: string;
+  columns: string[];
+}
+
+export interface Relation {
+  name?: string;
+  from: RelationEnd;
+  to: RelationEnd;
+  /** Declared in the notes, not in the database. */
+  virtual?: boolean;
+  onDelete?: string;
+  onUpdate?: string;
+}
+
+export interface Database {
+  name: string;
+  driver: string;
+  version?: string;
+  description?: string;
+  schemas: Schema[];
+  relations: Relation[];
+}
+
+export interface Endpoint {
+  method: string;
+  path: string;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+}
+
+export interface Api {
+  name: string;
+  description?: string;
+  endpoints: Endpoint[];
+}
+
+/** An endpoint and the tables it touches. */
+export interface Link {
+  api: string;
+  method: string;
+  path: string;
+  tables: string[];
+}
+
+export interface Group {
+  name: string;
+  description?: string;
+  tables: string[];
+}
+
+export interface Model {
+  dbtour: typeof MODEL_VERSION;
+  generatedAt?: string;
+  databases: Database[];
+  apis: Api[];
+  links: Link[];
+  groups: Group[];
+}
+
+export function emptyModel(): Model {
+  return { dbtour: MODEL_VERSION, databases: [], apis: [], links: [], groups: [] };
+}
+
+export interface TableRef {
+  schema: string;
+  table: string;
+  column?: string;
+}
+
+export function tableRef(schema: string, table: string): string {
+  return `${schema}.${table}`;
+}
+
+export function parseRef(ref: string): TableRef {
+  const parts = ref.split('.');
+  if (parts.length < 2 || parts.length > 3 || parts.some((p) => p === '')) {
+    throw new Error(`"${ref}" is not a ref: write schema.table, or schema.table.column`);
+  }
+  const [schema, table, column] = parts;
+  return column === undefined ? { schema, table } : { schema, table, column };
+}
+
+export interface Found {
+  database: Database;
+  schema: Schema;
+  table: Table;
+}
+
+export function findTable(model: Model, ref: string): Found | undefined {
+  const { schema: schemaName, table: tableName } = parseRef(ref);
+  for (const database of model.databases) {
+    for (const schema of database.schemas) {
+      if (schema.name !== schemaName) continue;
+      const table = schema.tables.find((t) => t.name === tableName);
+      if (table) return { database, schema, table };
+    }
+  }
+  return undefined;
+}
+
+/** Unique on its own, by a constraint or an index, and not the primary key, which says so already. */
+export function isUniqueColumn(table: Table, column: string): boolean {
+  if (table.primaryKey?.includes(column)) return false;
+  return (
+    table.constraints.some((c) => c.kind === 'unique' && c.columns.length === 1 && c.columns[0] === column) ||
+    table.indexes.some((i) => i.unique && i.columns.length === 1 && i.columns[0] === column)
+  );
+}
+
+export function relationsOf(model: Model, ref: string): { out: Relation[]; in: Relation[] } {
+  const out: Relation[] = [];
+  const inward: Relation[] = [];
+  for (const database of model.databases) {
+    for (const relation of database.relations) {
+      if (relation.from.table === ref) out.push(relation);
+      if (relation.to.table === ref) inward.push(relation);
+    }
+  }
+  return { out, in: inward };
+}
+
+export type Validation = { ok: true; model: Model } | { ok: false; errors: string[] };
+
+/** Checks the shape, then that every relation points at a table in its database. */
+export function validate(value: unknown): Validation {
+  const errors: string[] = [];
+  const check = new Checker(errors);
+  if (!check.object(value, 'model')) return { ok: false, errors };
+  const model = value as Record<string, unknown>;
+  if (model.dbtour !== MODEL_VERSION) errors.push(`model.dbtour must be ${MODEL_VERSION}, got ${JSON.stringify(model.dbtour)}`);
+  check.optionalString(model.generatedAt, 'generatedAt');
+  check.list(model.databases, 'databases', (d, p) => checkDatabase(check, d, p));
+  check.list(model.apis, 'apis', (a, p) => {
+    if (!check.object(a, p)) return;
+    check.string(a.name, `${p}.name`);
+    check.optionalString(a.description, `${p}.description`);
+    check.list(a.endpoints, `${p}.endpoints`, (e, ep) => {
+      if (!check.object(e, ep)) return;
+      check.string(e.method, `${ep}.method`);
+      check.string(e.path, `${ep}.path`);
+      check.optionalString(e.summary, `${ep}.summary`);
+      check.optionalString(e.description, `${ep}.description`);
+      if (e.tags !== undefined) check.strings(e.tags, `${ep}.tags`);
+    });
+  });
+  check.list(model.links, 'links', (l, p) => {
+    if (!check.object(l, p)) return;
+    check.string(l.api, `${p}.api`);
+    check.string(l.method, `${p}.method`);
+    check.string(l.path, `${p}.path`);
+    check.strings(l.tables, `${p}.tables`);
+  });
+  check.list(model.groups, 'groups', (g, p) => {
+    if (!check.object(g, p)) return;
+    check.string(g.name, `${p}.name`);
+    check.optionalString(g.description, `${p}.description`);
+    check.strings(g.tables, `${p}.tables`);
+  });
+  if (errors.length > 0) return { ok: false, errors };
+
+  const typed = value as Model;
+  typed.databases.forEach((database, i) => {
+    const refs = new Set(database.schemas.flatMap((s) => s.tables.map((t) => tableRef(s.name, t.name))));
+    database.relations.forEach((relation, j) => {
+      for (const end of ['from', 'to'] as const) {
+        if (!refs.has(relation[end].table)) {
+          errors.push(`databases[${i}].relations[${j}].${end}.table "${relation[end].table}" is not a table of ${database.name}`);
+        }
+      }
+    });
+  });
+  return errors.length > 0 ? { ok: false, errors } : { ok: true, model: typed };
+}
+
+function checkDatabase(check: Checker, d: unknown, p: string): void {
+  if (!check.object(d, p)) return;
+  check.string(d.name, `${p}.name`);
+  check.string(d.driver, `${p}.driver`);
+  check.optionalString(d.version, `${p}.version`);
+  check.optionalString(d.description, `${p}.description`);
+  check.list(d.schemas, `${p}.schemas`, (s, sp) => {
+    if (!check.object(s, sp)) return;
+    check.string(s.name, `${sp}.name`);
+    check.list(s.tables, `${sp}.tables`, (t, tp) => checkTable(check, t, tp));
+  });
+  check.list(d.relations, `${p}.relations`, (r, rp) => {
+    if (!check.object(r, rp)) return;
+    check.optionalString(r.name, `${rp}.name`);
+    for (const end of ['from', 'to']) {
+      const e = r[end];
+      if (!check.object(e, `${rp}.${end}`)) continue;
+      check.string(e.table, `${rp}.${end}.table`);
+      check.strings(e.columns, `${rp}.${end}.columns`);
+    }
+    check.optionalBoolean(r.virtual, `${rp}.virtual`);
+  });
+}
+
+function checkTable(check: Checker, t: unknown, p: string): void {
+  if (!check.object(t, p)) return;
+  check.string(t.name, `${p}.name`);
+  if (t.kind !== 'table' && t.kind !== 'view') check.errors.push(`${p}.kind must be "table" or "view"`);
+  check.optionalString(t.description, `${p}.description`);
+  check.optionalString(t.definition, `${p}.definition`);
+  if (t.primaryKey !== undefined) check.strings(t.primaryKey, `${p}.primaryKey`);
+  check.list(t.columns, `${p}.columns`, (c, cp) => {
+    if (!check.object(c, cp)) return;
+    check.string(c.name, `${cp}.name`);
+    check.string(c.type, `${cp}.type`);
+    if (typeof c.nullable !== 'boolean') check.errors.push(`${cp}.nullable must be true or false`);
+    check.optionalString(c.default, `${cp}.default`);
+    check.optionalString(c.computed, `${cp}.computed`);
+    check.optionalBoolean(c.identity, `${cp}.identity`);
+    check.optionalString(c.description, `${cp}.description`);
+  });
+  check.list(t.indexes, `${p}.indexes`, (x, xp) => {
+    if (!check.object(x, xp)) return;
+    check.string(x.name, `${xp}.name`);
+    check.strings(x.columns, `${xp}.columns`);
+    if (typeof x.unique !== 'boolean') check.errors.push(`${xp}.unique must be true or false`);
+  });
+  check.list(t.constraints, `${p}.constraints`, (c, cp) => {
+    if (!check.object(c, cp)) return;
+    check.string(c.name, `${cp}.name`);
+    if (!['primary', 'unique', 'check', 'foreign'].includes(String(c.kind))) check.errors.push(`${cp}.kind is not a constraint kind`);
+    check.strings(c.columns, `${cp}.columns`);
+    check.optionalString(c.definition, `${cp}.definition`);
+  });
+}
+
+class Checker {
+  errors: string[];
+
+  constructor(errors: string[]) {
+    this.errors = errors;
+  }
+
+  object(value: unknown, path: string): value is Record<string, any> { // eslint-disable-line @typescript-eslint/no-explicit-any
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) return true;
+    this.errors.push(`${path} must be an object`);
+    return false;
+  }
+
+  string(value: unknown, path: string): void {
+    if (typeof value !== 'string' || value === '') this.errors.push(`${path} must be a non-empty string`);
+  }
+
+  optionalString(value: unknown, path: string): void {
+    if (value !== undefined && typeof value !== 'string') this.errors.push(`${path} must be a string when given`);
+  }
+
+  optionalBoolean(value: unknown, path: string): void {
+    if (value !== undefined && typeof value !== 'boolean') this.errors.push(`${path} must be true or false when given`);
+  }
+
+  strings(value: unknown, path: string): void {
+    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) this.errors.push(`${path} must be a list of strings`);
+  }
+
+  list(value: unknown, path: string, each: (item: unknown, path: string) => void): void {
+    if (!Array.isArray(value)) {
+      this.errors.push(`${path} must be a list`);
+      return;
+    }
+    value.forEach((item, i) => each(item, `${path}[${i}]`));
+  }
+}

package/src/notes.ts

@@ -0,0 +1,130 @@
+// The notes file: what people add that the database cannot say. Merged into the model at render time and
+// winning over it, so a production database nobody may alter still gets documented.
+import { parse } from 'yaml';
+import { findTable, parseRef, tableRef, type Group, type Model, type Relation } from './model.ts';
+
+export interface TableNotes {
+  description?: string;
+  columns?: Record<string, string>;
+}
+
+export interface RelationNote {
+  from: string;
+  to: string;
+}
+
+export interface Notes {
+  tables: Record<string, TableNotes>;
+  relations: RelationNote[];
+  groups: Group[];
+}
+
+export function parseNotes(text: string): Notes {
+  const raw: unknown = parse(text) ?? {};
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) throw new Error('the notes file must be a map with tables, relations and groups');
+  const doc = raw as Record<string, unknown>;
+  const notes: Notes = { tables: {}, relations: [], groups: [] };
+
+  if (doc.tables !== undefined) {
+    if (typeof doc.tables !== 'object' || doc.tables === null || Array.isArray(doc.tables)) throw new Error('tables must be a map of schema.table to its notes');
+    for (const [ref, value] of Object.entries(doc.tables as Record<string, unknown>)) {
+      parseRef(ref);
+      if (typeof value !== 'object' || value === null) throw new Error(`tables.${ref} must be a map with description and columns`);
+      const entry = value as Record<string, unknown>;
+      const table: TableNotes = {};
+      if (entry.description !== undefined) table.description = String(entry.description);
+      if (entry.columns !== undefined) {
+        if (typeof entry.columns !== 'object' || entry.columns === null || Array.isArray(entry.columns)) throw new Error(`tables.${ref}.columns must be a map of column to description`);
+        table.columns = Object.fromEntries(Object.entries(entry.columns as Record<string, unknown>).map(([k, v]) => [k, String(v)]));
+      }
+      notes.tables[ref] = table;
+    }
+  }
+
+  if (doc.relations !== undefined) {
+    if (!Array.isArray(doc.relations)) throw new Error('relations must be a list of { from, to }');
+    doc.relations.forEach((value, i) => {
+      if (typeof value !== 'object' || value === null) throw new Error(`relations[${i}] must be { from, to }`);
+      const { from, to } = value as Record<string, unknown>;
+      for (const [end, ref] of [['from', from], ['to', to]] as const) {
+        if (typeof ref !== 'string' || parseRef(ref).column === undefined) throw new Error(`relations[${i}].${end} must be schema.table.column`);
+      }
+      notes.relations.push({ from: from as string, to: to as string });
+    });
+  }
+
+  if (doc.groups !== undefined) {
+    if (!Array.isArray(doc.groups)) throw new Error('groups must be a list of { name, description, tables }');
+    doc.groups.forEach((value, i) => {
+      if (typeof value !== 'object' || value === null) throw new Error(`groups[${i}] must be { name, description, tables }`);
+      const entry = value as Record<string, unknown>;
+      if (typeof entry.name !== 'string' || entry.name === '') throw new Error(`groups[${i}].name is required`);
+      if (!Array.isArray(entry.tables) || entry.tables.some((t) => typeof t !== 'string')) throw new Error(`groups[${i}].tables must be a list of schema.table`);
+      entry.tables.forEach((t) => parseRef(t));
+      const group: Group = { name: entry.name, tables: entry.tables as string[] };
+      if (entry.description !== undefined) group.description = String(entry.description);
+      notes.groups.push(group);
+    });
+  }
+  return notes;
+}
+
+export interface Applied {
+  model: Model;
+  /** What the notes name that the model does not have; said, then skipped. */
+  warnings: string[];
+}
+
+export function applyNotes(input: Model, notes: Notes): Applied {
+  const model = structuredClone(input);
+  const warnings: string[] = [];
+
+  for (const [ref, tableNotes] of Object.entries(notes.tables)) {
+    const found = findTable(model, ref);
+    if (!found) {
+      warnings.push(`notes: ${ref} is not a table in the model`);
+      continue;
+    }
+    if (tableNotes.description !== undefined) found.table.description = tableNotes.description;
+    for (const [name, description] of Object.entries(tableNotes.columns ?? {})) {
+      const column = found.table.columns.find((c) => c.name === name);
+      if (!column) {
+        warnings.push(`notes: ${ref}.${name} is not a column in the model`);
+        continue;
+      }
+      column.description = description;
+    }
+  }
+
+  for (const note of notes.relations) {
+    const from = parseRef(note.from);
+    const to = parseRef(note.to);
+    const relation: Relation = {
+      from: { table: tableRef(from.schema, from.table), columns: [from.column!] },
+      to: { table: tableRef(to.schema, to.table), columns: [to.column!] },
+      virtual: true,
+    };
+    const fromTable = findTable(model, relation.from.table);
+    const toTable = findTable(model, relation.to.table);
+    if (!fromTable || !toTable) {
+      warnings.push(`notes: relation ${note.from} → ${note.to} names a table that is not in the model`);
+      continue;
+    }
+    const exists = fromTable.database.relations.some((r) => sameEnd(r.from, relation.from) && sameEnd(r.to, relation.to));
+    if (!exists) fromTable.database.relations.push(relation);
+  }
+
+  for (const group of notes.groups) {
+    const tables = group.tables.filter((ref) => {
+      if (findTable(model, ref)) return true;
+      warnings.push(`notes: group ${group.name} lists ${ref}, which is not a table in the model`);
+      return false;
+    });
+    model.groups.push({ ...group, tables });
+  }
+  return { model, warnings };
+}
+
+function sameEnd(a: { table: string; columns: string[] }, b: { table: string; columns: string[] }): boolean {
+  return a.table === b.table && a.columns.join(',') === b.columns.join(',');
+}

package/src/plugins.ts

@@ -0,0 +1,63 @@
+// Sources and add-ons are packages named after their type: `type: mssql` loads dbtour-source-mssql, the
+// add-on `explorer` loads dbtour-addon-explorer. A `module` in the config loads that instead, for one kept
+// in the project.
+import type { AddonConfig, SourceConfig } from './config.ts';
+import type { Api, Database, Model } from './model.ts';
+
+export type Extract = (config: SourceConfig) => Promise<Database | Api>;
+
+export interface Source {
+  extract: Extract;
+}
+
+export type Importer = (specifier: string) => Promise<unknown>;
+
+export function sourceModuleName(source: SourceConfig): string {
+  return source.module ?? `dbtour-source-${source.type}`;
+}
+
+export async function loadSource(source: SourceConfig, importer: Importer = (s) => import(s)): Promise<Source> {
+  const name = sourceModuleName(source);
+  let loaded: unknown;
+  try {
+    loaded = await importer(name);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Source "${source.type}" is not installed: npm install ${name} (${reason})`, { cause: error });
+  }
+  const extract = (loaded as { extract?: unknown } | null)?.extract;
+  if (typeof extract !== 'function') throw new Error(`${name} does not export extract(config), so it is not a dbtour source`);
+  return { extract: extract as Extract };
+}
+
+/** Files to write under `out`, keyed by path, like renderMarkdown returns them. */
+export type Files = Record<string, string>;
+
+/** An add-on changes the model, writes files beside the Markdown, or both. */
+export interface Addon {
+  enrich?: (model: Model) => Model | Promise<Model>;
+  render?: (model: Model) => Files | Promise<Files>;
+}
+
+export function addonModuleName(addon: AddonConfig): string {
+  return addon.module ?? `dbtour-addon-${addon.type}`;
+}
+
+export async function loadAddon(addon: AddonConfig, importer: Importer = (s) => import(s)): Promise<Addon> {
+  const name = addonModuleName(addon);
+  let loaded: unknown;
+  try {
+    loaded = await importer(name);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Add-on "${addon.type}" is not installed: npm install ${name} (${reason})`, { cause: error });
+  }
+  const { enrich, render } = (loaded as { enrich?: unknown; render?: unknown } | null) ?? {};
+  if (typeof enrich !== 'function' && typeof render !== 'function') {
+    throw new Error(`${name} exports neither enrich(model) or render(model), so it is not a dbtour add-on`);
+  }
+  const result: Addon = {};
+  if (typeof enrich === 'function') result.enrich = enrich as Addon['enrich'];
+  if (typeof render === 'function') result.render = render as Addon['render'];
+  return result;
+}

package/src/render/markdown.ts

@@ -0,0 +1,147 @@
+// Markdown GitHub shows: an index with every table, and one page per table with its columns, keys,
+// relations both ways, indexes, constraints and the diagram of its neighbourhood.
+import { findTable, isUniqueColumn, relationsOf, tableRef, type Database, type Model, type Table } from '../model.ts';
+import { erDiagram, neighbourhood } from './mermaid.ts';
+
+// Mermaid lays out a whole database only while it is small; above this many tables the index shows the
+// groups and each table page shows its own neighbourhood instead.
+export const wholeDiagramLimit = 40;
+
+export function renderMarkdown(model: Model): Record<string, string> {
+  const files: Record<string, string> = { 'README.md': renderIndex(model) };
+  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);
+        files[`tables/${ref}.md`] = renderTable(model, ref, table);
+      }
+    }
+  }
+  return files;
+}
+
+function renderIndex(model: Model): string {
+  const parts: string[] = [];
+  const single = model.databases.length === 1;
+  if (!single) parts.push('# Databases\n');
+  for (const database of model.databases) {
+    parts.push(`${single ? '#' : '##'} ${database.name}\n`);
+    if (database.description) parts.push(`${database.description}\n`);
+    parts.push(`${driverLine(database)}\n`);
+    parts.push('| Table | Kind | Columns | Description |\n|---|---|---|---|');
+    for (const schema of database.schemas) {
+      for (const table of schema.tables) {
+        const ref = tableRef(schema.name, table.name);
+        parts.push(`| [${ref}](tables/${ref}.md) | ${table.kind} | ${table.columns.length} | ${cell(table.description)} |`);
+      }
+    }
+    parts.push('');
+  }
+  for (const group of model.groups) {
+    parts.push(`## ${group.name}\n`);
+    if (group.description) parts.push(`${group.description}\n`);
+    parts.push(group.tables.map((ref) => `- [${ref}](tables/${ref}.md)`).join('\n') + '\n');
+    parts.push(mermaid(erDiagram(model, group.tables)));
+  }
+  const refs = model.databases.flatMap((d) => d.schemas.flatMap((s) => s.tables.map((t) => tableRef(s.name, t.name))));
+  if (refs.length <= wholeDiagramLimit) {
+    parts.push('## Diagram\n');
+    parts.push(mermaid(erDiagram(model, refs)));
+  } else {
+    parts.push(`## Diagram\n\n${refs.length} tables is too many for one diagram: each table's page draws its own neighbourhood.\n`);
+  }
+  return parts.join('\n');
+}
+
+/** The product's name for a driver: mssql is SQL Server. */
+export function driverName(driver: string): string {
+  const names: Record<string, string> = { mssql: 'SQL Server', postgres: 'PostgreSQL', mysql: 'MySQL', sqlite: 'SQLite' };
+  return names[driver] ?? driver;
+}
+
+function driverLine(database: Database): string {
+  const name = driverName(database.driver);
+  return database.version ? `${name} ${database.version}.` : `${name}.`;
+}
+
+/** One table's page on its own: what the page hands to an agent. */
+export function renderTableMarkdown(model: Model, ref: string): string {
+  const found = findTable(model, ref);
+  if (!found) throw new Error(`${ref} is not a table in the model`);
+  return renderTable(model, ref, found.table);
+}
+
+function renderTable(model: Model, ref: string, table: Table): string {
+  const parts: string[] = [`# ${ref}\n`];
+  if (table.description) parts.push(`${table.description}\n`);
+  const relations = relationsOf(model, ref);
+
+  parts.push('| Column | Type | Nullable | Default | Key | Description |\n|---|---|---|---|---|---|');
+  for (const column of table.columns) {
+    const keys: string[] = [];
+    if (table.primaryKey?.includes(column.name)) keys.push('PK');
+    for (const relation of relations.out) {
+      const i = relation.from.columns.indexOf(column.name);
+      if (i === -1) continue;
+      const { table: toTable, columns } = relation.to;
+      keys.push(`FK → [${toTable}](${toTable}.md).${columns[i] ?? columns.join(',')}${relation.virtual ? ' (notes)' : ''}`);
+    }
+    if (isUniqueColumn(table, column.name)) keys.push('unique');
+    if (column.identity) keys.push('identity');
+    if (column.computed !== undefined) keys.push(`computed \`${column.computed}\``);
+    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('');
+
+  if (relations.in.length > 0) {
+    parts.push('## Referenced by\n');
+    const lines = relations.in
+      .map((r) => `- [${r.from.table}](${r.from.table}.md).${r.from.columns.join(', ')}${r.virtual ? ' (notes)' : ''}`)
+      .sort();
+    parts.push(lines.join('\n') + '\n');
+  }
+
+  if (table.indexes.length > 0) {
+    parts.push('## Indexes\n');
+    parts.push('| 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('');
+  }
+
+  if (table.constraints.length > 0) {
+    parts.push('## Constraints\n');
+    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)} |`);
+    }
+    parts.push('');
+  }
+
+  if (table.definition !== undefined) {
+    parts.push('## Definition\n');
+    parts.push('```sql\n' + table.definition.trim() + '\n```\n');
+  }
+
+  const around = neighbourhood(model, ref);
+  if (around.length > 1) {
+    parts.push('## Diagram\n');
+    parts.push(mermaid(erDiagram(model, around)));
+  }
+  return parts.join('\n');
+}
+
+function mermaid(diagram: string): string {
+  return '```mermaid\n' + diagram + '```\n';
+}
+
+/** A table cell: pipes and line breaks would end it. */
+function cell(text: string | undefined): string {
+  return (text ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+
+export { findTable };

package/src/render/mermaid.ts

@@ -0,0 +1,75 @@
+// Mermaid erDiagram text: GitHub draws it in the Markdown, no image service needed.
+import { findTable, relationsOf, type Model, type Relation, type Table } from '../model.ts';
+
+/** Mermaid takes letters, digits and underscores in an entity name. */
+export function entityName(ref: string): string {
+  return ref.replace(/[^A-Za-z0-9_]/g, '_');
+}
+
+/** The table and every table one relation away, in the order the relations are listed. */
+export function neighbourhood(model: Model, ref: string): string[] {
+  const refs = [ref];
+  for (const relation of model.databases.flatMap((d) => d.relations)) {
+    const other = relation.from.table === ref ? relation.to.table : relation.to.table === ref ? relation.from.table : undefined;
+    if (other !== undefined && !refs.includes(other)) refs.push(other);
+  }
+  return refs;
+}
+
+export function erDiagram(model: Model, refs: string[]): string {
+  const lines = ['erDiagram'];
+  const shown = new Set(refs);
+  for (const ref of refs) {
+    const found = findTable(model, ref);
+    if (!found) continue;
+    const foreign = new Set(relationsOf(model, ref).out.flatMap((r) => r.from.columns));
+    lines.push(`  ${entityName(ref)} {`);
+    for (const column of found.table.columns) {
+      const keys = keyMarks(found.table, column.name, foreign);
+      lines.push(`    ${attributeType(column.type)} ${attributeName(column.name)}${keys ? ' ' + keys : ''}`);
+    }
+    lines.push('  }');
+  }
+  for (const relation of model.databases.flatMap((d) => d.relations)) {
+    if (!shown.has(relation.from.table) || !shown.has(relation.to.table)) continue;
+    lines.push(`  ${entityName(relation.from.table)} ${cardinality(model, relation)} ${entityName(relation.to.table)} : ${label(relation)}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function keyMarks(table: Table, column: string, foreign: Set<string>): string {
+  const marks: string[] = [];
+  if (table.primaryKey?.includes(column)) marks.push('PK');
+  if (foreign.has(column)) marks.push('FK');
+  if (!marks.includes('PK') && table.constraints.some((c) => c.kind === 'unique' && c.columns.length === 1 && c.columns[0] === column)) marks.push('UK');
+  return marks.join(',');
+}
+
+// Mermaid 11 reads a type as one word of letters, digits, underscores, hyphens, brackets and the commas
+// inside them (decimal(18,2) is fine), and a name as one word; it does not take quotes on either, so anything
+// else becomes an underscore.
+function attributeType(type: string): string {
+  return type.replace(/^[^A-Za-z_]|[^A-Za-z0-9_,()[\]-]/g, '_');
+}
+
+function attributeName(name: string): string {
+  return name.replace(/^[^A-Za-z_]|[^A-Za-z0-9_-]/g, '_');
+}
+
+/** many-to-one unless the referencing columns are themselves a key, then one-to-one. Dotted when virtual. */
+function cardinality(model: Model, relation: Relation): string {
+  const from = findTable(model, relation.from.table)?.table;
+  const columns = relation.from.columns.join(',');
+  const isKey =
+    from !== undefined &&
+    (from.primaryKey?.join(',') === columns ||
+      from.constraints.some((c) => c.kind === 'unique' && c.columns.join(',') === columns) ||
+      from.indexes.some((i) => i.unique && i.columns.join(',') === columns));
+  const line = relation.virtual ? '..' : '--';
+  return `${isKey ? '|o' : '}o'}${line}||`;
+}
+
+function label(relation: Relation): string {
+  const text = relation.from.columns.join(', ') + (relation.virtual ? ' (notes)' : '');
+  return /^[A-Za-z0-9_]+$/.test(text) ? text : `"${text.replace(/"/g, "'")}"`;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.