@metamask-previews/platform-api-docs 0.0.0-preview-6235c3779 → 0.0.0-preview-e15374a5d

package/dist/cli.cjs

@@ -59,15 +59,18 @@ async function runDocusaurus(command, cwd, extraEnv = {}) {
     });
 }
 /**
- * Copy site files into the output directory, skipping `node_modules` and
- * `docs` (the latter is owned by the doc generator and shouldn't be carried
- * over from the source `site/` directory).
+ * Copy site files into the output directory, skipping `node_modules`, `docs`,
+ * and `tsconfig.json`. `docs` is owned by the doc generator and shouldn't be
+ * carried over from the source `site/` directory. `tsconfig.json` extends the
+ * monorepo's `tsconfig.base.json` via a relative path that only resolves from
+ * the source location — it's there for IDE / lint inheritance, not for
+ * Docusaurus, which uses `jiti` and doesn't consult the tsconfig at runtime.
  *
  * @param outDir - The output directory to set up.
  */
 async function setupSite(outDir) {
     const siteDir = path.resolve(__dirname, '..', 'site');
-    const skip = new Set(['node_modules', 'docs']);
+    const skip = new Set(['node_modules', 'docs', 'tsconfig.json']);
     console.log(`\nSetting up Docusaurus site in ${outDir}...`);
     // `fs.cp` has been available since Node 16.7 and only got the "stable"
     // marker in 22.3 — it's functional throughout our supported Node range

package/dist/cli.cjs.map

@@ -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 } from './generate';\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 */\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` and\n * `docs` (the latter is owned by the doc generator and shouldn't be carried\n * over from the source `site/` directory).\n *\n * @param outDir - The output directory to set up.\n */\nasync function setupSite(outDir: string): Promise<void> {\n  const siteDir = path.resolve(__dirname, '..', 'site');\n  const skip = new Set(['node_modules', 'docs']);\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  // 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\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 (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"]}
+{"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 } from './generate';\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 */\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 siteDir = path.resolve(__dirname, '..', 'site');\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  // 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\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 (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

@@ -57,15 +57,18 @@ async function runDocusaurus(command, cwd, extraEnv = {}) {
     });
 }
 /**
- * Copy site files into the output directory, skipping `node_modules` and
- * `docs` (the latter is owned by the doc generator and shouldn't be carried
- * over from the source `site/` directory).
+ * Copy site files into the output directory, skipping `node_modules`, `docs`,
+ * and `tsconfig.json`. `docs` is owned by the doc generator and shouldn't be
+ * carried over from the source `site/` directory. `tsconfig.json` extends the
+ * monorepo's `tsconfig.base.json` via a relative path that only resolves from
+ * the source location — it's there for IDE / lint inheritance, not for
+ * Docusaurus, which uses `jiti` and doesn't consult the tsconfig at runtime.
  *
  * @param outDir - The output directory to set up.
  */
 async function setupSite(outDir) {
     const siteDir = path.resolve($__dirname(import.meta.url), '..', 'site');
-    const skip = new Set(['node_modules', 'docs']);
+    const skip = new Set(['node_modules', 'docs', 'tsconfig.json']);
     console.log(`\nSetting up Docusaurus site in ${outDir}...`);
     // `fs.cp` has been available since Node 16.7 and only got the "stable"
     // marker in 22.3 — it's functional throughout our supported Node range

package/dist/cli.mjs.map

@@ -1 +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 } from './generate';\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 */\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` and\n * `docs` (the latter is owned by the doc generator and shouldn't be carried\n * over from the source `site/` directory).\n *\n * @param outDir - The output directory to set up.\n */\nasync function setupSite(outDir: string): Promise<void> {\n  const siteDir = path.resolve(__dirname, '..', 'site');\n  const skip = new Set(['node_modules', 'docs']);\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  // 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\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 (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"]}
+{"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 } from './generate';\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 */\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 siteDir = path.resolve(__dirname, '..', 'site');\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  // 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\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 (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

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractFromFile = exports.extractFromSourceFile = exports.createExtractionProject = void 0;
+exports.extractFromSourceFile = exports.createExtractionProject = void 0;
 const path = __importStar(require("node:path"));
 const ts_morph_1 = require("ts-morph");
 // ---------------------------------------------------------------------------
@@ -146,57 +146,63 @@ function hasDeprecatedJsDocTag(node) {
 // Type-resolution helpers (powered by ts-morph's type checker)
 // ---------------------------------------------------------------------------
 /**
- * If `typeNode` is `Class['method']`, resolve `Class` to its declaration
- * (across files if needed via the type checker) and look up the method by
- * name. Returns the method declaration when found.
+ * Locates the type that represents a method on a class (e.g.
+ * `Class['method']`), which itself comes from a messenger action handler.
  *
- * @param typeNode - The handler's type node.
- * @returns The method declaration, or null.
+ * @param typeNode - The node that represents the indexed access.
+ * @returns The found method declaration, or null.
  */
-function resolveIndexedAccessMethod(typeNode) {
-    if (!typeNode || !ts_morph_1.Node.isIndexedAccessTypeNode(typeNode)) {
+function findClassMethodDeclaration(typeNode) {
+    // Fundamental check: if we don't have `Class['method']`, we can't do anything.
+    if (!ts_morph_1.Node.isIndexedAccessTypeNode(typeNode)) {
         return null;
     }
+    // The type that represents the class being accessed.
+    // EXAMPLE:
+    //   FooController['someMethod']
+    //   ^^^^^^^^^^^^^
     const objectType = typeNode.getObjectTypeNode();
+    // The type that represents the property being accessed.
+    // EXAMPLE:
+    //   FooController['someMethod']
+    //                 ^^^^^^^^^^^^
     const indexType = typeNode.getIndexTypeNode();
-    // istanbul ignore next: handler indexed-access types in messenger fixtures
-    // always reference a class via TypeReference.
-    if (!ts_morph_1.Node.isTypeReference(objectType)) {
-        return null;
-    }
-    // istanbul ignore next: the index in `Class['method']` is always a literal
-    // type node in valid handler syntax.
-    if (!ts_morph_1.Node.isLiteralTypeNode(indexType)) {
+    // To access a property on a type, it must be a type we can access properties of.
+    if (!ts_morph_1.Node.isTypeReference(objectType) ||
+        !ts_morph_1.Node.isLiteralTypeNode(indexType)) {
         return null;
     }
     const indexLiteral = indexType.getLiteral();
-    // The index can be written as `'method'`, `"method"`, or `` `method` ``.
-    // The first two land as `StringLiteral`; the bare template literal is a
-    // `NoSubstitutionTemplateLiteral`.
-    // istanbul ignore next: numeric/boolean indices aren't valid method names.
+    // Names of methods must be static strings; they cannot be template strings.
     if (!ts_morph_1.Node.isStringLiteral(indexLiteral) &&
         !ts_morph_1.Node.isNoSubstitutionTemplateLiteral(indexLiteral)) {
         return null;
     }
     const methodName = indexLiteral.getLiteralValue();
+    // Reject qualified-name type names, as we need a plain identifier to
+    // resolve the symbol.
+    // EXAMPLE:
+    //   import * as somePackage from '...';
+    //   somePackage.FooController['someMethod']
+    //   ^^^^^^^^^^^^^^^^^^^^^^^^^
     const classNameNode = objectType.getTypeName();
-    // istanbul ignore next: qualified-name class references aren't used in
-    // messenger handler types.
     if (!ts_morph_1.Node.isIdentifier(classNameNode)) {
         return null;
     }
+    // Since we know we have a type reference, we can assume that we have a symbol.
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const localSymbol = classNameNode.getSymbol();
-    // istanbul ignore next: a referenced class name always resolves to a symbol
-    // in a typechecked project.
-    if (!localSymbol) {
-        return null;
-    }
-    // Follow the import alias (if any) so we can find the class declaration in
-    // its home file.
+    // If we have a type imported from another file, ensure that when we access
+    // the declaration, it's the type declaration in the other file, not the
+    // import declaration in this file.
+    // EXAMPLE:
+    //   import { FooController } from '@metamask/foo-controller';
+    //   FooController['someMethod']
+    //   ^^^^^^^^^^^^^
     const symbol = localSymbol.getAliasedSymbol() ?? localSymbol;
-    // istanbul ignore next: a resolved symbol always exposes its declarations
-    // array in a typechecked project.
-    for (const declaration of symbol.getDeclarations() ?? []) {
+    for (const declaration of symbol.getDeclarations()) {
+        // We must have a class to treat the property on the object type as a
+        // method.
         if (ts_morph_1.Node.isClassDeclaration(declaration)) {
             const method = declaration.getMethod(methodName);
             if (method) {
@@ -204,40 +210,37 @@ function resolveIndexedAccessMethod(typeNode) {
             }
         }
     }
-    // istanbul ignore next: only reached if the indexed method isn't declared
-    // on any of the resolved class declarations, which doesn't happen in valid
-    // handler types.
     return null;
 }
 // ---------------------------------------------------------------------------
 // Method info
 // ---------------------------------------------------------------------------
 /**
- * Build a {@link MethodInfo} record for a class method — its textual
- * signature plus the JSDoc description, `@param`, and `@returns` extracted
- * from the method itself.
+ * Build the textual signature of a class method — its parameter list and
+ * return type expressed as a TypeScript function type — so a handler that
+ * references `Class['method']` can be rendered as `(arg: T) => R` instead of
+ * the bare indexed-access syntax.
  *
  * @param method - The method declaration.
- * @returns The method info.
+ * @returns The signature, e.g. `(id: number) => Promise<string>`.
  */
-function buildMethodInfo(method) {
+function buildMethodSignature(method) {
     const signatureParams = method
         .getParameters()
         .map((param) => {
+        const rest = param.isRestParameter() ? '...' : '';
         const paramName = param.getNameNode().getText();
         const optional = param.hasQuestionToken() ? '?' : '';
         const typeNode = param.getTypeNode();
         const paramType = typeNode ? typeNode.getText() : 'unknown';
-        return `${paramName}${optional}: ${paramType}`;
+        return `${rest}${paramName}${optional}: ${paramType}`;
     })
         .join(', ');
     const returnTypeNode = method.getReturnTypeNode();
     const returnType = returnTypeNode ? returnTypeNode.getText() : 'void';
     // For async methods, the declared return type already includes `Promise<>`,
     // so we don't need to wrap again.
-    const signature = `(${signatureParams}) => ${returnType}`;
-    const { description, params, returns } = extractJsDoc(method);
-    return { jsDoc: description, params, returns, signature };
+    return `(${signatureParams}) => ${returnType}`;
 }
 /**
  * Looks for Messenger types in the source file (that is, those that are type
@@ -338,13 +341,16 @@ function recursivelyFindMessengerCapabilityTypeDeclarations(node, kind, visitedT
     //                  ^^^^^^^
     //   // Good
     //   type Actions = FooControllerSomeAction;
+    //                  ^^^^^^^^^^^^^^^^^^^^^^^
     //   // Good
     //   type Actions = ControllerGetStateAction<...>;
+    //                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     if (!ts_morph_1.Node.isTypeReference(node)) {
         return result;
     }
     const nameNode = node.getTypeName();
-    // Reject qualified-name type references, as we can't follow those.
+    // Reject qualified-name type names, as we need a plain identifier to
+    // resolve the symbol.
     // EXAMPLE:
     //   import * as somePackage from '...';
     //   type Actions = somePackage.FooControllerSomeAction;
@@ -356,8 +362,8 @@ function recursivelyFindMessengerCapabilityTypeDeclarations(node, kind, visitedT
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const localSymbol = nameNode.getSymbol();
     // If we have a type imported from another file, ensure that when we access
-    // the declaration, it's the *type* declaration in the other file, not the
-    // *import* declaration in this file.
+    // the declaration, it's the type declaration in the other file, not the
+    // import declaration in this file.
     // EXAMPLE:
     //   import { FooControllerSomeAction } from '@metamask/foo-controller';
     //   type Actions = FooControllerSomeAction;
@@ -376,14 +382,22 @@ function recursivelyFindMessengerCapabilityTypeDeclarations(node, kind, visitedT
         // If we have a type alias, then we have to handle a few scenarios.
         // EXAMPLES:
         //   type FooControllerMethodActions = ...
+        //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
         //   type FooControllerSomeAction = ...
+        //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
         if (ts_morph_1.Node.isTypeAliasDeclaration(declaration)) {
             const body = declaration.getTypeNode();
-            // If we have a union type, then walk each type in the union.
-            // EXAMPLE:
+            // If the body is a union type or a plain type reference (not a utility
+            // type), walk it.
+            // EXAMPLES:
             //   type FooControllerMethodActions = FooControllerSomeAction | FooControllerSomeOtherAction
-            //                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-            if (body && ts_morph_1.Node.isUnionTypeNode(body)) {
+            //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+            //   type DelegationControllerMethodActions = DelegationControllerSignDelegationAction
+            //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+            if (body &&
+                (ts_morph_1.Node.isUnionTypeNode(body) ||
+                    (ts_morph_1.Node.isTypeReference(body) &&
+                        body.getTypeArguments().length === 0))) {
                 const innerResult = recursivelyFindMessengerCapabilityTypeDeclarations(body, kind, result.visitedTypeDeclarations);
                 result.capabilityTypeDeclarations.push(...innerResult.capabilityTypeDeclarations);
                 for (const typeDeclaration of innerResult.visitedTypeDeclarations) {
@@ -391,32 +405,56 @@ function recursivelyFindMessengerCapabilityTypeDeclarations(node, kind, visitedT
                 }
                 continue;
             }
-            // TODO: Is this necessary?
-            // A bare TypeReference body with no type arguments (e.g.
-            // `type AllowedActions = ConnectivityControllerGetStateAction`) is a
-            // plain re-export — leave the target to be documented from its home
-            // package, not this one. TypeReferences *with* type arguments are
-            // capability-type-constructor invocations (e.g.
-            // `ControllerGetStateAction<typeof name, State>`) and are recorded.
-            if (body &&
-                ts_morph_1.Node.isTypeReference(body) &&
-                body.getTypeArguments().length === 0) {
+            // A TypeReference body with type arguments 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:
+                //   // Bad
+                //   import * as somePackage from '...';
+                //   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;
             }
-            // We finally found a messenger capability type! Capture the whole thing.
-            // (We will parse the body later.)
+            // 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({ declaration, kind });
+            result.capabilityTypeDeclarations.push({
+                bodyShape: 'object',
+                kind,
+                declaration,
+            });
         }
-        // If we have an interface, we don't have any scenarios to handle, so
-        // capture it as is.
+        // Interfaces always carry their members directly — tag for the literal
+        // extractor.
         // EXAMPLE:
         //   interface FooControllerSomeAction { ... }
         //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
         else if (ts_morph_1.Node.isInterfaceDeclaration(declaration)) {
-            result.capabilityTypeDeclarations.push({ declaration, kind });
+            result.capabilityTypeDeclarations.push({
+                bodyShape: 'object',
+                kind,
+                declaration,
+            });
         }
     }
     return result;
@@ -436,8 +474,10 @@ function recursivelyFindMessengerCapabilityTypeDeclarations(node, kind, visitedT
  * (may be `null` if the type is ineligible for extraction).
  */
 function extractFromMessengerCapabilityTypeDeclaration(capabilityTypeDeclaration, projectPath) {
-    return (tryToExtractFromMessengerCapabilityTypeLiteral(capabilityTypeDeclaration, projectPath) ??
-        tryToExtractFromCapabilityTypeConstructor(capabilityTypeDeclaration, projectPath));
+    if (capabilityTypeDeclaration.bodyShape === 'constructor') {
+        return tryToExtractFromCapabilityTypeConstructor(capabilityTypeDeclaration, projectPath);
+    }
+    return tryToExtractFromMessengerCapabilityTypeLiteral(capabilityTypeDeclaration, projectPath);
 }
 /**
  * If a messenger capability type is a type alias or interface and its body is
@@ -457,7 +497,7 @@ function extractFromMessengerCapabilityTypeDeclaration(capabilityTypeDeclaration
  */
 function tryToExtractFromMessengerCapabilityTypeLiteral(capabilityTypeDeclaration, projectPath) {
     const { declaration, kind } = capabilityTypeDeclaration;
-    // Reject empty type aliases or interfaces.
+    // We must have a object type alias or an interface, and the body must not be empty.
     // EXAMPLES:
     //   // Good
     //   type FooControllerSomeAction = {
@@ -504,25 +544,14 @@ function tryToExtractFromMessengerCapabilityTypeLiteral(capabilityTypeDeclaratio
     let handlerOrPayloadSignature = handlerOrPayloadPropertyTypeNode
         .getText()
         .trim();
-    let { description: jsDoc, params, returns } = extractJsDoc(declaration);
-    // For actions, if the handler resolves to a class method (e.g.
-    // `FooController['method']`), inherit its signature plus any JSDoc fields the
-    // type alias itself doesn't already provide.
-    // TODO: We don't want to do this.
+    const { description: jsDoc, params, returns } = extractJsDoc(declaration);
+    // For actions that represent methods (e.g. `Class['method']`), walk the
+    // handler type to find the underlying handler signature
+    // (e.g. `(id: number) => Promise<string>`).
     if (kind === 'action') {
-        const resolvedMethod = resolveIndexedAccessMethod(handlerOrPayloadPropertyTypeNode);
-        if (resolvedMethod) {
-            const info = buildMethodInfo(resolvedMethod);
-            handlerOrPayloadSignature = info.signature;
-            if (!jsDoc && info.jsDoc) {
-                jsDoc = info.jsDoc;
-            }
-            if (params.length === 0 && info.params.length > 0) {
-                params = info.params;
-            }
-            if (!returns && info.returns) {
-                returns = info.returns;
-            }
+        const methodDeclaration = findClassMethodDeclaration(handlerOrPayloadPropertyTypeNode);
+        if (methodDeclaration) {
+            handlerOrPayloadSignature = buildMethodSignature(methodDeclaration);
         }
     }
     const sourceFile = declaration.getSourceFile();
@@ -571,7 +600,7 @@ function getMessengerCapabilityTypeString(capabilityTypeProperties) {
     //   }
     //   type FooControllerSomeAction = {
     //     type: `${typeof CONTROLLER_NAME}:someAction`;
-    //           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    //           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     //   }
     const resolvedType = typeNode.getType();
     if (resolvedType.isStringLiteral()) {
@@ -618,37 +647,7 @@ function findProperty(propertySignatures, name) {
  * doesn't match.
  */
 function tryToExtractFromCapabilityTypeConstructor(capabilityTypeDeclaration, projectPath) {
-    const { declaration, kind } = capabilityTypeDeclaration;
-    // Basic check: we need a type alias, otherwise the rest doesn't make sense.
-    // EXAMPLE:
-    //   type FooControllerSomeAction = ...
-    if (!ts_morph_1.Node.isTypeAliasDeclaration(declaration)) {
-        return null;
-    }
-    // We want our type alias to be a reference to a utility type.
-    // Non-null assertion: We can assume the type has a body of some kind,
-    // otherwise it wouldn't compile.
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const body = declaration.getTypeNode();
-    // We already determined in
-    // `recursivelyFindMessengerCapabilityTypeDeclarations` that the declaration
-    // is a type reference.
-    // TODO: Capture the following information ahead of time so we don't need to
-    // check this again.
-    // istanbul ignore next
-    if (!ts_morph_1.Node.isTypeReference(body)) {
-        return null;
-    }
-    const typeName = body.getTypeName();
-    // We already determined in
-    // `recursivelyFindMessengerCapabilityTypeDeclarations` that the type is an
-    // identifier.
-    // TODO: Capture the following information ahead of time so we don't need to
-    // check this again.
-    // istanbul ignore next
-    if (!ts_morph_1.Node.isIdentifier(typeName)) {
-        return null;
-    }
+    const { declaration, kind, body, typeName } = capabilityTypeDeclaration;
     // The name of the utility type should be either `ControllerGetStateAction`
     // (for actions) or `ControllerStateChangeEvent` (for events).
     // EXAMPLES:
@@ -752,34 +751,4 @@ function extractFromSourceFile(sourceFile, projectPath) {
     return messengerCapabilityPackets;
 }
 exports.extractFromSourceFile = extractFromSourceFile;
-/**
- * Convenience wrapper: extract from a single file by path. Loads the file
- * and any sibling files in its parent directory into a fresh Project so
- * relative imports resolve.
- *
- * For batch operations across many files, prefer
- * {@link createExtractionProject} + {@link extractFromSourceFile} so one
- * Project amortizes the type-checker setup across the whole run.
- *
- * @param filePath - The absolute path to the TypeScript file.
- * @param projectPath - Base path for computing relative source paths.
- * @returns A promise that resolves to the extracted capability list.
- */
-async function extractFromFile(filePath, projectPath) {
-    const project = createExtractionProject();
-    const parentDir = path.dirname(filePath);
-    // Load the file's directory so single-hop relative imports resolve.
-    project.addSourceFilesAtPaths([
-        path.join(parentDir, '**/*.ts'),
-        path.join(parentDir, '**/*.d.cts'),
-    ]);
-    const sourceFile = project.getSourceFile(filePath);
-    // istanbul ignore next: the path always exists since the caller just
-    // wrote the file or it was scanned from disk.
-    if (!sourceFile) {
-        return [];
-    }
-    return extractFromSourceFile(sourceFile, projectPath);
-}
-exports.extractFromFile = extractFromFile;
 //# sourceMappingURL=extraction.cjs.map