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

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export * from './core/index.js';
 export * from './core/AnalysisOrchestrator.js';
 export * from './generators/index.js';
 export * from './utils/index.js';
+export * from './plugins/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,gBAAgB,CAAC;AAG/B,cAAc,kBAAkB,CAAC;AAGjC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gCAAgC,CAAC;AAG/C,cAAc,uBAAuB,CAAC;AAGtC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,gBAAgB,CAAC;AAG/B,cAAc,kBAAkB,CAAC;AAGjC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gCAAgC,CAAC;AAG/C,cAAc,uBAAuB,CAAC;AAGtC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -19,4 +19,6 @@ export * from './core/AnalysisOrchestrator.js';
 export * from './generators/index.js';
 // Utilities
 export * from './utils/index.js';
+// Plugin system
+export * from './plugins/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,2DAA2D;AAC3D,cAAc,gBAAgB,CAAC;AAE/B,aAAa;AACb,cAAc,kBAAkB,CAAC;AAEjC,iBAAiB;AACjB,cAAc,qBAAqB,CAAC;AAEpC,UAAU;AACV,cAAc,oBAAoB,CAAC;AAEnC,mBAAmB;AACnB,cAAc,kBAAkB,CAAC;AAEjC,kBAAkB;AAClB,cAAc,iBAAiB,CAAC;AAChC,cAAc,gCAAgC,CAAC;AAE/C,aAAa;AACb,cAAc,uBAAuB,CAAC;AAEtC,YAAY;AACZ,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,2DAA2D;AAC3D,cAAc,gBAAgB,CAAC;AAE/B,aAAa;AACb,cAAc,kBAAkB,CAAC;AAEjC,iBAAiB;AACjB,cAAc,qBAAqB,CAAC;AAEpC,UAAU;AACV,cAAc,oBAAoB,CAAC;AAEnC,mBAAmB;AACnB,cAAc,kBAAkB,CAAC;AAEjC,kBAAkB;AAClB,cAAc,iBAAiB,CAAC;AAChC,cAAc,gCAAgC,CAAC;AAE/C,aAAa;AACb,cAAc,uBAAuB,CAAC;AAEtC,YAAY;AACZ,cAAc,kBAAkB,CAAC;AAEjC,gBAAgB;AAChB,cAAc,oBAAoB,CAAC"}

package/dist/plugins/BaseAutoDocPlugin.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Base class for DBAutoDoc plugins.
+ *
+ * Subclass it, register it with `@RegisterClass(BaseAutoDocPlugin, '<Name>')`, and override
+ * only the hooks you need. Every hook is optional and defaults to a no-op. A hook that throws
+ * is recorded in the state file and does not stop the analysis run.
+ */
+import type { AutoDocExporter, AutoDocPluginContext, AutoDocPluginStateSection } from './types.js';
+export declare abstract class BaseAutoDocPlugin {
+    /** Runs after the state is loaded, before connecting to the database. */
+    OnPreRun(_context: AutoDocPluginContext): Promise<void>;
+    /** Runs after schema introspection and data sampling. */
+    OnAfterIntrospection(_context: AutoDocPluginContext): Promise<void>;
+    /** Runs after primary/foreign key discovery. */
+    OnAfterDiscovery(_context: AutoDocPluginContext): Promise<void>;
+    /** Runs after the LLM description loop. */
+    OnAfterDescriptions(_context: AutoDocPluginContext): Promise<void>;
+    /** Runs after key pruning (also runs when pruning is not configured). */
+    OnAfterPruning(_context: AutoDocPluginContext): Promise<void>;
+    /** Runs last, while the database connection is still open. */
+    OnPostRun(_context: AutoDocPluginContext): Promise<void>;
+    /** Export formats this plugin contributes to `db-auto-doc export --format`. */
+    GetExporters(): AutoDocExporter[];
+    /** Dispatches a hook name to the matching method. */
+    RunHook(context: AutoDocPluginContext): Promise<void>;
+    /** Reads this plugin's persisted data from the state file, if any. */
+    protected GetData<T extends object>(context: AutoDocPluginContext, pluginName: string): T | undefined;
+    /** Writes this plugin's data into its own section of the state file. */
+    protected SetData<T extends object>(context: AutoDocPluginContext, pluginName: string, data: T): void;
+    /** Returns the plugin's state section, creating it when missing. */
+    static EnsureSection(context: Pick<AutoDocPluginContext, 'State'>, pluginName: string): AutoDocPluginStateSection;
+}
+//# sourceMappingURL=BaseAutoDocPlugin.d.ts.map

