dbtour 0.2.0 → 0.2.4

package/bin/dbtour.mjs

@@ -1,9 +1,10 @@
 #!/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.
+// Node 22.18+ is what the published JavaScript targets; an older Node fails on syntax, 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');
+// dist/ is what `npm run build` emits and what the package ships; in the repository, build first.
+const { main } = await import('../dist/cli.js');
 process.exitCode = await main(process.argv.slice(2));

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+import { type AddonConfig, type SourceConfig } from './config.ts';
+import { type Addon, type Source } from './plugins.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>;
+}
+export declare function main(argv: string[], io?: Io): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,156 @@
+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;
+};
+// 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 } from "./config.js";
+import { emptyModel, validate } from "./model.js";
+import { applyNotes, parseNotes } from "./notes.js";
+import { loadAddon, loadSource } from "./plugins.js";
+import { renderMarkdown } from "./render/markdown.js";
+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, io = { cwd: process.cwd(), log: console.log, error: console.error }) {
+    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.exitCode ?? 1;
+    }
+}
+function missing(message) {
+    return Object.assign(new Error(message), { exitCode: 2 });
+}
+function init(io, source) {
+    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) {
+    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) {
+    const config = readConfig(io);
+    const env = io.env ?? process.env;
+    const load = io.load ?? ((source) => loadSource(source, importer(io.cwd)));
+    const 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;
+        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) {
+    return (specifier) => import(__rewriteRelativeImportExtension(specifier.startsWith('.') || specifier.startsWith('/') ? pathToFileURL(resolve(cwd, specifier)).href : specifier));
+}
+async function render(io) {
+    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) => loadAddon(addon, importer(io.cwd)));
+    const addons = [];
+    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/dist/config.d.ts

@@ -0,0 +1,26 @@
+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 declare const configFile = "dbtour.yaml";
+export declare const modelFile = "schema.json";
+export declare function parseConfig(text: string): Config;
+export declare function defaultConfigText(type: string): string;
+export declare function resolveConnection(value: string | undefined, env: Record<string, string | undefined>): string | undefined;

package/dist/config.js

@@ -0,0 +1,75 @@
+// dbtour.yaml: where the model goes, where it comes from, where the notes are.
+import { parse } from 'yaml';
+export const configFile = 'dbtour.yaml';
+export const modelFile = 'schema.json';
+export function parseConfig(text) {
+    const raw = 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;
+    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) => {
+        if (typeof value !== 'object' || value === null)
+            throw new Error(`sources[${i}] must be a map with type and name`);
+        const entry = value;
+        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) {
+    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) => {
+        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;
+        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) {
+    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, env) {
+    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/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./model.js";
+export { parseNotes, applyNotes } from "./notes.js";
+export { parseConfig, defaultConfigText, resolveConnection, configFile, modelFile } from "./config.js";
+export { loadSource, sourceModuleName, loadAddon, addonModuleName } from "./plugins.js";
+export { renderMarkdown, renderTableMarkdown, driverName, wholeDiagramLimit } from "./render/markdown.js";
+export { erDiagram, neighbourhood, entityName } from "./render/mermaid.js";

package/dist/model.d.ts

@@ -0,0 +1,121 @@
+export declare 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 declare function emptyModel(): Model;
+export interface TableRef {
+    schema: string;
+    table: string;
+    column?: string;
+}
+export declare function tableRef(schema: string, table: string): string;
+export declare function parseRef(ref: string): TableRef;
+export interface Found {
+    database: Database;
+    schema: Schema;
+    table: Table;
+}
+export declare function findTable(model: Model, ref: string): Found | undefined;
+/** Unique on its own, by a constraint or an index, and not the primary key, which says so already. */
+export declare function isUniqueColumn(table: Table, column: string): boolean;
+export declare function relationsOf(model: Model, ref: string): {
+    out: Relation[];
+    in: Relation[];
+};
+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 declare function validate(value: unknown): Validation;

package/dist/model.js

@@ -0,0 +1,210 @@
+// 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 function emptyModel() {
+    return { dbtour: MODEL_VERSION, databases: [], apis: [], links: [], groups: [] };
+}
+export function tableRef(schema, table) {
+    return `${schema}.${table}`;
+}
+export function parseRef(ref) {
+    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 function findTable(model, ref) {
+    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, column) {
+    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, ref) {
+    const out = [];
+    const inward = [];
+    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 };
+}
+/** Checks the shape, then that every relation points at a table in its database. */
+export function validate(value) {
+    const errors = [];
+    const check = new Checker(errors);
+    if (!check.object(value, 'model'))
+        return { ok: false, errors };
+    const model = value;
+    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;
+    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']) {
+                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, d, p) {
+    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, t, p) {
+    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;
+    constructor(errors) {
+        this.errors = errors;
+    }
+    object(value, path) {
+        if (typeof value === 'object' && value !== null && !Array.isArray(value))
+            return true;
+        this.errors.push(`${path} must be an object`);
+        return false;
+    }
+    string(value, path) {
+        if (typeof value !== 'string' || value === '')
+            this.errors.push(`${path} must be a non-empty string`);
+    }
+    optionalString(value, path) {
+        if (value !== undefined && typeof value !== 'string')
+            this.errors.push(`${path} must be a string when given`);
+    }
+    optionalBoolean(value, path) {
+        if (value !== undefined && typeof value !== 'boolean')
+            this.errors.push(`${path} must be true or false when given`);
+    }
+    strings(value, path) {
+        if (!Array.isArray(value) || value.some((v) => typeof v !== 'string'))
+            this.errors.push(`${path} must be a list of strings`);
+    }
+    list(value, path, each) {
+        if (!Array.isArray(value)) {
+            this.errors.push(`${path} must be a list`);
+            return;
+        }
+        value.forEach((item, i) => each(item, `${path}[${i}]`));
+    }
+}

package/dist/notes.d.ts

@@ -0,0 +1,21 @@
+import { type Group, type Model } 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 declare function parseNotes(text: string): Notes;
+export interface Applied {
+    model: Model;
+    /** What the notes name that the model does not have; said, then skipped. */
+    warnings: string[];
+}
+export declare function applyNotes(input: Model, notes: Notes): Applied;