@memberjunction/db-auto-doc 6.2.0-edge.4 → 6.2.0-edge.6

package/dist/generators/ErdClusterGenerator.js

@@ -0,0 +1,216 @@
+/**
+ * Renders an ErdClusterPlan as one Mermaid ERD per cluster page, each wrapped in a standalone HTML
+ * page, plus an index (HTML and Markdown) that lists the subject areas, the reference tables and the
+ * tables no diagram shows. Every page stays well inside Mermaid's text limit by drawing primary and
+ * foreign key columns only (configurable).
+ */
+/** Mermaid's default maxTextSize is 50,000; pages stay well below it, this is the viewer's ceiling. */
+const VIEWER_MAX_TEXT_SIZE = 200000;
+/** Mermaid's default maxEdges is 500; a hub page can carry more relationships than that. */
+const VIEWER_MAX_EDGES = 5000;
+/** Hub descriptions are long; the index shows this much of each. */
+const INDEX_DESCRIPTION_CHARS = 160;
+export class ErdClusterGenerator {
+    Generate(state, plan, options = {}) {
+        const columns = options.columns ?? 'keys';
+        const files = [];
+        for (const cluster of plan.Clusters) {
+            for (const page of cluster.Pages) {
+                const title = `${page.Title} — ${page.Tables.length} tables`;
+                const mermaid = this.RenderPage(plan, cluster, page, columns);
+                files.push({
+                    BaseName: page.BaseName,
+                    Title: title,
+                    Cluster: cluster,
+                    Page: page,
+                    Mermaid: mermaid,
+                    Html: this.renderPageHtml(state, plan, cluster, page, title, mermaid),
+                });
+            }
+        }
+        return {
+            Files: files,
+            IndexHtml: this.renderIndexHtml(state, plan, files),
+            IndexMarkdown: this.renderIndexMarkdown(state, plan, files),
+        };
+    }
+    /** The Mermaid source for one page: its tables and the FK edges between them. */
+    RenderPage(plan, cluster, page, columns = 'keys') {
+        const onPage = new Set(page.Tables);
+        const lines = ['erDiagram'];
+        for (const key of page.Tables) {
+            // Entity and relationship lines must agree on the name; the plan's display name is unique across schemas
+            lines.push(`    ${this.identifier(plan.NameOf(key))} {`);
+            for (const column of plan.TableOf(key).columns) {
+                if (!this.showColumn(column, columns))
+                    continue;
+                const flags = [column.isPrimaryKey && 'PK', column.isForeignKey && 'FK'].filter(Boolean).join(',');
+                const type = (column.dataType || 'unknown').replace(/\s+/g, '_');
+                lines.push(`        ${type} ${this.identifier(column.name)}${flags ? ` "${flags}"` : ''}`);
+            }
+            lines.push('    }');
+        }
+        for (const edge of cluster.InternalEdges) {
+            if (onPage.has(edge.From) && onPage.has(edge.To)) {
+                const parent = this.identifier(plan.NameOf(edge.To));
+                const child = this.identifier(plan.NameOf(edge.From));
+                lines.push(`    ${parent} ||--o{ ${child} : "${this.identifier(edge.FromColumn || '')}"`);
+            }
+        }
+        return lines.join('\n');
+    }
+    showColumn(column, mode) {
+        if (mode === 'none')
+            return false;
+        if (mode === 'all')
+            return true;
+        return column.isPrimaryKey || column.isForeignKey;
+    }
+    /** Mermaid entity and attribute names allow only word characters. */
+    identifier(name) {
+        return name.replace(/[^A-Za-z0-9_]/g, '_');
+    }
+    /** `label` plus the tables at the far end of `edges`, each with how many edges reach it. */
+    linkedAreas(plan, label, edges, farEnd) {
+        if (edges.length === 0)
+            return '';
+        const counts = new Map();
+        for (const e of edges)
+            counts.set(farEnd(e), (counts.get(farEnd(e)) ?? 0) + 1);
+        const items = [...counts]
+            .sort((a, b) => b[1] - a[1])
+            .map(([t, n]) => `${this.escape(plan.NameOf(t))} <span class="count">(${n})</span>`)
+            .join(', ');
+        return `<h3>${label}</h3><p class="refs">${items}</p>`;
+    }
+    renderPageHtml(state, plan, cluster, page, title, mermaid) {
+        const hub = plan.TableOf(cluster.Hub);
+        const pageLinks = cluster.Pages
+            .map(p => p.Number === page.Number ? `<strong>${p.Number}</strong>` : `<a href="${p.BaseName}.html">${p.Number}</a>`)
+            .join(' · ');
+        const otherPages = cluster.Pages.length > 1 ? `<p>Pages: ${pageLinks}</p>` : '';
+        const referenceItems = cluster.ReferenceTables
+            .map(r => `${this.escape(r.Table)} <span class="count">(${r.UsedBy})</span>`)
+            .join(', ');
+        const references = cluster.ReferenceTables.length > 0
+            ? `<h3>Reference tables used by this area</h3><p class="refs">${referenceItems}</p>`
+            : '';
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${this.escape(title)} - ${this.escape(state.database.name)}</title>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"><\/script>
+<style>
+  body { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; margin: 1.5rem; color: #333; }
+  h1 { color: #667eea; margin-bottom: .25rem; }
+  .desc { max-width: 70rem; color: #555; }
+  .mermaid { overflow: auto; background: #f9f9f9; border: 1px solid #e0e0e0; border-radius: 4px; padding: 1rem; }
+  .refs { max-width: 70rem; line-height: 1.6; }
+  .count { color: #888; }
+  nav a { margin-right: 1rem; }
+</style>
+</head>
+<body>
+<nav><a href="index.html">All subject areas</a><a href="../documentation.html">Documentation</a></nav>
+<h1>${this.escape(title)}</h1>
+${hub.description ? `<p class="desc">${this.escape(hub.description)}</p>` : ''}
+${otherPages}
+<pre class="mermaid">
+${this.escape(mermaid)}
+</pre>
+${references}
+${this.linkedAreas(plan, 'References tables in other areas', cluster.OutboundEdges, e => e.To)}
+${this.linkedAreas(plan, 'Referenced from other areas', cluster.InboundEdges, e => e.From)}
+<script>mermaid.initialize({ startOnLoad: true, theme: 'default', securityLevel: 'loose', maxTextSize: ${VIEWER_MAX_TEXT_SIZE}, maxEdges: ${VIEWER_MAX_EDGES} });<\/script>
+</body>
+</html>`;
+    }
+    renderIndexHtml(state, plan, files) {
+        const rows = files.map(f => {
+            const hub = plan.TableOf(f.Cluster.Hub);
+            const description = this.escape((hub.description ?? '').slice(0, INDEX_DESCRIPTION_CHARS));
+            return `<tr><td><a href="${f.BaseName}.html">${this.escape(f.Title)}</a></td>`
+                + `<td>${f.Cluster.Tables.length}</td><td>${f.Cluster.InternalEdges.length}</td>`
+                + `<td>${f.Cluster.OutboundEdges.length} / ${f.Cluster.InboundEdges.length}</td><td>${description}</td></tr>`;
+        }).join('\n');
+        const list = (title, items) => items.length === 0
+            ? ''
+            : `<h2>${title} (${items.length})</h2><p class="refs">${items.map(i => this.escape(i)).join(', ')}</p>`;
+        const summary = this.planSummary(plan, 'html');
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Subject areas - ${this.escape(state.database.name)}</title>
+<style>
+  body { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; margin: 1.5rem; color: #333; max-width: 80rem; }
+  h1 { color: #667eea; }
+  table { border-collapse: collapse; width: 100%; }
+  th, td { border: 1px solid #ddd; padding: .4rem .6rem; text-align: left; vertical-align: top; }
+  th { background: #f4f4f8; }
+  .refs { line-height: 1.6; color: #555; }
+  .meta { color: #666; }
+</style>
+</head>
+<body>
+<p><a href="../documentation.html">Documentation</a></p>
+<h1>Subject areas — ${this.escape(state.database.name)}</h1>
+<p class="meta">${summary}</p>
+<table>
+<thead><tr><th>Subject area</th><th>Tables</th><th>FKs inside</th><th>Links out / in</th><th>Hub description</th></tr></thead>
+<tbody>
+${rows}
+</tbody>
+</table>
+${list('Reference tables (listed, not drawn)', plan.ReferenceTables.map(r => `${r.Table} (${r.ReferencedBy})`))}
+${list('Tables with no foreign keys', plan.IsolatedTables)}
+${list('Connected tables outside every subject area', plan.UnassignedTables)}
+${list('Excluded by configuration', plan.ExcludedTables)}
+</body>
+</html>`;
+    }
+    renderIndexMarkdown(state, plan, files) {
+        const md = [
+            `# Subject areas — ${state.database.name}`,
+            '',
+            this.planSummary(plan, 'markdown'),
+            '',
+            '| Subject area | Tables | FKs inside | Links out / in | Hub description |',
+            '|---|---|---|---|---|',
+        ];
+        for (const f of files) {
+            const hub = plan.TableOf(f.Cluster.Hub);
+            const description = (hub.description ?? '').replace(/\|/g, '/').slice(0, INDEX_DESCRIPTION_CHARS);
+            const c = f.Cluster;
+            md.push(`| [${f.Title}](${f.BaseName}.html) | ${c.Tables.length} | ${c.InternalEdges.length} | ${c.OutboundEdges.length} / ${c.InboundEdges.length} | ${description} |`);
+        }
+        md.push('', '## Membership', '');
+        for (const c of plan.Clusters)
+            md.push(`**${c.HubName}**: ${c.Tables.map(plan.NameOf).join(', ')}`, '');
+        const section = (title, items) => {
+            if (items.length > 0)
+                md.push(`## ${title} (${items.length})`, '', items.join(', '), '');
+        };
+        section('Reference tables (listed, not drawn)', plan.ReferenceTables.map(r => `${r.Table} (${r.ReferencedBy})`));
+        section('Tables with no foreign keys', plan.IsolatedTables);
+        section('Connected tables outside every subject area', plan.UnassignedTables);
+        section('Excluded by configuration', plan.ExcludedTables);
+        return md.join('\n');
+    }
+    /** The one-paragraph description of how the plan was built, shared by both indexes. */
+    planSummary(plan, format) {
+        const covered = plan.Clusters.reduce((n, c) => n + c.Tables.length, 0);
+        const rows = plan.Options.lookupMaxRows.toLocaleString();
+        const head = `${plan.TotalTables} tables and ${plan.TotalEdges} foreign-key relationships. ${plan.Clusters.length} subject areas cover ${covered} tables`;
+        return format === 'html'
+            ? `${head}; hubs are tables referenced by at least ${plan.Options.hubMinInbound} others, reference tables are those that reference nothing and hold fewer than ${rows} rows.`
+            : `${head} (hubs: referenced by ≥ ${plan.Options.hubMinInbound}; reference tables: reference nothing and < ${rows} rows).`;
+    }
+    escape(text) {
+        return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    }
+}
+//# sourceMappingURL=ErdClusterGenerator.js.map

package/dist/generators/ErdClusterGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErdClusterGenerator.js","sourceRoot":"","sources":["../../src/generators/ErdClusterGenerator.ts"],"names":[],"mappings":"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"}

package/dist/generators/ErdClusterer.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Splits a database's foreign-key graph into hub-centred clusters ("subject areas") small enough
+ * to draw one at a time. Pure computation over the analysis state; rendering lives in
+ * ErdClusterGenerator.
+ *
+ * Method:
+ *  1. Reference (lookup) tables — tables that reference nothing and hold few rows — are set aside.
+ *     Left in, a table such as a yes/no flag referenced by sixty others links every subject area to
+ *     every other and the clusters collapse into one.
+ *  2. Hubs are the tables referenced by at least `hubMinInbound` non-reference tables, plus any
+ *     names in `hubs`.
+ *  3. Every other connected table is assigned to its nearest hub (multi-source breadth-first search
+ *     over the undirected FK graph).
+ *  4. A hub whose cluster is smaller than `minClusterSize` is folded into the neighbouring cluster
+ *     its members link to most, so the index is not littered with two-table "areas".
+ *  5. A cluster larger than `pageSize` is paginated; the hub appears on every page.
+ *
+ * Tables are keyed `schema.table` with case preserved: same-named tables in different schemas are
+ * different tables, and so are `Customer` and `customer` on PostgreSQL.
+ */
+import { DatabaseDocumentation, TableDefinition } from '../types/state.js';
+/** Mirrors the `output.erd` keys of config.json (camelCase) so a config object can be passed straight through. */
+export interface ErdClustererOptions {
+    hubMinInbound?: number;
+    lookupMaxRows?: number;
+    pageSize?: number;
+    minClusterSize?: number;
+    hubs?: string[];
+    excludeTables?: string[];
+    lookupTables?: string[];
+}
+/** One foreign key edge: `From.FromColumn` references `To.ToColumn`. Keys are `schema.table`. */
+export interface ErdEdge {
+    From: string;
+    To: string;
+    FromColumn: string;
+    ToColumn: string;
+}
+export interface ErdClusterPage {
+    /** 1-based page number within the cluster. */
+    Number: number;
+    /** `schema.table` keys on this page; the hub is always first. */
+    Tables: string[];
+    /** File name (without extension) every renderer uses for this page, unique across the plan. */
+    BaseName: string;
+    /** Page title, e.g. `Customer (2 of 5)`. */
+    Title: string;
+}
+export interface ErdCluster {
+    /** `schema.table` key of the hub table. */
+    Hub: string;
+    /** Display name of the hub table. */
+    HubName: string;
+    /** `schema.table` keys of every table in the cluster, hub first. */
+    Tables: string[];
+    Pages: ErdClusterPage[];
+    /** FK edges with both ends inside the cluster. */
+    InternalEdges: ErdEdge[];
+    /** FK edges leaving the cluster (From inside, To in another cluster). */
+    OutboundEdges: ErdEdge[];
+    /** FK edges entering the cluster (To inside, From in another cluster). */
+    InboundEdges: ErdEdge[];
+    /** Reference tables used by members of this cluster, with how many members use each. */
+    ReferenceTables: Array<{
+        Table: string;
+        UsedBy: number;
+    }>;
+}
+export type ErdClustererSettings = Required<Pick<ErdClustererOptions, 'hubMinInbound' | 'lookupMaxRows' | 'pageSize' | 'minClusterSize'>>;
+export interface ErdClusterPlan {
+    Clusters: ErdCluster[];
+    /** Settings that named tables the plan could not use (an unknown or edge-less hub, an unknown exclusion). */
+    Warnings: string[];
+    /** Reference tables set aside before clustering, with how many tables reference each. */
+    ReferenceTables: Array<{
+        Table: string;
+        ReferencedBy: number;
+    }>;
+    /** Tables with no foreign keys in either direction. */
+    IsolatedTables: string[];
+    /** Connected tables that reached no hub (small chains with no hub of their own). */
+    UnassignedTables: string[];
+    /** Tables removed by `excludeTables`. */
+    ExcludedTables: string[];
+    TotalTables: number;
+    TotalEdges: number;
+    Options: ErdClustererSettings;
+    /** Display name for a table key: the bare table name, or `schema.table` when another schema has a table of that name. */
+    NameOf(key: string): string;
+    /** The table definition for a key. */
+    TableOf(key: string): TableDefinition;
+}
+export declare class ErdClusterer {
+    Plan(state: DatabaseDocumentation, options?: ErdClustererOptions): ErdClusterPlan;
+    /** Defaults fill the gaps; every count must be at least 1 or the pagination and hub selection degenerate. */
+    private resolveSettings;
+    /** Index the tables, resolve exclusions and reference tables, and collect the FK graph. */
+    private buildGraph;
+    /** Distinct FK edges between known tables (a table may reference another through several columns). */
+    private collectEdges;
+    /**
+     * Resolve an FK target to a key. `dep.table` is usually the bare name within `dep.schema`, which also
+     * covers a table name that contains a dot (`Customer.bak`); the LLM sometimes writes `schema.table`
+     * instead, which the second lookup accepts.
+     */
+    private resolveTarget;
+    /** A configured table name may be given as `schema.table` or as a bare name (any schema, case-insensitive). */
+    private resolveNamed;
+    private isReferenceTable;
+    private link;
+    private neighbours;
+    private selectHubs;
+    /** Multi-source breadth-first search: every reachable table belongs to the hub nearest to it. */
+    private assignToNearestHub;
+    /** Fold each cluster below the minimum size into the neighbouring cluster its members link to most. */
+    private foldUndersizedClusters;
+    /**
+     * Folding only moves a small cluster into a larger neighbour, so two undersized clusters that
+     * link only to each other stay as they are. Say so rather than silently ignoring minClusterSize.
+     */
+    private warnAboutUndersizedClusters;
+    private buildCluster;
+    /**
+     * File names are decided once here so every renderer links to the same page. Two hubs whose names
+     * sanitise to the same identifier (`Order-Item`, `Order_Item`) get a numeric suffix instead of
+     * overwriting each other.
+     */
+    private assignPageFileNames;
+}
+//# sourceMappingURL=ErdClusterer.d.ts.map

package/dist/generators/ErdClusterer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErdClusterer.d.ts","sourceRoot":"","sources":["../../src/generators/ErdClusterer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAG3E,kHAAkH;AAClH,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,iGAAiG;AACjG,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,kDAAkD;IAClD,aAAa,EAAE,OAAO,EAAE,CAAC;IACzB,yEAAyE;IACzE,aAAa,EAAE,OAAO,EAAE,CAAC;IACzB,0EAA0E;IAC1E,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB,wFAAwF;IACxF,eAAe,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3D;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,IAAI,CAAC,mBAAmB,EAAE,eAAe,GAAG,eAAe,GAAG,UAAU,GAAG,gBAAgB,CAAC,CAAC,CAAC;AAE1I,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,6GAA6G;IAC7G,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,yFAAyF;IACzF,eAAe,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,uDAAuD;IACvD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,oFAAoF;IACpF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,yCAAyC;IACzC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,yHAAyH;IACzH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,sCAAsC;IACtC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAAC;CACvC;AAyBD,qBAAa,YAAY;IAChB,IAAI,CAAC,KAAK,EAAE,qBAAqB,EAAE,OAAO,GAAE,mBAAwB,GAAG,cAAc;IAuC5F,6GAA6G;IAC7G,OAAO,CAAC,eAAe;IAgBvB,2FAA2F;IAC3F,OAAO,CAAC,UAAU;IA+ClB,sGAAsG;IACtG,OAAO,CAAC,YAAY;IAcpB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAOrB,+GAA+G;IAC/G,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,IAAI;IAKZ,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,UAAU;IAYlB,iGAAiG;IACjG,OAAO,CAAC,kBAAkB;IAmB1B,uGAAuG;IACvG,OAAO,CAAC,sBAAsB;IAuB9B;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IASnC,OAAO,CAAC,YAAY;IAiCpB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;CAc5B"}