feat(platform-api-docs): add root-messenger strategy

[cryptodev-2s]

Explanation

@metamask/platform-api-docs documents the platform API — every messenger action and event a project exposes. Until now it had one way of finding them: parse every TypeScript source and declaration file it can reach (the scan directories, packages/*/src, and node_modules/@metamask/*/dist/**/*.d.cts) and walk every type alias named *Messenger.

That is the right approach for this monorepo, which has no single messenger aggregating every capability. It is a poor fit for a client, which already declares the complete set on its root messenger. Re-deriving that from the whole dependency tree means parsing ~11,600 files in metamask-mobile and ~4,500 in metamask-extension, to rediscover something the client has written down in one place.

This PR adds a second strategy that reads what the client already declares.

--strategy

• scan (default) — unchanged behaviour, and the only option for a project with no single aggregating messenger.
• root-messenger — resolves the two types named by --root-actions and --root-events (each written <file>#<TypeName>) and lets the TypeScript type checker enumerate them. Only the named files are opened; the checker pulls in the rest.

Flags belonging to the strategy that wasn't selected are rejected rather than ignored, via a yargs .check, so a mistaken invocation fails loudly instead of quietly producing docs built the wrong way. The <file>#<TypeName> references are parsed in a yargs .coerce, so a malformed one is reported like any other
bad argument before work begins.

Why the type checker rather than the AST

This is the non-obvious part. The two clients declare their root unions differently:

• metamask-mobile writes GlobalActions by hand as a union of type references. A syntactic walk would work.
• metamask-extension derives RootMessengerActions from a registry of messenger factories via
  MessengerActions<ReturnType<(typeof MESSENGER_FACTORIES)[…]['getMessenger']>>.
  There is no syntactic union to walk — only the type checker can say what it contains.

Going through the checker handles both shapes with one code path. Once it reports which capability types are in the union, each declaration is handed to the existing extractor in extraction.ts, so JSDoc, handler/payload signatures, source links, and deprecation flags come out identical to scan. The new module is a discovery front-end, not a second extractor.

Two details worth knowing:

• A capability declared as a type alias carries its name and JSDoc on the alias symbol; the plain symbol points at the anonymous object type. An interface has no alias symbol, being its own declaration, so both are
  consulted. Missing the interface case silently dropped 61 actions and 8 events on mobile before it was fixed.
• For a lone generic instantiation (type Actions = Foo<Bar>) the checker attributes the alias to the root union itself, which would hand the extractor the wrong declaration. That case is guarded.

Failure behaviour

Generation now fails loudly instead of producing an empty site. writeOutput deletes docs/ before writing, so a root union that resolves to nothing — a renamed type, or imports that don't resolve — would previously have replaced a
published docs directory with an empty one and exited 0. It now throws, naming both references.

Capability types that can't be documented are reported with their names rather than counted, in three buckets: declared inline (no name or JSDoc), unresolved (any/unknown, usually a failed import), and unextractable (a shape the extractor rejects). A count alone isn't actionable at this scale.

Also fixed: MDX escaping

escapeJsDocTextForMdx escaped { and } but not <, which MDX reads as the start of a JSX tag. A @returns comment such as Promise<PointsBoostDto[]> therefore failed the site build rather than rendering:

Unexpected character `[` (U+005B) in name, expected a name character…

This is pre-existing and independent of the new strategy — scan produces the byte-identical line — but it blocked --build and --serve for both clients, so it is fixed here. Affects description, @param, and @returns text; handler and payload signatures were already safe inside fenced code blocks.

---

Benchmarks

Measured on a warm checkout, doc generation only.

Project	scan	root-messenger	Speedup
metamask-extension	47.9s	4.7s	~10×
metamask-mobile	96.9s	5.7s	~17×

scan parses ~5,600 app/**/*.ts plus ~6,026 .d.cts in mobile, and ~4,472 .d.cts in the extension. root-messenger opens the entry file and lets the checker pull in only what the union references.

Strategy comparison

metamask-mobile

	scan	root-messenger
Namespaces	112	103
Actions	1184	1157
Events	181	171
Unique capabilities	1365	1328 (97.3%)

The 37 not documented are mostly controllers genuinely not on the root messenger — PasskeyController alone accounts for 17, plus RatesController (4), the sample controllers, and the decrypt/encrypt message managers. Nothing is found by root-messenger that scan misses.

metamask-extension

	scan	root-messenger
Namespaces	119	115
Actions	1209	1085
Events	183	176
Unique capabilities	1392	1261 (90.6%)

99 of the 131-capability gap is PerpsController, and the cause is worth flagging to the extension team rather than treating as a tool limitation:

export type PerpsControllerMessenger = Messenger<
  'PerpsController',
  AllowedActions,   // actions Perps may CALL
  AllowedEvents
>;

RootMessengerActions is MessengerActions<ChildMessengers> — the union of what each child messenger is allowed to call, not what each controller provides. A controller whose actions are only invoked from the UI, never from another controller's messenger, never appears. PerpsController is registered in
MESSENGER_FACTORIES yet contributes zero constituents.

root-messenger documents exactly what the named types contain. Full coverage in. the extension needs an aggregate of provided actions, which is an extension-side change.

Conversely, root-messenger finds 6 capabilities scan misses(MultichainRoutingService ×4, PPOMController ×2).

Reported-but-skipped, current run: mobile 39 unextractable; extension 2 inline + 33 unextractable.

---

Usage in clients

Once published, add the dependency and two scripts. For metamask-mobile:

{
  "scripts": {
    "docs:platform-api:build": "platform-api-docs --build --project-label Mobile --strategy root-messenger --root-actions 'app/core/Engine/types.ts#GlobalActions' --root-events 'app/core/Engine/types.ts#GlobalEvents'",
    "docs:platform-api:serve": "platform-api-docs --serve --project-label Mobile --site-base-url / --strategy root-messenger --root-actions 'app/core/Engine/types.ts#GlobalActions' --root-events 'app/core/Engine/types.ts#GlobalEvents'"
  }
}

For metamask-extension, the label and references change:

--project-label Extension
--root-actions 'app/scripts/lib/messenger.ts#RootMessengerActions'
--root-events  'app/scripts/lib/messenger.ts#RootMessengerEvents'

Notes for consumers:

• Keep the # inside quotes — unquoted, most shells treat it as a comment and silently truncate the argument.
• --root-actions / --root-events are relative to the project path, not the shell's working directory.
• Output defaults to <project-path>/.platform-api-docs; gitignore it.
• metamask-extension additionally needs its postcss-loader/jiti resolution narrowed to postcss-loader@^8.2.1/jiti. The unversioned form also stubs the postcss-loader@^7.3.4 that @docusaurus/bundler depends on, replacing jiti with an empty package and breaking the site build. Narrowing preserves the stub's original intent for the extension's own postcss-loader@8.2.1.

References

Fixes: https://consensyssoftware.atlassian.net/browse/WPC-1202

• Consumer PR (mobile): feat: wire up @metamask/platform-api-docs metamask-mobile#26526
• Consumer PR (extension, includes the jiti resolution fix): feat: wire up @metamask/platform-api-docs metamask-extension#40352

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

---

Note

Medium Risk
Large new discovery path and stricter generate failure modes could break client doc CI if root types or imports are wrong; changes are confined to the docs tool, not runtime wallet logic.

Overview
Adds a root-messenger docs generation path alongside the existing scan default. Clients can point at their root action/event unions via --root-actions and --root-events (<file>#<TypeName>); the CLI validates strategy-specific flags so mixed invocations fail loudly.

root-messenger uses the TypeScript checker to expand those unions (including computed unions like MessengerActions<…>), then reuses the shared extractor so output matches scan. Skipped inline or unextractable capabilities get named warnings; resolving to nothing or any/unknown throws instead of writing an empty docs tree.

Also escapes < in JSDoc for MDX (fixes site builds on generic return/param text) and documents the new options in the README.

^{Reviewed by Cursor Bugbot for commit 11c0860. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cryptodev-2s]

@metamaskbot publish-preview

[cryptodev-2s]

@metamaskbot publish-preview

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5fe1f30. Configure here.}