package/dist/plugins/BaseAutoDocPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseAutoDocPlugin.d.ts","sourceRoot":"","sources":["../../src/plugins/BaseAutoDocPlugin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EAEpB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAGpB,8BACsB,iBAAiB;IACrC,yEAAyE;IAC5D,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAEpE,yDAAyD;IAC5C,oBAAoB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhF,gDAAgD;IACnC,gBAAgB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE5E,2CAA2C;IAC9B,mBAAmB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE/E,yEAAyE;IAC5D,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E,8DAA8D;IACjD,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAErE,+EAA+E;IACxE,YAAY,IAAI,eAAe,EAAE;IAIxC,qDAAqD;IACxC,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlE,sEAAsE;IACtE,SAAS,CAAC,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIrG,wEAAwE;IACxE,SAAS,CAAC,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI;IAKrG,oEAAoE;WACtD,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,yBAAyB;CASzH"}

package/dist/plugins/BaseAutoDocPlugin.js

@@ -0,0 +1,70 @@
+/**
+ * Base class for DBAutoDoc plugins.
+ *
+ * Subclass it, register it with `@RegisterClass(BaseAutoDocPlugin, '<Name>')`, and override
+ * only the hooks you need. Every hook is optional and defaults to a no-op. A hook that throws
+ * is recorded in the state file and does not stop the analysis run.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var BaseAutoDocPlugin_1;
+import { RequiresSubclass } from '@memberjunction/global';
+// Never hand back a hollow base instance for an unknown plugin name.
+let BaseAutoDocPlugin = BaseAutoDocPlugin_1 = class BaseAutoDocPlugin {
+    /** Runs after the state is loaded, before connecting to the database. */
+    async OnPreRun(_context) { }
+    /** Runs after schema introspection and data sampling. */
+    async OnAfterIntrospection(_context) { }
+    /** Runs after primary/foreign key discovery. */
+    async OnAfterDiscovery(_context) { }
+    /** Runs after the LLM description loop. */
+    async OnAfterDescriptions(_context) { }
+    /** Runs after key pruning (also runs when pruning is not configured). */
+    async OnAfterPruning(_context) { }
+    /** Runs last, while the database connection is still open. */
+    async OnPostRun(_context) { }
+    /** Export formats this plugin contributes to `db-auto-doc export --format`. */
+    GetExporters() {
+        return [];
+    }
+    /** Dispatches a hook name to the matching method. */
+    async RunHook(context) {
+        const handlers = {
+            PreRun: (c) => this.OnPreRun(c),
+            AfterIntrospection: (c) => this.OnAfterIntrospection(c),
+            AfterDiscovery: (c) => this.OnAfterDiscovery(c),
+            AfterDescriptions: (c) => this.OnAfterDescriptions(c),
+            AfterPruning: (c) => this.OnAfterPruning(c),
+            PostRun: (c) => this.OnPostRun(c)
+        };
+        await handlers[context.Hook](context);
+    }
+    /** Reads this plugin's persisted data from the state file, if any. */
+    GetData(context, pluginName) {
+        return context.State.plugins?.[pluginName]?.Data;
+    }
+    /** Writes this plugin's data into its own section of the state file. */
+    SetData(context, pluginName, data) {
+        const section = BaseAutoDocPlugin_1.EnsureSection(context, pluginName);
+        section.Data = data;
+    }
+    /** Returns the plugin's state section, creating it when missing. */
+    static EnsureSection(context, pluginName) {
+        if (!context.State.plugins) {
+            context.State.plugins = {};
+        }
+        if (!context.State.plugins[pluginName]) {
+            context.State.plugins[pluginName] = { Runs: [] };
+        }
+        return context.State.plugins[pluginName];
+    }
+};
+BaseAutoDocPlugin = BaseAutoDocPlugin_1 = __decorate([
+    RequiresSubclass()
+], BaseAutoDocPlugin);
+export { BaseAutoDocPlugin };
+//# sourceMappingURL=BaseAutoDocPlugin.js.map

