npm - @metamask-previews/platform-api-docs - Versions diffs - 0.0.0-preview-f7d67b054 → 0.0.0-preview-3c77cf4 - Mend

@metamask-previews/platform-api-docs 0.0.0-preview-f7d67b054 → 0.0.0-preview-3c77cf4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/CHANGELOG.md +1 -1
package/README.md +50 -1
package/dist/cli.cjs +54 -1
package/dist/cli.cjs.map +1 -1
package/dist/cli.mjs +54 -1
package/dist/cli.mjs.map +1 -1
package/dist/extraction.cjs +70 -44
package/dist/extraction.cjs.map +1 -1
package/dist/extraction.d.cts +57 -1
package/dist/extraction.d.cts.map +1 -1
package/dist/extraction.d.mts +57 -1
package/dist/extraction.d.mts.map +1 -1
package/dist/extraction.mjs +68 -44
package/dist/extraction.mjs.map +1 -1
package/dist/generate.cjs +72 -6
package/dist/generate.cjs.map +1 -1
package/dist/generate.d.cts +28 -3
package/dist/generate.d.cts.map +1 -1
package/dist/generate.d.mts +28 -3
package/dist/generate.d.mts.map +1 -1
package/dist/generate.mjs +72 -6
package/dist/generate.mjs.map +1 -1
package/dist/root-messenger-discovery.cjs +234 -0
package/dist/root-messenger-discovery.cjs.map +1 -0
package/dist/root-messenger-discovery.d.cts +58 -0
package/dist/root-messenger-discovery.d.cts.map +1 -0
package/dist/root-messenger-discovery.d.mts +58 -0
package/dist/root-messenger-discovery.d.mts.map +1 -0
package/dist/root-messenger-discovery.mjs +206 -0
package/dist/root-messenger-discovery.mjs.map +1 -0
package/package.json +1 -1

package/CHANGELOG.md CHANGED Viewed

