@metamask-previews/messenger-cli 0.0.0-preview-4a2a8e8f6 → 0.1.0-preview-e19d3725e

package/dist/docs/generate.cjs

@@ -0,0 +1,254 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generate = void 0;
+const node_1 = require("@metamask/utils/node");
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const node_util_1 = require("node:util");
+const discovery_1 = require("./discovery.cjs");
+const extraction_1 = require("./extraction.cjs");
+const markdown_1 = require("./markdown.cjs");
+/**
+ * Compute a deduplication score for a messenger item, preferring items with
+ * JSDoc and from the "home" package whose name matches the namespace.
+ *
+ * @param item - The messenger item to score.
+ * @returns A numeric score (higher is better).
+ */
+function deduplicationScore(item) {
+    const jsDocScore = item.jsDoc ? 2 : 0;
+    const namespacePrefix = item.typeString
+        .split(':')[0]
+        .replace(/Controller|Service/u, '')
+        .toLowerCase();
+    const homeScore = item.sourceFile.includes(namespacePrefix) ? 1 : 0;
+    return jsDocScore + homeScore;
+}
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+/**
+ * Resolve the GitHub blob base URL for a project by reading its git remote.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns A base URL like "https://github.com/Owner/Repo/blob/main/" or null.
+ */
+async function resolveRepoBaseUrl(projectPath) {
+    try {
+        const { stdout: remoteRaw } = await execFileAsync('git', ['remote', 'get-url', 'origin'], { cwd: projectPath });
+        const remote = remoteRaw.trim();
+        // Parse owner/repo from SSH or HTTPS remote URLs
+        // Handles aliases like github.com-Org used in SSH configs
+        const match = remote.match(/github\.com[^:/]*[:/]([^/]+\/[^/]+?)(?:\.git)?$/u);
+        if (!match) {
+            return null;
+        }
+        return `https://github.com/${match[1]}/blob/main/`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scan a project for messenger action/event types and generate documentation.
+ *
+ * @param options - Generation options.
+ * @returns A promise resolving to counts of generated namespaces, actions, and events.
+ */
+async function generate(options) {
+    const { projectPath, outputDir, scanDirs } = options;
+    const allItems = [];
+    // Check which sources are available
+    const existingScanDirs = [];
+    for (const dir of scanDirs) {
+        const abs = path.join(projectPath, dir);
+        if (await (0, node_1.directoryExists)(abs)) {
+            existingScanDirs.push(dir);
+        }
+    }
+    const packagesDir = path.join(projectPath, 'packages');
+    const hasPackages = await (0, node_1.directoryExists)(packagesDir);
+    const nmDir = path.join(projectPath, 'node_modules', '@metamask');
+    const hasNodeModules = await (0, node_1.directoryExists)(nmDir);
+    const sources = [];
+    for (const dir of existingScanDirs) {
+        sources.push(`${dir}/ (.ts)`);
+    }
+    if (hasPackages) {
+        sources.push('packages/*/src (.ts)');
+    }
+    if (hasNodeModules) {
+        sources.push('node_modules/@metamask/*/dist (.d.cts)');
+    }
+    console.log(`Scanning ${sources.join(', ')} for Messenger action/event types...`);
+    // Scan configured source directories for .ts files
+    for (const dir of existingScanDirs) {
+        const abs = path.join(projectPath, dir);
+        const tsFiles = await (0, discovery_1.findTsFiles)(abs);
+        for (const file of tsFiles) {
+            try {
+                const items = await (0, extraction_1.extractFromFile)(file, projectPath);
+                allItems.push(...items);
+            }
+            catch (error) {
+                console.warn(`Warning: failed to parse ${path.relative(projectPath, file)}: ${String(error)}`);
+            }
+        }
+    }
+    // Scan packages/*/src for .ts source files (monorepo)
+    if (hasPackages) {
+        const entries = await fs.readdir(packagesDir, { withFileTypes: true });
+        const packageDirs = entries
+            .filter((dirent) => dirent.isDirectory())
+            .map((dirent) => path.join(packagesDir, dirent.name, 'src'));
+        for (const srcDir of packageDirs) {
+            if (!(await (0, node_1.directoryExists)(srcDir))) {
+                continue;
+            }
+            const tsFiles = await (0, discovery_1.findTsFiles)(srcDir);
+            for (const file of tsFiles) {
+                try {
+                    const items = await (0, extraction_1.extractFromFile)(file, projectPath);
+                    allItems.push(...items);
+                }
+                catch (error) {
+                    console.warn(`Warning: failed to parse ${path.relative(projectPath, file)}: ${String(error)}`);
+                }
+            }
+        }
+    }
+    // Scan node_modules/@metamask/*/dist for .d.cts declaration files
+    if (hasNodeModules) {
+        const entries = await fs.readdir(nmDir, { withFileTypes: true });
+        const pkgDirs = entries
+            .filter((dirent) => dirent.isDirectory() || dirent.isSymbolicLink())
+            .map((dirent) => path.join(nmDir, dirent.name, 'dist'));
+        for (const distDir of pkgDirs) {
+            if (!(await (0, node_1.directoryExists)(distDir))) {
+                continue;
+            }
+            const dtsFiles = await (0, discovery_1.findDtsFiles)(distDir);
+            for (const file of dtsFiles) {
+                try {
+                    const items = await (0, extraction_1.extractFromFile)(file, projectPath);
+                    allItems.push(...items);
+                }
+                catch (error) {
+                    console.warn(`Warning: failed to parse ${path.relative(projectPath, file)}: ${String(error)}`);
+                }
+            }
+        }
+    }
+    if (existingScanDirs.length === 0 && !hasPackages && !hasNodeModules) {
+        throw new Error(`No scannable directories found in ${projectPath}. ` +
+            `Looked for: ${scanDirs.join(', ')}, packages/, node_modules/@metamask/`);
+    }
+    console.log(`Found ${allItems.length} messenger items total.`);
+    // Group by namespace (part before the colon), deduplicating by typeString.
+    // When duplicates exist, prefer the one with JSDoc, or from the package
+    // whose name matches the namespace.
+    const byNamespace = new Map();
+    const seen = new Map(); // key: typeString
+    for (const item of allItems) {
+        const existing = seen.get(item.typeString);
+        if (existing) {
+            // Prefer item with JSDoc, or from the "home" package
+            const existingScore = deduplicationScore(existing);
+            const newScore = deduplicationScore(item);
+            if (newScore <= existingScore) {
+                continue;
+            }
+            // Replace existing with better item
+            const ns = item.typeString.split(':')[0];
+            const group = byNamespace.get(ns);
+            if (group) {
+                const list = existing.kind === 'action' ? group.actions : group.events;
+                const idx = list.indexOf(existing);
+                if (idx !== -1) {
+                    list[idx] = item;
+                }
+            }
+            seen.set(item.typeString, item);
+            continue;
+        }
+        seen.set(item.typeString, item);
+        const ns = item.typeString.split(':')[0];
+        if (!byNamespace.has(ns)) {
+            byNamespace.set(ns, { namespace: ns, actions: [], events: [] });
+        }
+        const group = byNamespace.get(ns);
+        if (group) {
+            if (item.kind === 'action') {
+                group.actions.push(item);
+            }
+            else {
+                group.events.push(item);
+            }
+        }
+    }
+    // Sort namespaces alphabetically, sort items within each namespace
+    const namespaces = Array.from(byNamespace.values()).sort((a, b) => a.namespace.localeCompare(b.namespace));
+    for (const ns of namespaces) {
+        ns.actions.sort((a, b) => a.typeString.localeCompare(b.typeString));
+        ns.events.sort((a, b) => a.typeString.localeCompare(b.typeString));
+    }
+    // Resolve repository base URL for source links
+    const repoBaseUrl = await resolveRepoBaseUrl(projectPath);
+    // Write output
+    const docsDir = path.join(outputDir, 'docs');
+    // Clean existing generated docs
+    if (await (0, node_1.directoryExists)(docsDir)) {
+        await fs.rm(docsDir, { recursive: true });
+    }
+    await fs.mkdir(docsDir, { recursive: true });
+    // Generate namespace pages
+    for (const ns of namespaces) {
+        const nsDir = path.join(docsDir, ns.namespace);
+        await fs.mkdir(nsDir, { recursive: true });
+        if (ns.actions.length > 0) {
+            await fs.writeFile(path.join(nsDir, 'actions.md'), (0, markdown_1.generateNamespacePage)(ns, 'action', repoBaseUrl));
+        }
+        if (ns.events.length > 0) {
+            await fs.writeFile(path.join(nsDir, 'events.md'), (0, markdown_1.generateNamespacePage)(ns, 'event', repoBaseUrl));
+        }
+    }
+    // Generate index page
+    await fs.writeFile(path.join(docsDir, 'index.md'), (0, markdown_1.generateIndexPage)(namespaces));
+    // Generate sidebars
+    await fs.writeFile(path.join(outputDir, 'sidebars.ts'), (0, markdown_1.generateSidebars)(namespaces));
+    const totalActions = namespaces.reduce((sum, ns) => sum + ns.actions.length, 0);
+    const totalEvents = namespaces.reduce((sum, ns) => sum + ns.events.length, 0);
+    console.log(`Generated docs for ${namespaces.length} namespaces.`);
+    console.log(`  Actions: ${totalActions}`);
+    console.log(`  Events: ${totalEvents}`);
+    console.log(`Output: ${docsDir}/`);
+    return {
+        namespaces: namespaces.length,
+        actions: totalActions,
+        events: totalEvents,
+    };
+}
+exports.generate = generate;
+//# sourceMappingURL=generate.cjs.map

package/dist/docs/generate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.cjs","sourceRoot":"","sources":["../../src/docs/generate.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,+CAAuD;AACvD,2DAA8C;AAC9C,qDAAuC;AACvC,gDAAkC;AAClC,yCAAsC;AAEtC,+CAAwD;AACxD,iDAA+C;AAC/C,6CAIoB;AAGpB;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,IAAsB;IAChD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,eAAe,GAAG,IAAI,CAAC,UAAU;SACpC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACb,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC;SAClC,WAAW,EAAE,CAAC;IACjB,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,UAAU,GAAG,SAAS,CAAC;AAChC,CAAC;AAED,MAAM,aAAa,GAAG,IAAA,qBAAS,EAAC,6BAAQ,CAAC,CAAC;AAE1C;;;;;GAKG;AACH,KAAK,UAAU,kBAAkB,CAAC,WAAmB;IACnD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,aAAa,CAC/C,KAAK,EACL,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,EAC/B,EAAE,GAAG,EAAE,WAAW,EAAE,CACrB,CAAC;QAEF,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QAEhC,iDAAiD;QACjD,0DAA0D;QAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CACxB,kDAAkD,CACnD,CAAC;QACF,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,sBAAsB,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAuBD;;;;;GAKG;AACI,KAAK,UAAU,QAAQ,CAC5B,OAAwB;IAExB,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAErD,MAAM,QAAQ,GAAuB,EAAE,CAAC;IAExC,oCAAoC;IACpC,MAAM,gBAAgB,GAAa,EAAE,CAAC;IACtC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACxC,IAAI,MAAM,IAAA,sBAAe,EAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IACvD,MAAM,WAAW,GAAG,MAAM,IAAA,sBAAe,EAAC,WAAW,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;IAClE,MAAM,cAAc,GAAG,MAAM,IAAA,sBAAe,EAAC,KAAK,CAAC,CAAC;IAEpD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,CAAC,GAAG,CACT,YAAY,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,sCAAsC,CACrE,CAAC;IAEF,mDAAmD;IACnD,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,MAAM,IAAA,uBAAW,EAAC,GAAG,CAAC,CAAC;QACvC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,IAAA,4BAAe,EAAC,IAAI,EAAE,WAAW,CAAC,CAAC;gBACvD,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,CACV,4BAA4B,IAAI,CAAC,QAAQ,CACvC,WAAW,EACX,IAAI,CACL,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CACtB,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACvE,MAAM,WAAW,GAAG,OAAO;aACxB,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;aACxC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QAE/D,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;YACjC,IAAI,CAAC,CAAC,MAAM,IAAA,sBAAe,EAAC,MAAM,CAAC,CAAC,EAAE,CAAC;gBACrC,SAAS;YACX,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,IAAA,uBAAW,EAAC,MAAM,CAAC,CAAC;YAC1C,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;gBAC3B,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,MAAM,IAAA,4BAAe,EAAC,IAAI,EAAE,WAAW,CAAC,CAAC;oBACvD,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;gBAC1B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,IAAI,CACV,4BAA4B,IAAI,CAAC,QAAQ,CACvC,WAAW,EACX,IAAI,CACL,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CACtB,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,MAAM,OAAO,GAAG,OAAO;aACpB,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;aACnE,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAE1D,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;YAC9B,IAAI,CAAC,CAAC,MAAM,IAAA,sBAAe,EAAC,OAAO,CAAC,CAAC,EAAE,CAAC;gBACtC,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,IAAA,wBAAY,EAAC,OAAO,CAAC,CAAC;YAC7C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;gBAC5B,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,MAAM,IAAA,4BAAe,EAAC,IAAI,EAAE,WAAW,CAAC,CAAC;oBACvD,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;gBAC1B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,IAAI,CACV,4BAA4B,IAAI,CAAC,QAAQ,CACvC,WAAW,EACX,IAAI,CACL,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CACtB,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,cAAc,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CACb,qCAAqC,WAAW,IAAI;YAClD,eAAe,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,sCAAsC,CAC3E,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,SAAS,QAAQ,CAAC,MAAM,yBAAyB,CAAC,CAAC;IAE/D,2EAA2E;IAC3E,wEAAwE;IACxE,oCAAoC;IACpC,MAAM,WAAW,GAAG,IAAI,GAAG,EAA0B,CAAC;IACtD,MAAM,IAAI,GAAG,IAAI,GAAG,EAA4B,CAAC,CAAC,kBAAkB;IAEpE,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,QAAQ,EAAE,CAAC;YACb,qDAAqD;YACrD,MAAM,aAAa,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YACnD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,QAAQ,IAAI,aAAa,EAAE,CAAC;gBAC9B,SAAS;YACX,CAAC;YACD,oCAAoC;YACpC,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACzC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClC,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;gBACvE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACnC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;oBACf,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;gBACnB,CAAC;YACH,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YAChC,SAAS;QACX,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAChC,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACzB,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC3B,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAChE,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CACvC,CAAC;IAEF,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;QACpE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IACrE,CAAC;IAED,+CAA+C;IAC/C,MAAM,WAAW,GAAG,MAAM,kBAAkB,CAAC,WAAW,CAAC,CAAC;IAE1D,eAAe;IACf,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAE7C,gCAAgC;IAChC,IAAI,MAAM,IAAA,sBAAe,EAAC,OAAO,CAAC,EAAE,CAAC;QACnC,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7C,2BAA2B;IAC3B,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE3C,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,EAC9B,IAAA,gCAAqB,EAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,CAAC,CACjD,CAAC;QACJ,CAAC;QAED,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,EAC7B,IAAA,gCAAqB,EAAC,EAAE,EAAE,OAAO,EAAE,WAAW,CAAC,CAChD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,EAC9B,IAAA,4BAAiB,EAAC,UAAU,CAAC,CAC9B,CAAC;IAEF,oBAAoB;IACpB,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,EACnC,IAAA,2BAAgB,EAAC,UAAU,CAAC,CAC7B,CAAC;IAEF,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CACpC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EACpC,CAAC,CACF,CAAC;IACF,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAE9E,OAAO,CAAC,GAAG,CAAC,sBAAsB,UAAU,CAAC,MAAM,cAAc,CAAC,CAAC;IACnE,OAAO,CAAC,GAAG,CAAC,cAAc,YAAY,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,CAAC,aAAa,WAAW,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,WAAW,OAAO,GAAG,CAAC,CAAC;IAEnC,OAAO;QACL,UAAU,EAAE,UAAU,CAAC,MAAM;QAC7B,OAAO,EAAE,YAAY;QACrB,MAAM,EAAE,WAAW;KACpB,CAAC;AACJ,CAAC;AA1OD,4BA0OC","sourcesContent":["import { directoryExists } from '@metamask/utils/node';\nimport { execFile } from 'node:child_process';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport { promisify } from 'node:util';\n\nimport { findDtsFiles, findTsFiles } from './discovery';\nimport { extractFromFile } from './extraction';\nimport {\n  generateIndexPage,\n  generateNamespacePage,\n  generateSidebars,\n} from './markdown';\nimport type { MessengerItemDoc, NamespaceGroup } from './types';\n\n/**\n * Compute a deduplication score for a messenger item, preferring items with\n * JSDoc and from the \"home\" package whose name matches the namespace.\n *\n * @param item - The messenger item to score.\n * @returns A numeric score (higher is better).\n */\nfunction deduplicationScore(item: MessengerItemDoc): number {\n  const jsDocScore = item.jsDoc ? 2 : 0;\n  const namespacePrefix = item.typeString\n    .split(':')[0]\n    .replace(/Controller|Service/u, '')\n    .toLowerCase();\n  const homeScore = item.sourceFile.includes(namespacePrefix) ? 1 : 0;\n  return jsDocScore + homeScore;\n}\n\nconst execFileAsync = promisify(execFile);\n\n/**\n * Resolve the GitHub blob base URL for a project by reading its git remote.\n *\n * @param projectPath - Absolute path to the project root.\n * @returns A base URL like \"https://github.com/Owner/Repo/blob/main/\" or null.\n */\nasync function resolveRepoBaseUrl(projectPath: string): Promise<string | null> {\n  try {\n    const { stdout: remoteRaw } = await execFileAsync(\n      'git',\n      ['remote', 'get-url', 'origin'],\n      { cwd: projectPath },\n    );\n\n    const remote = remoteRaw.trim();\n\n    // Parse owner/repo from SSH or HTTPS remote URLs\n    // Handles aliases like github.com-Org used in SSH configs\n    const match = remote.match(\n      /github\\.com[^:/]*[:/]([^/]+\\/[^/]+?)(?:\\.git)?$/u,\n    );\n    if (!match) {\n      return null;\n    }\n\n    return `https://github.com/${match[1]}/blob/main/`;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Options for the generate function.\n */\nexport type GenerateOptions = {\n  /** Absolute path to the project to scan. */\n  projectPath: string;\n  /** Absolute path to the output directory for generated docs. */\n  outputDir: string;\n  /** Directories (relative to projectPath) to scan for .ts source files. */\n  scanDirs: string[];\n};\n\n/**\n * Result returned by the generate function.\n */\nexport type GenerateResult = {\n  namespaces: number;\n  actions: number;\n  events: number;\n};\n\n/**\n * Scan a project for messenger action/event types and generate documentation.\n *\n * @param options - Generation options.\n * @returns A promise resolving to counts of generated namespaces, actions, and events.\n */\nexport async function generate(\n  options: GenerateOptions,\n): Promise<GenerateResult> {\n  const { projectPath, outputDir, scanDirs } = options;\n\n  const allItems: MessengerItemDoc[] = [];\n\n  // Check which sources are available\n  const existingScanDirs: string[] = [];\n  for (const dir of scanDirs) {\n    const abs = path.join(projectPath, dir);\n    if (await directoryExists(abs)) {\n      existingScanDirs.push(dir);\n    }\n  }\n  const packagesDir = path.join(projectPath, 'packages');\n  const hasPackages = await directoryExists(packagesDir);\n  const nmDir = path.join(projectPath, 'node_modules', '@metamask');\n  const hasNodeModules = await directoryExists(nmDir);\n\n  const sources: string[] = [];\n  for (const dir of existingScanDirs) {\n    sources.push(`${dir}/ (.ts)`);\n  }\n  if (hasPackages) {\n    sources.push('packages/*/src (.ts)');\n  }\n  if (hasNodeModules) {\n    sources.push('node_modules/@metamask/*/dist (.d.cts)');\n  }\n  console.log(\n    `Scanning ${sources.join(', ')} for Messenger action/event types...`,\n  );\n\n  // Scan configured source directories for .ts files\n  for (const dir of existingScanDirs) {\n    const abs = path.join(projectPath, dir);\n    const tsFiles = await findTsFiles(abs);\n    for (const file of tsFiles) {\n      try {\n        const items = await extractFromFile(file, projectPath);\n        allItems.push(...items);\n      } catch (error) {\n        console.warn(\n          `Warning: failed to parse ${path.relative(\n            projectPath,\n            file,\n          )}: ${String(error)}`,\n        );\n      }\n    }\n  }\n\n  // Scan packages/*/src for .ts source files (monorepo)\n  if (hasPackages) {\n    const entries = await fs.readdir(packagesDir, { withFileTypes: true });\n    const packageDirs = entries\n      .filter((dirent) => dirent.isDirectory())\n      .map((dirent) => path.join(packagesDir, dirent.name, 'src'));\n\n    for (const srcDir of packageDirs) {\n      if (!(await directoryExists(srcDir))) {\n        continue;\n      }\n\n      const tsFiles = await findTsFiles(srcDir);\n      for (const file of tsFiles) {\n        try {\n          const items = await extractFromFile(file, projectPath);\n          allItems.push(...items);\n        } catch (error) {\n          console.warn(\n            `Warning: failed to parse ${path.relative(\n              projectPath,\n              file,\n            )}: ${String(error)}`,\n          );\n        }\n      }\n    }\n  }\n\n  // Scan node_modules/@metamask/*/dist for .d.cts declaration files\n  if (hasNodeModules) {\n    const entries = await fs.readdir(nmDir, { withFileTypes: true });\n    const pkgDirs = entries\n      .filter((dirent) => dirent.isDirectory() || dirent.isSymbolicLink())\n      .map((dirent) => path.join(nmDir, dirent.name, 'dist'));\n\n    for (const distDir of pkgDirs) {\n      if (!(await directoryExists(distDir))) {\n        continue;\n      }\n\n      const dtsFiles = await findDtsFiles(distDir);\n      for (const file of dtsFiles) {\n        try {\n          const items = await extractFromFile(file, projectPath);\n          allItems.push(...items);\n        } catch (error) {\n          console.warn(\n            `Warning: failed to parse ${path.relative(\n              projectPath,\n              file,\n            )}: ${String(error)}`,\n          );\n        }\n      }\n    }\n  }\n\n  if (existingScanDirs.length === 0 && !hasPackages && !hasNodeModules) {\n    throw new Error(\n      `No scannable directories found in ${projectPath}. ` +\n        `Looked for: ${scanDirs.join(', ')}, packages/, node_modules/@metamask/`,\n    );\n  }\n\n  console.log(`Found ${allItems.length} messenger items total.`);\n\n  // Group by namespace (part before the colon), deduplicating by typeString.\n  // When duplicates exist, prefer the one with JSDoc, or from the package\n  // whose name matches the namespace.\n  const byNamespace = new Map<string, NamespaceGroup>();\n  const seen = new Map<string, MessengerItemDoc>(); // key: typeString\n\n  for (const item of allItems) {\n    const existing = seen.get(item.typeString);\n    if (existing) {\n      // Prefer item with JSDoc, or from the \"home\" package\n      const existingScore = deduplicationScore(existing);\n      const newScore = deduplicationScore(item);\n      if (newScore <= existingScore) {\n        continue;\n      }\n      // Replace existing with better item\n      const ns = item.typeString.split(':')[0];\n      const group = byNamespace.get(ns);\n      if (group) {\n        const list = existing.kind === 'action' ? group.actions : group.events;\n        const idx = list.indexOf(existing);\n        if (idx !== -1) {\n          list[idx] = item;\n        }\n      }\n      seen.set(item.typeString, item);\n      continue;\n    }\n\n    seen.set(item.typeString, item);\n    const ns = item.typeString.split(':')[0];\n    if (!byNamespace.has(ns)) {\n      byNamespace.set(ns, { namespace: ns, actions: [], events: [] });\n    }\n    const group = byNamespace.get(ns);\n    if (group) {\n      if (item.kind === 'action') {\n        group.actions.push(item);\n      } else {\n        group.events.push(item);\n      }\n    }\n  }\n\n  // Sort namespaces alphabetically, sort items within each namespace\n  const namespaces = Array.from(byNamespace.values()).sort((a, b) =>\n    a.namespace.localeCompare(b.namespace),\n  );\n\n  for (const ns of namespaces) {\n    ns.actions.sort((a, b) => a.typeString.localeCompare(b.typeString));\n    ns.events.sort((a, b) => a.typeString.localeCompare(b.typeString));\n  }\n\n  // Resolve repository base URL for source links\n  const repoBaseUrl = await resolveRepoBaseUrl(projectPath);\n\n  // Write output\n  const docsDir = path.join(outputDir, 'docs');\n\n  // Clean existing generated docs\n  if (await directoryExists(docsDir)) {\n    await fs.rm(docsDir, { recursive: true });\n  }\n  await fs.mkdir(docsDir, { recursive: true });\n\n  // Generate namespace pages\n  for (const ns of namespaces) {\n    const nsDir = path.join(docsDir, ns.namespace);\n    await fs.mkdir(nsDir, { recursive: true });\n\n    if (ns.actions.length > 0) {\n      await fs.writeFile(\n        path.join(nsDir, 'actions.md'),\n        generateNamespacePage(ns, 'action', repoBaseUrl),\n      );\n    }\n\n    if (ns.events.length > 0) {\n      await fs.writeFile(\n        path.join(nsDir, 'events.md'),\n        generateNamespacePage(ns, 'event', repoBaseUrl),\n      );\n    }\n  }\n\n  // Generate index page\n  await fs.writeFile(\n    path.join(docsDir, 'index.md'),\n    generateIndexPage(namespaces),\n  );\n\n  // Generate sidebars\n  await fs.writeFile(\n    path.join(outputDir, 'sidebars.ts'),\n    generateSidebars(namespaces),\n  );\n\n  const totalActions = namespaces.reduce(\n    (sum, ns) => sum + ns.actions.length,\n    0,\n  );\n  const totalEvents = namespaces.reduce((sum, ns) => sum + ns.events.length, 0);\n\n  console.log(`Generated docs for ${namespaces.length} namespaces.`);\n  console.log(`  Actions: ${totalActions}`);\n  console.log(`  Events: ${totalEvents}`);\n  console.log(`Output: ${docsDir}/`);\n\n  return {\n    namespaces: namespaces.length,\n    actions: totalActions,\n    events: totalEvents,\n  };\n}\n"]}

package/dist/docs/generate.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Options for the generate function.
+ */
+export type GenerateOptions = {
+    /** Absolute path to the project to scan. */
+    projectPath: string;
+    /** Absolute path to the output directory for generated docs. */
+    outputDir: string;
+    /** Directories (relative to projectPath) to scan for .ts source files. */
+    scanDirs: string[];
+};
+/**
+ * Result returned by the generate function.
+ */
+export type GenerateResult = {
+    namespaces: number;
+    actions: number;
+    events: number;
+};
+/**
+ * Scan a project for messenger action/event types and generate documentation.
+ *
+ * @param options - Generation options.
+ * @returns A promise resolving to counts of generated namespaces, actions, and events.
+ */
+export declare function generate(options: GenerateOptions): Promise<GenerateResult>;
+//# sourceMappingURL=generate.d.cts.map

package/dist/docs/generate.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.cts","sourceRoot":"","sources":["../../src/docs/generate.ts"],"names":[],"mappings":"AAiEA;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAwOzB"}

package/dist/docs/generate.d.mts

@@ -0,0 +1,27 @@
+/**
+ * Options for the generate function.
+ */
+export type GenerateOptions = {
+    /** Absolute path to the project to scan. */
+    projectPath: string;
+    /** Absolute path to the output directory for generated docs. */
+    outputDir: string;
+    /** Directories (relative to projectPath) to scan for .ts source files. */
+    scanDirs: string[];
+};
+/**
+ * Result returned by the generate function.
+ */
+export type GenerateResult = {
+    namespaces: number;
+    actions: number;
+    events: number;
+};
+/**
+ * Scan a project for messenger action/event types and generate documentation.
+ *
+ * @param options - Generation options.
+ * @returns A promise resolving to counts of generated namespaces, actions, and events.
+ */
+export declare function generate(options: GenerateOptions): Promise<GenerateResult>;
+//# sourceMappingURL=generate.d.mts.map

package/dist/docs/generate.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.mts","sourceRoot":"","sources":["../../src/docs/generate.ts"],"names":[],"mappings":"AAiEA;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAwOzB"}

package/dist/docs/generate.mjs

@@ -0,0 +1,227 @@
+import { directoryExists } from "@metamask/utils/node";
+import { execFile } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { findDtsFiles, findTsFiles } from "./discovery.mjs";
+import { extractFromFile } from "./extraction.mjs";
+import { generateIndexPage, generateNamespacePage, generateSidebars } from "./markdown.mjs";
+/**
+ * Compute a deduplication score for a messenger item, preferring items with
+ * JSDoc and from the "home" package whose name matches the namespace.
+ *
+ * @param item - The messenger item to score.
+ * @returns A numeric score (higher is better).
+ */
+function deduplicationScore(item) {
+    const jsDocScore = item.jsDoc ? 2 : 0;
+    const namespacePrefix = item.typeString
+        .split(':')[0]
+        .replace(/Controller|Service/u, '')
+        .toLowerCase();
+    const homeScore = item.sourceFile.includes(namespacePrefix) ? 1 : 0;
+    return jsDocScore + homeScore;
+}
+const execFileAsync = promisify(execFile);
+/**
+ * Resolve the GitHub blob base URL for a project by reading its git remote.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns A base URL like "https://github.com/Owner/Repo/blob/main/" or null.
+ */
+async function resolveRepoBaseUrl(projectPath) {
+    try {
+        const { stdout: remoteRaw } = await execFileAsync('git', ['remote', 'get-url', 'origin'], { cwd: projectPath });
+        const remote = remoteRaw.trim();
+        // Parse owner/repo from SSH or HTTPS remote URLs
+        // Handles aliases like github.com-Org used in SSH configs
+        const match = remote.match(/github\.com[^:/]*[:/]([^/]+\/[^/]+?)(?:\.git)?$/u);
+        if (!match) {
+            return null;
+        }
+        return `https://github.com/${match[1]}/blob/main/`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scan a project for messenger action/event types and generate documentation.
+ *
+ * @param options - Generation options.
+ * @returns A promise resolving to counts of generated namespaces, actions, and events.
+ */
+export async function generate(options) {
+    const { projectPath, outputDir, scanDirs } = options;
+    const allItems = [];
+    // Check which sources are available
+    const existingScanDirs = [];
+    for (const dir of scanDirs) {
+        const abs = path.join(projectPath, dir);
+        if (await directoryExists(abs)) {
+            existingScanDirs.push(dir);
+        }
+    }
+    const packagesDir = path.join(projectPath, 'packages');
+    const hasPackages = await directoryExists(packagesDir);
+    const nmDir = path.join(projectPath, 'node_modules', '@metamask');
+    const hasNodeModules = await directoryExists(nmDir);
+    const sources = [];
+    for (const dir of existingScanDirs) {
+        sources.push(`${dir}/ (.ts)`);
+    }
+    if (hasPackages) {
+        sources.push('packages/*/src (.ts)');
+    }
+    if (hasNodeModules) {
+        sources.push('node_modules/@metamask/*/dist (.d.cts)');
+    }
+    console.log(`Scanning ${sources.join(', ')} for Messenger action/event types...`);
+    // Scan configured source directories for .ts files
+    for (const dir of existingScanDirs) {
+        const abs = path.join(projectPath, dir);
+        const tsFiles = await findTsFiles(abs);
+        for (const file of tsFiles) {
+            try {
+                const items = await extractFromFile(file, projectPath);
+                allItems.push(...items);
+            }
+            catch (error) {
+                console.warn(`Warning: failed to parse ${path.relative(projectPath, file)}: ${String(error)}`);
+            }
+        }
+    }
+    // Scan packages/*/src for .ts source files (monorepo)
+    if (hasPackages) {
+        const entries = await fs.readdir(packagesDir, { withFileTypes: true });
+        const packageDirs = entries
+            .filter((dirent) => dirent.isDirectory())
+            .map((dirent) => path.join(packagesDir, dirent.name, 'src'));
+        for (const srcDir of packageDirs) {
+            if (!(await directoryExists(srcDir))) {
+                continue;
+            }
+            const tsFiles = await findTsFiles(srcDir);
+            for (const file of tsFiles) {
+                try {
+                    const items = await extractFromFile(file, projectPath);
+                    allItems.push(...items);
+                }
+                catch (error) {
+                    console.warn(`Warning: failed to parse ${path.relative(projectPath, file)}: ${String(error)}`);
+                }
+            }
+        }
+    }
+    // Scan node_modules/@metamask/*/dist for .d.cts declaration files
+    if (hasNodeModules) {
+        const entries = await fs.readdir(nmDir, { withFileTypes: true });
+        const pkgDirs = entries
+            .filter((dirent) => dirent.isDirectory() || dirent.isSymbolicLink())
+            .map((dirent) => path.join(nmDir, dirent.name, 'dist'));
+        for (const distDir of pkgDirs) {
+            if (!(await directoryExists(distDir))) {
+                continue;
+            }
+            const dtsFiles = await findDtsFiles(distDir);
+            for (const file of dtsFiles) {
+                try {
+                    const items = await extractFromFile(file, projectPath);
+                    allItems.push(...items);
+                }
+                catch (error) {
+                    console.warn(`Warning: failed to parse ${path.relative(projectPath, file)}: ${String(error)}`);
+                }
+            }
+        }
+    }
+    if (existingScanDirs.length === 0 && !hasPackages && !hasNodeModules) {
+        throw new Error(`No scannable directories found in ${projectPath}. ` +
+            `Looked for: ${scanDirs.join(', ')}, packages/, node_modules/@metamask/`);
+    }
+    console.log(`Found ${allItems.length} messenger items total.`);
+    // Group by namespace (part before the colon), deduplicating by typeString.
+    // When duplicates exist, prefer the one with JSDoc, or from the package
+    // whose name matches the namespace.
+    const byNamespace = new Map();
+    const seen = new Map(); // key: typeString
+    for (const item of allItems) {
+        const existing = seen.get(item.typeString);
+        if (existing) {
+            // Prefer item with JSDoc, or from the "home" package
+            const existingScore = deduplicationScore(existing);
+            const newScore = deduplicationScore(item);
+            if (newScore <= existingScore) {
+                continue;
+            }
+            // Replace existing with better item
+            const ns = item.typeString.split(':')[0];
+            const group = byNamespace.get(ns);
+            if (group) {
+                const list = existing.kind === 'action' ? group.actions : group.events;
+                const idx = list.indexOf(existing);
+                if (idx !== -1) {
+                    list[idx] = item;
+                }
+            }
+            seen.set(item.typeString, item);
+            continue;
+        }
+        seen.set(item.typeString, item);
+        const ns = item.typeString.split(':')[0];
+        if (!byNamespace.has(ns)) {
+            byNamespace.set(ns, { namespace: ns, actions: [], events: [] });
+        }
+        const group = byNamespace.get(ns);
+        if (group) {
+            if (item.kind === 'action') {
+                group.actions.push(item);
+            }
+            else {
+                group.events.push(item);
+            }
+        }
+    }
+    // Sort namespaces alphabetically, sort items within each namespace
+    const namespaces = Array.from(byNamespace.values()).sort((a, b) => a.namespace.localeCompare(b.namespace));
+    for (const ns of namespaces) {
+        ns.actions.sort((a, b) => a.typeString.localeCompare(b.typeString));
+        ns.events.sort((a, b) => a.typeString.localeCompare(b.typeString));
+    }
+    // Resolve repository base URL for source links
+    const repoBaseUrl = await resolveRepoBaseUrl(projectPath);
+    // Write output
+    const docsDir = path.join(outputDir, 'docs');
+    // Clean existing generated docs
+    if (await directoryExists(docsDir)) {
+        await fs.rm(docsDir, { recursive: true });
+    }
+    await fs.mkdir(docsDir, { recursive: true });
+    // Generate namespace pages
+    for (const ns of namespaces) {
+        const nsDir = path.join(docsDir, ns.namespace);
+        await fs.mkdir(nsDir, { recursive: true });
+        if (ns.actions.length > 0) {
+            await fs.writeFile(path.join(nsDir, 'actions.md'), generateNamespacePage(ns, 'action', repoBaseUrl));
+        }
+        if (ns.events.length > 0) {
+            await fs.writeFile(path.join(nsDir, 'events.md'), generateNamespacePage(ns, 'event', repoBaseUrl));
+        }
+    }
+    // Generate index page
+    await fs.writeFile(path.join(docsDir, 'index.md'), generateIndexPage(namespaces));
+    // Generate sidebars
+    await fs.writeFile(path.join(outputDir, 'sidebars.ts'), generateSidebars(namespaces));
+    const totalActions = namespaces.reduce((sum, ns) => sum + ns.actions.length, 0);
+    const totalEvents = namespaces.reduce((sum, ns) => sum + ns.events.length, 0);
+    console.log(`Generated docs for ${namespaces.length} namespaces.`);
+    console.log(`  Actions: ${totalActions}`);
+    console.log(`  Events: ${totalEvents}`);
+    console.log(`Output: ${docsDir}/`);
+    return {
+        namespaces: namespaces.length,
+        actions: totalActions,
+        events: totalEvents,
+    };
+}
+//# sourceMappingURL=generate.mjs.map

package/dist/docs/generate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.mjs","sourceRoot":"","sources":["../../src/docs/generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,6BAA6B;AACvD,OAAO,EAAE,QAAQ,EAAE,2BAA2B;AAC9C,OAAO,KAAK,EAAE,yBAAyB;AACvC,OAAO,KAAK,IAAI,kBAAkB;AAClC,OAAO,EAAE,SAAS,EAAE,kBAAkB;AAEtC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,wBAAoB;AACxD,OAAO,EAAE,eAAe,EAAE,yBAAqB;AAC/C,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EACjB,uBAAmB;AAGpB;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,IAAsB;IAChD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,eAAe,GAAG,IAAI,CAAC,UAAU;SACpC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACb,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC;SAClC,WAAW,EAAE,CAAC;IACjB,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,UAAU,GAAG,SAAS,CAAC;AAChC,CAAC;AAED,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C;;;;;GAKG;AACH,KAAK,UAAU,kBAAkB,CAAC,WAAmB;IACnD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,aAAa,CAC/C,KAAK,EACL,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,EAC/B,EAAE,GAAG,EAAE,WAAW,EAAE,CACrB,CAAC;QAEF,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QAEhC,iDAAiD;QACjD,0DAA0D;QAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CACxB,kDAAkD,CACnD,CAAC;QACF,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,sBAAsB,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAuBD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,OAAwB;IAExB,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAErD,MAAM,QAAQ,GAAuB,EAAE,CAAC;IAExC,oCAAoC;IACpC,MAAM,gBAAgB,GAAa,EAAE,CAAC;IACtC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACxC,IAAI,MAAM,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IACvD,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,WAAW,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;IAClE,MAAM,cAAc,GAAG,MAAM,eAAe,CAAC,KAAK,CAAC,CAAC;IAEpD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,CAAC,GAAG,CACT,YAAY,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,sCAAsC,CACrE,CAAC;IAEF,mDAAmD;IACnD,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;QACvC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;gBACvD,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,CACV,4BAA4B,IAAI,CAAC,QAAQ,CACvC,WAAW,EACX,IAAI,CACL,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CACtB,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACvE,MAAM,WAAW,GAAG,OAAO;aACxB,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;aACxC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QAE/D,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;YACjC,IAAI,CAAC,CAAC,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;gBACrC,SAAS;YACX,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;YAC1C,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;gBAC3B,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;oBACvD,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;gBAC1B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,IAAI,CACV,4BAA4B,IAAI,CAAC,QAAQ,CACvC,WAAW,EACX,IAAI,CACL,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CACtB,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,MAAM,OAAO,GAAG,OAAO;aACpB,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;aACnE,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAE1D,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;YAC9B,IAAI,CAAC,CAAC,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;gBACtC,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;YAC7C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;gBAC5B,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;oBACvD,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;gBAC1B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,IAAI,CACV,4BAA4B,IAAI,CAAC,QAAQ,CACvC,WAAW,EACX,IAAI,CACL,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CACtB,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,cAAc,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CACb,qCAAqC,WAAW,IAAI;YAClD,eAAe,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,sCAAsC,CAC3E,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,SAAS,QAAQ,CAAC,MAAM,yBAAyB,CAAC,CAAC;IAE/D,2EAA2E;IAC3E,wEAAwE;IACxE,oCAAoC;IACpC,MAAM,WAAW,GAAG,IAAI,GAAG,EAA0B,CAAC;IACtD,MAAM,IAAI,GAAG,IAAI,GAAG,EAA4B,CAAC,CAAC,kBAAkB;IAEpE,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,QAAQ,EAAE,CAAC;YACb,qDAAqD;YACrD,MAAM,aAAa,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YACnD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,QAAQ,IAAI,aAAa,EAAE,CAAC;gBAC9B,SAAS;YACX,CAAC;YACD,oCAAoC;YACpC,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACzC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClC,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;gBACvE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACnC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;oBACf,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;gBACnB,CAAC;YACH,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YAChC,SAAS;QACX,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAChC,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACzB,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC3B,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAChE,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CACvC,CAAC;IAEF,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;QACpE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IACrE,CAAC;IAED,+CAA+C;IAC/C,MAAM,WAAW,GAAG,MAAM,kBAAkB,CAAC,WAAW,CAAC,CAAC;IAE1D,eAAe;IACf,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAE7C,gCAAgC;IAChC,IAAI,MAAM,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7C,2BAA2B;IAC3B,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE3C,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,EAC9B,qBAAqB,CAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,CAAC,CACjD,CAAC;QACJ,CAAC;QAED,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,EAC7B,qBAAqB,CAAC,EAAE,EAAE,OAAO,EAAE,WAAW,CAAC,CAChD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,EAC9B,iBAAiB,CAAC,UAAU,CAAC,CAC9B,CAAC;IAEF,oBAAoB;IACpB,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,EACnC,gBAAgB,CAAC,UAAU,CAAC,CAC7B,CAAC;IAEF,MAAM,YAAY,GAAG,UAAU,CAAC,MAAM,CACpC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EACpC,CAAC,CACF,CAAC;IACF,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAE9E,OAAO,CAAC,GAAG,CAAC,sBAAsB,UAAU,CAAC,MAAM,cAAc,CAAC,CAAC;IACnE,OAAO,CAAC,GAAG,CAAC,cAAc,YAAY,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,CAAC,aAAa,WAAW,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,GAAG,CAAC,WAAW,OAAO,GAAG,CAAC,CAAC;IAEnC,OAAO;QACL,UAAU,EAAE,UAAU,CAAC,MAAM;QAC7B,OAAO,EAAE,YAAY;QACrB,MAAM,EAAE,WAAW;KACpB,CAAC;AACJ,CAAC","sourcesContent":["import { directoryExists } from '@metamask/utils/node';\nimport { execFile } from 'node:child_process';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport { promisify } from 'node:util';\n\nimport { findDtsFiles, findTsFiles } from './discovery';\nimport { extractFromFile } from './extraction';\nimport {\n  generateIndexPage,\n  generateNamespacePage,\n  generateSidebars,\n} from './markdown';\nimport type { MessengerItemDoc, NamespaceGroup } from './types';\n\n/**\n * Compute a deduplication score for a messenger item, preferring items with\n * JSDoc and from the \"home\" package whose name matches the namespace.\n *\n * @param item - The messenger item to score.\n * @returns A numeric score (higher is better).\n */\nfunction deduplicationScore(item: MessengerItemDoc): number {\n  const jsDocScore = item.jsDoc ? 2 : 0;\n  const namespacePrefix = item.typeString\n    .split(':')[0]\n    .replace(/Controller|Service/u, '')\n    .toLowerCase();\n  const homeScore = item.sourceFile.includes(namespacePrefix) ? 1 : 0;\n  return jsDocScore + homeScore;\n}\n\nconst execFileAsync = promisify(execFile);\n\n/**\n * Resolve the GitHub blob base URL for a project by reading its git remote.\n *\n * @param projectPath - Absolute path to the project root.\n * @returns A base URL like \"https://github.com/Owner/Repo/blob/main/\" or null.\n */\nasync function resolveRepoBaseUrl(projectPath: string): Promise<string | null> {\n  try {\n    const { stdout: remoteRaw } = await execFileAsync(\n      'git',\n      ['remote', 'get-url', 'origin'],\n      { cwd: projectPath },\n    );\n\n    const remote = remoteRaw.trim();\n\n    // Parse owner/repo from SSH or HTTPS remote URLs\n    // Handles aliases like github.com-Org used in SSH configs\n    const match = remote.match(\n      /github\\.com[^:/]*[:/]([^/]+\\/[^/]+?)(?:\\.git)?$/u,\n    );\n    if (!match) {\n      return null;\n    }\n\n    return `https://github.com/${match[1]}/blob/main/`;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Options for the generate function.\n */\nexport type GenerateOptions = {\n  /** Absolute path to the project to scan. */\n  projectPath: string;\n  /** Absolute path to the output directory for generated docs. */\n  outputDir: string;\n  /** Directories (relative to projectPath) to scan for .ts source files. */\n  scanDirs: string[];\n};\n\n/**\n * Result returned by the generate function.\n */\nexport type GenerateResult = {\n  namespaces: number;\n  actions: number;\n  events: number;\n};\n\n/**\n * Scan a project for messenger action/event types and generate documentation.\n *\n * @param options - Generation options.\n * @returns A promise resolving to counts of generated namespaces, actions, and events.\n */\nexport async function generate(\n  options: GenerateOptions,\n): Promise<GenerateResult> {\n  const { projectPath, outputDir, scanDirs } = options;\n\n  const allItems: MessengerItemDoc[] = [];\n\n  // Check which sources are available\n  const existingScanDirs: string[] = [];\n  for (const dir of scanDirs) {\n    const abs = path.join(projectPath, dir);\n    if (await directoryExists(abs)) {\n      existingScanDirs.push(dir);\n    }\n  }\n  const packagesDir = path.join(projectPath, 'packages');\n  const hasPackages = await directoryExists(packagesDir);\n  const nmDir = path.join(projectPath, 'node_modules', '@metamask');\n  const hasNodeModules = await directoryExists(nmDir);\n\n  const sources: string[] = [];\n  for (const dir of existingScanDirs) {\n    sources.push(`${dir}/ (.ts)`);\n  }\n  if (hasPackages) {\n    sources.push('packages/*/src (.ts)');\n  }\n  if (hasNodeModules) {\n    sources.push('node_modules/@metamask/*/dist (.d.cts)');\n  }\n  console.log(\n    `Scanning ${sources.join(', ')} for Messenger action/event types...`,\n  );\n\n  // Scan configured source directories for .ts files\n  for (const dir of existingScanDirs) {\n    const abs = path.join(projectPath, dir);\n    const tsFiles = await findTsFiles(abs);\n    for (const file of tsFiles) {\n      try {\n        const items = await extractFromFile(file, projectPath);\n        allItems.push(...items);\n      } catch (error) {\n        console.warn(\n          `Warning: failed to parse ${path.relative(\n            projectPath,\n            file,\n          )}: ${String(error)}`,\n        );\n      }\n    }\n  }\n\n  // Scan packages/*/src for .ts source files (monorepo)\n  if (hasPackages) {\n    const entries = await fs.readdir(packagesDir, { withFileTypes: true });\n    const packageDirs = entries\n      .filter((dirent) => dirent.isDirectory())\n      .map((dirent) => path.join(packagesDir, dirent.name, 'src'));\n\n    for (const srcDir of packageDirs) {\n      if (!(await directoryExists(srcDir))) {\n        continue;\n      }\n\n      const tsFiles = await findTsFiles(srcDir);\n      for (const file of tsFiles) {\n        try {\n          const items = await extractFromFile(file, projectPath);\n          allItems.push(...items);\n        } catch (error) {\n          console.warn(\n            `Warning: failed to parse ${path.relative(\n              projectPath,\n              file,\n            )}: ${String(error)}`,\n          );\n        }\n      }\n    }\n  }\n\n  // Scan node_modules/@metamask/*/dist for .d.cts declaration files\n  if (hasNodeModules) {\n    const entries = await fs.readdir(nmDir, { withFileTypes: true });\n    const pkgDirs = entries\n      .filter((dirent) => dirent.isDirectory() || dirent.isSymbolicLink())\n      .map((dirent) => path.join(nmDir, dirent.name, 'dist'));\n\n    for (const distDir of pkgDirs) {\n      if (!(await directoryExists(distDir))) {\n        continue;\n      }\n\n      const dtsFiles = await findDtsFiles(distDir);\n      for (const file of dtsFiles) {\n        try {\n          const items = await extractFromFile(file, projectPath);\n          allItems.push(...items);\n        } catch (error) {\n          console.warn(\n            `Warning: failed to parse ${path.relative(\n              projectPath,\n              file,\n            )}: ${String(error)}`,\n          );\n        }\n      }\n    }\n  }\n\n  if (existingScanDirs.length === 0 && !hasPackages && !hasNodeModules) {\n    throw new Error(\n      `No scannable directories found in ${projectPath}. ` +\n        `Looked for: ${scanDirs.join(', ')}, packages/, node_modules/@metamask/`,\n    );\n  }\n\n  console.log(`Found ${allItems.length} messenger items total.`);\n\n  // Group by namespace (part before the colon), deduplicating by typeString.\n  // When duplicates exist, prefer the one with JSDoc, or from the package\n  // whose name matches the namespace.\n  const byNamespace = new Map<string, NamespaceGroup>();\n  const seen = new Map<string, MessengerItemDoc>(); // key: typeString\n\n  for (const item of allItems) {\n    const existing = seen.get(item.typeString);\n    if (existing) {\n      // Prefer item with JSDoc, or from the \"home\" package\n      const existingScore = deduplicationScore(existing);\n      const newScore = deduplicationScore(item);\n      if (newScore <= existingScore) {\n        continue;\n      }\n      // Replace existing with better item\n      const ns = item.typeString.split(':')[0];\n      const group = byNamespace.get(ns);\n      if (group) {\n        const list = existing.kind === 'action' ? group.actions : group.events;\n        const idx = list.indexOf(existing);\n        if (idx !== -1) {\n          list[idx] = item;\n        }\n      }\n      seen.set(item.typeString, item);\n      continue;\n    }\n\n    seen.set(item.typeString, item);\n    const ns = item.typeString.split(':')[0];\n    if (!byNamespace.has(ns)) {\n      byNamespace.set(ns, { namespace: ns, actions: [], events: [] });\n    }\n    const group = byNamespace.get(ns);\n    if (group) {\n      if (item.kind === 'action') {\n        group.actions.push(item);\n      } else {\n        group.events.push(item);\n      }\n    }\n  }\n\n  // Sort namespaces alphabetically, sort items within each namespace\n  const namespaces = Array.from(byNamespace.values()).sort((a, b) =>\n    a.namespace.localeCompare(b.namespace),\n  );\n\n  for (const ns of namespaces) {\n    ns.actions.sort((a, b) => a.typeString.localeCompare(b.typeString));\n    ns.events.sort((a, b) => a.typeString.localeCompare(b.typeString));\n  }\n\n  // Resolve repository base URL for source links\n  const repoBaseUrl = await resolveRepoBaseUrl(projectPath);\n\n  // Write output\n  const docsDir = path.join(outputDir, 'docs');\n\n  // Clean existing generated docs\n  if (await directoryExists(docsDir)) {\n    await fs.rm(docsDir, { recursive: true });\n  }\n  await fs.mkdir(docsDir, { recursive: true });\n\n  // Generate namespace pages\n  for (const ns of namespaces) {\n    const nsDir = path.join(docsDir, ns.namespace);\n    await fs.mkdir(nsDir, { recursive: true });\n\n    if (ns.actions.length > 0) {\n      await fs.writeFile(\n        path.join(nsDir, 'actions.md'),\n        generateNamespacePage(ns, 'action', repoBaseUrl),\n      );\n    }\n\n    if (ns.events.length > 0) {\n      await fs.writeFile(\n        path.join(nsDir, 'events.md'),\n        generateNamespacePage(ns, 'event', repoBaseUrl),\n      );\n    }\n  }\n\n  // Generate index page\n  await fs.writeFile(\n    path.join(docsDir, 'index.md'),\n    generateIndexPage(namespaces),\n  );\n\n  // Generate sidebars\n  await fs.writeFile(\n    path.join(outputDir, 'sidebars.ts'),\n    generateSidebars(namespaces),\n  );\n\n  const totalActions = namespaces.reduce(\n    (sum, ns) => sum + ns.actions.length,\n    0,\n  );\n  const totalEvents = namespaces.reduce((sum, ns) => sum + ns.events.length, 0);\n\n  console.log(`Generated docs for ${namespaces.length} namespaces.`);\n  console.log(`  Actions: ${totalActions}`);\n  console.log(`  Events: ${totalEvents}`);\n  console.log(`Output: ${docsDir}/`);\n\n  return {\n    namespaces: namespaces.length,\n    actions: totalActions,\n    events: totalEvents,\n  };\n}\n"]}