package/dist/plugins/BaseAutoDocPlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseAutoDocPlugin.js","sourceRoot":"","sources":["../../src/plugins/BaseAutoDocPlugin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;;;;;;;;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAQ1D,qEAAqE;AAE9D,IAAe,iBAAiB,yBAAhC,MAAe,iBAAiB;IACrC,yEAAyE;IAClE,KAAK,CAAC,QAAQ,CAAC,QAA8B,IAAkB,CAAC;IAEvE,yDAAyD;IAClD,KAAK,CAAC,oBAAoB,CAAC,QAA8B,IAAkB,CAAC;IAEnF,gDAAgD;IACzC,KAAK,CAAC,gBAAgB,CAAC,QAA8B,IAAkB,CAAC;IAE/E,2CAA2C;IACpC,KAAK,CAAC,mBAAmB,CAAC,QAA8B,IAAkB,CAAC;IAElF,yEAAyE;IAClE,KAAK,CAAC,cAAc,CAAC,QAA8B,IAAkB,CAAC;IAE7E,8DAA8D;IACvD,KAAK,CAAC,SAAS,CAAC,QAA8B,IAAkB,CAAC;IAExE,+EAA+E;IACxE,YAAY;QACjB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,qDAAqD;IAC9C,KAAK,CAAC,OAAO,CAAC,OAA6B;QAChD,MAAM,QAAQ,GAA0E;YACtF,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC/B,kBAAkB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;YACvD,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;YAC/C,iBAAiB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;YACrD,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;YAC3C,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;SAClC,CAAC;QACF,MAAM,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,sEAAsE;IAC5D,OAAO,CAAmB,OAA6B,EAAE,UAAkB;QACnF,OAAO,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE,IAAqB,CAAC;IACpE,CAAC;IAED,wEAAwE;IAC9D,OAAO,CAAmB,OAA6B,EAAE,UAAkB,EAAE,IAAO;QAC5F,MAAM,OAAO,GAAG,mBAAiB,CAAC,aAAa,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACrE,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,oEAAoE;IAC7D,MAAM,CAAC,aAAa,CAAC,OAA4C,EAAE,UAAkB;QAC1F,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YAC3B,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC;QAC7B,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YACvC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACnD,CAAC;QACD,OAAO,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3C,CAAC;CACF,CAAA;AA1DqB,iBAAiB;IADtC,gBAAgB,EAAE;GACG,iBAAiB,CA0DtC"}

package/dist/plugins/PluginManager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Loads, orders and runs DBAutoDoc plugins.
+ *
+ * Plugins come from two places:
+ *  - built-ins shipped with this package (registered by importing `./builtins.js`), and
+ *  - external modules named in the config file's `plugins[].Module`, loaded at runtime.
+ *
+ * Each plugin is created through MJ's ClassFactory by its registration key, so anyone can
+ * ship a plugin as an npm package or a local file without changing DBAutoDoc.
+ */
+import { BaseAutoDocPlugin } from './BaseAutoDocPlugin.js';
+import type { AutoDocExporter, AutoDocPluginConfigEntry, AutoDocPluginContext, AutoDocPluginHook } from './types.js';
+/** A plugin that resolved and is enabled for this run. */
+export interface LoadedAutoDocPlugin {
+    Entry: AutoDocPluginConfigEntry;
+    Instance: BaseAutoDocPlugin;
+}
+/** The parts of a hook context the caller supplies; the manager adds the rest per plugin. */
+export type AutoDocPluginRunContext = Omit<AutoDocPluginContext, 'Options' | 'Hook'>;
+export declare class PluginManager {
+    private loaded;
+    /** Enabled plugins in execution order. Empty until {@link Load} runs. */
+    get Plugins(): LoadedAutoDocPlugin[];
+    /**
+     * Resolves the effective plugin list (built-ins plus config entries), loads external
+     * modules, and creates an instance of every enabled plugin.
+     * Throws when an enabled plugin's name is not registered, so typos fail loudly.
+     */
+    Load(entries: AutoDocPluginConfigEntry[] | undefined): Promise<void>;
+    /**
+     * Runs one hook on every enabled plugin, in priority order. A failing plugin is logged and
+     * recorded in its state section; the remaining plugins and the analysis run continue.
+     */
+    RunHook(hook: AutoDocPluginHook, context: AutoDocPluginRunContext): Promise<void>;
+    /** Every exporter contributed by the loaded plugins. */
+    GetExporters(): AutoDocExporter[];
+    private runOne;
+    /**
+     * Adds every built-in plugin the config doesn't mention, using its default enabled state.
+     * A config entry for a built-in (e.g. `{ "Name": "IndexAdvisor", "Enabled": false }`) wins.
+     */
+    static MergeWithBuiltIns(entries: AutoDocPluginConfigEntry[]): AutoDocPluginConfigEntry[];
+    /**
+     * Imports every external plugin module named in the entries, so its `@RegisterClass`
+     * decorators run. Relative paths resolve from the current working directory.
+     */
+    static LoadModules(entries: AutoDocPluginConfigEntry[]): Promise<void>;
+    /** Creates one plugin by registration key, failing clearly when it isn't registered. */
+    static CreatePlugin(name: string): BaseAutoDocPlugin;
+    /** Registration keys of every plugin currently registered with the ClassFactory. */
+    static RegisteredNames(): string[];
+    private static importModule;
+}
+//# sourceMappingURL=PluginManager.d.ts.map

