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

package/README.md

@@ -63,8 +63,9 @@ graph TD
 - **CodeGen Integration** -- Emit `additionalSchemaInfo.json` for MemberJunction CodeGen soft FK/PK support
 - **Granular Guardrails** -- Multi-level resource controls (run, phase, iteration limits)
 - **Resume Capability** -- Pause and resume analysis from checkpoint state files
+- **Index Advisor** -- Built-in plugin that reads existing indexes, proposes missing ones (uncovered foreign keys, discovered primary keys) with an optional LLM review, flags redundant indexes, and exports the proposals as a SQL migration. See [Index Advisor](#index-advisor-built-in-plugin)
 - **Programmatic API** -- Use as a library in your own applications
-- **Extensible** -- Custom database drivers and analysis plugins
+- **Extensible** -- Custom database drivers, plus a [plugin system](#plugins) for adding steps before, during and after a run and new export formats
 
 ### Output Formats
 - **SQL Scripts** -- Database-specific metadata scripts (extended properties, comments)
@@ -74,6 +75,7 @@ graph TD
 - **Mermaid Diagrams** -- Standalone ERD files (.mmd and .html)
 - **Analysis Reports** -- Detailed metrics and quality assessments
 - **Additional Schema Info** -- CodeGen-compatible JSON for soft FK/PK metadata
+- **Index Migration** -- Flyway-style SQL migration creating the Index Advisor's proposed indexes (`export --format index-migration`)
 
 ## Installation
 
@@ -162,6 +164,38 @@ This will:
 - Perform sanity checks
 - Save state to `db-doc-state.json`
 
+#### Large databases
+
+```bash
+# Skip the table data sampling pass (row counts, distinct counts, sample values)
+db-auto-doc analyze --skip-sampling          # or "analysis": { "skipSampling": true }
+
+# An interrupted sampling pass resumes where it stopped: state is saved every 25 tables and a
+# resume samples only the tables that have no statistics yet
+db-auto-doc analyze --resume ./output/run-3/state.json
+```
+
+Sampling is what the enum/value-list verdicts and the organic-key cardinality gate are based on, so with
+`--skip-sampling` those verdicts fall back to the LLM's judgement. Organic-key detection is skipped with
+a warning when no table has column statistics; on a `--resume --skip-sampling` of a run that already
+sampled, the earlier statistics are kept and detection still runs.
+
+#### Seed context from files
+
+Long-form context (a data dictionary, an engineering assessment) can live in files instead of inline
+`customInstructions`; their contents are appended to it:
+
+```json
+"seedContext": {
+  "overallPurpose": "Association management system",
+  "file": "./context/data-dictionary.md",
+  "files": ["./context/assessment.md", "./context/glossary.md"]
+}
+```
+
+Paths are relative to `config.json`. The text is sent with every table prompt, so keep it to what the
+model needs for descriptions rather than a full specification.
+
 ### 3. Generate Sample Queries (Optional)
 
 Generate reference SQL queries for AI agent training:
@@ -319,6 +353,68 @@ Export only AI-discovered relationships (exclude hard DB constraints):
 db-auto-doc export --schema-info --schema-info-discovered-only --confidence-threshold 70
 ```
 
+Plugins can contribute their own export formats. List them, then generate one or more with `--format` (repeatable):
+
+```bash
+db-auto-doc export --state-file ./output/run-1/state.json --list-formats
+db-auto-doc export --state-file ./output/run-1/state.json --format index-migration
+```
+
+Dialect-specific formats take the database platform from the state file; override it with `--provider sqlserver|postgresql|mysql`. `--file-prefix` replaces a format's default file-name prefix (for example a migration version such as `V202610081500__`).
+
+#### Subject-area diagrams for large schemas
+
+Mermaid refuses a diagram whose source exceeds ~50,000 characters, and a schema of a few hundred tables
+passes that long before it becomes readable. `--erd-mode clusters` splits the foreign-key graph into
+hub-centred subject areas and writes one diagram per area to `erd/`, with an index and a "Subject Areas"
+section in `documentation.html`:
+
+```bash
+db-auto-doc export --html --mermaid --erd-mode clusters
+db-auto-doc export --mermaid --erd-mode both --erd-columns keys     # keep the full diagram too
+```
+
+How the areas are chosen:
+
+1. **Reference tables** — tables that reference nothing and hold fewer than `lookupMaxRows` rows
+   (status codes, types, flags) — are listed beside each diagram rather than drawn. Left in, a flag table
+   referenced by sixty others links every area to every other.
+2. **Hubs** are tables referenced by at least `hubMinInbound` other tables.
+3. Every other connected table joins its nearest hub; an area smaller than `minClusterSize` folds into
+   the neighbour it links to most.
+4. An area larger than `pageSize` is paginated, with the hub on every page.
+
+Defaults live in `config.json` and any of them can be overridden per run:
+
+```json
+"output": {
+  "erd": {
+    "mode": "clusters",
+    "columns": "keys",
+    "hubMinInbound": 8,
+    "lookupMaxRows": 5000,
+    "pageSize": 50,
+    "minClusterSize": 4,
+    "hubs": ["Invoice"],
+    "lookupTables": ["AuditFlag"],
+    "excludeTables": ["Customer.bak"]
+  }
+}
+```
+
+| Flag | Overrides |
+|------|-----------|
+| `--erd-mode full\|clusters\|both` | `erd.mode` |
+| `--erd-columns all\|keys\|none` | `erd.columns` (clusters default to `keys`) |
+| `--erd-hub-min-inbound N` | `erd.hubMinInbound` |
+| `--erd-lookup-max-rows N` | `erd.lookupMaxRows` |
+| `--erd-page-size N` | `erd.pageSize` |
+| `--erd-min-cluster-size N` | `erd.minClusterSize` |
+
+`erd/index.md` names every area's members, the reference tables, the tables with no foreign keys and any
+connected tables that reached no hub, so a wrong-looking split can be traced to a threshold or pinned with
+`hubs` / `lookupTables` / `excludeTables`.
+
 ### 5. Export Sample Queries to Metadata (Optional)
 
 Transform generated sample queries into MemberJunction metadata format for syncing to the database:
@@ -417,6 +513,16 @@ Triggered automatically when:
 - Tables lack primary key constraints
 - Insufficient foreign key relationships detected (below threshold)
 
+### Existing Indexes as Evidence
+
+Databases often have indexes where no key is declared: developers index the columns they join and filter on. DBAutoDoc reads every table's indexes right after introspection and stores them in the state file (`schemas[].tables[].indexes`). The LLM sees them in the discovery validation pass, table analysis, and PK/FK pruning:
+
+- A `UNIQUE` index or primary key on non-null columns is strong evidence for the primary key (or an alternate key).
+- A non-unique index led by an ID- or code-like column often marks a foreign key.
+- In FK pruning, each candidate says whether its target column has a unique index.
+
+They are hints, not proof, and are weighed with names, statistics and value overlap. Turn this off with `"analysis": { "useExistingIndexes": false }`. A resumed run reads indexes for any table whose state has none yet. If a schema's catalog can't be read, the run continues without its indexes.
+
 ### Organic Key Detection (Optional)
 
 Foreign keys require **shared exact values**. Organic keys (MemberJunction [PR #2193](https://github.com/MemberJunction/MJ/pull/2193)) capture the weaker-but-broader condition of **shared identity**: two columns refer to the same real-world thing once each is canonicalized through its own transformation. That joins far more cross-system data than exact-match FKs -- e.g. the same phone number stored as `+1 (555) 123-4567`, `5551234567`, and `555.123.4567` across HubSpot, Zendesk, and QuickBooks.
@@ -434,6 +540,97 @@ Results are written into `additionalSchemaInfo.json` (see [CodeGen Integration](
 
 > **Note:** Embeddings route through MemberJunction's `BaseEmbeddings` drivers (OpenAI, Mistral, Azure, Bedrock, Ollama, local), defaulting to `OpenAIEmbedding`. The detection pass therefore requires an embedding provider with a valid key configured.
 
+### Plugins
+
+A plugin adds work to an analysis run and, optionally, new export formats. Plugins are classes registered with MemberJunction's class factory (`@RegisterClass` from `@memberjunction/global`, which needs no running MemberJunction system) and enabled in the config file.
+
+**Hooks.** A plugin overrides any of these, in run order. Each receives the state, the config, the plugin's options, the run folder, a logger, and (from `AfterIntrospection` on) the open database connection:
+
+| Hook | Runs |
+|---|---|
+| `OnPreRun` | after the state loads, before connecting |
+| `OnAfterIntrospection` | after schema introspection and data sampling |
+| `OnAfterDiscovery` | after primary/foreign key discovery |
+| `OnAfterDescriptions` | after the LLM description loop |
+| `OnAfterPruning` | after key pruning (also when pruning is not configured) |
+| `OnPostRun` | last, while the database connection is still open |
+
+Plugins run in `Priority` order (lower first, default 100). A hook that throws is logged and recorded in the state file, and the run continues. Each plugin keeps its hook history and any data it saves in its own section, `state.plugins.<Name>`. Hooks also run on `--resume`, so they should be safe to run more than once.
+
+**Configuration.** Built-in plugins run by default. External plugins are listed with a `Module`: an npm package name or a file path (relative paths resolve from the current directory), loaded at startup.
+
+```json
+{
+  "plugins": [
+    { "Name": "IndexAdvisor", "Options": { "MinRowCount": 5000 } },
+    { "Name": "MyCustomCheck", "Module": "./plugins/my-custom-check.js", "Priority": 50, "Options": { "Strict": true } },
+    { "Name": "SomeBuiltIn", "Enabled": false }
+  ]
+}
+```
+
+An enabled plugin whose name is not registered fails the run at startup, naming the plugins that are registered.
+
+**Writing a plugin:**
+
+```typescript
+import { RegisterClass } from '@memberjunction/global';
+import { BaseAutoDocPlugin, AutoDocPluginContext, AutoDocExporter } from '@memberjunction/db-auto-doc';
+
+@RegisterClass(BaseAutoDocPlugin, 'MyCustomCheck')
+export class MyCustomCheck extends BaseAutoDocPlugin {
+  public override async OnPostRun(context: AutoDocPluginContext): Promise<void> {
+    const tables = context.State.schemas.flatMap(s => s.tables);
+    this.SetData(context, 'MyCustomCheck', { TablesSeen: tables.length });
+    context.Log(`MyCustomCheck saw ${tables.length} tables`);
+  }
+
+  public override GetExporters(): AutoDocExporter[] {
+    return [{
+      Format: 'my-report',
+      Description: 'One-line summary from MyCustomCheck',
+      Generate: (state) => [{ FileName: 'my-report.txt', Content: JSON.stringify(state.plugins?.['MyCustomCheck']?.Data) }]
+    }];
+  }
+}
+```
+
+### Index Advisor (Built-in Plugin)
+
+The Index Advisor runs at the end of every analysis (`OnPostRun`) unless turned off. It never changes the database: it records proposals in the state file, and `export --format index-migration` writes them as a migration for someone to review and apply.
+
+1. **Reads existing indexes** on every analyzed schema: SQL Server `sys.indexes`, PostgreSQL `pg_index`, MySQL `information_schema.STATISTICS`. Primary-key, unique, partial (filtered), expression and INCLUDE columns are all captured; an expression key part keeps its position (as `(expression)`), so an index *led* by an expression never counts as covering the column after it. A schema whose indexes cannot be read is recorded in `SkippedSchemas`, and no proposals are made for it.
+2. **Proposes indexes with deterministic rules:**
+   - a foreign key (declared, or discovered and `confirmed` at `KeyMinConfidence` or higher) whose column has no index starting with it. A partial index does not count as covering;
+   - a confirmed discovered primary key on a table with no index on it.
+
+   Tables below `MinRowCount` are skipped, and so are leading columns that make poor index keys (large text/JSON/binary types, or two or fewer distinct values). Proposals are ranked by table size.
+3. **LLM review** (on by default). For up to `MaxLLMTables` tables, largest first, that carry a proposal or appear in a [sample query](#sample-query-generation), the model sees the column statistics, descriptions, existing indexes, rule-based proposals and the queries that use the table. It may **keep, drop or modify** each proposal (for example make it composite, or add INCLUDE columns) and **add** new ones, each with a reason. The model returns structured decisions, never SQL. Every change is validated: the columns must exist, the index must not duplicate an existing or planned one, and the leading column must be a usable key. Rejected suggestions are recorded with the reason. If a table's review call fails, that table keeps its rule-based proposals. Use the `indexAdvisor` key in `ai.modelOverrides` to review with a different model.
+4. **Flags redundant indexes** whose key columns are a leading prefix of (or identical to) another index of the same kind on the same table. They are reported only, never dropped. Unique, primary-key, partial and expression indexes are never flagged.
+
+**Options** (`plugins[].Options` for `IndexAdvisor`):
+
+| Option | Default | Meaning |
+|---|---|---|
+| `MinRowCount` | `1000` | Tables with fewer rows get no proposals |
+| `IncludeDiscoveredFKs` | `true` | Also index discovered (not only declared) foreign keys |
+| `KeyMinConfidence` | `90` | Minimum confidence for a discovered key to be used |
+| `LLMReview` | `true` | Run the LLM review layer |
+| `MaxLLMTables` | `40` | Most tables the review looks at |
+| `Concurrently` | `true` | PostgreSQL: `CREATE INDEX CONCURRENTLY` (see below) |
+
+Turn the plugin off with `{ "Name": "IndexAdvisor", "Enabled": false }`.
+
+**The migration** (`export --format index-migration`) is named `V<yyyyMMddHHmm>__dbautodoc_indexes.sql` from the analysis time (override the prefix with `--file-prefix`), highest-priority index first, each with a comment giving its source and reason. Index names are `IX_<table>_<columns>`, shortened with a hash suffix to the platform's identifier limit. On PostgreSQL, where index names must be unique across a schema, every name carries a hash of its exact table and columns so two similar names can't collide. Reasons are written on a single comment line, so multi-line text from the LLM can't spill into the SQL.
+
+| Platform | Statement |
+|---|---|
+| SQL Server | `CREATE NONCLUSTERED INDEX … INCLUDE (…)` guarded by `IF NOT EXISTS` on `sys.indexes`, so the script can be re-run |
+| PostgreSQL | `CREATE INDEX CONCURRENTLY IF NOT EXISTS … INCLUDE (…)` |
+| MySQL | `CREATE INDEX …` (MySQL has no `IF NOT EXISTS` for indexes, so the script cannot be re-run; INCLUDE columns are omitted) |
+
+> **PostgreSQL and `CONCURRENTLY`:** building concurrently does not lock writes on a live database, but it cannot run inside a transaction. The exporter therefore also writes `<migration>.sql.conf` containing `executeInTransaction=false`, which Flyway honors. **Skyway 0.6.x always runs each migration inside a transaction**, so a `CONCURRENTLY` migration fails there ("cannot run inside a transaction block"). Until Skyway supports a per-migration opt-out, apply the file with `psql` or Flyway, or set `"Concurrently": false` (which locks writes on each table while its index builds).
+
 ### Sample Query Generation
 
 DBAutoDoc can generate reference SQL queries for AI agents, solving the **query alignment problem** where multi-query patterns (summary + detail) have inconsistent filtering logic:
@@ -978,7 +1175,7 @@ Use different models for different pipeline phases. A cheaper/faster model for b
 {
   "ai": {
     "provider": "gemini",
-    "model": "gemini-3-flash-preview",
+    "model": "gemini-3.8-flash",
     "modelOverrides": {
       "fkPruning": {
         "model": "gemini-3.1-pro-preview",
@@ -1017,7 +1214,7 @@ DBAutoDoc integrates with [MemberJunction's AI provider system](../../packages/A
 ```json
 {
   "provider": "gemini",
-  "model": "gemini-3-flash-preview",
+  "model": "gemini-3.8-flash",
   "apiKey": "..."
 }
 ```

package/dist/commands/analyze.d.ts

@@ -11,6 +11,7 @@ export default class Analyze extends Command {
         'max-iterations': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         'reanalyze-below': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         'pruning-only': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        'skip-sampling': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
     };
     static args: {};
     run(): Promise<void>;

package/dist/commands/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/commands/analyze.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAM7C,MAAM,CAAC,OAAO,OAAO,OAAQ,SAAQ,OAAO;IAC1C,MAAM,CAAC,WAAW,SAAiD;IAEnE,MAAM,CAAC,QAAQ,WAOb;IAEF,MAAM,CAAC,KAAK;;;;;;MAwBV;IAEF,MAAM,CAAC,IAAI,KAAM;IAEX,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAqE3B"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/commands/analyze.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAM7C,MAAM,CAAC,OAAO,OAAO,OAAQ,SAAQ,OAAO;IAC1C,MAAM,CAAC,WAAW,SAAiD;IAEnE,MAAM,CAAC,QAAQ,WAOb;IAEF,MAAM,CAAC,KAAK;;;;;;;MA4BV;IAEF,MAAM,CAAC,IAAI,KAAM;IAEX,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAuE3B"}

package/dist/commands/analyze.js

@@ -39,6 +39,10 @@ export default class Analyze extends Command {
         'pruning-only': Flags.boolean({
             description: 'Skip discovery and analysis iterations. Only run the FK pruning pass on an existing state file. Requires --resume.',
             default: false
+        }),
+        'skip-sampling': Flags.boolean({
+            description: 'Skip table data sampling pass (useful for large databases or when schema/dictionary is already provided)',
+            default: false
         })
     }; }
     static { this.args = {}; }
@@ -68,6 +72,8 @@ export default class Analyze extends Command {
                 resumeFromState: flags.resume,
                 reanalyzeBelowConfidence,
                 maxIterations,
+                // --pruning-only runs the FK pruning pass alone; sampling would be new work it never asked for
+                skipSampling: flags['skip-sampling'] || flags['pruning-only'],
                 onProgress: (message, data) => {
                     if (data) {
                         spinner.succeed(`${message}: ${JSON.stringify(data)}`);

package/dist/commands/analyze.js.map

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

package/dist/commands/export.d.ts

@@ -1,26 +1,43 @@
 /**
  * Export command - Generate SQL and Markdown documentation
  */
-import { Command } from '@oclif/core';
+import { Command, Interfaces } from '@oclif/core';
+import { ErdColumnMode, ErdMode } from '../types/config.js';
 export default class Export extends Command {
     static description: string;
     static examples: string[];
     static flags: {
-        'state-file': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
-        'output-dir': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
-        sql: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        markdown: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        html: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        csv: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        mermaid: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        report: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        'schema-info': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        'schema-info-discovered-only': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        'schema-info-confirmed-only': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        apply: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        'approved-only': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
-        'confidence-threshold': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        'state-file': Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        'output-dir': Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        sql: Interfaces.BooleanFlag<boolean>;
+        markdown: Interfaces.BooleanFlag<boolean>;
+        html: Interfaces.BooleanFlag<boolean>;
+        csv: Interfaces.BooleanFlag<boolean>;
+        mermaid: Interfaces.BooleanFlag<boolean>;
+        report: Interfaces.BooleanFlag<boolean>;
+        'schema-info': Interfaces.BooleanFlag<boolean>;
+        'schema-info-discovered-only': Interfaces.BooleanFlag<boolean>;
+        'schema-info-confirmed-only': Interfaces.BooleanFlag<boolean>;
+        apply: Interfaces.BooleanFlag<boolean>;
+        'approved-only': Interfaces.BooleanFlag<boolean>;
+        'confidence-threshold': Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        'erd-mode': Interfaces.OptionFlag<ErdMode, Interfaces.CustomOptions>;
+        'erd-columns': Interfaces.OptionFlag<ErdColumnMode, Interfaces.CustomOptions>;
+        'erd-hub-min-inbound': Interfaces.OptionFlag<number, Interfaces.CustomOptions>;
+        'erd-lookup-max-rows': Interfaces.OptionFlag<number, Interfaces.CustomOptions>;
+        'erd-page-size': Interfaces.OptionFlag<number, Interfaces.CustomOptions>;
+        'erd-min-cluster-size': Interfaces.OptionFlag<number, Interfaces.CustomOptions>;
+        format: Interfaces.OptionFlag<string[], Interfaces.CustomOptions>;
+        'list-formats': Interfaces.BooleanFlag<boolean>;
+        provider: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        'file-prefix': Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
     };
     run(): Promise<void>;
+    /** Merge the ERD settings: defaults, then config.output.erd, then the export flags. */
+    private resolveErdConfig;
+    /** Loads built-in plugins plus any external plugin modules named in the config. */
+    private loadPluginExporters;
+    private listFormats;
+    private runPluginExports;
 }
 //# sourceMappingURL=export.d.ts.map

package/dist/commands/export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/commands/export.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAgB7C,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,OAAO;IACzC,MAAM,CAAC,WAAW,SAAkF;IAEpG,MAAM,CAAC,QAAQ,WAQb;IAEF,MAAM,CAAC,KAAK;;;;;;;;;;;;;;;MAeV;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAyL3B"}
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/commands/export.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAS,UAAU,EAAE,MAAM,aAAa,CAAC;AAezD,OAAO,EAAgB,aAAa,EAAa,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAerF,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,OAAO;IACzC,MAAM,CAAC,WAAW,SAAkF;IAEpG,MAAM,CAAC,QAAQ,WAUb;IAEF,MAAM,CAAC,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;MA+CV;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA0O1B,uFAAuF;IACvF,OAAO,CAAC,gBAAgB;IAYxB,mFAAmF;YACrE,mBAAmB;IAMjC,OAAO,CAAC,WAAW;YAUL,gBAAgB;CAsB/B"}

package/dist/commands/export.js

@@ -14,8 +14,16 @@ import { ReportGenerator } from '../generators/ReportGenerator.js';
 import { HTMLGenerator } from '../generators/HTMLGenerator.js';
 import { CSVGenerator } from '../generators/CSVGenerator.js';
 import { MermaidGenerator } from '../generators/MermaidGenerator.js';
+import { ErdClusterer } from '../generators/ErdClusterer.js';
+import { ErdClusterGenerator } from '../generators/ErdClusterGenerator.js';
+import { ERD_DEFAULTS } from '../types/config.js';
 import { AdditionalSchemaInfoGenerator } from '../generators/AdditionalSchemaInfoGenerator.js';
+import { PluginManager } from '../plugins/PluginManager.js';
 // DatabaseConnection is lazy-imported only when --apply is used (requires DB credentials)
+/** Sub-directory of the output directory that holds the subject-area diagrams. */
+const ERD_CLUSTER_DIR = 'erd';
+const ERD_MODES = ['full', 'clusters', 'both'];
+const ERD_COLUMN_MODES = ['all', 'keys', 'none'];
 export default class Export extends Command {
     static { this.description = 'Export documentation in multiple formats (SQL, Markdown, HTML, CSV, Mermaid)'; }
     static { this.examples = [
@@ -25,7 +33,9 @@ export default class Export extends Command {
         '$ db-auto-doc export --html',
         '$ db-auto-doc export --csv',
         '$ db-auto-doc export --mermaid',
-        '$ db-auto-doc export --sql --markdown --html --csv --mermaid --apply'
+        '$ db-auto-doc export --sql --markdown --html --csv --mermaid --apply',
+        '$ db-auto-doc export --mermaid --erd-mode clusters',
+        '$ db-auto-doc export --html --mermaid --erd-mode clusters --erd-hub-min-inbound 12 --erd-page-size 40'
     ]; }
     static { this.flags = {
         'state-file': Flags.string({ description: 'Path to state JSON file', char: 's' }),
@@ -41,7 +51,39 @@ export default class Export extends Command {
         'schema-info-confirmed-only': Flags.boolean({ description: 'Only include confirmed candidates in schema info', default: false }),
         apply: Flags.boolean({ description: 'Apply SQL to database', default: false }),
         'approved-only': Flags.boolean({ description: 'Only export approved items', default: false }),
-        'confidence-threshold': Flags.string({ description: 'Minimum confidence threshold', default: '0' })
+        'confidence-threshold': Flags.string({ description: 'Minimum confidence threshold', default: '0' }),
+        'erd-mode': Flags.custom({ options: ERD_MODES })({
+            description: 'ERD layout: full (one diagram), clusters (one per subject area), both. Overrides output.erd.mode'
+        }),
+        'erd-columns': Flags.custom({ options: ERD_COLUMN_MODES })({
+            description: 'Columns drawn per entity: all, keys (PK/FK only), none. Overrides output.erd.columns'
+        }),
+        'erd-hub-min-inbound': Flags.integer({
+            min: 1,
+            description: `A table referenced by at least this many tables is a subject-area hub (default ${ERD_DEFAULTS.hubMinInbound})`
+        }),
+        'erd-lookup-max-rows': Flags.integer({
+            min: 1,
+            description: `A table that references nothing and has fewer rows than this is a reference table, listed not drawn (default ${ERD_DEFAULTS.lookupMaxRows})`
+        }),
+        'erd-page-size': Flags.integer({
+            min: 1,
+            description: `Tables per diagram page beyond the hub (default ${ERD_DEFAULTS.pageSize})`
+        }),
+        'erd-min-cluster-size': Flags.integer({
+            min: 1,
+            description: `Subject areas smaller than this fold into a neighbour (default ${ERD_DEFAULTS.minClusterSize})`
+        }),
+        format: Flags.string({
+            description: 'Plugin export format to generate (repeatable). See --list-formats.',
+            multiple: true
+        }),
+        'list-formats': Flags.boolean({ description: 'List the export formats contributed by plugins and exit', default: false }),
+        provider: Flags.string({
+            description: 'Database platform for dialect-specific output (defaults to the state file, then config, then sqlserver)',
+            options: ['sqlserver', 'mysql', 'postgresql']
+        }),
+        'file-prefix': Flags.string({ description: 'File name prefix override for plugin exports (e.g. a migration version prefix)' })
     }; }
     async run() {
         const { flags } = await this.parse(Export);
@@ -76,8 +118,18 @@ export default class Export extends Command {
             spinner.succeed('State loaded');
             // Ensure output directory exists
             await fs.mkdir(outputDir, { recursive: true });
+            // Plugin-contributed formats (--format / --list-formats)
+            const exporters = await this.loadPluginExporters(config?.plugins);
+            if (flags['list-formats']) {
+                this.listFormats(exporters);
+                return;
+            }
+            if (flags.format?.length) {
+                const provider = (flags.provider ?? state.database.provider ?? config?.database?.provider ?? 'sqlserver');
+                await this.runPluginExports(flags.format, exporters, state, outputDir, { Provider: provider, FileNamePrefix: flags['file-prefix'] }, spinner);
+            }
             // Default to SQL + Markdown if no specific format flags provided
-            const anyFormatSpecified = flags.sql || flags.markdown || flags.html || flags.csv || flags.mermaid || flags.report || flags['schema-info'];
+            const anyFormatSpecified = flags.sql || flags.markdown || flags.html || flags.csv || flags.mermaid || flags.report || flags['schema-info'] || !!flags.format?.length;
             const generateSQL = flags.sql || !anyFormatSpecified;
             const generateMarkdown = flags.markdown || !anyFormatSpecified;
             const generateHTML = flags.html;
@@ -139,11 +191,29 @@ export default class Export extends Command {
                 await fs.writeFile(mdPath, markdown, 'utf-8');
                 spinner.succeed(`Markdown documentation saved to ${mdPath}`);
             }
+            // ERD options: export flags override config.output.erd, which overrides the defaults.
+            const erd = this.resolveErdConfig(config?.output?.erd, flags);
+            // The plan is built whenever an output needs it: the HTML's Subject Areas section links to the
+            // cluster pages, so requesting --html in clusters mode also writes them.
+            let clusterPlan = (generateMermaid || generateHTML) && erd.mode !== 'full'
+                ? new ErdClusterer().Plan(state, erd)
+                : undefined;
+            for (const warning of clusterPlan?.Warnings ?? []) {
+                this.warn(`ERD ${warning}`);
+            }
+            if (clusterPlan && clusterPlan.Clusters.length === 0) {
+                // Nothing is referenced often enough to anchor an area: fall back to the single diagram
+                // rather than leaving the documentation with no ERD at all.
+                this.warn(`ERD: no table is referenced by at least ${clusterPlan.Options.hubMinInbound} others, so there are no subject areas; `
+                    + 'drawing the full diagram instead (lower --erd-hub-min-inbound to cluster)');
+                clusterPlan = undefined;
+                erd.mode = 'full';
+            }
             // Generate HTML
             if (generateHTML) {
                 spinner.start('Generating HTML documentation');
                 const htmlGen = new HTMLGenerator();
-                const html = htmlGen.generate(state, generatorOptions);
+                const html = htmlGen.generate(state, { ...generatorOptions, clusterPlan, clusterDir: ERD_CLUSTER_DIR });
                 const htmlPath = path.join(outputDir, 'documentation.html');
                 await fs.writeFile(htmlPath, html, 'utf-8');
                 spinner.succeed(`HTML documentation saved to ${htmlPath}`);
@@ -159,17 +229,35 @@ export default class Export extends Command {
                 await fs.writeFile(columnsPath, csvExport.columns, 'utf-8');
                 spinner.succeed(`CSV exports saved to ${tablesPath} and ${columnsPath}`);
             }
-            // Generate Mermaid
+            // Generate Mermaid: the schema-wide diagram, the clustered subject areas, or both
             if (generateMermaid) {
-                spinner.start('Generating Mermaid diagram');
-                const mermaidGen = new MermaidGenerator();
-                const mermaidDiagram = mermaidGen.generate(state, generatorOptions);
-                const mermaidHtml = mermaidGen.generateHtml(state, generatorOptions);
-                const mermaidPath = path.join(outputDir, 'erd.mmd');
-                const mermaidHtmlPath = path.join(outputDir, 'erd.html');
-                await fs.writeFile(mermaidPath, mermaidDiagram, 'utf-8');
-                await fs.writeFile(mermaidHtmlPath, mermaidHtml, 'utf-8');
-                spinner.succeed(`Mermaid diagram saved to ${mermaidPath} and ${mermaidHtmlPath}`);
+                if (erd.mode === 'full' || erd.mode === 'both') {
+                    spinner.start('Generating Mermaid diagram');
+                    const mermaidGen = new MermaidGenerator();
+                    const fullOptions = { ...generatorOptions, columns: erd.columns === 'keys' || erd.columns === 'none' ? erd.columns : 'all' };
+                    const mermaidDiagram = mermaidGen.generate(state, fullOptions);
+                    const mermaidHtml = mermaidGen.generateHtml(state, fullOptions);
+                    const mermaidPath = path.join(outputDir, 'erd.mmd');
+                    const mermaidHtmlPath = path.join(outputDir, 'erd.html');
+                    await fs.writeFile(mermaidPath, mermaidDiagram, 'utf-8');
+                    await fs.writeFile(mermaidHtmlPath, mermaidHtml, 'utf-8');
+                    spinner.succeed(`Mermaid diagram saved to ${mermaidPath} and ${mermaidHtmlPath}`);
+                }
+            }
+            if (clusterPlan) {
+                spinner.start('Generating subject-area diagrams');
+                const clusterGen = new ErdClusterGenerator();
+                const output = clusterGen.Generate(state, clusterPlan, { columns: erd.columns ?? 'keys' });
+                const clusterDir = path.join(outputDir, ERD_CLUSTER_DIR);
+                await fs.mkdir(clusterDir, { recursive: true });
+                for (const file of output.Files) {
+                    await fs.writeFile(path.join(clusterDir, `${file.BaseName}.mmd`), file.Mermaid, 'utf-8');
+                    await fs.writeFile(path.join(clusterDir, `${file.BaseName}.html`), file.Html, 'utf-8');
+                }
+                await fs.writeFile(path.join(clusterDir, 'index.html'), output.IndexHtml, 'utf-8');
+                await fs.writeFile(path.join(clusterDir, 'index.md'), output.IndexMarkdown, 'utf-8');
+                const largest = output.Files.reduce((n, f) => Math.max(n, f.Mermaid.length), 0);
+                spinner.succeed(`${clusterPlan.Clusters.length} subject areas (${output.Files.length} diagram pages, largest ${largest.toLocaleString()} chars) saved to ${clusterDir}`);
             }
             // Generate Report
             if (flags.report) {
@@ -201,5 +289,47 @@ export default class Export extends Command {
             this.error(error.message);
         }
     }
+    /** Merge the ERD settings: defaults, then config.output.erd, then the export flags. */
+    resolveErdConfig(configured, flags) {
+        return {
+            ...configured,
+            mode: flags['erd-mode'] ?? configured?.mode ?? 'full',
+            columns: flags['erd-columns'] ?? configured?.columns,
+            hubMinInbound: flags['erd-hub-min-inbound'] ?? configured?.hubMinInbound,
+            lookupMaxRows: flags['erd-lookup-max-rows'] ?? configured?.lookupMaxRows,
+            pageSize: flags['erd-page-size'] ?? configured?.pageSize,
+            minClusterSize: flags['erd-min-cluster-size'] ?? configured?.minClusterSize,
+        };
+    }
+    /** Loads built-in plugins plus any external plugin modules named in the config. */
+    async loadPluginExporters(entries) {
+        const plugins = new PluginManager();
+        await plugins.Load(entries);
+        return plugins.GetExporters();
+    }
+    listFormats(exporters) {
+        if (exporters.length === 0) {
+            this.log('No plugin export formats are available.');
+            return;
+        }
+        for (const e of exporters) {
+            this.log(`${chalk.cyan(e.Format)}  ${e.Description}`);
+        }
+    }
+    async runPluginExports(formats, exporters, state, outputDir, options, spinner) {
+        for (const format of formats) {
+            const exporter = exporters.find((e) => e.Format.toLowerCase() === format.toLowerCase());
+            if (!exporter) {
+                const known = exporters.map((e) => e.Format).join(', ') || '(none)';
+                throw new Error(`Unknown export format '${format}'. Available: ${known}`);
+            }
+            spinner.start(`Generating ${exporter.Format}`);
+            const files = exporter.Generate(state, options);
+            for (const file of files) {
+                await fs.writeFile(path.join(outputDir, file.FileName), file.Content, 'utf-8');
+            }
+            spinner.succeed(`${exporter.Format}: ${files.length ? files.map((f) => f.FileName).join(', ') : 'nothing to export'}`);
+        }
+    }
 }
 //# sourceMappingURL=export.js.map