dbtour 0.2.0 → 0.2.4

package/src/render/markdown.ts

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

@@ -1,75 +0,0 @@
-// 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, "'")}"`;
-}