package/dist/plugins/PluginManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginManager.d.ts","sourceRoot":"","sources":["../../src/plugins/PluginManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EACV,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAIpB,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,wBAAwB,CAAC;IAChC,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,6FAA6F;AAC7F,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,oBAAoB,EAAE,SAAS,GAAG,MAAM,CAAC,CAAC;AAErF,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAA6B;IAE3C,yEAAyE;IACzE,IAAW,OAAO,IAAI,mBAAmB,EAAE,CAE1C;IAED;;;;OAIG;IACU,IAAI,CAAC,OAAO,EAAE,wBAAwB,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IASjF;;;OAGG;IACU,OAAO,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9F,wDAAwD;IACjD,YAAY,IAAI,eAAe,EAAE;YAI1B,MAAM;IAmBpB;;;OAGG;WACW,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,EAAE,GAAG,wBAAwB,EAAE;IAQhG;;;OAGG;WACiB,WAAW,CAAC,OAAO,EAAE,wBAAwB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnF,wFAAwF;WAC1E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB;IAS3D,oFAAoF;WACtE,eAAe,IAAI,MAAM,EAAE;mBAMpB,YAAY;CAOlC"}

package/dist/plugins/PluginManager.js

@@ -0,0 +1,115 @@
+/**
+ * Loads, orders and runs DBAutoDoc plugins.
+ *
+ * Plugins come from two places:
+ *  - built-ins shipped with this package (registered by importing `./builtins.js`), and
+ *  - external modules named in the config file's `plugins[].Module`, loaded at runtime.
+ *
+ * Each plugin is created through MJ's ClassFactory by its registration key, so anyone can
+ * ship a plugin as an npm package or a local file without changing DBAutoDoc.
+ */
+import * as path from 'path';
+import { pathToFileURL } from 'node:url';
+import { MJGlobal } from '@memberjunction/global';
+import { BaseAutoDocPlugin } from './BaseAutoDocPlugin.js';
+import { BUILT_IN_PLUGINS } from './builtins.js';
+const DEFAULT_PRIORITY = 100;
+export class PluginManager {
+    constructor() {
+        this.loaded = [];
+    }
+    /** Enabled plugins in execution order. Empty until {@link Load} runs. */
+    get Plugins() {
+        return this.loaded;
+    }
+    /**
+     * Resolves the effective plugin list (built-ins plus config entries), loads external
+     * modules, and creates an instance of every enabled plugin.
+     * Throws when an enabled plugin's name is not registered, so typos fail loudly.
+     */
+    async Load(entries) {
+        const effective = PluginManager.MergeWithBuiltIns(entries ?? []);
+        await PluginManager.LoadModules(effective);
+        this.loaded = effective
+            .filter((e) => e.Enabled !== false)
+            .sort((a, b) => (a.Priority ?? DEFAULT_PRIORITY) - (b.Priority ?? DEFAULT_PRIORITY))
+            .map((entry) => ({ Entry: entry, Instance: PluginManager.CreatePlugin(entry.Name) }));
+    }
+    /**
+     * Runs one hook on every enabled plugin, in priority order. A failing plugin is logged and
+     * recorded in its state section; the remaining plugins and the analysis run continue.
+     */
+    async RunHook(hook, context) {
+        for (const plugin of this.loaded) {
+            await this.runOne(plugin, hook, context);
+        }
+    }
+    /** Every exporter contributed by the loaded plugins. */
+    GetExporters() {
+        return this.loaded.flatMap((p) => p.Instance.GetExporters());
+    }
+    async runOne(plugin, hook, context) {
+        const startedAt = new Date().toISOString();
+        const fullContext = { ...context, Hook: hook, Options: plugin.Entry.Options ?? {} };
+        let errorMessage;
+        try {
+            await plugin.Instance.RunHook(fullContext);
+        }
+        catch (err) {
+            errorMessage = err instanceof Error ? err.message : String(err);
+            context.Log(`Plugin '${plugin.Entry.Name}' failed in ${hook} (continuing): ${errorMessage}`);
+        }
+        BaseAutoDocPlugin.EnsureSection(context, plugin.Entry.Name).Runs.push({
+            Hook: hook,
+            StartedAt: startedAt,
+            CompletedAt: new Date().toISOString(),
+            Success: errorMessage === undefined,
+            ErrorMessage: errorMessage
+        });
+    }
+    /**
+     * Adds every built-in plugin the config doesn't mention, using its default enabled state.
+     * A config entry for a built-in (e.g. `{ "Name": "IndexAdvisor", "Enabled": false }`) wins.
+     */
+    static MergeWithBuiltIns(entries) {
+        const named = new Set(entries.map((e) => e.Name.toLowerCase()));
+        const missingBuiltIns = BUILT_IN_PLUGINS
+            .filter((b) => !named.has(b.Name.toLowerCase()))
+            .map((b) => ({ Name: b.Name, Enabled: b.EnabledByDefault }));
+        return [...entries, ...missingBuiltIns];
+    }
+    /**
+     * Imports every external plugin module named in the entries, so its `@RegisterClass`
+     * decorators run. Relative paths resolve from the current working directory.
+     */
+    static async LoadModules(entries) {
+        for (const entry of entries) {
+            if (entry.Module && entry.Enabled !== false) {
+                await PluginManager.importModule(entry.Module);
+            }
+        }
+    }
+    /** Creates one plugin by registration key, failing clearly when it isn't registered. */
+    static CreatePlugin(name) {
+        const result = MJGlobal.Instance.ClassFactory.TryCreateInstance(BaseAutoDocPlugin, name);
+        if (!result.Resolved || !result.Instance) {
+            const known = PluginManager.RegisteredNames().join(', ') || '(none)';
+            throw new Error(`DBAutoDoc plugin '${name}' is not registered. Registered plugins: ${known}`);
+        }
+        return result.Instance;
+    }
+    /** Registration keys of every plugin currently registered with the ClassFactory. */
+    static RegisteredNames() {
+        return MJGlobal.Instance.ClassFactory.GetAllRegistrations(BaseAutoDocPlugin)
+            .map((r) => r.Key)
+            .filter((k) => !!k);
+    }
+    static async importModule(specifier) {
+        const isPath = specifier.startsWith('.') || path.isAbsolute(specifier);
+        const target = isPath ? pathToFileURL(path.resolve(specifier)).href : specifier;
+        // Dynamic import is intentional: runtime plugin discovery from config (the module path is
+        // only known at run time). DBAutoDoc runs outside the MJ runtime, where this is permitted.
+        await import(target);
+    }
+}
+//# sourceMappingURL=PluginManager.js.map

