dbtour 0.2.0 → 0.2.2

package/src/config.ts

@@ -1,93 +0,0 @@
-// 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/model.ts

@@ -1,318 +0,0 @@
-// 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

@@ -1,130 +0,0 @@
-// 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

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