dbtour 0.2.0 → 0.2.4

package/dist/notes.js

@@ -0,0 +1,115 @@
+// 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 } from "./model.js";
+export function parseNotes(text) {
+    const raw = 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;
+    const 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)) {
+            parseRef(ref);
+            if (typeof value !== 'object' || value === null)
+                throw new Error(`tables.${ref} must be a map with description and columns`);
+            const entry = value;
+            const table = {};
+            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).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;
+            for (const [end, ref] of [['from', from], ['to', to]]) {
+                if (typeof ref !== 'string' || parseRef(ref).column === undefined)
+                    throw new Error(`relations[${i}].${end} must be schema.table.column`);
+            }
+            notes.relations.push({ from: from, to: to });
+        });
+    }
+    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;
+            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 = { name: entry.name, tables: entry.tables };
+            if (entry.description !== undefined)
+                group.description = String(entry.description);
+            notes.groups.push(group);
+        });
+    }
+    return notes;
+}
+export function applyNotes(input, notes) {
+    const model = structuredClone(input);
+    const warnings = [];
+    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 = {
+            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, b) {
+    return a.table === b.table && a.columns.join(',') === b.columns.join(',');
+}

package/dist/plugins.d.ts

@@ -0,0 +1,18 @@
+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 declare function sourceModuleName(source: SourceConfig): string;
+export declare function loadSource(source: SourceConfig, importer?: Importer): Promise<Source>;
+/** 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 declare function addonModuleName(addon: AddonConfig): string;
+export declare function loadAddon(addon: AddonConfig, importer?: Importer): Promise<Addon>;

package/dist/plugins.js

@@ -0,0 +1,50 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+export function sourceModuleName(source) {
+    return source.module ?? `dbtour-source-${source.type}`;
+}
+export async function loadSource(source, importer = (s) => import(__rewriteRelativeImportExtension(s))) {
+    const name = sourceModuleName(source);
+    let loaded;
+    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?.extract;
+    if (typeof extract !== 'function')
+        throw new Error(`${name} does not export extract(config), so it is not a dbtour source`);
+    return { extract: extract };
+}
+export function addonModuleName(addon) {
+    return addon.module ?? `dbtour-addon-${addon.type}`;
+}
+export async function loadAddon(addon, importer = (s) => import(__rewriteRelativeImportExtension(s))) {
+    const name = addonModuleName(addon);
+    let loaded;
+    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 ?? {};
+    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 = {};
+    if (typeof enrich === 'function')
+        result.enrich = enrich;
+    if (typeof render === 'function')
+        result.render = render;
+    return result;
+}

package/dist/render/markdown.d.ts

@@ -0,0 +1,8 @@
+import { findTable, type Model } 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;
+/** One table's page on its own: what the page hands to an agent. */
+export declare function renderTableMarkdown(model: Model, ref: string): string;
+export { findTable };

package/dist/render/markdown.js

@@ -0,0 +1,142 @@
+// 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 } from "../model.js";
+import { erDiagram, neighbourhood } from "./mermaid.js";
+// 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) {
+    const files = { '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) {
+    const parts = [];
+    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) {
+    const names = { mssql: 'SQL Server', postgres: 'PostgreSQL', mysql: 'MySQL', sqlite: 'SQLite' };
+    return names[driver] ?? driver;
+}
+function driverLine(database) {
+    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, ref) {
+    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, ref, table) {
+    const parts = [`# ${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 = [];
+        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) {
+    return '```mermaid\n' + diagram + '```\n';
+}
+/** A table cell: pipes and line breaks would end it. */
+function cell(text) {
+    return (text ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+export { findTable };

package/dist/render/mermaid.d.ts

@@ -0,0 +1,6 @@
+import { type Model } from '../model.ts';
+/** Mermaid takes letters, digits and underscores in an entity name. */
+export declare function entityName(ref: string): string;
+/** The table and every table one relation away, in the order the relations are listed. */
+export declare function neighbourhood(model: Model, ref: string): string[];
+export declare function erDiagram(model: Model, refs: string[]): string;

package/dist/render/mermaid.js

@@ -0,0 +1,72 @@
+// Mermaid erDiagram text: GitHub draws it in the Markdown, no image service needed.
+import { findTable, relationsOf } from "../model.js";
+/** Mermaid takes letters, digits and underscores in an entity name. */
+export function entityName(ref) {
+    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, ref) {
+    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, refs) {
+    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, column, foreign) {
+    const marks = [];
+    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) {
+    return type.replace(/^[^A-Za-z_]|[^A-Za-z0-9_,()[\]-]/g, '_');
+}
+function attributeName(name) {
+    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, relation) {
+    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) {
+    const text = relation.from.columns.join(', ') + (relation.virtual ? ' (notes)' : '');
+    return /^[A-Za-z0-9_]+$/.test(text) ? text : `"${text.replace(/"/g, "'")}"`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbtour",
-  "version": "0.2.0",
+  "version": "0.2.4",
   "description": "Tour your database and its API: searchable docs, relations and diagrams, generated from the schema, kept in the repo.",
   "type": "module",
   "license": "MIT",
@@ -17,14 +17,26 @@
     "dbtour": "bin/dbtour.mjs"
   },
   "exports": {
-    ".": "./src/index.ts",
-    "./model": "./src/model.ts",
-    "./markdown": "./src/render/markdown.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./model": {
+      "types": "./dist/model.d.ts",
+      "default": "./dist/model.js"
+    },
+    "./markdown": {
+      "types": "./dist/render/markdown.d.ts",
+      "default": "./dist/render/markdown.js"
+    }
   },
   "files": [
     "bin",
-    "src"
+    "dist"
   ],
+  "scripts": {
+    "prepack": "node ../../scripts/build.mjs"
+  },
   "keywords": [
     "database",
     "documentation",

package/src/cli.ts

@@ -1,156 +0,0 @@
-// 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;
-}