package/dist/plugins/PluginManager.js.map

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

package/dist/plugins/builtins.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Built-in plugins shipped with DBAutoDoc.
+ *
+ * Each built-in is imported here so its `@RegisterClass` registration runs whenever the plugin
+ * system is used, and listed with its default enabled state. Users can still turn a built-in
+ * off with `{ "Name": "<Name>", "Enabled": false }` in the config's `plugins` array.
+ */
+export interface BuiltInAutoDocPlugin {
+    Name: string;
+    EnabledByDefault: boolean;
+}
+export declare const BUILT_IN_PLUGINS: BuiltInAutoDocPlugin[];
+//# sourceMappingURL=builtins.d.ts.map

package/dist/plugins/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/plugins/builtins.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,eAAO,MAAM,gBAAgB,EAAE,oBAAoB,EAElD,CAAC"}

package/dist/plugins/builtins.js

@@ -0,0 +1,12 @@
+/**
+ * Built-in plugins shipped with DBAutoDoc.
+ *
+ * Each built-in is imported here so its `@RegisterClass` registration runs whenever the plugin
+ * system is used, and listed with its default enabled state. Users can still turn a built-in
+ * off with `{ "Name": "<Name>", "Enabled": false }` in the config's `plugins` array.
+ */
+import { INDEX_ADVISOR_PLUGIN_NAME } from './index-advisor/IndexAdvisorPlugin.js';
+export const BUILT_IN_PLUGINS = [
+    { Name: INDEX_ADVISOR_PLUGIN_NAME, EnabledByDefault: true }
+];
+//# sourceMappingURL=builtins.js.map

package/dist/plugins/builtins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.js","sourceRoot":"","sources":["../../src/plugins/builtins.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAC;AAOlF,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACtD,EAAE,IAAI,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,IAAI,EAAE;CAC5D,CAAC"}