@@ -9,6 +9,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
-- Initial release of the platform-api-docs package ([#8012](https://github.com/MetaMask/core/pull/8012))
+- Initial release of the platform-api-docs package ([#8012](https://github.com/MetaMask/core/pull/8012), [#9913](https://github.com/MetaMask/core/pull/9913))
 [Unreleased]: https://github.com/MetaMask/core/

package/README.md CHANGED Viewed

@@ -35,12 +35,61 @@ Options:
   --build                  Generate docs and build static site
   --serve                  Generate docs, build, and serve static site
   --dev                    Generate docs and start dev server with hot reload
-  --scan-dir <dir>         Extra source directory to scan (repeatable)
+  --strategy <name>        How to find actions and events: "scan" (default) or
+                           "root-messenger" (see below)
+  --scan-dir <dir>         Extra source directory to scan (repeatable; --strategy scan only)
+  --root-actions <ref>     Type aliasing the union of every action, as "<file>#<TypeName>"
+                           (required with --strategy root-messenger)
+  --root-events <ref>      Type aliasing the union of every event, as "<file>#<TypeName>"
+                           (required with --strategy root-messenger)
   --output <dir>           Output directory (default: <project-path>/.platform-api-docs)
   --project-label <label>  Short label identifying the project (e.g. "Core", "Extension")
   --help                   Show this help message
 ```
+## Strategies
+Which strategy to use depends on whether the project has a single messenger
+carrying every action and event.
+### `scan` (default)
+Parses every TypeScript source and declaration file it can find — the scan
+directories, `packages/*/src`, and `node_modules/@metamask/*/dist` — and reads
+every `*Messenger` type alias it encounters.
+Use this when no single messenger aggregates every capability, as in a monorepo
+of independently published packages.
+### `root-messenger`
+Resolves the two types the project declares for its root messenger — the union
+of every action and the union of every event — and lets the TypeScript type
+checker enumerate them. Only the files named on the command line are opened.
+Use this when the project has one root messenger carrying every action and
+event, as a client application built on these packages does. It is
+substantially faster than `scan`, because it reads what the project already
+declares instead of re-deriving it, and it documents only what is reachable
+through that messenger.
+```
+platform-api-docs \
+  --strategy root-messenger \
+  --root-actions 'src/messenger.ts#RootActions' \
+  --root-events 'src/messenger.ts#RootEvents'
+```
+Each reference names a type alias, written by hand or computed — the type
+checker resolves either.
+The docs contain exactly what the named types contain, so those types should be
+the ones carrying every capability rather than a narrowed subset. Capability
+types that can't be documented are reported rather than dropped silently: those
+declared inline in the union (with no name or JSDoc to document), and those
+whose shape can't be read (most often a `type` property that isn't a namespaced
+string literal).
 ## Contributing
 This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

package/dist/cli.cjs CHANGED Viewed

@@ -33,6 +33,7 @@ const path = __importStar(require("node:path"));
 const npm_which_1 = __importDefault(require("npm-which"));
 const yargs_1 = __importDefault(require("yargs"));
 const generate_js_1 = require("./generate.cjs");
+const root_messenger_discovery_js_1 = require("./root-messenger-discovery.cjs");
 /**
  * Locate the Docusaurus binary in this package's `node_modules/.bin`. Using
  * `npm-which` lets the lookup track wherever the installed Docusaurus puts
@@ -128,6 +129,35 @@ async function resolveCommitSha(projectPath) {
         return null;
     }
 }
+/**
+ * Reject flag combinations that don't make sense, so a mistaken invocation
+ * fails instead of silently producing docs built the wrong way.
+ *
+ * Flags belonging to the strategy that wasn't selected are errors rather than
+ * ignored. Used as a yargs `.check`, so failures print alongside usage.
+ *
+ * @param argv - The parsed arguments.
+ * @returns True when the combination is valid.
+ */
+function checkStrategyArgs(argv) {
+    const rootActions = argv['root-actions'];
+    const rootEvents = argv['root-events'];
+    if (argv.strategy !== 'root-messenger') {
+        if (rootActions !== undefined || rootEvents !== undefined) {
+            throw new Error('--root-actions and --root-events only apply to --strategy root-messenger.');
+        }
+        return true;
+    }
+    if (rootActions === undefined || rootEvents === undefined) {
+        throw new Error('--strategy root-messenger requires both --root-actions and --root-events, ' +
+            'each written as "<file>#<TypeName>".');
+    }
+    if ((argv['scan-dir'] ?? []).length > 0) {
+        throw new Error('--scan-dir only applies to --strategy scan; --strategy root-messenger reads ' +
+            'only the files named by --root-actions and --root-events.');
+    }
+    return true;
+}
 /**
  * Main CLI entry point.
  */
@@ -154,6 +184,20 @@ async function main() {
         type: 'boolean',
         description: 'Generate platform API docs and serve a development-only site',
         default: false,
+    })
+        .option('strategy', {
+        type: 'string',
+        choices: ['scan', 'root-messenger'],
+        description: 'How to find messenger actions and events. "scan" parses every source and declaration file looking for messenger types. "root-messenger" instead resolves the two types the project declares for its root messenger',
+        default: 'scan',
+    })
+        .option('root-actions', {
+        type: 'string',
+        description: 'Type aliasing the union of every action on the root messenger, written as "<file>#<TypeName>" (required with --strategy root-messenger)',
+    })
+        .option('root-events', {
+        type: 'string',
+        description: 'Type aliasing the union of every event on the root messenger, written as "<file>#<TypeName>" (required with --strategy root-messenger)',
     })
         .option('scan-dir', {
         type: 'string',
@@ -177,6 +221,9 @@ async function main() {
         type: 'string',
         description: 'Path prefix the built site will be served under, e.g. /core/platform-api/',
     })
+        .coerce('root-actions', root_messenger_discovery_js_1.parseRootTypeReference)
+        .coerce('root-events', root_messenger_discovery_js_1.parseRootTypeReference)
+        .check(checkStrategyArgs)
         .help().argv;
     const projectPathArg = argv['project-path'];
     const resolvedProjectPath = path.resolve(typeof projectPathArg === 'string' ? projectPathArg : '.');
@@ -192,9 +239,15 @@ async function main() {
     await (0, generate_js_1.generate)({
         projectPath: resolvedProjectPath,
         outputDir: resolvedOutputDir,
-        scanDirs,
         projectLabel,
         commitSha,
+        ...(argv.strategy === 'root-messenger'
+            ? {
+                strategy: 'root-messenger',
+                rootActions: argv['root-actions'],
+                rootEvents: argv['root-events'],
+            }
+            : { strategy: 'scan', scanDirs }),
     });
     // Step 2: If --build, --serve, or --dev, set up and run Docusaurus
     if (argv.build || argv.serve || argv.dev) {

package/dist/cli.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"cli.cjs","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n\nimport execa from 'execa';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport npmWhich from 'npm-which';\nimport yargs from 'yargs';\n\nimport { generate, resolveRepoUrl } from './generate.js';\n\n/*\n Locate the Docusaurus binary in this package's `node_modules/.bin`. Using\n * `npm-which` lets the lookup track wherever the installed Docusaurus puts\n * its binary, so a future Docusaurus upgrade can't break this path.\n \n @returns Absolute path to the `docusaurus` executable.\n /\nfunction resolveDocusaurus(): string {\n return npmWhich(__dirname).sync('docusaurus');\n}\n\n/\n Run a Docusaurus command.\n \n @param command - The docusaurus command (start, build, serve).\n * @param cwd - The site directory.\n * @param extraEnv - Extra environment variables passed through to the\n * Docusaurus process (e.g. `DOCS_PROJECT_LABEL`, `DOCS_COMMIT_SHA`,\n * `DOCS_REPO_URL`).\n /\nasync function runDocusaurus(\n command: string,\n cwd: string,\n extraEnv: Record<string, string> = {},\n): Promise<void> {\n await execa(resolveDocusaurus(), [command], {\n cwd,\n stdio: 'inherit',\n env: { ...process.env, ...extraEnv },\n });\n}\n\n/\n Copy site files into the output directory, skipping `node_modules`, `docs`,\n * and `tsconfig.json`. `docs` is owned by the doc generator and shouldn't be\n * carried over from the source `site/` directory. `tsconfig.json` extends the\n * monorepo's `tsconfig.base.json` via a relative path that only resolves from\n * the source location — it's there for IDE / lint inheritance, not for\n * Docusaurus, which uses `jiti` and doesn't consult the tsconfig at runtime.\n \n @param outDir - The output directory to set up.\n /\nasync function setupSite(outDir: string): Promise<void> {\n const packageDir = path.resolve(__dirname, '..');\n const siteDir = path.join(packageDir, 'site');\n const packageNodeModules = path.join(packageDir, 'node_modules');\n const skip = new Set(['node_modules', 'docs', 'tsconfig.json']);\n\n console.log(`\\nSetting up Docusaurus site in ${outDir}...`);\n\n // `fs.cp` has been available since Node 16.7 and only got the \"stable\"\n // marker in 22.3 — it's functional throughout our supported Node range\n // (`^18.18 \|\| >=20`), even though the linter flags the older versions.\n // eslint-disable-next-line n/no-unsupported-features/node-builtins\n await fs.cp(siteDir, outDir, {\n recursive: true,\n filter: (source) => !skip.has(path.basename(source)),\n });\n\n // Symlink this package's `node_modules` into the output so the copied\n // `docusaurus.config.ts` and the rest of Docusaurus's bundling pipeline can\n // resolve their deps the same way they do in the source tree. Without it,\n // Node's resolver walks up from the output and can't reach our nested deps\n // when the package is installed as a regular dependency by an external\n // consumer (e.g. `metamask-extension`, `metamask-mobile`).\n const linkPath = path.join(outDir, 'node_modules');\n try {\n // `'junction'` works cross-platform (POSIX ignores it; Windows uses it\n // without admin) — `'dir'` would require admin on Windows.\n await fs.symlink(packageNodeModules, linkPath, 'junction');\n } catch (error) {\n if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {\n throw error;\n }\n }\n\n // Write a minimal package.json so Docusaurus doesn't warn about a missing one\n const pkgJsonPath = path.join(outDir, 'package.json');\n try {\n await fs.access(pkgJsonPath);\n } catch {\n await fs.writeFile(\n pkgJsonPath,\n JSON.stringify(\n { name: 'platform-api-docs-site', private: true },\n null,\n 2,\n ),\n );\n }\n}\n\n/\n Resolve the short Git commit SHA the docs are being generated from.\n * Returns null when the project isn't a git repo or git isn't available.\n \n @param projectPath - The project root path.\n * @returns The short SHA, or null on failure.\n /\nasync function resolveCommitSha(projectPath: string): Promise<string \| null> {\n try {\n const { stdout } = await execa('git', ['rev-parse', '--short', 'HEAD'], {\n cwd: projectPath,\n });\n const trimmed = stdout.trim();\n return trimmed.length > 0 ? trimmed : null;\n } catch {\n return null;\n }\n}\n\n/\n Main CLI entry point.\n */\nasync function main(): Promise<void> {\n const argv = await yargs(process.argv.slice(2))\n .command(\n '$0 [project-path]',\n 'Produces documentation for the platform API, the set of actions and events available in clients through the message bus.',\n (yargsInstance) => {\n yargsInstance.positional('project-path', {\n type: 'string',\n description: 'Path to the project to scan',\n default: '.',\n });\n },\n )\n .option('build', {\n type: 'boolean',\n description:\n 'Generate platform API docs and build a production-ready site',\n default: false,\n })\n .option('serve', {\n type: 'boolean',\n description:\n 'Generate platform API docs and serve a production-ready site',\n default: false,\n })\n .option('dev', {\n type: 'boolean',\n description:\n 'Generate platform API docs and serve a development-only site',\n default: false,\n })\n .option('scan-dir', {\n type: 'string',\n array: true,\n description:\n 'Additional directories within the project to scan for messenger actions and events (note: may be specified multiple times)',\n default: [] as string[],\n })\n .option('output', {\n type: 'string',\n description: 'Output directory',\n })\n .option('project-label', {\n type: 'string',\n description:\n 'Short label identifying the project (e.g. \"Core\", \"Extension\") — stamped on the site title and headings',\n })\n .option('site-url', {\n type: 'string',\n description:\n 'Absolute URL the built site will be served from, e.g. https://metamask.github.io',\n })\n .option('site-base-url', {\n type: 'string',\n description:\n 'Path prefix the built site will be served under, e.g. /core/platform-api/',\n })\n .help().argv;\n\n const projectPathArg = argv['project-path'];\n const resolvedProjectPath = path.resolve(\n typeof projectPathArg === 'string' ? projectPathArg : '.',\n );\n const resolvedOutputDir = path.resolve(\n argv.output ?? path.join(resolvedProjectPath, '.platform-api-docs'),\n );\n const scanDirs = ['src', ...argv['scan-dir']].filter(\n (dir, index, dirs) => dirs.indexOf(dir) === index,\n );\n const projectLabel =\n typeof argv['project-label'] === 'string' &&\n argv['project-label'].length > 0\n ? argv['project-label']\n : null;\n const commitSha = await resolveCommitSha(resolvedProjectPath);\n const repoUrl = await resolveRepoUrl(resolvedProjectPath);\n\n // Step 1: Generate docs\n await generate({\n projectPath: resolvedProjectPath,\n outputDir: resolvedOutputDir,\n scanDirs,\n projectLabel,\n commitSha,\n });\n\n // Step 2: If --build, --serve, or --dev, set up and run Docusaurus\n if (argv.build \|\| argv.serve \|\| argv.dev) {\n await setupSite(resolvedOutputDir);\n\n // Translate CLI flags into the environment variables Docusaurus's\n // config reads. Keeping the CLI surface flag-only means consumers\n // (workflow files, package.json scripts) don't have to know how the\n // values are plumbed through to Docusaurus.\n const docusaurusEnv: Record<string, string> = {};\n if (projectLabel) {\n docusaurusEnv.DOCS_PROJECT_LABEL = projectLabel;\n }\n if (commitSha) {\n docusaurusEnv.DOCS_COMMIT_SHA = commitSha;\n }\n if (repoUrl) {\n docusaurusEnv.DOCS_REPO_URL = repoUrl;\n }\n if (typeof argv['site-url'] === 'string' && argv['site-url'].length > 0) {\n docusaurusEnv.DOCS_URL = argv['site-url'];\n }\n if (\n typeof argv['site-base-url'] === 'string' &&\n argv['site-base-url'].length > 0\n ) {\n docusaurusEnv.DOCS_BASE_URL = argv['site-base-url'];\n }\n\n if (argv.dev) {\n console.log('\\nStarting dev server...');\n await runDocusaurus('start', resolvedOutputDir, docusaurusEnv);\n } else if (argv.build \|\| argv.serve) {\n console.log('\\nBuilding static site...');\n await runDocusaurus('build', resolvedOutputDir, docusaurusEnv);\n\n if (argv.serve) {\n console.log('\\nServing static site...');\n await runDocusaurus('serve', resolvedOutputDir, docusaurusEnv);\n }\n }\n }\n}\n\nmain().catch((error) => {\n console.error(error);\n process.exitCode = 1;\n});\n"]}
1	+ {"version":3,"file":"cli.cjs","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n\nimport execa from 'execa';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport npmWhich from 'npm-which';\nimport yargs from 'yargs';\n\nimport { generate, resolveRepoUrl } from './generate.js';\nimport type { RootTypeReference } from './root-messenger-discovery.js';\nimport { parseRootTypeReference } from './root-messenger-discovery.js';\n\n/*\n Locate the Docusaurus binary in this package's `node_modules/.bin`. Using\n * `npm-which` lets the lookup track wherever the installed Docusaurus puts\n * its binary, so a future Docusaurus upgrade can't break this path.\n \n @returns Absolute path to the `docusaurus` executable.\n /\nfunction resolveDocusaurus(): string {\n return npmWhich(__dirname).sync('docusaurus');\n}\n\n/\n Run a Docusaurus command.\n \n @param command - The docusaurus command (start, build, serve).\n * @param cwd - The site directory.\n * @param extraEnv - Extra environment variables passed through to the\n * Docusaurus process (e.g. `DOCS_PROJECT_LABEL`, `DOCS_COMMIT_SHA`,\n * `DOCS_REPO_URL`).\n /\nasync function runDocusaurus(\n command: string,\n cwd: string,\n extraEnv: Record<string, string> = {},\n): Promise<void> {\n await execa(resolveDocusaurus(), [command], {\n cwd,\n stdio: 'inherit',\n env: { ...process.env, ...extraEnv },\n });\n}\n\n/\n Copy site files into the output directory, skipping `node_modules`, `docs`,\n * and `tsconfig.json`. `docs` is owned by the doc generator and shouldn't be\n * carried over from the source `site/` directory. `tsconfig.json` extends the\n * monorepo's `tsconfig.base.json` via a relative path that only resolves from\n * the source location — it's there for IDE / lint inheritance, not for\n * Docusaurus, which uses `jiti` and doesn't consult the tsconfig at runtime.\n \n @param outDir - The output directory to set up.\n /\nasync function setupSite(outDir: string): Promise<void> {\n const packageDir = path.resolve(__dirname, '..');\n const siteDir = path.join(packageDir, 'site');\n const packageNodeModules = path.join(packageDir, 'node_modules');\n const skip = new Set(['node_modules', 'docs', 'tsconfig.json']);\n\n console.log(`\\nSetting up Docusaurus site in ${outDir}...`);\n\n // `fs.cp` has been available since Node 16.7 and only got the \"stable\"\n // marker in 22.3 — it's functional throughout our supported Node range\n // (`^18.18 \|\| >=20`), even though the linter flags the older versions.\n // eslint-disable-next-line n/no-unsupported-features/node-builtins\n await fs.cp(siteDir, outDir, {\n recursive: true,\n filter: (source) => !skip.has(path.basename(source)),\n });\n\n // Symlink this package's `node_modules` into the output so the copied\n // `docusaurus.config.ts` and the rest of Docusaurus's bundling pipeline can\n // resolve their deps the same way they do in the source tree. Without it,\n // Node's resolver walks up from the output and can't reach our nested deps\n // when the package is installed as a regular dependency by an external\n // consumer (e.g. `metamask-extension`, `metamask-mobile`).\n const linkPath = path.join(outDir, 'node_modules');\n try {\n // `'junction'` works cross-platform (POSIX ignores it; Windows uses it\n // without admin) — `'dir'` would require admin on Windows.\n await fs.symlink(packageNodeModules, linkPath, 'junction');\n } catch (error) {\n if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {\n throw error;\n }\n }\n\n // Write a minimal package.json so Docusaurus doesn't warn about a missing one\n const pkgJsonPath = path.join(outDir, 'package.json');\n try {\n await fs.access(pkgJsonPath);\n } catch {\n await fs.writeFile(\n pkgJsonPath,\n JSON.stringify(\n { name: 'platform-api-docs-site', private: true },\n null,\n 2,\n ),\n );\n }\n}\n\n/\n Resolve the short Git commit SHA the docs are being generated from.\n * Returns null when the project isn't a git repo or git isn't available.\n \n @param projectPath - The project root path.\n * @returns The short SHA, or null on failure.\n /\nasync function resolveCommitSha(projectPath: string): Promise<string \| null> {\n try {\n const { stdout } = await execa('git', ['rev-parse', '--short', 'HEAD'], {\n cwd: projectPath,\n });\n const trimmed = stdout.trim();\n return trimmed.length > 0 ? trimmed : null;\n } catch {\n return null;\n }\n}\n\n/* The subset of parsed arguments {@link checkStrategyArgs} validates. /\ntype StrategyArgs = {\n strategy?: string;\n 'root-actions'?: unknown;\n 'root-events'?: unknown;\n 'scan-dir'?: string[];\n};\n\n/\n Reject flag combinations that don't make sense, so a mistaken invocation\n * fails instead of silently producing docs built the wrong way.\n \n Flags belonging to the strategy that wasn't selected are errors rather than\n * ignored. Used as a yargs `.check`, so failures print alongside usage.\n \n @param argv - The parsed arguments.\n * @returns True when the combination is valid.\n /\nfunction checkStrategyArgs(argv: StrategyArgs): boolean {\n const rootActions = argv['root-actions'];\n const rootEvents = argv['root-events'];\n\n if (argv.strategy !== 'root-messenger') {\n if (rootActions !== undefined \|\| rootEvents !== undefined) {\n throw new Error(\n '--root-actions and --root-events only apply to --strategy root-messenger.',\n );\n }\n return true;\n }\n\n if (rootActions === undefined \|\| rootEvents === undefined) {\n throw new Error(\n '--strategy root-messenger requires both --root-actions and --root-events, ' +\n 'each written as \"<file>#<TypeName>\".',\n );\n }\n if ((argv['scan-dir'] ?? []).length > 0) {\n throw new Error(\n '--scan-dir only applies to --strategy scan; --strategy root-messenger reads ' +\n 'only the files named by --root-actions and --root-events.',\n );\n }\n\n return true;\n}\n\n/\n Main CLI entry point.\n */\nasync function main(): Promise<void> {\n const argv = await yargs(process.argv.slice(2))\n .command(\n '$0 [project-path]',\n 'Produces documentation for the platform API, the set of actions and events available in clients through the message bus.',\n (yargsInstance) => {\n yargsInstance.positional('project-path', {\n type: 'string',\n description: 'Path to the project to scan',\n default: '.',\n });\n },\n )\n .option('build', {\n type: 'boolean',\n description:\n 'Generate platform API docs and build a production-ready site',\n default: false,\n })\n .option('serve', {\n type: 'boolean',\n description:\n 'Generate platform API docs and serve a production-ready site',\n default: false,\n })\n .option('dev', {\n type: 'boolean',\n description:\n 'Generate platform API docs and serve a development-only site',\n default: false,\n })\n .option('strategy', {\n type: 'string',\n choices: ['scan', 'root-messenger'],\n description:\n 'How to find messenger actions and events. \"scan\" parses every source and declaration file looking for messenger types. \"root-messenger\" instead resolves the two types the project declares for its root messenger',\n default: 'scan',\n })\n .option('root-actions', {\n type: 'string',\n description:\n 'Type aliasing the union of every action on the root messenger, written as \"<file>#<TypeName>\" (required with --strategy root-messenger)',\n })\n .option('root-events', {\n type: 'string',\n description:\n 'Type aliasing the union of every event on the root messenger, written as \"<file>#<TypeName>\" (required with --strategy root-messenger)',\n })\n .option('scan-dir', {\n type: 'string',\n array: true,\n description:\n 'Additional directories within the project to scan for messenger actions and events (note: may be specified multiple times)',\n default: [] as string[],\n })\n .option('output', {\n type: 'string',\n description: 'Output directory',\n })\n .option('project-label', {\n type: 'string',\n description:\n 'Short label identifying the project (e.g. \"Core\", \"Extension\") — stamped on the site title and headings',\n })\n .option('site-url', {\n type: 'string',\n description:\n 'Absolute URL the built site will be served from, e.g. https://metamask.github.io',\n })\n .option('site-base-url', {\n type: 'string',\n description:\n 'Path prefix the built site will be served under, e.g. /core/platform-api/',\n })\n .coerce('root-actions', parseRootTypeReference)\n .coerce('root-events', parseRootTypeReference)\n .check(checkStrategyArgs)\n .help().argv;\n\n const projectPathArg = argv['project-path'];\n const resolvedProjectPath = path.resolve(\n typeof projectPathArg === 'string' ? projectPathArg : '.',\n );\n const resolvedOutputDir = path.resolve(\n argv.output ?? path.join(resolvedProjectPath, '.platform-api-docs'),\n );\n const scanDirs = ['src', ...argv['scan-dir']].filter(\n (dir, index, dirs) => dirs.indexOf(dir) === index,\n );\n const projectLabel =\n typeof argv['project-label'] === 'string' &&\n argv['project-label'].length > 0\n ? argv['project-label']\n : null;\n const commitSha = await resolveCommitSha(resolvedProjectPath);\n const repoUrl = await resolveRepoUrl(resolvedProjectPath);\n\n // Step 1: Generate docs\n await generate({\n projectPath: resolvedProjectPath,\n outputDir: resolvedOutputDir,\n projectLabel,\n commitSha,\n ...(argv.strategy === 'root-messenger'\n ? {\n strategy: 'root-messenger' as const,\n rootActions: argv['root-actions'] as RootTypeReference,\n rootEvents: argv['root-events'] as RootTypeReference,\n }\n : { strategy: 'scan' as const, scanDirs }),\n });\n\n // Step 2: If --build, --serve, or --dev, set up and run Docusaurus\n if (argv.build \|\| argv.serve \|\| argv.dev) {\n await setupSite(resolvedOutputDir);\n\n // Translate CLI flags into the environment variables Docusaurus's\n // config reads. Keeping the CLI surface flag-only means consumers\n // (workflow files, package.json scripts) don't have to know how the\n // values are plumbed through to Docusaurus.\n const docusaurusEnv: Record<string, string> = {};\n if (projectLabel) {\n docusaurusEnv.DOCS_PROJECT_LABEL = projectLabel;\n }\n if (commitSha) {\n docusaurusEnv.DOCS_COMMIT_SHA = commitSha;\n }\n if (repoUrl) {\n docusaurusEnv.DOCS_REPO_URL = repoUrl;\n }\n if (typeof argv['site-url'] === 'string' && argv['site-url'].length > 0) {\n docusaurusEnv.DOCS_URL = argv['site-url'];\n }\n if (\n typeof argv['site-base-url'] === 'string' &&\n argv['site-base-url'].length > 0\n ) {\n docusaurusEnv.DOCS_BASE_URL = argv['site-base-url'];\n }\n\n if (argv.dev) {\n console.log('\\nStarting dev server...');\n await runDocusaurus('start', resolvedOutputDir, docusaurusEnv);\n } else if (argv.build \|\| argv.serve) {\n console.log('\\nBuilding static site...');\n await runDocusaurus('build', resolvedOutputDir, docusaurusEnv);\n\n if (argv.serve) {\n console.log('\\nServing static site...');\n await runDocusaurus('serve', resolvedOutputDir, docusaurusEnv);\n }\n }\n }\n}\n\nmain().catch((error) => {\n console.error(error);\n process.exitCode = 1;\n});\n"]}

package/dist/cli.mjs CHANGED Viewed

@@ -31,6 +31,7 @@ import $npmWhich from "npm-which";
 const npmWhich = $importDefault($npmWhich);
 import yargs from "yargs";
 import { generate, resolveRepoUrl } from "./generate.mjs";
+import { parseRootTypeReference } from "./root-messenger-discovery.mjs";
 /**
  * Locate the Docusaurus binary in this package's `node_modules/.bin`. Using
  * `npm-which` lets the lookup track wherever the installed Docusaurus puts
@@ -126,6 +127,35 @@ async function resolveCommitSha(projectPath) {
         return null;
     }
 }
+/**
+ * Reject flag combinations that don't make sense, so a mistaken invocation
+ * fails instead of silently producing docs built the wrong way.
+ *
+ * Flags belonging to the strategy that wasn't selected are errors rather than
+ * ignored. Used as a yargs `.check`, so failures print alongside usage.
+ *
+ * @param argv - The parsed arguments.
+ * @returns True when the combination is valid.
+ */
+function checkStrategyArgs(argv) {
+    const rootActions = argv['root-actions'];
+    const rootEvents = argv['root-events'];
+    if (argv.strategy !== 'root-messenger') {
+        if (rootActions !== undefined || rootEvents !== undefined) {
+            throw new Error('--root-actions and --root-events only apply to --strategy root-messenger.');
+        }
+        return true;
+    }
+    if (rootActions === undefined || rootEvents === undefined) {
+        throw new Error('--strategy root-messenger requires both --root-actions and --root-events, ' +
+            'each written as "<file>#<TypeName>".');
+    }
+    if ((argv['scan-dir'] ?? []).length > 0) {
+        throw new Error('--scan-dir only applies to --strategy scan; --strategy root-messenger reads ' +
+            'only the files named by --root-actions and --root-events.');
+    }
+    return true;
+}
 /**
  * Main CLI entry point.
  */
@@ -152,6 +182,20 @@ async function main() {
         type: 'boolean',
         description: 'Generate platform API docs and serve a development-only site',
         default: false,
+    })
+        .option('strategy', {
+        type: 'string',
+        choices: ['scan', 'root-messenger'],
+        description: 'How to find messenger actions and events. "scan" parses every source and declaration file looking for messenger types. "root-messenger" instead resolves the two types the project declares for its root messenger',
+        default: 'scan',
+    })
+        .option('root-actions', {
+        type: 'string',
+        description: 'Type aliasing the union of every action on the root messenger, written as "<file>#<TypeName>" (required with --strategy root-messenger)',
+    })
+        .option('root-events', {
+        type: 'string',
+        description: 'Type aliasing the union of every event on the root messenger, written as "<file>#<TypeName>" (required with --strategy root-messenger)',
     })
         .option('scan-dir', {
         type: 'string',
@@ -175,6 +219,9 @@ async function main() {
         type: 'string',
         description: 'Path prefix the built site will be served under, e.g. /core/platform-api/',
     })
+        .coerce('root-actions', parseRootTypeReference)
+        .coerce('root-events', parseRootTypeReference)
+        .check(checkStrategyArgs)
         .help().argv;
     const projectPathArg = argv['project-path'];
     const resolvedProjectPath = path.resolve(typeof projectPathArg === 'string' ? projectPathArg : '.');
@@ -190,9 +237,15 @@ async function main() {
     await generate({
         projectPath: resolvedProjectPath,
         outputDir: resolvedOutputDir,
-        scanDirs,
         projectLabel,
         commitSha,
+        ...(argv.strategy === 'root-messenger'
+            ? {
+                strategy: 'root-messenger',
+                rootActions: argv['root-actions'],
+                rootEvents: argv['root-events'],
+            }
+            : { strategy: 'scan', scanDirs }),
     });
     // Step 2: If --build, --serve, or --dev, set up and run Docusaurus
     if (argv.build || argv.serve || argv.dev) {

package/dist/cli.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"cli.mjs","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAEA,OAAO,MAAK,uBAAc;;AAC1B,OAAO,KAAK,EAAE,yBAAyB;AACvC,OAAO,KAAK,IAAI,kBAAkB;AAClC,OAAO,SAAQ,kBAAkB;;AACjC,OAAO,KAAK,cAAc;AAE1B,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,uBAAsB;AAEzD;;;;;;GAMG;AACH,SAAS,iBAAiB;IACxB,OAAO,QAAQ,6BAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,aAAa,CAC1B,OAAe,EACf,GAAW,EACX,WAAmC,EAAE;IAErC,MAAM,KAAK,CAAC,iBAAiB,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE;QAC1C,GAAG;QACH,KAAK,EAAE,SAAS;QAChB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE;KACrC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,SAAS,CAAC,MAAc;IACrC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,8BAAY,IAAI,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC9C,MAAM,kBAAkB,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;IAEhE,OAAO,CAAC,GAAG,CAAC,mCAAmC,MAAM,KAAK,CAAC,CAAC;IAE5D,uEAAuE;IACvE,uEAAuE;IACvE,uEAAuE;IACvE,mEAAmE;IACnE,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE;QAC3B,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;KACrD,CAAC,CAAC;IAEH,sEAAsE;IACtE,4EAA4E;IAC5E,0EAA0E;IAC1E,2EAA2E;IAC3E,uEAAuE;IACvE,2DAA2D;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnD,IAAI,CAAC;QACH,uEAAuE;QACvE,2DAA2D;QAC3D,MAAM,EAAE,CAAC,OAAO,CAAC,kBAAkB,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,EAAE,CAAC,SAAS,CAChB,WAAW,EACX,IAAI,CAAC,SAAS,CACZ,EAAE,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,IAAI,EAAE,EACjD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,gBAAgB,CAAC,WAAmB;IACjD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE;YACtE,GAAG,EAAE,WAAW;SACjB,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAC5C,OAAO,CACN,mBAAmB,EACnB,0HAA0H,EAC1H,CAAC,aAAa,EAAE,EAAE;QAChB,aAAa,CAAC,UAAU,CAAC,cAAc,EAAE;YACvC,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,6BAA6B;YAC1C,OAAO,EAAE,GAAG;SACb,CAAC,CAAC;IACL,CAAC,CACF;SACA,MAAM,CAAC,OAAO,EAAE;QACf,IAAI,EAAE,SAAS;QACf,WAAW,EACT,8DAA8D;QAChE,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,OAAO,EAAE;QACf,IAAI,EAAE,SAAS;QACf,WAAW,EACT,8DAA8D;QAChE,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,KAAK,EAAE;QACb,IAAI,EAAE,SAAS;QACf,WAAW,EACT,8DAA8D;QAChE,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,UAAU,EAAE;QAClB,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,IAAI;QACX,WAAW,EACT,4HAA4H;QAC9H,OAAO,EAAE,EAAc;KACxB,CAAC;SACD,MAAM,CAAC,QAAQ,EAAE;QAChB,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,kBAAkB;KAChC,CAAC;SACD,MAAM,CAAC,eAAe,EAAE;QACvB,IAAI,EAAE,QAAQ;QACd,WAAW,EACT,yGAAyG;KAC5G,CAAC;SACD,MAAM,CAAC,UAAU,EAAE;QAClB,IAAI,EAAE,QAAQ;QACd,WAAW,EACT,kFAAkF;KACrF,CAAC;SACD,MAAM,CAAC,eAAe,EAAE;QACvB,IAAI,EAAE,QAAQ;QACd,WAAW,EACT,2EAA2E;KAC9E,CAAC;SACD,IAAI,EAAE,CAAC,IAAI,CAAC;IAEf,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC;IAC5C,MAAM,mBAAmB,GAAG,IAAI,CAAC,OAAO,CACtC,OAAO,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAC1D,CAAC;IACF,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,CACpC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,oBAAoB,CAAC,CACpE,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAClD,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,CAClD,CAAC;IACF,MAAM,YAAY,GAChB,OAAO,IAAI,CAAC,eAAe,CAAC,KAAK,QAAQ;QACzC,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,GAAG,CAAC;QAC9B,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC;QACvB,CAAC,CAAC,IAAI,CAAC;IACX,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,mBAAmB,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,mBAAmB,CAAC,CAAC;IAE1D,wBAAwB;IACxB,MAAM,QAAQ,CAAC;QACb,WAAW,EAAE,mBAAmB;QAChC,SAAS,EAAE,iBAAiB;QAC5B,QAAQ;QACR,YAAY;QACZ,SAAS;KACV,CAAC,CAAC;IAEH,mEAAmE;IACnE,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACzC,MAAM,SAAS,CAAC,iBAAiB,CAAC,CAAC;QAEnC,kEAAkE;QAClE,kEAAkE;QAClE,oEAAoE;QACpE,4CAA4C;QAC5C,MAAM,aAAa,GAA2B,EAAE,CAAC;QACjD,IAAI,YAAY,EAAE,CAAC;YACjB,aAAa,CAAC,kBAAkB,GAAG,YAAY,CAAC;QAClD,CAAC;QACD,IAAI,SAAS,EAAE,CAAC;YACd,aAAa,CAAC,eAAe,GAAG,SAAS,CAAC;QAC5C,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACZ,aAAa,CAAC,aAAa,GAAG,OAAO,CAAC;QACxC,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxE,aAAa,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,CAAC;QACD,IACE,OAAO,IAAI,CAAC,eAAe,CAAC,KAAK,QAAQ;YACzC,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,GAAG,CAAC,EAChC,CAAC;YACD,aAAa,CAAC,aAAa,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;YACxC,MAAM,aAAa,CAAC,OAAO,EAAE,iBAAiB,EAAE,aAAa,CAAC,CAAC;QACjE,CAAC;aAAM,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;YACzC,MAAM,aAAa,CAAC,OAAO,EAAE,iBAAiB,EAAE,aAAa,CAAC,CAAC;YAE/D,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;gBACxC,MAAM,aAAa,CAAC,OAAO,EAAE,iBAAiB,EAAE,aAAa,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACrB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\n\nimport execa from 'execa';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport npmWhich from 'npm-which';\nimport yargs from 'yargs';\n\nimport { generate, resolveRepoUrl } from './generate.js';\n\n/*\n Locate the Docusaurus binary in this package's `node_modules/.bin`. Using\n * `npm-which` lets the lookup track wherever the installed Docusaurus puts\n * its binary, so a future Docusaurus upgrade can't break this path.\n \n @returns Absolute path to the `docusaurus` executable.\n /\nfunction resolveDocusaurus(): string {\n return npmWhich(__dirname).sync('docusaurus');\n}\n\n/\n Run a Docusaurus command.\n \n @param command - The docusaurus command (start, build, serve).\n * @param cwd - The site directory.\n * @param extraEnv - Extra environment variables passed through to the\n * Docusaurus process (e.g. `DOCS_PROJECT_LABEL`, `DOCS_COMMIT_SHA`,\n * `DOCS_REPO_URL`).\n /\nasync function runDocusaurus(\n command: string,\n cwd: string,\n extraEnv: Record<string, string> = {},\n): Promise<void> {\n await execa(resolveDocusaurus(), [command], {\n cwd,\n stdio: 'inherit',\n env: { ...process.env, ...extraEnv },\n });\n}\n\n/\n Copy site files into the output directory, skipping `node_modules`, `docs`,\n * and `tsconfig.json`. `docs` is owned by the doc generator and shouldn't be\n * carried over from the source `site/` directory. `tsconfig.json` extends the\n * monorepo's `tsconfig.base.json` via a relative path that only resolves from\n * the source location — it's there for IDE / lint inheritance, not for\n * Docusaurus, which uses `jiti` and doesn't consult the tsconfig at runtime.\n \n @param outDir - The output directory to set up.\n /\nasync function setupSite(outDir: string): Promise<void> {\n const packageDir = path.resolve(__dirname, '..');\n const siteDir = path.join(packageDir, 'site');\n const packageNodeModules = path.join(packageDir, 'node_modules');\n const skip = new Set(['node_modules', 'docs', 'tsconfig.json']);\n\n console.log(`\\nSetting up Docusaurus site in ${outDir}...`);\n\n // `fs.cp` has been available since Node 16.7 and only got the \"stable\"\n // marker in 22.3 — it's functional throughout our supported Node range\n // (`^18.18 \|\| >=20`), even though the linter flags the older versions.\n // eslint-disable-next-line n/no-unsupported-features/node-builtins\n await fs.cp(siteDir, outDir, {\n recursive: true,\n filter: (source) => !skip.has(path.basename(source)),\n });\n\n // Symlink this package's `node_modules` into the output so the copied\n // `docusaurus.config.ts` and the rest of Docusaurus's bundling pipeline can\n // resolve their deps the same way they do in the source tree. Without it,\n // Node's resolver walks up from the output and can't reach our nested deps\n // when the package is installed as a regular dependency by an external\n // consumer (e.g. `metamask-extension`, `metamask-mobile`).\n const linkPath = path.join(outDir, 'node_modules');\n try {\n // `'junction'` works cross-platform (POSIX ignores it; Windows uses it\n // without admin) — `'dir'` would require admin on Windows.\n await fs.symlink(packageNodeModules, linkPath, 'junction');\n } catch (error) {\n if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {\n throw error;\n }\n }\n\n // Write a minimal package.json so Docusaurus doesn't warn about a missing one\n const pkgJsonPath = path.join(outDir, 'package.json');\n try {\n await fs.access(pkgJsonPath);\n } catch {\n await fs.writeFile(\n pkgJsonPath,\n JSON.stringify(\n { name: 'platform-api-docs-site', private: true },\n null,\n 2,\n ),\n );\n }\n}\n\n/\n Resolve the short Git commit SHA the docs are being generated from.\n * Returns null when the project isn't a git repo or git isn't available.\n \n @param projectPath - The project root path.\n * @returns The short SHA, or null on failure.\n /\nasync function resolveCommitSha(projectPath: string): Promise<string \| null> {\n try {\n const { stdout } = await execa('git', ['rev-parse', '--short', 'HEAD'], {\n cwd: projectPath,\n });\n const trimmed = stdout.trim();\n return trimmed.length > 0 ? trimmed : null;\n } catch {\n return null;\n }\n}\n\n/\n Main CLI entry point.\n */\nasync function main(): Promise<void> {\n const argv = await yargs(process.argv.slice(2))\n .command(\n '$0 [project-path]',\n 'Produces documentation for the platform API, the set of actions and events available in clients through the message bus.',\n (yargsInstance) => {\n yargsInstance.positional('project-path', {\n type: 'string',\n description: 'Path to the project to scan',\n default: '.',\n });\n },\n )\n .option('build', {\n type: 'boolean',\n description:\n 'Generate platform API docs and build a production-ready site',\n default: false,\n })\n .option('serve', {\n type: 'boolean',\n description:\n 'Generate platform API docs and serve a production-ready site',\n default: false,\n })\n .option('dev', {\n type: 'boolean',\n description:\n 'Generate platform API docs and serve a development-only site',\n default: false,\n })\n .option('scan-dir', {\n type: 'string',\n array: true,\n description:\n 'Additional directories within the project to scan for messenger actions and events (note: may be specified multiple times)',\n default: [] as string[],\n })\n .option('output', {\n type: 'string',\n description: 'Output directory',\n })\n .option('project-label', {\n type: 'string',\n description:\n 'Short label identifying the project (e.g. \"Core\", \"Extension\") — stamped on the site title and headings',\n })\n .option('site-url', {\n type: 'string',\n description:\n 'Absolute URL the built site will be served from, e.g. https://metamask.github.io',\n })\n .option('site-base-url', {\n type: 'string',\n description:\n 'Path prefix the built site will be served under, e.g. /core/platform-api/',\n })\n .help().argv;\n\n const projectPathArg = argv['project-path'];\n const resolvedProjectPath = path.resolve(\n typeof projectPathArg === 'string' ? projectPathArg : '.',\n );\n const resolvedOutputDir = path.resolve(\n argv.output ?? path.join(resolvedProjectPath, '.platform-api-docs'),\n );\n const scanDirs = ['src', ...argv['scan-dir']].filter(\n (dir, index, dirs) => dirs.indexOf(dir) === index,\n );\n const projectLabel =\n typeof argv['project-label'] === 'string' &&\n argv['project-label'].length > 0\n ? argv['project-label']\n : null;\n const commitSha = await resolveCommitSha(resolvedProjectPath);\n const repoUrl = await resolveRepoUrl(resolvedProjectPath);\n\n // Step 1: Generate docs\n await generate({\n projectPath: resolvedProjectPath,\n outputDir: resolvedOutputDir,\n scanDirs,\n projectLabel,\n commitSha,\n });\n\n // Step 2: If --build, --serve, or --dev, set up and run Docusaurus\n if (argv.build \|\| argv.serve \|\| argv.dev) {\n await setupSite(resolvedOutputDir);\n\n // Translate CLI flags into the environment variables Docusaurus's\n // config reads. Keeping the CLI surface flag-only means consumers\n // (workflow files, package.json scripts) don't have to know how the\n // values are plumbed through to Docusaurus.\n const docusaurusEnv: Record<string, string> = {};\n if (projectLabel) {\n docusaurusEnv.DOCS_PROJECT_LABEL = projectLabel;\n }\n if (commitSha) {\n docusaurusEnv.DOCS_COMMIT_SHA = commitSha;\n }\n if (repoUrl) {\n docusaurusEnv.DOCS_REPO_URL = repoUrl;\n }\n if (typeof argv['site-url'] === 'string' && argv['site-url'].length > 0) {\n docusaurusEnv.DOCS_URL = argv['site-url'];\n }\n if (\n typeof argv['site-base-url'] === 'string' &&\n argv['site-base-url'].length > 0\n ) {\n docusaurusEnv.DOCS_BASE_URL = argv['site-base-url'];\n }\n\n if (argv.dev) {\n console.log('\\nStarting dev server...');\n await runDocusaurus('start', resolvedOutputDir, docusaurusEnv);\n } else if (argv.build \|\| argv.serve) {\n console.log('\\nBuilding static site...');\n await runDocusaurus('build', resolvedOutputDir, docusaurusEnv);\n\n if (argv.serve) {\n console.log('\\nServing static site...');\n await runDocusaurus('serve', resolvedOutputDir, docusaurusEnv);\n }\n }\n }\n}\n\nmain().catch((error) => {\n console.error(error);\n process.exitCode = 1;\n});\n"]}
1	+ {"version":3,"file":"cli.mjs","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n\nimport execa from 'execa';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport npmWhich from 'npm-which';\nimport yargs from 'yargs';\n\nimport { generate, resolveRepoUrl } from './generate.js';\nimport type { RootTypeReference } from './root-messenger-discovery.js';\nimport { parseRootTypeReference } from './root-messenger-discovery.js';\n\n/*\n Locate the Docusaurus binary in this package's `node_modules/.bin`. Using\n * `npm-which` lets the lookup track wherever the installed Docusaurus puts\n * its binary, so a future Docusaurus upgrade can't break this path.\n \n @returns Absolute path to the `docusaurus` executable.\n /\nfunction resolveDocusaurus(): string {\n return npmWhich(__dirname).sync('docusaurus');\n}\n\n/\n Run a Docusaurus command.\n \n @param command - The docusaurus command (start, build, serve).\n * @param cwd - The site directory.\n * @param extraEnv - Extra environment variables passed through to the\n * Docusaurus process (e.g. `DOCS_PROJECT_LABEL`, `DOCS_COMMIT_SHA`,\n * `DOCS_REPO_URL`).\n /\nasync function runDocusaurus(\n command: string,\n cwd: string,\n extraEnv: Record<string, string> = {},\n): Promise<void> {\n await execa(resolveDocusaurus(), [command], {\n cwd,\n stdio: 'inherit',\n env: { ...process.env, ...extraEnv },\n });\n}\n\n/\n Copy site files into the output directory, skipping `node_modules`, `docs`,\n * and `tsconfig.json`. `docs` is owned by the doc generator and shouldn't be\n * carried over from the source `site/` directory. `tsconfig.json` extends the\n * monorepo's `tsconfig.base.json` via a relative path that only resolves from\n * the source location — it's there for IDE / lint inheritance, not for\n * Docusaurus, which uses `jiti` and doesn't consult the tsconfig at runtime.\n \n @param outDir - The output directory to set up.\n /\nasync function setupSite(outDir: string): Promise<void> {\n const packageDir = path.resolve(__dirname, '..');\n const siteDir = path.join(packageDir, 'site');\n const packageNodeModules = path.join(packageDir, 'node_modules');\n const skip = new Set(['node_modules', 'docs', 'tsconfig.json']);\n\n console.log(`\\nSetting up Docusaurus site in ${outDir}...`);\n\n // `fs.cp` has been available since Node 16.7 and only got the \"stable\"\n // marker in 22.3 — it's functional throughout our supported Node range\n // (`^18.18 \|\| >=20`), even though the linter flags the older versions.\n // eslint-disable-next-line n/no-unsupported-features/node-builtins\n await fs.cp(siteDir, outDir, {\n recursive: true,\n filter: (source) => !skip.has(path.basename(source)),\n });\n\n // Symlink this package's `node_modules` into the output so the copied\n // `docusaurus.config.ts` and the rest of Docusaurus's bundling pipeline can\n // resolve their deps the same way they do in the source tree. Without it,\n // Node's resolver walks up from the output and can't reach our nested deps\n // when the package is installed as a regular dependency by an external\n // consumer (e.g. `metamask-extension`, `metamask-mobile`).\n const linkPath = path.join(outDir, 'node_modules');\n try {\n // `'junction'` works cross-platform (POSIX ignores it; Windows uses it\n // without admin) — `'dir'` would require admin on Windows.\n await fs.symlink(packageNodeModules, linkPath, 'junction');\n } catch (error) {\n if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {\n throw error;\n }\n }\n\n // Write a minimal package.json so Docusaurus doesn't warn about a missing one\n const pkgJsonPath = path.join(outDir, 'package.json');\n try {\n await fs.access(pkgJsonPath);\n } catch {\n await fs.writeFile(\n pkgJsonPath,\n JSON.stringify(\n { name: 'platform-api-docs-site', private: true },\n null,\n 2,\n ),\n );\n }\n}\n\n/\n Resolve the short Git commit SHA the docs are being generated from.\n * Returns null when the project isn't a git repo or git isn't available.\n \n @param projectPath - The project root path.\n * @returns The short SHA, or null on failure.\n /\nasync function resolveCommitSha(projectPath: string): Promise<string \| null> {\n try {\n const { stdout } = await execa('git', ['rev-parse', '--short', 'HEAD'], {\n cwd: projectPath,\n });\n const trimmed = stdout.trim();\n return trimmed.length > 0 ? trimmed : null;\n } catch {\n return null;\n }\n}\n\n/* The subset of parsed arguments {@link checkStrategyArgs} validates. /\ntype StrategyArgs = {\n strategy?: string;\n 'root-actions'?: unknown;\n 'root-events'?: unknown;\n 'scan-dir'?: string[];\n};\n\n/\n Reject flag combinations that don't make sense, so a mistaken invocation\n * fails instead of silently producing docs built the wrong way.\n \n Flags belonging to the strategy that wasn't selected are errors rather than\n * ignored. Used as a yargs `.check`, so failures print alongside usage.\n \n @param argv - The parsed arguments.\n * @returns True when the combination is valid.\n /\nfunction checkStrategyArgs(argv: StrategyArgs): boolean {\n const rootActions = argv['root-actions'];\n const rootEvents = argv['root-events'];\n\n if (argv.strategy !== 'root-messenger') {\n if (rootActions !== undefined \|\| rootEvents !== undefined) {\n throw new Error(\n '--root-actions and --root-events only apply to --strategy root-messenger.',\n );\n }\n return true;\n }\n\n if (rootActions === undefined \|\| rootEvents === undefined) {\n throw new Error(\n '--strategy root-messenger requires both --root-actions and --root-events, ' +\n 'each written as \"<file>#<TypeName>\".',\n );\n }\n if ((argv['scan-dir'] ?? []).length > 0) {\n throw new Error(\n '--scan-dir only applies to --strategy scan; --strategy root-messenger reads ' +\n 'only the files named by --root-actions and --root-events.',\n );\n }\n\n return true;\n}\n\n/\n Main CLI entry point.\n */\nasync function main(): Promise<void> {\n const argv = await yargs(process.argv.slice(2))\n .command(\n '$0 [project-path]',\n 'Produces documentation for the platform API, the set of actions and events available in clients through the message bus.',\n (yargsInstance) => {\n yargsInstance.positional('project-path', {\n type: 'string',\n description: 'Path to the project to scan',\n default: '.',\n });\n },\n )\n .option('build', {\n type: 'boolean',\n description:\n 'Generate platform API docs and build a production-ready site',\n default: false,\n })\n .option('serve', {\n type: 'boolean',\n description:\n 'Generate platform API docs and serve a production-ready site',\n default: false,\n })\n .option('dev', {\n type: 'boolean',\n description:\n 'Generate platform API docs and serve a development-only site',\n default: false,\n })\n .option('strategy', {\n type: 'string',\n choices: ['scan', 'root-messenger'],\n description:\n 'How to find messenger actions and events. \"scan\" parses every source and declaration file looking for messenger types. \"root-messenger\" instead resolves the two types the project declares for its root messenger',\n default: 'scan',\n })\n .option('root-actions', {\n type: 'string',\n description:\n 'Type aliasing the union of every action on the root messenger, written as \"<file>#<TypeName>\" (required with --strategy root-messenger)',\n })\n .option('root-events', {\n type: 'string',\n description:\n 'Type aliasing the union of every event on the root messenger, written as \"<file>#<TypeName>\" (required with --strategy root-messenger)',\n })\n .option('scan-dir', {\n type: 'string',\n array: true,\n description:\n 'Additional directories within the project to scan for messenger actions and events (note: may be specified multiple times)',\n default: [] as string[],\n })\n .option('output', {\n type: 'string',\n description: 'Output directory',\n })\n .option('project-label', {\n type: 'string',\n description:\n 'Short label identifying the project (e.g. \"Core\", \"Extension\") — stamped on the site title and headings',\n })\n .option('site-url', {\n type: 'string',\n description:\n 'Absolute URL the built site will be served from, e.g. https://metamask.github.io',\n })\n .option('site-base-url', {\n type: 'string',\n description:\n 'Path prefix the built site will be served under, e.g. /core/platform-api/',\n })\n .coerce('root-actions', parseRootTypeReference)\n .coerce('root-events', parseRootTypeReference)\n .check(checkStrategyArgs)\n .help().argv;\n\n const projectPathArg = argv['project-path'];\n const resolvedProjectPath = path.resolve(\n typeof projectPathArg === 'string' ? projectPathArg : '.',\n );\n const resolvedOutputDir = path.resolve(\n argv.output ?? path.join(resolvedProjectPath, '.platform-api-docs'),\n );\n const scanDirs = ['src', ...argv['scan-dir']].filter(\n (dir, index, dirs) => dirs.indexOf(dir) === index,\n );\n const projectLabel =\n typeof argv['project-label'] === 'string' &&\n argv['project-label'].length > 0\n ? argv['project-label']\n : null;\n const commitSha = await resolveCommitSha(resolvedProjectPath);\n const repoUrl = await resolveRepoUrl(resolvedProjectPath);\n\n // Step 1: Generate docs\n await generate({\n projectPath: resolvedProjectPath,\n outputDir: resolvedOutputDir,\n projectLabel,\n commitSha,\n ...(argv.strategy === 'root-messenger'\n ? {\n strategy: 'root-messenger' as const,\n rootActions: argv['root-actions'] as RootTypeReference,\n rootEvents: argv['root-events'] as RootTypeReference,\n }\n : { strategy: 'scan' as const, scanDirs }),\n });\n\n // Step 2: If --build, --serve, or --dev, set up and run Docusaurus\n if (argv.build \|\| argv.serve \|\| argv.dev) {\n await setupSite(resolvedOutputDir);\n\n // Translate CLI flags into the environment variables Docusaurus's\n // config reads. Keeping the CLI surface flag-only means consumers\n // (workflow files, package.json scripts) don't have to know how the\n // values are plumbed through to Docusaurus.\n const docusaurusEnv: Record<string, string> = {};\n if (projectLabel) {\n docusaurusEnv.DOCS_PROJECT_LABEL = projectLabel;\n }\n if (commitSha) {\n docusaurusEnv.DOCS_COMMIT_SHA = commitSha;\n }\n if (repoUrl) {\n docusaurusEnv.DOCS_REPO_URL = repoUrl;\n }\n if (typeof argv['site-url'] === 'string' && argv['site-url'].length > 0) {\n docusaurusEnv.DOCS_URL = argv['site-url'];\n }\n if (\n typeof argv['site-base-url'] === 'string' &&\n argv['site-base-url'].length > 0\n ) {\n docusaurusEnv.DOCS_BASE_URL = argv['site-base-url'];\n }\n\n if (argv.dev) {\n console.log('\\nStarting dev server...');\n await runDocusaurus('start', resolvedOutputDir, docusaurusEnv);\n } else if (argv.build \|\| argv.serve) {\n console.log('\\nBuilding static site...');\n await runDocusaurus('build', resolvedOutputDir, docusaurusEnv);\n\n if (argv.serve) {\n console.log('\\nServing static site...');\n await runDocusaurus('serve', resolvedOutputDir, docusaurusEnv);\n }\n }\n }\n}\n\nmain().catch((error) => {\n console.error(error);\n process.exitCode = 1;\n});\n"]}

package/dist/extraction.cjs CHANGED Viewed

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractFromSourceFile = exports.createExtractionProject = void 0;
+exports.extractFromSourceFile = exports.createExtractionProject = exports.extractFromMessengerCapabilityTypeDeclaration = exports.classifyMessengerCapabilityTypeDeclaration = void 0;
 const path = __importStar(require("node:path"));
 const ts_morph_1 = require("ts-morph");
 // ---------------------------------------------------------------------------
@@ -45,15 +45,11 @@ const ts_morph_1 = require("ts-morph");
  */
 function escapeJsDocTextForMdx(text) {
     const withLinksResolved = text.replace(/\{@link\s+([^}]+)\}/gu, '`$1`');
-    return withLinksResolved.replace(/`[^`]*`|(\{)|(\})/gu, (match, open, close) => {
-        if (open) {
-            return '\\{';
-        }
-        if (close) {
-            return '\\}';
-        }
-        return match;
-    });
+    // Escape the characters MDX reads as syntax rather than text: `{` and `}`
+    // open an expression, and `<` opens a JSX tag — so an unescaped return type
+    // like `Promise<Foo[]>` fails the site build. Content already inside a code
+    // span is left alone.
+    return withLinksResolved.replace(/`[^`]*`|([{}<])/gu, (match, special) => special === undefined ? match : `\\${special}`);
 }
 /**
  * Extract the comment text of a JSDoc tag — the part that comes after the tag
@@ -242,6 +238,60 @@ function buildMethodSignature(method) {
     // so we don't need to wrap again.
     return `(${signatureParams}) => ${returnType}`;
 }
+/**
+ * Tag a capability type declaration with the body shape it has, so the right
+ * extractor can read it: 'constructor' for a capability-type-constructor
+ * invocation such as `ControllerGetStateAction<...>`, 'object' otherwise.
+ *
+ * Callers must resolve unions and bare type references first, so that the
+ * declaration reaching here is a leaf.
+ *
+ * @param declaration - The type alias or interface to classify.
+ * @param kind - Whether to tag the declaration as 'action' or 'event'.
+ * @returns The tagged declaration, or null for a qualified-name reference.
+ */
+function classifyMessengerCapabilityTypeDeclaration(declaration, kind) {
+    // Interfaces always carry their members directly.
+    // EXAMPLE:
+    //   interface FooControllerSomeAction { ... }
+    if (ts_morph_1.Node.isInterfaceDeclaration(declaration)) {
+        return { bodyShape: 'object', kind, declaration };
+    }
+    const body = declaration.getTypeNode();
+    // A TypeReference body is a capability-type-constructor invocation (e.g.
+    // `ControllerGetStateAction<typeof name, State>`). Tag it so the constructor
+    // extractor can read `body` directly without re-checking its shape.
+    // EXAMPLE:
+    //   type FooControllerSomeAction = ControllerGetStateAction<...>
+    //                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    if (body && ts_morph_1.Node.isTypeReference(body)) {
+        // Reject qualified-name constructor type names, as we need a plain
+        // identifier to match the constructor by name.
+        // EXAMPLE:
+        //   import * as somePackage from '....js';
+        //   type FooControllerSomeAction = somePackage.ControllerGetStateAction<...>
+        //                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        const constructorTypeName = body.getTypeName();
+        if (!ts_morph_1.Node.isIdentifier(constructorTypeName)) {
+            return null;
+        }
+        return {
+            bodyShape: 'constructor',
+            kind,
+            declaration,
+            body,
+            typeName: constructorTypeName,
+        };
+    }
+    // Anything else (a type literal, intersection, conditional, …) goes to the
+    // literal extractor, which knows how to read members off a type literal and
+    // rejects exotic shapes.
+    // EXAMPLE:
+    //   type FooControllerSomeAction = { ... }
+    //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    return { bodyShape: 'object', kind, declaration };
+}
+exports.classifyMessengerCapabilityTypeDeclaration = classifyMessengerCapabilityTypeDeclaration;
 /**
  * Looks for Messenger types in the source file (that is, those that are type
  * aliases whose names end with "Messenger"), then extracts the `Actions` and
@@ -405,44 +455,19 @@ function recursivelyFindMessengerCapabilityTypeDeclarations(node, kind, visitedT
                 }
                 continue;
             }
-            // A TypeReference body with type arguments is a capability-type-
+            // Everything else is a leaf capability type — a capability-type-
             // constructor invocation (e.g. `ControllerGetStateAction<typeof name,
-            // State>`). Tag it so the constructor extractor can read `body`
-            // directly without re-checking its shape.
-            // EXAMPLE:
+            // State>`) or a literal object type. Tag it so the matching extractor
+            // can read it without re-checking its shape.
+            // EXAMPLES:
             //   type FooControllerSomeAction = ControllerGetStateAction<...>
-            //                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-            if (body && ts_morph_1.Node.isTypeReference(body)) {
-                // Reject qualified-name constructor type names, as we need a plain
-                // identifier to match the constructor by name.
-                // EXAMPLE:
-                //   // Bad
-                //   import * as somePackage from '....js';
-                //   type FooControllerSomeAction = somePackage.ControllerGetStateAction<...>
-                //                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-                const constructorTypeName = body.getTypeName();
-                if (ts_morph_1.Node.isIdentifier(constructorTypeName)) {
-                    result.capabilityTypeDeclarations.push({
-                        bodyShape: 'constructor',
-                        kind,
-                        declaration,
-                        body,
-                        typeName: constructorTypeName,
-                    });
-                }
-                continue;
-            }
-            // Anything else (a type literal, intersection, conditional, …) gets
-            // tagged for the literal extractor, which knows how to read members
-            // off a type literal and rejects exotic shapes.
-            // EXAMPLE:
+            //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
             //   type FooControllerSomeAction = { ... }
             //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-            result.capabilityTypeDeclarations.push({
-                bodyShape: 'object',
-                kind,
-                declaration,
-            });
+            const classified = classifyMessengerCapabilityTypeDeclaration(declaration, kind);
+            if (classified) {
+                result.capabilityTypeDeclarations.push(classified);
+            }
         }
         // Interfaces always carry their members directly — tag for the literal
         // extractor.
@@ -479,6 +504,7 @@ function extractFromMessengerCapabilityTypeDeclaration(capabilityTypeDeclaration
     }
     return tryToExtractFromMessengerCapabilityTypeLiteral(capabilityTypeDeclaration, projectPath);
 }
+exports.extractFromMessengerCapabilityTypeDeclaration = extractFromMessengerCapabilityTypeDeclaration;
 /**
  * If a messenger capability type is a type alias or interface and its body is
  * a literal object type — i.e. one of: