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

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":"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"}

package/dist/generators/ErdClusterer.js

@@ -0,0 +1,308 @@
+/**
+ * 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 { ERD_DEFAULTS } from '../types/config.js';
+/** The fold pass converges in one or two rounds; this caps a pathological ping-pong between two tiny areas. */
+const MAX_FOLD_PASSES = 5;
+export class ErdClusterer {
+    Plan(state, options = {}) {
+        const settings = this.resolveSettings(options);
+        const graph = this.buildGraph(state, options, settings);
+        const forcedHubs = graph.forcedHubs;
+        const connected = [...graph.tables.keys()].filter(k => !graph.references.has(k) && this.neighbours(graph, k).size > 0);
+        const isolated = [...graph.tables.keys()].filter(k => !graph.references.has(k) && this.neighbours(graph, k).size === 0);
+        const hubs = this.selectHubs(graph, connected, forcedHubs, settings);
+        let owner = this.assignToNearestHub(graph, hubs);
+        owner = this.foldUndersizedClusters(graph, owner, forcedHubs, settings);
+        const members = new Map();
+        for (const [table, hub] of owner) {
+            if (!members.has(hub))
+                members.set(hub, []);
+            members.get(hub).push(table);
+        }
+        this.warnAboutUndersizedClusters(graph, members, forcedHubs, settings);
+        const clusters = [...members].map(([hub, list]) => this.buildCluster(graph, owner, hub, list, settings));
+        clusters.sort((a, b) => b.Tables.length - a.Tables.length || a.HubName.localeCompare(b.HubName));
+        this.assignPageFileNames(clusters);
+        return {
+            Clusters: clusters,
+            Warnings: graph.warnings,
+            ReferenceTables: [...graph.references]
+                .map(k => ({ Table: graph.nameOf(k), ReferencedBy: graph.inbound.get(k) ?? 0 }))
+                .sort((a, b) => b.ReferencedBy - a.ReferencedBy || a.Table.localeCompare(b.Table)),
+            IsolatedTables: isolated.map(graph.nameOf).sort(),
+            UnassignedTables: connected.filter(k => !owner.has(k)).map(graph.nameOf).sort(),
+            ExcludedTables: [...graph.excludedNames].sort(),
+            TotalTables: graph.tables.size,
+            TotalEdges: graph.edges.size,
+            Options: settings,
+            NameOf: graph.nameOf,
+            TableOf: (key) => graph.tables.get(key),
+        };
+    }
+    /** Defaults fill the gaps; every count must be at least 1 or the pagination and hub selection degenerate. */
+    resolveSettings(options) {
+        const atLeastOne = (name, value) => {
+            const resolved = value ?? ERD_DEFAULTS[name];
+            if (!Number.isInteger(resolved) || resolved < 1) {
+                throw new Error(`ERD setting ${name} must be a whole number of at least 1 (got ${String(value)})`);
+            }
+            return resolved;
+        };
+        return {
+            hubMinInbound: atLeastOne('hubMinInbound', options.hubMinInbound),
+            lookupMaxRows: atLeastOne('lookupMaxRows', options.lookupMaxRows),
+            pageSize: atLeastOne('pageSize', options.pageSize),
+            minClusterSize: atLeastOne('minClusterSize', options.minClusterSize),
+        };
+    }
+    /** Index the tables, resolve exclusions and reference tables, and collect the FK graph. */
+    buildGraph(state, options, settings) {
+        const tables = new Map();
+        const schemaOf = new Map();
+        for (const schema of state.schemas) {
+            for (const table of schema.tables) {
+                tables.set(`${schema.name}.${table.name}`, table);
+                schemaOf.set(`${schema.name}.${table.name}`, schema.name);
+            }
+        }
+        // A table is shown with its schema only when another schema has a table of the same name.
+        const nameCounts = new Map();
+        for (const t of tables.values())
+            nameCounts.set(t.name, (nameCounts.get(t.name) ?? 0) + 1);
+        const nameOf = (key) => {
+            const table = tables.get(key);
+            if (!table)
+                return key;
+            return (nameCounts.get(table.name) ?? 0) > 1 ? `${schemaOf.get(key)}.${table.name}` : table.name;
+        };
+        const graph = {
+            tables, schemaOf, nameOf, warnings: [], excludedNames: [], forcedHubs: new Set(),
+            edges: new Map(), inbound: new Map(), outbound: new Map(), adjacency: new Map(), hubScore: new Map(), references: new Set(),
+        };
+        const excluded = this.resolveNamed(graph, options.excludeTables, 'excludeTables');
+        for (const key of excluded) {
+            graph.excludedNames.push(nameOf(key));
+            tables.delete(key);
+        }
+        this.collectEdges(graph);
+        graph.forcedHubs = this.resolveNamed(graph, options.hubs, 'hubs');
+        const forcedLookups = this.resolveNamed(graph, options.lookupTables, 'lookupTables');
+        for (const key of tables.keys()) {
+            if (this.isReferenceTable(graph, key, graph.forcedHubs, forcedLookups, settings))
+                graph.references.add(key);
+        }
+        for (const edge of graph.edges.values()) {
+            if (graph.references.has(edge.From) || graph.references.has(edge.To))
+                continue;
+            this.link(graph, edge.From, edge.To);
+            this.link(graph, edge.To, edge.From);
+            graph.hubScore.set(edge.To, (graph.hubScore.get(edge.To) ?? 0) + 1);
+        }
+        return graph;
+    }
+    /** Distinct FK edges between known tables (a table may reference another through several columns). */
+    collectEdges(graph) {
+        for (const [from, table] of graph.tables) {
+            for (const dep of table.dependsOn ?? []) {
+                const to = this.resolveTarget(graph, dep.schema ?? graph.schemaOf.get(from), dep.table ?? '');
+                if (!to || to === from)
+                    continue;
+                const id = `${from}->${to}`;
+                if (graph.edges.has(id))
+                    continue;
+                graph.edges.set(id, { From: from, To: to, FromColumn: dep.column, ToColumn: dep.referencedColumn });
+                graph.outbound.set(from, (graph.outbound.get(from) ?? 0) + 1);
+                graph.inbound.set(to, (graph.inbound.get(to) ?? 0) + 1);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    resolveTarget(graph, schema, name) {
+        const inSchema = `${schema}.${name}`;
+        if (graph.tables.has(inSchema))
+            return inSchema;
+        if (graph.tables.has(name))
+            return name;
+        return undefined;
+    }
+    /** A configured table name may be given as `schema.table` or as a bare name (any schema, case-insensitive). */
+    resolveNamed(graph, names, setting) {
+        const keys = new Set();
+        for (const name of names ?? []) {
+            const wanted = name.toLowerCase();
+            const matches = graph.tables.has(name)
+                ? [name]
+                : [...graph.tables.keys()].filter(k => k.toLowerCase() === wanted || graph.tables.get(k).name.toLowerCase() === wanted);
+            if (matches.length === 0)
+                graph.warnings.push(`${setting}: no table named '${name}'`);
+            for (const k of matches)
+                keys.add(k);
+        }
+        return keys;
+    }
+    isReferenceTable(graph, key, forcedHubs, forcedLookups, settings) {
+        if (forcedHubs.has(key))
+            return false;
+        if (forcedLookups.has(key))
+            return true;
+        return (graph.outbound.get(key) ?? 0) === 0
+            && (graph.inbound.get(key) ?? 0) >= 1
+            && (graph.tables.get(key).rowCount ?? 0) < settings.lookupMaxRows;
+    }
+    link(graph, a, b) {
+        if (!graph.adjacency.has(a))
+            graph.adjacency.set(a, new Set());
+        graph.adjacency.get(a).add(b);
+    }
+    neighbours(graph, key) {
+        return graph.adjacency.get(key) ?? new Set();
+    }
+    selectHubs(graph, connected, forcedHubs, settings) {
+        for (const hub of forcedHubs) {
+            if (!connected.includes(hub)) {
+                graph.warnings.push(`hubs: '${graph.nameOf(hub)}' has no foreign-key relationships to other drawn tables and cannot anchor a subject area`);
+            }
+        }
+        const score = (key) => graph.hubScore.get(key) ?? 0;
+        return connected
+            .filter(k => forcedHubs.has(k) || score(k) >= settings.hubMinInbound)
+            .sort((a, b) => score(b) - score(a));
+    }
+    /** Multi-source breadth-first search: every reachable table belongs to the hub nearest to it. */
+    assignToNearestHub(graph, hubs) {
+        const owner = new Map();
+        const queue = [];
+        for (const hub of hubs) {
+            owner.set(hub, hub);
+            queue.push(hub);
+        }
+        for (let head = 0; head < queue.length; head++) {
+            const current = queue[head];
+            for (const next of this.neighbours(graph, current)) {
+                if (!owner.has(next)) {
+                    owner.set(next, owner.get(current));
+                    queue.push(next);
+                }
+            }
+        }
+        return owner;
+    }
+    /** Fold each cluster below the minimum size into the neighbouring cluster its members link to most. */
+    foldUndersizedClusters(graph, owner, forcedHubs, settings) {
+        for (let pass = 0; pass < MAX_FOLD_PASSES; pass++) {
+            const sizes = new Map();
+            for (const hub of owner.values())
+                sizes.set(hub, (sizes.get(hub) ?? 0) + 1);
+            const tiny = new Set([...sizes].filter(([hub, n]) => n < settings.minClusterSize && !forcedHubs.has(hub)).map(([hub]) => hub));
+            if (tiny.size === 0)
+                break;
+            for (const hub of tiny) {
+                const votes = new Map();
+                for (const [table, o] of owner) {
+                    if (o !== hub)
+                        continue;
+                    for (const n of this.neighbours(graph, table)) {
+                        const target = owner.get(n);
+                        if (target && target !== hub && !tiny.has(target))
+                            votes.set(target, (votes.get(target) ?? 0) + 1);
+                    }
+                }
+                const best = [...votes].sort((a, b) => b[1] - a[1])[0];
+                if (!best)
+                    continue;
+                for (const [table, o] of owner)
+                    if (o === hub)
+                        owner.set(table, best[0]);
+            }
+        }
+        return owner;
+    }
+    /**
+     * 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.
+     */
+    warnAboutUndersizedClusters(graph, members, forcedHubs, settings) {
+        const undersized = [...members]
+            .filter(([hub, list]) => list.length < settings.minClusterSize && !forcedHubs.has(hub))
+            .sort((a, b) => graph.nameOf(a[0]).localeCompare(graph.nameOf(b[0])));
+        for (const [hub, list] of undersized) {
+            graph.warnings.push(`minClusterSize: subject area '${graph.nameOf(hub)}' has ${list.length} table(s), below the minimum of ${settings.minClusterSize}, and no larger neighbouring area to fold into`);
+        }
+    }
+    buildCluster(graph, owner, hub, list, settings) {
+        const score = (key) => graph.hubScore.get(key) ?? 0;
+        const rest = list.filter(k => k !== hub).sort((a, b) => (score(b) - score(a)) || a.localeCompare(b));
+        const ordered = [hub, ...rest];
+        const inside = new Set(ordered);
+        const pages = [];
+        for (let i = 0, n = 1; i < Math.max(1, rest.length); i += settings.pageSize, n++) {
+            pages.push({ Number: n, Tables: [hub, ...rest.slice(i, i + settings.pageSize)], BaseName: '', Title: '' });
+        }
+        const internal = [], outboundEdges = [], inboundEdges = [];
+        const referenceUse = new Map();
+        for (const e of graph.edges.values()) {
+            if (inside.has(e.From) && inside.has(e.To))
+                internal.push(e);
+            else if (inside.has(e.From) && graph.references.has(e.To))
+                referenceUse.set(e.To, (referenceUse.get(e.To) ?? 0) + 1);
+            else if (inside.has(e.From) && owner.has(e.To))
+                outboundEdges.push(e);
+            else if (inside.has(e.To) && owner.has(e.From))
+                inboundEdges.push(e);
+        }
+        return {
+            Hub: hub,
+            HubName: graph.nameOf(hub),
+            Tables: ordered,
+            Pages: pages,
+            InternalEdges: internal,
+            OutboundEdges: outboundEdges,
+            InboundEdges: inboundEdges,
+            ReferenceTables: [...referenceUse]
+                .map(([t, n]) => ({ Table: graph.nameOf(t), UsedBy: n }))
+                .sort((a, b) => b.UsedBy - a.UsedBy || a.Table.localeCompare(b.Table)),
+        };
+    }
+    /**
+     * 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.
+     */
+    assignPageFileNames(clusters) {
+        const taken = new Map();
+        for (const cluster of clusters) {
+            const base = `cluster-${cluster.HubName.replace(/[^A-Za-z0-9_]/g, '_')}`;
+            const seen = taken.get(base) ?? 0;
+            taken.set(base, seen + 1);
+            const unique = seen === 0 ? base : `${base}~${seen + 1}`;
+            const multi = cluster.Pages.length > 1;
+            for (const page of cluster.Pages) {
+                page.BaseName = multi ? `${unique}-${page.Number}` : unique;
+                page.Title = multi ? `${cluster.HubName} (${page.Number} of ${cluster.Pages.length})` : cluster.HubName;
+            }
+        }
+    }
+}
+//# sourceMappingURL=ErdClusterer.js.map

package/dist/generators/ErdClusterer.js.map

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

package/dist/generators/HTMLGenerator.d.ts

@@ -2,10 +2,15 @@
  * Generates interactive HTML documentation with Mermaid ERD
  */
 import { DatabaseDocumentation } from '../types/state.js';
+import { ErdClusterPlan } from './ErdClusterer.js';
 export interface HTMLGeneratorOptions {
     approvedOnly?: boolean;
     confidenceThreshold?: number;
     includeMermaid?: boolean;
+    /** When set, a "Subject areas" section links to the per-cluster diagrams and the inline per-schema ERD is replaced by a link to them. */
+    clusterPlan?: ErdClusterPlan;
+    /** Directory of the cluster pages, relative to documentation.html. Default `erd`. */
+    clusterDir?: string;
 }
 export declare class HTMLGenerator {
     /**
@@ -23,6 +28,7 @@ export declare class HTMLGenerator {
     private appendSearchableList;
     private appendSearchScript;
     private appendSchemas;
+    private appendSubjectAreas;
     private generateMermaidERD;
     private toAnchor;
     private escapeHtml;

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

@@ -1 +1 @@
-{"version":3,"file":"HTMLGenerator.d.ts","sourceRoot":"","sources":["../../src/generators/HTMLGenerator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qBAAa,aAAa;IACxB;;OAEG;IACI,QAAQ,CACb,KAAK,EAAE,qBAAqB,EAC5B,OAAO,GAAE,oBAAyB,GACjC,MAAM;IAyCT,wCAAwC;IACjC,QAAQ,CACb,KAAK,EAAE,qBAAqB,EAC5B,OAAO,GAAE,oBAAyB,GACjC,MAAM;IAIT,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,YAAY;IAwWpB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,qBAAqB;IA2C7B,OAAO,CAAC,qBAAqB;IAyB7B,OAAO,CAAC,oBAAoB;IAoD5B,OAAO,CAAC,kBAAkB;IAwC1B,OAAO,CAAC,aAAa;IAsHrB,OAAO,CAAC,kBAAkB;IAoC1B,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,UAAU;CAGnB"}
+{"version":3,"file":"HTMLGenerator.d.ts","sourceRoot":"","sources":["../../src/generators/HTMLGenerator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKnD,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yIAAyI;IACzI,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IACxB;;OAEG;IACI,QAAQ,CACb,KAAK,EAAE,qBAAqB,EAC5B,OAAO,GAAE,oBAAyB,GACjC,MAAM;IA8CT,wCAAwC;IACjC,QAAQ,CACb,KAAK,EAAE,qBAAqB,EAC5B,OAAO,GAAE,oBAAyB,GACjC,MAAM;IAIT,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,YAAY;IAwWpB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,qBAAqB;IA2C7B,OAAO,CAAC,qBAAqB;IAyB7B,OAAO,CAAC,oBAAoB;IAoD5B,OAAO,CAAC,kBAAkB;IAwC1B,OAAO,CAAC,aAAa;IA2HrB,OAAO,CAAC,kBAAkB;IAoB1B,OAAO,CAAC,kBAAkB;IAoC1B,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,UAAU;CAGnB"}

package/dist/generators/HTMLGenerator.js

@@ -1,6 +1,8 @@
 /**
  * Generates interactive HTML documentation with Mermaid ERD
  */
+/** Hub descriptions are long; the Subject Areas table shows this much of each. */
+const SUBJECT_AREA_DESCRIPTION_CHARS = 200;
 export class HTMLGenerator {
     /**
      * Generate interactive HTML documentation
@@ -16,13 +18,17 @@ export class HTMLGenerator {
         this.appendHeaderSection(htmlLines, state);
         // Sidebar with navigation
         htmlLines.push('<div class="main-wrapper">');
-        this.appendSidebar(htmlLines, state);
+        this.appendSidebar(htmlLines, state, options);
         // Main content
         htmlLines.push('<div class="main-content">');
         // Analysis summary
         this.appendAnalysisSummary(htmlLines, state);
         // Database context
         this.appendDatabaseContext(htmlLines, state);
+        // Subject areas (clustered ERDs), when export produced them
+        if (options.clusterPlan) {
+            this.appendSubjectAreas(htmlLines, options.clusterPlan, options.clusterDir ?? 'erd');
+        }
         // Searchable table/column list
         this.appendSearchableList(htmlLines, state, options);
         // Schemas with ERD and tables
@@ -417,8 +423,12 @@ export class HTMLGenerator {
         lines.push('</div>');
         lines.push('</header>');
     }
-    appendSidebar(lines, state) {
+    appendSidebar(lines, state, options = {}) {
         lines.push('<aside class="sidebar">');
+        if (options.clusterPlan) {
+            lines.push('<h3>🗺️ Subject Areas</h3>');
+            lines.push('<a href="#subject-areas">Overview</a>');
+        }
         lines.push('<h3>📑 Schemas</h3>');
         for (const schema of state.schemas) {
             lines.push(`<a href="#schema-${this.toAnchor(schema.name)}">${this.escapeHtml(schema.name)}</a>`);
@@ -577,11 +587,17 @@ export class HTMLGenerator {
             if (schema.businessDomains && schema.businessDomains.length > 0) {
                 lines.push(`<p><strong>Business Domains:</strong> ${schema.businessDomains.map(d => this.escapeHtml(d)).join(', ')}</p>`);
             }
-            // Entity Relationship Diagram
+            // Entity Relationship Diagram. With a cluster plan the schema-wide diagram is replaced by the
+            // subject-area pages: one diagram of every table exceeds Mermaid's text limit on large schemas.
             lines.push('<h3>Entity Relationship Diagram</h3>');
-            lines.push('<div class="mermaid">');
-            lines.push(this.generateMermaidERD(schema));
-            lines.push('</div>');
+            if (options.clusterPlan) {
+                lines.push(`<p>Drawn per subject area — see <a href="#subject-areas">Subject Areas</a> or open <a href="${this.escapeHtml(options.clusterDir ?? 'erd')}/index.html">the subject-area index</a>.</p>`);
+            }
+            else {
+                lines.push('<div class="mermaid">');
+                lines.push(this.generateMermaidERD(schema));
+                lines.push('</div>');
+            }
             // Tables
             lines.push('<h3>Tables</h3>');
             for (const table of schema.tables) {
@@ -659,6 +675,25 @@ export class HTMLGenerator {
         lines.push('<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"><\/script>');
         lines.push('<script>mermaid.initialize({ startOnLoad: true, theme: "default" }); mermaid.contentLoaded();<\/script>');
     }
+    appendSubjectAreas(lines, plan, dir) {
+        const covered = plan.Clusters.reduce((n, c) => n + c.Tables.length, 0);
+        lines.push('<section id="subject-areas">');
+        lines.push('<h2>🗺️ Subject Areas</h2>');
+        lines.push(`<p>${plan.TotalTables} tables and ${plan.TotalEdges} foreign-key relationships, drawn as ${plan.Clusters.length} subject areas covering ${covered} tables. Each area is centred on a hub table that many others reference. <a href="${this.escapeHtml(dir)}/index.html">Open the subject-area index</a> for reference tables and tables outside every area.</p>`);
+        lines.push('<table>');
+        lines.push('<thead><tr><th>Subject area</th><th>Tables</th><th>Diagram</th><th>Hub description</th></tr></thead>');
+        lines.push('<tbody>');
+        for (const cluster of plan.Clusters) {
+            const hub = plan.TableOf(cluster.Hub);
+            const pages = cluster.Pages.length > 1
+                ? cluster.Pages.map(p => `<a href="${this.escapeHtml(`${dir}/${p.BaseName}`)}.html">page ${p.Number}</a>`).join(', ')
+                : `<a href="${this.escapeHtml(`${dir}/${cluster.Pages[0].BaseName}`)}.html">diagram</a>`;
+            lines.push(`<tr><td><a href="#table-${this.toAnchor(hub.name)}">${this.escapeHtml(cluster.HubName)}</a></td><td>${cluster.Tables.length}</td><td>${pages}</td><td>${this.escapeHtml((hub.description ?? '').slice(0, SUBJECT_AREA_DESCRIPTION_CHARS))}</td></tr>`);
+        }
+        lines.push('</tbody>');
+        lines.push('</table>');
+        lines.push('</section>');
+    }
     generateMermaidERD(schema) {
         const lines = [];
         lines.push('erDiagram');