package/dist/plugins/index-advisor/IndexAdvisorPlugin.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Index Advisor — built-in DBAutoDoc plugin.
+ *
+ * At the end of a run it reads the existing indexes, proposes new ones from what DBAutoDoc
+ * learned (foreign keys, discovered primary keys, column statistics), flags redundant existing
+ * indexes, and stores everything in `state.plugins.IndexAdvisor`. The `index-migration` export
+ * format turns the proposals into a SQL migration.
+ */
+import { BaseAutoDocPlugin } from '../BaseAutoDocPlugin.js';
+import type { AutoDocExporter, AutoDocPluginContext, AutoDocPluginJSONValue } from '../types.js';
+import type { DatabaseDocumentation } from '../../types/state.js';
+import type { IndexAdvisorData, IndexAdvisorOptions } from './IndexAdvisorTypes.js';
+export declare const INDEX_ADVISOR_PLUGIN_NAME = "IndexAdvisor";
+export declare const DEFAULT_INDEX_ADVISOR_OPTIONS: IndexAdvisorOptions;
+export declare class IndexAdvisorPlugin extends BaseAutoDocPlugin {
+    OnPostRun(context: AutoDocPluginContext): Promise<void>;
+    GetExporters(): AutoDocExporter[];
+}
+/** The Index Advisor's section of a state file, when the plugin has run. */
+export declare function GetIndexAdvisorData(state: DatabaseDocumentation): IndexAdvisorData | undefined;
+/** Merges config-file options over the defaults, ignoring values of the wrong type. */
+export declare function ResolveIndexAdvisorOptions(raw: {
+    [key: string]: AutoDocPluginJSONValue;
+}): IndexAdvisorOptions;
+//# sourceMappingURL=IndexAdvisorPlugin.d.ts.map

package/dist/plugins/index-advisor/IndexAdvisorPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexAdvisorPlugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/index-advisor/IndexAdvisorPlugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAGjG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAKpF,eAAO,MAAM,yBAAyB,iBAAiB,CAAC;AAExD,eAAO,MAAM,6BAA6B,EAAE,mBAQ3C,CAAC;AAEF,qBACa,kBAAmB,SAAQ,iBAAiB;IACjC,SAAS,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB7D,YAAY,IAAI,eAAe,EAAE;CAUlD;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,qBAAqB,GAAG,gBAAgB,GAAG,SAAS,CAE9F;AAED,uFAAuF;AACvF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,CAAA;CAAE,GAAG,mBAAmB,CAY9G"}

package/dist/plugins/index-advisor/IndexAdvisorPlugin.js

@@ -0,0 +1,128 @@
+/**
+ * Index Advisor — built-in DBAutoDoc plugin.
+ *
+ * At the end of a run it reads the existing indexes, proposes new ones from what DBAutoDoc
+ * learned (foreign keys, discovered primary keys, column statistics), flags redundant existing
+ * indexes, and stores everything in `state.plugins.IndexAdvisor`. The `index-migration` export
+ * format turns the proposals into a SQL migration.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { BaseAutoDocPlugin } from '../BaseAutoDocPlugin.js';
+import { ProposeIndexes, FindRedundantIndexes } from './IndexRules.js';
+import { IndexMigrationGenerator } from './IndexMigrationGenerator.js';
+import { IndexLLMReviewer } from './IndexLLMReview.js';
+export const INDEX_ADVISOR_PLUGIN_NAME = 'IndexAdvisor';
+export const DEFAULT_INDEX_ADVISOR_OPTIONS = {
+    MinRowCount: 1000,
+    IncludeDiscoveredFKs: true,
+    KeyMinConfidence: 90,
+    LLMReview: true,
+    MaxLLMTables: 40,
+    // PostgreSQL: build indexes without locking writes on a live database (Craig, 2026-10-08)
+    Concurrently: true
+};
+let IndexAdvisorPlugin = class IndexAdvisorPlugin extends BaseAutoDocPlugin {
+    async OnPostRun(context) {
+        if (!context.Driver) {
+            throw new Error('Index Advisor needs an open database connection');
+        }
+        const options = ResolveIndexAdvisorOptions(context.Options);
+        const { Existing, SkippedSchemas } = await readExistingIndexes(context.Driver, context.State);
+        const data = {
+            AnalyzedAt: new Date().toISOString(),
+            Options: options,
+            Existing,
+            Proposed: ProposeIndexes(withoutSkippedSchemas(context.State, SkippedSchemas), Existing, options),
+            Redundant: FindRedundantIndexes(Existing),
+            SkippedSchemas
+        };
+        if (options.LLMReview) {
+            await runLLMReview(context, data);
+        }
+        this.SetData(context, INDEX_ADVISOR_PLUGIN_NAME, data);
+        context.Log(`Index Advisor: ${data.Existing.length} existing index(es), ${data.Proposed.length} proposed, ${data.Redundant.length} redundant` +
+            (SkippedSchemas.length ? `, ${SkippedSchemas.length} schema(s) skipped` : '') +
+            (data.LLMReview ? `; LLM review: ${data.LLMReview.TablesReviewed} table(s), ${data.LLMReview.Dropped.length} dropped, ${data.LLMReview.Errors.length} error(s)` : ''));
+    }
+    GetExporters() {
+        return [{
+                Format: 'index-migration',
+                Description: 'SQL migration creating the indexes proposed by the Index Advisor',
+                Generate: (state, options) => {
+                    const data = GetIndexAdvisorData(state);
+                    return data ? new IndexMigrationGenerator().Generate(data, options) : [];
+                }
+            }];
+    }
+};
+IndexAdvisorPlugin = __decorate([
+    RegisterClass(BaseAutoDocPlugin, INDEX_ADVISOR_PLUGIN_NAME)
+], IndexAdvisorPlugin);
+export { IndexAdvisorPlugin };
+/** The Index Advisor's section of a state file, when the plugin has run. */
+export function GetIndexAdvisorData(state) {
+    return state.plugins?.[INDEX_ADVISOR_PLUGIN_NAME]?.Data;
+}
+/** Merges config-file options over the defaults, ignoring values of the wrong type. */
+export function ResolveIndexAdvisorOptions(raw) {
+    const num = (v, d) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
+    const bool = (v, d) => (typeof v === 'boolean' ? v : d);
+    const d = DEFAULT_INDEX_ADVISOR_OPTIONS;
+    return {
+        MinRowCount: num(raw['MinRowCount'], d.MinRowCount),
+        IncludeDiscoveredFKs: bool(raw['IncludeDiscoveredFKs'], d.IncludeDiscoveredFKs),
+        KeyMinConfidence: num(raw['KeyMinConfidence'], d.KeyMinConfidence),
+        LLMReview: bool(raw['LLMReview'], d.LLMReview),
+        MaxLLMTables: num(raw['MaxLLMTables'], d.MaxLLMTables),
+        Concurrently: bool(raw['Concurrently'], d.Concurrently)
+    };
+}
+/** Reads indexes schema by schema; a schema that fails is recorded and skipped. */
+async function readExistingIndexes(driver, state) {
+    const existing = [];
+    const skipped = [];
+    for (const schema of state.schemas) {
+        try {
+            existing.push(...(await driver.GetIndexes(schema.name)));
+        }
+        catch (err) {
+            skipped.push({ SchemaName: schema.name, Error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return { Existing: existing, SkippedSchemas: skipped };
+}
+/**
+ * The state limited to schemas whose indexes were read. Proposing for a schema whose existing
+ * indexes are unknown would suggest indexes that may already exist.
+ */
+function withoutSkippedSchemas(state, skipped) {
+    const skippedNames = new Set(skipped.map((s) => s.SchemaName));
+    return skippedNames.size ? { ...state, schemas: state.schemas.filter((s) => !skippedNames.has(s.name)) } : state;
+}
+/**
+ * Lets the LLM keep, drop, modify or add proposals. Any failure to set up the model keeps the
+ * rule-based proposals and is recorded in the review summary.
+ */
+async function runLLMReview(context, data) {
+    const platform = context.State.database.provider ?? context.Config.database.provider ?? 'sqlserver';
+    try {
+        const reviewer = await IndexLLMReviewer.Create(context.Config.ai, context.Log);
+        const reviewed = await reviewer.Review(context.State, data, platform);
+        data.Proposed = reviewed.Proposals;
+        data.LLMReview = reviewed.Summary;
+    }
+    catch (err) {
+        data.LLMReview = {
+            Model: context.Config.ai.modelOverrides?.['indexAdvisor']?.model ?? context.Config.ai.model,
+            TablesReviewed: 0, TokensUsed: 0, Dropped: [], Rejected: [],
+            Errors: [{ TableName: '*', Error: err instanceof Error ? err.message : String(err) }]
+        };
+    }
+}
+//# sourceMappingURL=IndexAdvisorPlugin.js.map

package/dist/plugins/index-advisor/IndexAdvisorPlugin.js.map

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

package/dist/plugins/index-advisor/IndexAdvisorTypes.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Types for the Index Advisor plugin's options and its section of the state file.
+ */
+import type { AutoDocIndex } from '../../types/driver.js';
+/** Where a proposal came from. */
+export type IndexProposalSource = 'FKCoverage' | 'SoftPrimaryKey' | 'LLM';
+/** A proposed new index. */
+export interface IndexProposal {
+    SchemaName: string;
+    TableName: string;
+    /** Key columns, in index order. */
+    Columns: string[];
+    /** Non-key covering columns (SQL Server / PostgreSQL INCLUDE). */
+    IncludeColumns: string[];
+    Source: IndexProposalSource;
+    Reason: string;
+    /** 1 (low) – 100 (high); larger tables score higher. */
+    Priority: number;
+    Evidence: IndexProposalEvidence;
+}
+export interface IndexProposalEvidence {
+    RowCount: number;
+    /** Distinct values of the leading column, when column statistics are available. */
+    LeadingColumnDistinctCount?: number;
+    /** `schema.table.column` the foreign key points at (FK coverage proposals). */
+    References?: string;
+    /** Confidence of the discovered key that motivated the proposal (0–100). */
+    KeyConfidence?: number;
+    /** Whether the motivating key is declared in the database or was discovered. */
+    KeyOrigin?: 'declared' | 'discovered';
+}
+/** An existing index whose job another index already does. Reported only; never dropped. */
+export interface RedundantIndex {
+    SchemaName: string;
+    TableName: string;
+    IndexName: string;
+    CoveredBy: string;
+    Reason: string;
+}
+/** Index Advisor options from the config file (`plugins[].Options`). */
+export interface IndexAdvisorOptions {
+    /** Tables with fewer rows get no proposals. Default 1000. */
+    MinRowCount: number;
+    /** Also index discovered (not just declared) foreign keys. Default true. */
+    IncludeDiscoveredFKs: boolean;
+    /** Minimum confidence for a discovered key to be used. Default 90. */
+    KeyMinConfidence: number;
+    /** Run the LLM review layer. Default true. */
+    LLMReview: boolean;
+    /** Most tables the LLM review looks at (largest first). Default 40. */
+    MaxLLMTables: number;
+    /** PostgreSQL: emit CREATE INDEX CONCURRENTLY (no write lock while building; runs outside a transaction). Default true. */
+    Concurrently: boolean;
+}
+/** The plugin's section of the state file (`state.plugins.IndexAdvisor.Data`). */
+export interface IndexAdvisorData {
+    AnalyzedAt: string;
+    Options: IndexAdvisorOptions;
+    Existing: AutoDocIndex[];
+    Proposed: IndexProposal[];
+    Redundant: RedundantIndex[];
+    /** Schemas whose existing indexes could not be read (proposals for them are skipped). */
+    SkippedSchemas: {
+        SchemaName: string;
+        Error: string;
+    }[];
+    /** What the LLM review did. Absent when the review was off. */
+    LLMReview?: IndexLLMReviewSummary;
+}
+/** Outcome of the LLM review layer. */
+export interface IndexLLMReviewSummary {
+    Model: string;
+    TablesReviewed: number;
+    TokensUsed: number;
+    /** Rule-based proposals the review removed, with its reason. */
+    Dropped: {
+        Proposal: IndexProposal;
+        Reason: string;
+    }[];
+    /** LLM suggestions that failed validation and were not applied. */
+    Rejected: {
+        TableName: string;
+        Columns: string[];
+        Why: string;
+    }[];
+    /** Tables whose review call failed; their rule-based proposals were kept unchanged. */
+    Errors: {
+        TableName: string;
+        Error: string;
+    }[];
+}
+/** One proposal decision the LLM returns. `Proposal` is the 1-based number shown in the prompt. */
+export interface IndexReviewDecision {
+    Proposal: number;
+    Action: 'keep' | 'drop' | 'modify';
+    Columns?: string[];
+    IncludeColumns?: string[];
+    Reason: string;
+}
+/** A new index the LLM suggests. */
+export interface IndexReviewAddition {
+    Columns: string[];
+    IncludeColumns?: string[];
+    Reason: string;
+}
+/** The LLM's full response for one table. */
+export interface IndexReviewResponse {
+    Decisions: IndexReviewDecision[];
+    Additions: IndexReviewAddition[];
+}
+//# sourceMappingURL=IndexAdvisorTypes.d.ts.map