@metamask-previews/platform-api-docs 0.1.0-preview-abca9bcea → 0.2.0-preview-0a30e47

package/dist/root-messenger-discovery.cjs

@@ -1,359 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.discoverFromRootMessengerCapabilitiesTypes = exports.parseRootCapabilitiesTypeReference = void 0;
-const path = __importStar(require("node:path"));
-const ts_morph_1 = require("ts-morph");
-const extraction_js_1 = require("./extraction.cjs");
-const ts_project_js_1 = require("./ts-project.cjs");
-/**
- * Split a `<file>#<TypeName>` reference into its parts, on the last `#` so
- * that paths containing a `#` still work.
- *
- * @param reference - The raw reference, e.g. `src/messenger.ts#RootActions`.
- * @returns The parsed reference.
- * @throws If the reference has no `#`, or either side of it is empty.
- */
-function parseRootCapabilitiesTypeReference(reference) {
-    const separatorIndex = reference.lastIndexOf('#');
-    if (separatorIndex === -1) {
-        throw new Error(`Expected a reference of the form "<file>#<TypeName>", got "${reference}".`);
-    }
-    const filePath = reference.slice(0, separatorIndex);
-    const typeName = reference.slice(separatorIndex + 1);
-    if (filePath.length === 0 || typeName.length === 0) {
-        throw new Error(`Expected a reference of the form "<file>#<TypeName>", got "${reference}".`);
-    }
-    return { filePath, typeName };
-}
-exports.parseRootCapabilitiesTypeReference = parseRootCapabilitiesTypeReference;
-/**
- * A `<file>#<TypeName>` string, passed from the command line, refers to an
- * messenger actions or events collection type. This function reads the file and
- * looks up the matching type alias.
- *
- * @param args - The arguments to this function.
- * @param args.project - The ts-morph project to load the file into.
- * @param args.projectPath - Absolute path to the project root.
- * @param args.reference - The root capability collection type reference to
- * resolve.
- * @param args.commandLineOptionName - The command-line option the reference
- * came from, used in errors.
- * @returns The type alias declaration the reference names.
- * @throws If the file can't be read or declares no such type alias.
- */
-function resolveMessengerCapabilitiesTypeReference({ project, projectPath, reference, commandLineOptionName, }) {
-    const absolutePath = path.resolve(projectPath, reference.filePath);
-    let sourceFile;
-    try {
-        // `addSourceFileAtPath` is idempotent: the two references often name the
-        // same file, and the second call returns the source file added by the first.
-        sourceFile = project.addSourceFileAtPath(absolutePath);
-    }
-    catch {
-        throw new Error(`Could not read ${absolutePath}, which was named by ${commandLineOptionName}.`);
-    }
-    // EXAMPLES:
-    //   type RootMessengerActions = ...
-    //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    //   type RootMessengerEvents = ...
-    //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    const declaration = sourceFile.getTypeAlias(reference.typeName);
-    if (!declaration) {
-        throw new Error(`No type alias named "${reference.typeName}" in ${reference.filePath}, which was named by ${commandLineOptionName}.`);
-    }
-    return declaration;
-}
-/**
- * Given the type of a messenger capability (e.g.
- * `NetworkControllerAddNetworkAction`) as obtained from a collection of
- * capability types (e.g. `RootMessengerActions` or `RootMessengerEvents`),
- * locate the type declaration for that capability type.
- *
- * This is not as simple as following the type to its declaration, because both
- * a collection of capability types and the capability type itself can have
- * multiple representations. So there are three strategies for finding the type:
- *
- * 1. If the capability type was declared as a type alias (e.g. `type
- *    FooControllerSomeAction = { ... }`), then we need to use the symbol to
- *    find the declaration.
- * 2. If the capability type was declared as an interface (e.g. `interface
- *    FooControllerSomeAction { ... }`), we don't need to do this; interfaces
- *    are their own declaration.
- * 3. If the capability *collection* type is not a union but merely a type alias
- *    (e.g. `type RootMessengerActions = NetworkControllerAddNetworkAction`)
- *    then we follow the right-hand side of the type alias.
- *
- * When none of these find a type declaration, the capability is anonymous
- * (e.g. an inline object type with no name to document) and `undefined` is
- * returned, so the caller can record it as skipped rather than document it.
- *
- * @param capabilityType - The type of the individual capability to find the
- * declaration for.
- * @param capabilityCollectionTypeDeclaration - The declaration of the whole
- * collection the capability came from (e.g. `type RootMessengerActions = ...`).
- * @param isLoneConstituent - Whether the capability collection only includes
- * one capability type.
- * @returns The type alias or interface declaration for the capability, or
- * `undefined` when the capability is anonymous.
- */
-function findMessengerCapabilityTypeDeclaration(capabilityType, capabilityCollectionTypeDeclaration, isLoneConstituent) {
-    // If we have a type alias, look for its symbol.
-    //
-    // EXAMPLE:
-    //   type FooControllerSomeAction = { type: '...'; handler: () => void };
-    //        ^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    //        the alias symbol names    the plain symbol points at this anonymous
-    //        this declaration          object
-    //
-    // But skip an alias that resolves back to the capability collection itself,
-    // which is what TypeScript reports for a lone generic instantiation.
-    //
-    // EXAMPLE:
-    //   Here the alias symbol of the sole member is `Actions`, i.e.
-    //   `capabilityCollectionTypeDeclaration`, which is not the capability we
-    //   want to document:
-    //
-    //   type Actions = Foo<Bar>;
-    //        ^^^^^^^ capabilityCollectionTypeDeclaration
-    const typeAliasDeclarations = (capabilityType.getAliasSymbol()?.getDeclarations() ?? []).filter((node) => node !== capabilityCollectionTypeDeclaration);
-    // An interface has no alias symbol, being its own declaration, so fall back
-    // to the plain symbol to reach it.
-    // EXAMPLE:
-    //   interface FooControllerSomeAction { type: '...'; handler: () => void }
-    //             ^^^^^^^^^^^^^^^^^^^^^^^ reached via the plain symbol
-    const typeDeclarations = typeAliasDeclarations.length > 0
-        ? typeAliasDeclarations
-        : (capabilityType.getSymbol()?.getDeclarations() ?? []);
-    // Of the declarations behind whichever symbol we used, pick the type alias or
-    // interface.
-    // EXAMPLES:
-    //   type FooControllerSomeAction = { ... }
-    //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    //   interface FooControllerSomeAction { ... }
-    //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    const foundTypeDeclaration = typeDeclarations.find((node) => ts_morph_1.Node.isTypeAliasDeclaration(node) ||
-        ts_morph_1.Node.isInterfaceDeclaration(node));
-    if (foundTypeDeclaration) {
-        return foundTypeDeclaration;
-    }
-    // If the capability collection type has only one constituent, we can safely
-    // assume it's a type alias. If, in this case, it's also generic, the
-    // declaration we want is the one its type node references, so follow it.
-    //
-    // EXAMPLE:
-    //   type Actions = Foo<Bar>;
-    //                  ^^^ follow this reference to its declaration
-    //
-    if (isLoneConstituent) {
-        return resolveGenericCapabilityCollectionTypeDeclaration(capabilityCollectionTypeDeclaration);
-    }
-    // If, after all of this, the capability collection is a union with an
-    // anonymous constituent, we ignore it:
-    //
-    // EXAMPLE:
-    //   type Actions = FooControllerSomeAction | { type: '...'; handler: ... };
-    //                                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    return undefined;
-}
-/**
- * Given a messenger capability collection with one constituent which is a
- * generic capability type, follow that type to find its declaration.
- *
- * A type that is aliased to a generic type is a special case we need to handle,
- * because it won't have a direct alias symbol; we need to pick out the type
- * that acts as the "box" in the generic (e.g. the `Foo` in `type Actions =
- * Foo<Bar>`).
- *
- * @param capabilityCollectionTypeDeclaration - The declaration for a
- * collection of capability types (e.g. `type RootMessengerActions = ...`).
- * @returns The resolved sole capability type.
- */
-function resolveGenericCapabilityCollectionTypeDeclaration(capabilityCollectionTypeDeclaration) {
-    // The root alias must reference another type by name for there to be a
-    // declaration to follow.
-    // EXAMPLE:
-    //   type Actions = Foo<Bar>;
-    //                  ^^^^^^^^
-    const typeNode = capabilityCollectionTypeDeclaration.getTypeNode();
-    if (!typeNode || !ts_morph_1.Node.isTypeReference(typeNode)) {
-        return undefined;
-    }
-    // Resolve the referenced name (e.g. `Foo` in `Foo<Bar>`) to its symbol.
-    const localSymbol = typeNode.getTypeName().getSymbol();
-    // If the type is 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 { Foo } from '@metamask/foo';
-    //   type Actions = Foo<Bar>;
-    //                  ^^^
-    const symbol = localSymbol?.getAliasedSymbol() ?? localSymbol;
-    // Follow the reference to the type alias or interface it names.
-    // EXAMPLES:
-    //   type Foo<T> = { ... }
-    //   ^^^^^^^^^^^^^^^^^^^^
-    //   interface Foo<T> { ... }
-    //   ^^^^^^^^^^^^^^^^^^^^^^^
-    return symbol
-        ?.getDeclarations()
-        .find((node) => ts_morph_1.Node.isTypeAliasDeclaration(node) ||
-        ts_morph_1.Node.isInterfaceDeclaration(node));
-}
-/**
- * Render a short, single-line label for an anonymous type.
- *
- * @param type - The type to describe.
- * @param enclosingNode - Node to render the type relative to, so an aliased
- * type reads as its name rather than `import("<absolute path>").Name`.
- * @returns The label.
- */
-function summarizeType(type, enclosingNode) {
-    const text = type.getText(enclosingNode).replace(/\s+/gu, ' ');
-    return text.length > 80 ? `${text.slice(0, 77)}...` : text;
-}
-/**
- * Walk a messenger capability collection type (e.g. `RootMessengerActions` or
- * `RootMessengerEvents`) to gather all of the consitutent capability types
- * (e.g. `NetworkControllerAddNetworkAction`), then package them so that they
- * can be displayed within the documentation.
- *
- * Messenger capabilities that cannot be extracted for some reason are captured
- * separately.
- *
- * @param args - The arguments to this function.
- * @param args.projectPath - Absolute path to the project root.
- * @param args.capabilityKind - Whether these are actions or events.
- * @param args.capabilityCollectionTypeReference - A reference to a messenger
- * capability collection type within the project, in `<file>#<TypeName>` format.
- * @param args.capabilityCollectionTypeDeclaration - The type declaration
- * representing a collection of messenger capabilities.
- * @param args.commandLineOptionName - The command-line option the reference
- * came from, used in errors.
- * @returns The extracted capabilities along with skipped capabilities.
- * @throws If the capability collection type resolved to `any` or `unknown`.
- */
-function extractFromMessengerCapabilitiesUnionTypeDeclaration({ projectPath, capabilityKind, capabilityCollectionTypeReference, capabilityCollectionTypeDeclaration, commandLineOptionName, }) {
-    const capabilityCollectionType = capabilityCollectionTypeDeclaration
-        .getTypeNodeOrThrow()
-        .getType();
-    // If one or more of the constituent capabilities in the collection is `any`
-    // or `unknown` — e.g. its import failed — then the type of the whole
-    // collection will also be `any` or `unknown`. Fail instead of emitting a
-    // catalog that looks complete but silently isn't.
-    if (capabilityCollectionType.isAny() ||
-        capabilityCollectionType.isUnknown()) {
-        throw new Error(`${capabilityCollectionTypeReference.filePath}#${capabilityCollectionTypeReference.typeName}, named by ${commandLineOptionName}, ` +
-            `resolved to \`${capabilityCollectionType.getText()}\`. ` +
-            `It's likely that an individual action or event type is also \`${capabilityCollectionType.getText()}\`, ` +
-            `which may be due to a failed import. ` +
-            `You will need to fix this first before generating docs for this project.`);
-    }
-    const skippedCapabilities = {
-        unnamedCapabilities: [],
-        unextractableCapabilities: [],
-    };
-    // A project with no capabilities of this kind aliases the union to `never`.
-    if (capabilityCollectionType.isNever()) {
-        return {
-            capabilityPackets: [],
-            skippedCapabilities,
-        };
-    }
-    const individualCapabilityTypes = capabilityCollectionType.isUnion()
-        ? capabilityCollectionType.getUnionTypes()
-        : [capabilityCollectionType];
-    const capabilityPackets = [];
-    for (const capabilityType of individualCapabilityTypes) {
-        const capabilityTypeDeclaration = findMessengerCapabilityTypeDeclaration(capabilityType, capabilityCollectionTypeDeclaration, individualCapabilityTypes.length === 1);
-        if (!capabilityTypeDeclaration) {
-            skippedCapabilities.unnamedCapabilities.push(summarizeType(capabilityType, capabilityCollectionTypeDeclaration));
-            continue;
-        }
-        const classifiedTypeDeclaration = (0, extraction_js_1.classifyMessengerCapabilityTypeDeclaration)(capabilityTypeDeclaration, capabilityKind);
-        const capabilityPacket = classifiedTypeDeclaration &&
-            (0, extraction_js_1.extractFromMessengerCapabilityTypeDeclaration)(classifiedTypeDeclaration, projectPath);
-        if (!capabilityPacket) {
-            const sourceFile = capabilityTypeDeclaration
-                .getSourceFile()
-                .getFilePath();
-            skippedCapabilities.unextractableCapabilities.push(`${capabilityTypeDeclaration.getName()} (${path.relative(projectPath, sourceFile)}:${capabilityTypeDeclaration.getStartLineNumber()})`);
-            continue;
-        }
-        capabilityPackets.push(capabilityPacket);
-    }
-    return { capabilityPackets, skippedCapabilities };
-}
-/**
- * Resolves `<file>#<TypeName>` references to messenger actions and events
- * collection types within the given project (e.g. `RootMessengerActions` or
- * `RootMessengerEvents`), walks the collection to gather all of the containing
- * capability types (e.g. `NetworkControllerAddNetworkAction`), then packages
- * them so that they can be displayed within the documentation site.
- *
- * @param args - The arguments to this function.
- * @param args.projectPath -Absolute path to the project to scan.
- * @param args.rootActionsTypeReference - A reference to a messenger
- * actions collection type within the project, in `<file>#<TypeName>` format.
- * @param args.rootEventsTypeReference - A reference to a messenger events
- * collection type within the project, in `<file>#<TypeName>` format.
- * @returns The extracted capabilities plus any capabilities that were skipped.
- */
-function discoverFromRootMessengerCapabilitiesTypes({ projectPath, rootActionsTypeReference, rootEventsTypeReference, }) {
-    const project = (0, ts_project_js_1.createProject)();
-    const capabilityPacketCollections = [
-        [rootActionsTypeReference, 'action', '--root-actions'],
-        [rootEventsTypeReference, 'event', '--root-events'],
-    ];
-    const allCapabilityPackets = [];
-    const allSkippedCapabilities = {
-        unnamedCapabilities: [],
-        unextractableCapabilities: [],
-    };
-    for (const [capabilitiesCollectionTypeReference, kind, commandLineOptionName,] of capabilityPacketCollections) {
-        const capabilitiesCollectionTypeDeclaration = resolveMessengerCapabilitiesTypeReference({
-            project,
-            projectPath,
-            reference: capabilitiesCollectionTypeReference,
-            commandLineOptionName,
-        });
-        const { capabilityPackets, skippedCapabilities } = extractFromMessengerCapabilitiesUnionTypeDeclaration({
-            projectPath,
-            capabilityKind: kind,
-            capabilityCollectionTypeReference: capabilitiesCollectionTypeReference,
-            capabilityCollectionTypeDeclaration: capabilitiesCollectionTypeDeclaration,
-            commandLineOptionName,
-        });
-        allCapabilityPackets.push(...capabilityPackets);
-        allSkippedCapabilities.unnamedCapabilities.push(...skippedCapabilities.unnamedCapabilities);
-        allSkippedCapabilities.unextractableCapabilities.push(...skippedCapabilities.unextractableCapabilities);
-    }
-    return {
-        capabilityPackets: allCapabilityPackets,
-        skippedCapabilities: allSkippedCapabilities,
-    };
-}
-exports.discoverFromRootMessengerCapabilitiesTypes = discoverFromRootMessengerCapabilitiesTypes;
-//# sourceMappingURL=root-messenger-discovery.cjs.map

package/dist/root-messenger-discovery.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"root-messenger-discovery.cjs","sourceRoot":"","sources":["../src/root-messenger-discovery.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'node:path';\nimport type {\n  InterfaceDeclaration,\n  Project as TsMorphProject,\n  Type,\n  TypeAliasDeclaration,\n} from 'ts-morph';\nimport { Node as NodeGuards } from 'ts-morph';\n\nimport {\n  classifyMessengerCapabilityTypeDeclaration,\n  extractFromMessengerCapabilityTypeDeclaration,\n} from './extraction.js';\nimport { createProject } from './ts-project.js';\nimport type { MessengerCapabilityPacket } from './types.js';\n\n// ---------------------------------------------------------------------------\n// The `root-messenger` strategy: resolve the types a project declares for its\n// collection of root messenger actions and events and let TypeScript walk them.\n// Each capability type found is handed to the shared extractor in\n// `extraction.ts`, so the output matches what the `scan` strategy produces.\n// ---------------------------------------------------------------------------\n\n/**\n * A reference to a type declared in a file, written as `<file>#<TypeName>`.\n *\n * The `root-messenger` strategy takes two of these on the command line — one\n * naming a collection of messenger action types, one naming a collection of\n * messenger event types  — and uses them to locate the type declarations to\n * enumerate.\n */\nexport type RootCapabilitiesTypeReference = {\n  /** Path to the declaring file, relative to the project root. */\n  filePath: string;\n  /** Name of the type alias within that file. */\n  typeName: string;\n};\n\n/**\n * Labels for capability types that were found but couldn't be documented,\n * grouped by why. Labels rather than counts, so warnings can name what to fix.\n */\ntype SkippedCapabilities = {\n  /**\n   * Capabilities declared inline in the capability collection type, so there is\n   * no name or JSDoc to document.\n   */\n  unnamedCapabilities: string[];\n  /*\n   * Capabilities that are named, but of a shape the extractor rejects.\n   */\n  unextractableCapabilities: string[];\n};\n\n/**\n * Split a `<file>#<TypeName>` reference into its parts, on the last `#` so\n * that paths containing a `#` still work.\n *\n * @param reference - The raw reference, e.g. `src/messenger.ts#RootActions`.\n * @returns The parsed reference.\n * @throws If the reference has no `#`, or either side of it is empty.\n */\nexport function parseRootCapabilitiesTypeReference(\n  reference: string,\n): RootCapabilitiesTypeReference {\n  const separatorIndex = reference.lastIndexOf('#');\n  if (separatorIndex === -1) {\n    throw new Error(\n      `Expected a reference of the form \"<file>#<TypeName>\", got \"${reference}\".`,\n    );\n  }\n\n  const filePath = reference.slice(0, separatorIndex);\n  const typeName = reference.slice(separatorIndex + 1);\n  if (filePath.length === 0 || typeName.length === 0) {\n    throw new Error(\n      `Expected a reference of the form \"<file>#<TypeName>\", got \"${reference}\".`,\n    );\n  }\n\n  return { filePath, typeName };\n}\n\n/**\n * A `<file>#<TypeName>` string, passed from the command line, refers to an\n * messenger actions or events collection type. This function reads the file and\n * looks up the matching type alias.\n *\n * @param args - The arguments to this function.\n * @param args.project - The ts-morph project to load the file into.\n * @param args.projectPath - Absolute path to the project root.\n * @param args.reference - The root capability collection type reference to\n * resolve.\n * @param args.commandLineOptionName - The command-line option the reference\n * came from, used in errors.\n * @returns The type alias declaration the reference names.\n * @throws If the file can't be read or declares no such type alias.\n */\nfunction resolveMessengerCapabilitiesTypeReference({\n  project,\n  projectPath,\n  reference,\n  commandLineOptionName,\n}: {\n  project: TsMorphProject;\n  projectPath: string;\n  reference: RootCapabilitiesTypeReference;\n  commandLineOptionName: string;\n}): TypeAliasDeclaration {\n  const absolutePath = path.resolve(projectPath, reference.filePath);\n\n  let sourceFile;\n  try {\n    // `addSourceFileAtPath` is idempotent: the two references often name the\n    // same file, and the second call returns the source file added by the first.\n    sourceFile = project.addSourceFileAtPath(absolutePath);\n  } catch {\n    throw new Error(\n      `Could not read ${absolutePath}, which was named by ${commandLineOptionName}.`,\n    );\n  }\n\n  // EXAMPLES:\n  //   type RootMessengerActions = ...\n  //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  //   type RootMessengerEvents = ...\n  //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  const declaration = sourceFile.getTypeAlias(reference.typeName);\n  if (!declaration) {\n    throw new Error(\n      `No type alias named \"${reference.typeName}\" in ${reference.filePath}, which was named by ${commandLineOptionName}.`,\n    );\n  }\n\n  return declaration;\n}\n\n/**\n * Given the type of a messenger capability (e.g.\n * `NetworkControllerAddNetworkAction`) as obtained from a collection of\n * capability types (e.g. `RootMessengerActions` or `RootMessengerEvents`),\n * locate the type declaration for that capability type.\n *\n * This is not as simple as following the type to its declaration, because both\n * a collection of capability types and the capability type itself can have\n * multiple representations. So there are three strategies for finding the type:\n *\n * 1. If the capability type was declared as a type alias (e.g. `type\n *    FooControllerSomeAction = { ... }`), then we need to use the symbol to\n *    find the declaration.\n * 2. If the capability type was declared as an interface (e.g. `interface\n *    FooControllerSomeAction { ... }`), we don't need to do this; interfaces\n *    are their own declaration.\n * 3. If the capability *collection* type is not a union but merely a type alias\n *    (e.g. `type RootMessengerActions = NetworkControllerAddNetworkAction`)\n *    then we follow the right-hand side of the type alias.\n *\n * When none of these find a type declaration, the capability is anonymous\n * (e.g. an inline object type with no name to document) and `undefined` is\n * returned, so the caller can record it as skipped rather than document it.\n *\n * @param capabilityType - The type of the individual capability to find the\n * declaration for.\n * @param capabilityCollectionTypeDeclaration - The declaration of the whole\n * collection the capability came from (e.g. `type RootMessengerActions = ...`).\n * @param isLoneConstituent - Whether the capability collection only includes\n * one capability type.\n * @returns The type alias or interface declaration for the capability, or\n * `undefined` when the capability is anonymous.\n */\nfunction findMessengerCapabilityTypeDeclaration(\n  capabilityType: Type,\n  capabilityCollectionTypeDeclaration: TypeAliasDeclaration,\n  isLoneConstituent: boolean,\n): TypeAliasDeclaration | InterfaceDeclaration | undefined {\n  // If we have a type alias, look for its symbol.\n  //\n  // EXAMPLE:\n  //   type FooControllerSomeAction = { type: '...'; handler: () => void };\n  //        ^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  //        the alias symbol names    the plain symbol points at this anonymous\n  //        this declaration          object\n  //\n  // But skip an alias that resolves back to the capability collection itself,\n  // which is what TypeScript reports for a lone generic instantiation.\n  //\n  // EXAMPLE:\n  //   Here the alias symbol of the sole member is `Actions`, i.e.\n  //   `capabilityCollectionTypeDeclaration`, which is not the capability we\n  //   want to document:\n  //\n  //   type Actions = Foo<Bar>;\n  //        ^^^^^^^ capabilityCollectionTypeDeclaration\n  const typeAliasDeclarations = (\n    capabilityType.getAliasSymbol()?.getDeclarations() ?? []\n  ).filter((node) => node !== capabilityCollectionTypeDeclaration);\n\n  // An interface has no alias symbol, being its own declaration, so fall back\n  // to the plain symbol to reach it.\n  // EXAMPLE:\n  //   interface FooControllerSomeAction { type: '...'; handler: () => void }\n  //             ^^^^^^^^^^^^^^^^^^^^^^^ reached via the plain symbol\n  const typeDeclarations =\n    typeAliasDeclarations.length > 0\n      ? typeAliasDeclarations\n      : (capabilityType.getSymbol()?.getDeclarations() ?? []);\n\n  // Of the declarations behind whichever symbol we used, pick the type alias or\n  // interface.\n  // EXAMPLES:\n  //   type FooControllerSomeAction = { ... }\n  //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  //   interface FooControllerSomeAction { ... }\n  //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  const foundTypeDeclaration = typeDeclarations.find(\n    (node): node is TypeAliasDeclaration | InterfaceDeclaration =>\n      NodeGuards.isTypeAliasDeclaration(node) ||\n      NodeGuards.isInterfaceDeclaration(node),\n  );\n  if (foundTypeDeclaration) {\n    return foundTypeDeclaration;\n  }\n\n  // If the capability collection type has only one constituent, we can safely\n  // assume it's a type alias. If, in this case, it's also generic, the\n  // declaration we want is the one its type node references, so follow it.\n  //\n  // EXAMPLE:\n  //   type Actions = Foo<Bar>;\n  //                  ^^^ follow this reference to its declaration\n  //\n  if (isLoneConstituent) {\n    return resolveGenericCapabilityCollectionTypeDeclaration(\n      capabilityCollectionTypeDeclaration,\n    );\n  }\n\n  // If, after all of this, the capability collection is a union with an\n  // anonymous constituent, we ignore it:\n  //\n  // EXAMPLE:\n  //   type Actions = FooControllerSomeAction | { type: '...'; handler: ... };\n  //                                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  return undefined;\n}\n\n/**\n * Given a messenger capability collection with one constituent which is a\n * generic capability type, follow that type to find its declaration.\n *\n * A type that is aliased to a generic type is a special case we need to handle,\n * because it won't have a direct alias symbol; we need to pick out the type\n * that acts as the \"box\" in the generic (e.g. the `Foo` in `type Actions =\n * Foo<Bar>`).\n *\n * @param capabilityCollectionTypeDeclaration - The declaration for a\n * collection of capability types (e.g. `type RootMessengerActions = ...`).\n * @returns The resolved sole capability type.\n */\nfunction resolveGenericCapabilityCollectionTypeDeclaration(\n  capabilityCollectionTypeDeclaration: TypeAliasDeclaration,\n): TypeAliasDeclaration | InterfaceDeclaration | undefined {\n  // The root alias must reference another type by name for there to be a\n  // declaration to follow.\n  // EXAMPLE:\n  //   type Actions = Foo<Bar>;\n  //                  ^^^^^^^^\n  const typeNode = capabilityCollectionTypeDeclaration.getTypeNode();\n  if (!typeNode || !NodeGuards.isTypeReference(typeNode)) {\n    return undefined;\n  }\n\n  // Resolve the referenced name (e.g. `Foo` in `Foo<Bar>`) to its symbol.\n  const localSymbol = typeNode.getTypeName().getSymbol();\n  // If the type is imported from another file, ensure that when we access the\n  // declaration, it's the type declaration in the other file, not the import\n  // declaration in this file.\n  // EXAMPLE:\n  //   import { Foo } from '@metamask/foo';\n  //   type Actions = Foo<Bar>;\n  //                  ^^^\n  const symbol = localSymbol?.getAliasedSymbol() ?? localSymbol;\n\n  // Follow the reference to the type alias or interface it names.\n  // EXAMPLES:\n  //   type Foo<T> = { ... }\n  //   ^^^^^^^^^^^^^^^^^^^^\n  //   interface Foo<T> { ... }\n  //   ^^^^^^^^^^^^^^^^^^^^^^^\n  return symbol\n    ?.getDeclarations()\n    .find(\n      (node): node is TypeAliasDeclaration | InterfaceDeclaration =>\n        NodeGuards.isTypeAliasDeclaration(node) ||\n        NodeGuards.isInterfaceDeclaration(node),\n    );\n}\n\n/**\n * Render a short, single-line label for an anonymous type.\n *\n * @param type - The type to describe.\n * @param enclosingNode - Node to render the type relative to, so an aliased\n * type reads as its name rather than `import(\"<absolute path>\").Name`.\n * @returns The label.\n */\nfunction summarizeType(\n  type: Type,\n  enclosingNode: TypeAliasDeclaration,\n): string {\n  const text = type.getText(enclosingNode).replace(/\\s+/gu, ' ');\n  return text.length > 80 ? `${text.slice(0, 77)}...` : text;\n}\n\n/**\n * Walk a messenger capability collection type (e.g. `RootMessengerActions` or\n * `RootMessengerEvents`) to gather all of the consitutent capability types\n * (e.g. `NetworkControllerAddNetworkAction`), then package them so that they\n * can be displayed within the documentation.\n *\n * Messenger capabilities that cannot be extracted for some reason are captured\n * separately.\n *\n * @param args - The arguments to this function.\n * @param args.projectPath - Absolute path to the project root.\n * @param args.capabilityKind - Whether these are actions or events.\n * @param args.capabilityCollectionTypeReference - A reference to a messenger\n * capability collection type within the project, in `<file>#<TypeName>` format.\n * @param args.capabilityCollectionTypeDeclaration - The type declaration\n * representing a collection of messenger capabilities.\n * @param args.commandLineOptionName - The command-line option the reference\n * came from, used in errors.\n * @returns The extracted capabilities along with skipped capabilities.\n * @throws If the capability collection type resolved to `any` or `unknown`.\n */\nfunction extractFromMessengerCapabilitiesUnionTypeDeclaration({\n  projectPath,\n  capabilityKind,\n  capabilityCollectionTypeReference,\n  capabilityCollectionTypeDeclaration,\n  commandLineOptionName,\n}: {\n  projectPath: string;\n  capabilityKind: 'action' | 'event';\n  capabilityCollectionTypeReference: RootCapabilitiesTypeReference;\n  capabilityCollectionTypeDeclaration: TypeAliasDeclaration;\n  commandLineOptionName: string;\n}): {\n  capabilityPackets: MessengerCapabilityPacket[];\n  skippedCapabilities: SkippedCapabilities;\n} {\n  const capabilityCollectionType = capabilityCollectionTypeDeclaration\n    .getTypeNodeOrThrow()\n    .getType();\n\n  // If one or more of the constituent capabilities in the collection is `any`\n  // or `unknown` — e.g. its import failed — then the type of the whole\n  // collection will also be `any` or `unknown`. Fail instead of emitting a\n  // catalog that looks complete but silently isn't.\n  if (\n    capabilityCollectionType.isAny() ||\n    capabilityCollectionType.isUnknown()\n  ) {\n    throw new Error(\n      `${capabilityCollectionTypeReference.filePath}#${capabilityCollectionTypeReference.typeName}, named by ${commandLineOptionName}, ` +\n        `resolved to \\`${capabilityCollectionType.getText()}\\`. ` +\n        `It's likely that an individual action or event type is also \\`${capabilityCollectionType.getText()}\\`, ` +\n        `which may be due to a failed import. ` +\n        `You will need to fix this first before generating docs for this project.`,\n    );\n  }\n\n  const skippedCapabilities: SkippedCapabilities = {\n    unnamedCapabilities: [],\n    unextractableCapabilities: [],\n  };\n\n  // A project with no capabilities of this kind aliases the union to `never`.\n  if (capabilityCollectionType.isNever()) {\n    return {\n      capabilityPackets: [],\n      skippedCapabilities,\n    };\n  }\n\n  const individualCapabilityTypes = capabilityCollectionType.isUnion()\n    ? capabilityCollectionType.getUnionTypes()\n    : [capabilityCollectionType];\n  const capabilityPackets: MessengerCapabilityPacket[] = [];\n\n  for (const capabilityType of individualCapabilityTypes) {\n    const capabilityTypeDeclaration = findMessengerCapabilityTypeDeclaration(\n      capabilityType,\n      capabilityCollectionTypeDeclaration,\n      individualCapabilityTypes.length === 1,\n    );\n    if (!capabilityTypeDeclaration) {\n      skippedCapabilities.unnamedCapabilities.push(\n        summarizeType(capabilityType, capabilityCollectionTypeDeclaration),\n      );\n      continue;\n    }\n\n    const classifiedTypeDeclaration =\n      classifyMessengerCapabilityTypeDeclaration(\n        capabilityTypeDeclaration,\n        capabilityKind,\n      );\n    const capabilityPacket =\n      classifiedTypeDeclaration &&\n      extractFromMessengerCapabilityTypeDeclaration(\n        classifiedTypeDeclaration,\n        projectPath,\n      );\n    if (!capabilityPacket) {\n      const sourceFile = capabilityTypeDeclaration\n        .getSourceFile()\n        .getFilePath();\n      skippedCapabilities.unextractableCapabilities.push(\n        `${capabilityTypeDeclaration.getName()} (${path.relative(projectPath, sourceFile)}:${capabilityTypeDeclaration.getStartLineNumber()})`,\n      );\n      continue;\n    }\n\n    capabilityPackets.push(capabilityPacket);\n  }\n\n  return { capabilityPackets, skippedCapabilities };\n}\n\n/**\n * Resolves `<file>#<TypeName>` references to messenger actions and events\n * collection types within the given project (e.g. `RootMessengerActions` or\n * `RootMessengerEvents`), walks the collection to gather all of the containing\n * capability types (e.g. `NetworkControllerAddNetworkAction`), then packages\n * them so that they can be displayed within the documentation site.\n *\n * @param args - The arguments to this function.\n * @param args.projectPath -Absolute path to the project to scan.\n * @param args.rootActionsTypeReference - A reference to a messenger\n * actions collection type within the project, in `<file>#<TypeName>` format.\n * @param args.rootEventsTypeReference - A reference to a messenger events\n * collection type within the project, in `<file>#<TypeName>` format.\n * @returns The extracted capabilities plus any capabilities that were skipped.\n */\nexport function discoverFromRootMessengerCapabilitiesTypes({\n  projectPath,\n  rootActionsTypeReference,\n  rootEventsTypeReference,\n}: {\n  projectPath: string;\n  rootActionsTypeReference: RootCapabilitiesTypeReference;\n  rootEventsTypeReference: RootCapabilitiesTypeReference;\n}): {\n  capabilityPackets: MessengerCapabilityPacket[];\n  skippedCapabilities: SkippedCapabilities;\n} {\n  const project = createProject();\n  const capabilityPacketCollections = [\n    [rootActionsTypeReference, 'action', '--root-actions'],\n    [rootEventsTypeReference, 'event', '--root-events'],\n  ] as const;\n  const allCapabilityPackets: MessengerCapabilityPacket[] = [];\n  const allSkippedCapabilities: SkippedCapabilities = {\n    unnamedCapabilities: [],\n    unextractableCapabilities: [],\n  };\n\n  for (const [\n    capabilitiesCollectionTypeReference,\n    kind,\n    commandLineOptionName,\n  ] of capabilityPacketCollections) {\n    const capabilitiesCollectionTypeDeclaration =\n      resolveMessengerCapabilitiesTypeReference({\n        project,\n        projectPath,\n        reference: capabilitiesCollectionTypeReference,\n        commandLineOptionName,\n      });\n    const { capabilityPackets, skippedCapabilities } =\n      extractFromMessengerCapabilitiesUnionTypeDeclaration({\n        projectPath,\n        capabilityKind: kind,\n        capabilityCollectionTypeReference: capabilitiesCollectionTypeReference,\n        capabilityCollectionTypeDeclaration:\n          capabilitiesCollectionTypeDeclaration,\n        commandLineOptionName,\n      });\n    allCapabilityPackets.push(...capabilityPackets);\n    allSkippedCapabilities.unnamedCapabilities.push(\n      ...skippedCapabilities.unnamedCapabilities,\n    );\n    allSkippedCapabilities.unextractableCapabilities.push(\n      ...skippedCapabilities.unextractableCapabilities,\n    );\n  }\n\n  return {\n    capabilityPackets: allCapabilityPackets,\n    skippedCapabilities: allSkippedCapabilities,\n  };\n}\n"]}

package/dist/root-messenger-discovery.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"root-messenger-discovery.d.cts","sourceRoot":"","sources":["../src/root-messenger-discovery.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,yBAAyB,EAAE,oBAAmB;AAS5D;;;;;;;GAOG;AACH,MAAM,MAAM,6BAA6B,GAAG;IAC1C,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,KAAK,mBAAmB,GAAG;IACzB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAI9B,yBAAyB,EAAE,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,CAChD,SAAS,EAAE,MAAM,GAChB,6BAA6B,CAiB/B;AA6VD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0CAA0C,CAAC,EACzD,WAAW,EACX,wBAAwB,EACxB,uBAAuB,GACxB,EAAE;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB,EAAE,6BAA6B,CAAC;IACxD,uBAAuB,EAAE,6BAA6B,CAAC;CACxD,GAAG;IACF,iBAAiB,EAAE,yBAAyB,EAAE,CAAC;IAC/C,mBAAmB,EAAE,mBAAmB,CAAC;CAC1C,CA8CA"}

package/dist/root-messenger-discovery.d.mts

@@ -1,61 +0,0 @@
-import type { MessengerCapabilityPacket } from "./types.mjs";
-/**
- * A reference to a type declared in a file, written as `<file>#<TypeName>`.
- *
- * The `root-messenger` strategy takes two of these on the command line — one
- * naming a collection of messenger action types, one naming a collection of
- * messenger event types  — and uses them to locate the type declarations to
- * enumerate.
- */
-export type RootCapabilitiesTypeReference = {
-    /** Path to the declaring file, relative to the project root. */
-    filePath: string;
-    /** Name of the type alias within that file. */
-    typeName: string;
-};
-/**
- * Labels for capability types that were found but couldn't be documented,
- * grouped by why. Labels rather than counts, so warnings can name what to fix.
- */
-type SkippedCapabilities = {
-    /**
-     * Capabilities declared inline in the capability collection type, so there is
-     * no name or JSDoc to document.
-     */
-    unnamedCapabilities: string[];
-    unextractableCapabilities: string[];
-};
-/**
- * Split a `<file>#<TypeName>` reference into its parts, on the last `#` so
- * that paths containing a `#` still work.
- *
- * @param reference - The raw reference, e.g. `src/messenger.ts#RootActions`.
- * @returns The parsed reference.
- * @throws If the reference has no `#`, or either side of it is empty.
- */
-export declare function parseRootCapabilitiesTypeReference(reference: string): RootCapabilitiesTypeReference;
-/**
- * Resolves `<file>#<TypeName>` references to messenger actions and events
- * collection types within the given project (e.g. `RootMessengerActions` or
- * `RootMessengerEvents`), walks the collection to gather all of the containing
- * capability types (e.g. `NetworkControllerAddNetworkAction`), then packages
- * them so that they can be displayed within the documentation site.
- *
- * @param args - The arguments to this function.
- * @param args.projectPath -Absolute path to the project to scan.
- * @param args.rootActionsTypeReference - A reference to a messenger
- * actions collection type within the project, in `<file>#<TypeName>` format.
- * @param args.rootEventsTypeReference - A reference to a messenger events
- * collection type within the project, in `<file>#<TypeName>` format.
- * @returns The extracted capabilities plus any capabilities that were skipped.
- */
-export declare function discoverFromRootMessengerCapabilitiesTypes({ projectPath, rootActionsTypeReference, rootEventsTypeReference, }: {
-    projectPath: string;
-    rootActionsTypeReference: RootCapabilitiesTypeReference;
-    rootEventsTypeReference: RootCapabilitiesTypeReference;
-}): {
-    capabilityPackets: MessengerCapabilityPacket[];
-    skippedCapabilities: SkippedCapabilities;
-};
-export {};
-//# sourceMappingURL=root-messenger-discovery.d.mts.map

package/dist/root-messenger-discovery.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"root-messenger-discovery.d.mts","sourceRoot":"","sources":["../src/root-messenger-discovery.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,yBAAyB,EAAE,oBAAmB;AAS5D;;;;;;;GAOG;AACH,MAAM,MAAM,6BAA6B,GAAG;IAC1C,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,KAAK,mBAAmB,GAAG;IACzB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAI9B,yBAAyB,EAAE,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,CAChD,SAAS,EAAE,MAAM,GAChB,6BAA6B,CAiB/B;AA6VD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0CAA0C,CAAC,EACzD,WAAW,EACX,wBAAwB,EACxB,uBAAuB,GACxB,EAAE;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB,EAAE,6BAA6B,CAAC;IACxD,uBAAuB,EAAE,6BAA6B,CAAC;CACxD,GAAG;IACF,iBAAiB,EAAE,yBAAyB,EAAE,CAAC;IAC/C,mBAAmB,EAAE,mBAAmB,CAAC;CAC1C,CA8CA"}

package/dist/root-messenger-discovery.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"root-messenger-discovery.mjs","sourceRoot":"","sources":["../src/root-messenger-discovery.ts"],"names":[],"mappings":"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","sourcesContent":["import * as path from 'node:path';\nimport type {\n  InterfaceDeclaration,\n  Project as TsMorphProject,\n  Type,\n  TypeAliasDeclaration,\n} from 'ts-morph';\nimport { Node as NodeGuards } from 'ts-morph';\n\nimport {\n  classifyMessengerCapabilityTypeDeclaration,\n  extractFromMessengerCapabilityTypeDeclaration,\n} from './extraction.js';\nimport { createProject } from './ts-project.js';\nimport type { MessengerCapabilityPacket } from './types.js';\n\n// ---------------------------------------------------------------------------\n// The `root-messenger` strategy: resolve the types a project declares for its\n// collection of root messenger actions and events and let TypeScript walk them.\n// Each capability type found is handed to the shared extractor in\n// `extraction.ts`, so the output matches what the `scan` strategy produces.\n// ---------------------------------------------------------------------------\n\n/**\n * A reference to a type declared in a file, written as `<file>#<TypeName>`.\n *\n * The `root-messenger` strategy takes two of these on the command line — one\n * naming a collection of messenger action types, one naming a collection of\n * messenger event types  — and uses them to locate the type declarations to\n * enumerate.\n */\nexport type RootCapabilitiesTypeReference = {\n  /** Path to the declaring file, relative to the project root. */\n  filePath: string;\n  /** Name of the type alias within that file. */\n  typeName: string;\n};\n\n/**\n * Labels for capability types that were found but couldn't be documented,\n * grouped by why. Labels rather than counts, so warnings can name what to fix.\n */\ntype SkippedCapabilities = {\n  /**\n   * Capabilities declared inline in the capability collection type, so there is\n   * no name or JSDoc to document.\n   */\n  unnamedCapabilities: string[];\n  /*\n   * Capabilities that are named, but of a shape the extractor rejects.\n   */\n  unextractableCapabilities: string[];\n};\n\n/**\n * Split a `<file>#<TypeName>` reference into its parts, on the last `#` so\n * that paths containing a `#` still work.\n *\n * @param reference - The raw reference, e.g. `src/messenger.ts#RootActions`.\n * @returns The parsed reference.\n * @throws If the reference has no `#`, or either side of it is empty.\n */\nexport function parseRootCapabilitiesTypeReference(\n  reference: string,\n): RootCapabilitiesTypeReference {\n  const separatorIndex = reference.lastIndexOf('#');\n  if (separatorIndex === -1) {\n    throw new Error(\n      `Expected a reference of the form \"<file>#<TypeName>\", got \"${reference}\".`,\n    );\n  }\n\n  const filePath = reference.slice(0, separatorIndex);\n  const typeName = reference.slice(separatorIndex + 1);\n  if (filePath.length === 0 || typeName.length === 0) {\n    throw new Error(\n      `Expected a reference of the form \"<file>#<TypeName>\", got \"${reference}\".`,\n    );\n  }\n\n  return { filePath, typeName };\n}\n\n/**\n * A `<file>#<TypeName>` string, passed from the command line, refers to an\n * messenger actions or events collection type. This function reads the file and\n * looks up the matching type alias.\n *\n * @param args - The arguments to this function.\n * @param args.project - The ts-morph project to load the file into.\n * @param args.projectPath - Absolute path to the project root.\n * @param args.reference - The root capability collection type reference to\n * resolve.\n * @param args.commandLineOptionName - The command-line option the reference\n * came from, used in errors.\n * @returns The type alias declaration the reference names.\n * @throws If the file can't be read or declares no such type alias.\n */\nfunction resolveMessengerCapabilitiesTypeReference({\n  project,\n  projectPath,\n  reference,\n  commandLineOptionName,\n}: {\n  project: TsMorphProject;\n  projectPath: string;\n  reference: RootCapabilitiesTypeReference;\n  commandLineOptionName: string;\n}): TypeAliasDeclaration {\n  const absolutePath = path.resolve(projectPath, reference.filePath);\n\n  let sourceFile;\n  try {\n    // `addSourceFileAtPath` is idempotent: the two references often name the\n    // same file, and the second call returns the source file added by the first.\n    sourceFile = project.addSourceFileAtPath(absolutePath);\n  } catch {\n    throw new Error(\n      `Could not read ${absolutePath}, which was named by ${commandLineOptionName}.`,\n    );\n  }\n\n  // EXAMPLES:\n  //   type RootMessengerActions = ...\n  //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  //   type RootMessengerEvents = ...\n  //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  const declaration = sourceFile.getTypeAlias(reference.typeName);\n  if (!declaration) {\n    throw new Error(\n      `No type alias named \"${reference.typeName}\" in ${reference.filePath}, which was named by ${commandLineOptionName}.`,\n    );\n  }\n\n  return declaration;\n}\n\n/**\n * Given the type of a messenger capability (e.g.\n * `NetworkControllerAddNetworkAction`) as obtained from a collection of\n * capability types (e.g. `RootMessengerActions` or `RootMessengerEvents`),\n * locate the type declaration for that capability type.\n *\n * This is not as simple as following the type to its declaration, because both\n * a collection of capability types and the capability type itself can have\n * multiple representations. So there are three strategies for finding the type:\n *\n * 1. If the capability type was declared as a type alias (e.g. `type\n *    FooControllerSomeAction = { ... }`), then we need to use the symbol to\n *    find the declaration.\n * 2. If the capability type was declared as an interface (e.g. `interface\n *    FooControllerSomeAction { ... }`), we don't need to do this; interfaces\n *    are their own declaration.\n * 3. If the capability *collection* type is not a union but merely a type alias\n *    (e.g. `type RootMessengerActions = NetworkControllerAddNetworkAction`)\n *    then we follow the right-hand side of the type alias.\n *\n * When none of these find a type declaration, the capability is anonymous\n * (e.g. an inline object type with no name to document) and `undefined` is\n * returned, so the caller can record it as skipped rather than document it.\n *\n * @param capabilityType - The type of the individual capability to find the\n * declaration for.\n * @param capabilityCollectionTypeDeclaration - The declaration of the whole\n * collection the capability came from (e.g. `type RootMessengerActions = ...`).\n * @param isLoneConstituent - Whether the capability collection only includes\n * one capability type.\n * @returns The type alias or interface declaration for the capability, or\n * `undefined` when the capability is anonymous.\n */\nfunction findMessengerCapabilityTypeDeclaration(\n  capabilityType: Type,\n  capabilityCollectionTypeDeclaration: TypeAliasDeclaration,\n  isLoneConstituent: boolean,\n): TypeAliasDeclaration | InterfaceDeclaration | undefined {\n  // If we have a type alias, look for its symbol.\n  //\n  // EXAMPLE:\n  //   type FooControllerSomeAction = { type: '...'; handler: () => void };\n  //        ^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  //        the alias symbol names    the plain symbol points at this anonymous\n  //        this declaration          object\n  //\n  // But skip an alias that resolves back to the capability collection itself,\n  // which is what TypeScript reports for a lone generic instantiation.\n  //\n  // EXAMPLE:\n  //   Here the alias symbol of the sole member is `Actions`, i.e.\n  //   `capabilityCollectionTypeDeclaration`, which is not the capability we\n  //   want to document:\n  //\n  //   type Actions = Foo<Bar>;\n  //        ^^^^^^^ capabilityCollectionTypeDeclaration\n  const typeAliasDeclarations = (\n    capabilityType.getAliasSymbol()?.getDeclarations() ?? []\n  ).filter((node) => node !== capabilityCollectionTypeDeclaration);\n\n  // An interface has no alias symbol, being its own declaration, so fall back\n  // to the plain symbol to reach it.\n  // EXAMPLE:\n  //   interface FooControllerSomeAction { type: '...'; handler: () => void }\n  //             ^^^^^^^^^^^^^^^^^^^^^^^ reached via the plain symbol\n  const typeDeclarations =\n    typeAliasDeclarations.length > 0\n      ? typeAliasDeclarations\n      : (capabilityType.getSymbol()?.getDeclarations() ?? []);\n\n  // Of the declarations behind whichever symbol we used, pick the type alias or\n  // interface.\n  // EXAMPLES:\n  //   type FooControllerSomeAction = { ... }\n  //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  //   interface FooControllerSomeAction { ... }\n  //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  const foundTypeDeclaration = typeDeclarations.find(\n    (node): node is TypeAliasDeclaration | InterfaceDeclaration =>\n      NodeGuards.isTypeAliasDeclaration(node) ||\n      NodeGuards.isInterfaceDeclaration(node),\n  );\n  if (foundTypeDeclaration) {\n    return foundTypeDeclaration;\n  }\n\n  // If the capability collection type has only one constituent, we can safely\n  // assume it's a type alias. If, in this case, it's also generic, the\n  // declaration we want is the one its type node references, so follow it.\n  //\n  // EXAMPLE:\n  //   type Actions = Foo<Bar>;\n  //                  ^^^ follow this reference to its declaration\n  //\n  if (isLoneConstituent) {\n    return resolveGenericCapabilityCollectionTypeDeclaration(\n      capabilityCollectionTypeDeclaration,\n    );\n  }\n\n  // If, after all of this, the capability collection is a union with an\n  // anonymous constituent, we ignore it:\n  //\n  // EXAMPLE:\n  //   type Actions = FooControllerSomeAction | { type: '...'; handler: ... };\n  //                                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  return undefined;\n}\n\n/**\n * Given a messenger capability collection with one constituent which is a\n * generic capability type, follow that type to find its declaration.\n *\n * A type that is aliased to a generic type is a special case we need to handle,\n * because it won't have a direct alias symbol; we need to pick out the type\n * that acts as the \"box\" in the generic (e.g. the `Foo` in `type Actions =\n * Foo<Bar>`).\n *\n * @param capabilityCollectionTypeDeclaration - The declaration for a\n * collection of capability types (e.g. `type RootMessengerActions = ...`).\n * @returns The resolved sole capability type.\n */\nfunction resolveGenericCapabilityCollectionTypeDeclaration(\n  capabilityCollectionTypeDeclaration: TypeAliasDeclaration,\n): TypeAliasDeclaration | InterfaceDeclaration | undefined {\n  // The root alias must reference another type by name for there to be a\n  // declaration to follow.\n  // EXAMPLE:\n  //   type Actions = Foo<Bar>;\n  //                  ^^^^^^^^\n  const typeNode = capabilityCollectionTypeDeclaration.getTypeNode();\n  if (!typeNode || !NodeGuards.isTypeReference(typeNode)) {\n    return undefined;\n  }\n\n  // Resolve the referenced name (e.g. `Foo` in `Foo<Bar>`) to its symbol.\n  const localSymbol = typeNode.getTypeName().getSymbol();\n  // If the type is imported from another file, ensure that when we access the\n  // declaration, it's the type declaration in the other file, not the import\n  // declaration in this file.\n  // EXAMPLE:\n  //   import { Foo } from '@metamask/foo';\n  //   type Actions = Foo<Bar>;\n  //                  ^^^\n  const symbol = localSymbol?.getAliasedSymbol() ?? localSymbol;\n\n  // Follow the reference to the type alias or interface it names.\n  // EXAMPLES:\n  //   type Foo<T> = { ... }\n  //   ^^^^^^^^^^^^^^^^^^^^\n  //   interface Foo<T> { ... }\n  //   ^^^^^^^^^^^^^^^^^^^^^^^\n  return symbol\n    ?.getDeclarations()\n    .find(\n      (node): node is TypeAliasDeclaration | InterfaceDeclaration =>\n        NodeGuards.isTypeAliasDeclaration(node) ||\n        NodeGuards.isInterfaceDeclaration(node),\n    );\n}\n\n/**\n * Render a short, single-line label for an anonymous type.\n *\n * @param type - The type to describe.\n * @param enclosingNode - Node to render the type relative to, so an aliased\n * type reads as its name rather than `import(\"<absolute path>\").Name`.\n * @returns The label.\n */\nfunction summarizeType(\n  type: Type,\n  enclosingNode: TypeAliasDeclaration,\n): string {\n  const text = type.getText(enclosingNode).replace(/\\s+/gu, ' ');\n  return text.length > 80 ? `${text.slice(0, 77)}...` : text;\n}\n\n/**\n * Walk a messenger capability collection type (e.g. `RootMessengerActions` or\n * `RootMessengerEvents`) to gather all of the consitutent capability types\n * (e.g. `NetworkControllerAddNetworkAction`), then package them so that they\n * can be displayed within the documentation.\n *\n * Messenger capabilities that cannot be extracted for some reason are captured\n * separately.\n *\n * @param args - The arguments to this function.\n * @param args.projectPath - Absolute path to the project root.\n * @param args.capabilityKind - Whether these are actions or events.\n * @param args.capabilityCollectionTypeReference - A reference to a messenger\n * capability collection type within the project, in `<file>#<TypeName>` format.\n * @param args.capabilityCollectionTypeDeclaration - The type declaration\n * representing a collection of messenger capabilities.\n * @param args.commandLineOptionName - The command-line option the reference\n * came from, used in errors.\n * @returns The extracted capabilities along with skipped capabilities.\n * @throws If the capability collection type resolved to `any` or `unknown`.\n */\nfunction extractFromMessengerCapabilitiesUnionTypeDeclaration({\n  projectPath,\n  capabilityKind,\n  capabilityCollectionTypeReference,\n  capabilityCollectionTypeDeclaration,\n  commandLineOptionName,\n}: {\n  projectPath: string;\n  capabilityKind: 'action' | 'event';\n  capabilityCollectionTypeReference: RootCapabilitiesTypeReference;\n  capabilityCollectionTypeDeclaration: TypeAliasDeclaration;\n  commandLineOptionName: string;\n}): {\n  capabilityPackets: MessengerCapabilityPacket[];\n  skippedCapabilities: SkippedCapabilities;\n} {\n  const capabilityCollectionType = capabilityCollectionTypeDeclaration\n    .getTypeNodeOrThrow()\n    .getType();\n\n  // If one or more of the constituent capabilities in the collection is `any`\n  // or `unknown` — e.g. its import failed — then the type of the whole\n  // collection will also be `any` or `unknown`. Fail instead of emitting a\n  // catalog that looks complete but silently isn't.\n  if (\n    capabilityCollectionType.isAny() ||\n    capabilityCollectionType.isUnknown()\n  ) {\n    throw new Error(\n      `${capabilityCollectionTypeReference.filePath}#${capabilityCollectionTypeReference.typeName}, named by ${commandLineOptionName}, ` +\n        `resolved to \\`${capabilityCollectionType.getText()}\\`. ` +\n        `It's likely that an individual action or event type is also \\`${capabilityCollectionType.getText()}\\`, ` +\n        `which may be due to a failed import. ` +\n        `You will need to fix this first before generating docs for this project.`,\n    );\n  }\n\n  const skippedCapabilities: SkippedCapabilities = {\n    unnamedCapabilities: [],\n    unextractableCapabilities: [],\n  };\n\n  // A project with no capabilities of this kind aliases the union to `never`.\n  if (capabilityCollectionType.isNever()) {\n    return {\n      capabilityPackets: [],\n      skippedCapabilities,\n    };\n  }\n\n  const individualCapabilityTypes = capabilityCollectionType.isUnion()\n    ? capabilityCollectionType.getUnionTypes()\n    : [capabilityCollectionType];\n  const capabilityPackets: MessengerCapabilityPacket[] = [];\n\n  for (const capabilityType of individualCapabilityTypes) {\n    const capabilityTypeDeclaration = findMessengerCapabilityTypeDeclaration(\n      capabilityType,\n      capabilityCollectionTypeDeclaration,\n      individualCapabilityTypes.length === 1,\n    );\n    if (!capabilityTypeDeclaration) {\n      skippedCapabilities.unnamedCapabilities.push(\n        summarizeType(capabilityType, capabilityCollectionTypeDeclaration),\n      );\n      continue;\n    }\n\n    const classifiedTypeDeclaration =\n      classifyMessengerCapabilityTypeDeclaration(\n        capabilityTypeDeclaration,\n        capabilityKind,\n      );\n    const capabilityPacket =\n      classifiedTypeDeclaration &&\n      extractFromMessengerCapabilityTypeDeclaration(\n        classifiedTypeDeclaration,\n        projectPath,\n      );\n    if (!capabilityPacket) {\n      const sourceFile = capabilityTypeDeclaration\n        .getSourceFile()\n        .getFilePath();\n      skippedCapabilities.unextractableCapabilities.push(\n        `${capabilityTypeDeclaration.getName()} (${path.relative(projectPath, sourceFile)}:${capabilityTypeDeclaration.getStartLineNumber()})`,\n      );\n      continue;\n    }\n\n    capabilityPackets.push(capabilityPacket);\n  }\n\n  return { capabilityPackets, skippedCapabilities };\n}\n\n/**\n * Resolves `<file>#<TypeName>` references to messenger actions and events\n * collection types within the given project (e.g. `RootMessengerActions` or\n * `RootMessengerEvents`), walks the collection to gather all of the containing\n * capability types (e.g. `NetworkControllerAddNetworkAction`), then packages\n * them so that they can be displayed within the documentation site.\n *\n * @param args - The arguments to this function.\n * @param args.projectPath -Absolute path to the project to scan.\n * @param args.rootActionsTypeReference - A reference to a messenger\n * actions collection type within the project, in `<file>#<TypeName>` format.\n * @param args.rootEventsTypeReference - A reference to a messenger events\n * collection type within the project, in `<file>#<TypeName>` format.\n * @returns The extracted capabilities plus any capabilities that were skipped.\n */\nexport function discoverFromRootMessengerCapabilitiesTypes({\n  projectPath,\n  rootActionsTypeReference,\n  rootEventsTypeReference,\n}: {\n  projectPath: string;\n  rootActionsTypeReference: RootCapabilitiesTypeReference;\n  rootEventsTypeReference: RootCapabilitiesTypeReference;\n}): {\n  capabilityPackets: MessengerCapabilityPacket[];\n  skippedCapabilities: SkippedCapabilities;\n} {\n  const project = createProject();\n  const capabilityPacketCollections = [\n    [rootActionsTypeReference, 'action', '--root-actions'],\n    [rootEventsTypeReference, 'event', '--root-events'],\n  ] as const;\n  const allCapabilityPackets: MessengerCapabilityPacket[] = [];\n  const allSkippedCapabilities: SkippedCapabilities = {\n    unnamedCapabilities: [],\n    unextractableCapabilities: [],\n  };\n\n  for (const [\n    capabilitiesCollectionTypeReference,\n    kind,\n    commandLineOptionName,\n  ] of capabilityPacketCollections) {\n    const capabilitiesCollectionTypeDeclaration =\n      resolveMessengerCapabilitiesTypeReference({\n        project,\n        projectPath,\n        reference: capabilitiesCollectionTypeReference,\n        commandLineOptionName,\n      });\n    const { capabilityPackets, skippedCapabilities } =\n      extractFromMessengerCapabilitiesUnionTypeDeclaration({\n        projectPath,\n        capabilityKind: kind,\n        capabilityCollectionTypeReference: capabilitiesCollectionTypeReference,\n        capabilityCollectionTypeDeclaration:\n          capabilitiesCollectionTypeDeclaration,\n        commandLineOptionName,\n      });\n    allCapabilityPackets.push(...capabilityPackets);\n    allSkippedCapabilities.unnamedCapabilities.push(\n      ...skippedCapabilities.unnamedCapabilities,\n    );\n    allSkippedCapabilities.unextractableCapabilities.push(\n      ...skippedCapabilities.unextractableCapabilities,\n    );\n  }\n\n  return {\n    capabilityPackets: allCapabilityPackets,\n    skippedCapabilities: allSkippedCapabilities,\n  };\n}\n"]}

package/dist/ts-project.cjs

@@ -1,33 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createProject = void 0;
-const ts_morph_1 = require("ts-morph");
-/**
- * Create a ts-morph Project configured for reading messenger capability types.
- *
- * Both discovery strategies share this: `scan` adds every file it can find so
- * the checker can resolve cross-file references, while `root-messenger` adds
- * only the entry files and lets the checker pull in the rest.
- *
- * @returns A new ts-morph Project.
- */
-function createProject() {
-    return new ts_morph_1.Project({
-        compilerOptions: {
-            allowJs: false,
-            noEmit: true,
-            // Match the project's permissive defaults — we only need symbol
-            // resolution, not full typechecking, so a project's own strictness
-            // settings shouldn't be able to fail the docs build.
-            strict: false,
-            skipLibCheck: true,
-            // Explicit module options so cross-file symbol resolution works
-            // regardless of the host process's tsconfig.
-            target: ts_morph_1.ts.ScriptTarget.ESNext,
-            module: ts_morph_1.ts.ModuleKind.ESNext,
-            moduleResolution: ts_morph_1.ts.ModuleResolutionKind.NodeJs,
-        },
-    });
-}
-exports.createProject = createProject;
-//# sourceMappingURL=ts-project.cjs.map

package/dist/ts-project.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"ts-project.cjs","sourceRoot":"","sources":["../src/ts-project.ts"],"names":[],"mappings":";;;AAAA,uCAAuC;AAEvC;;;;;;;;GAQG;AACH,SAAgB,aAAa;IAC3B,OAAO,IAAI,kBAAO,CAAC;QACjB,eAAe,EAAE;YACf,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,IAAI;YACZ,gEAAgE;YAChE,mEAAmE;YACnE,qDAAqD;YACrD,MAAM,EAAE,KAAK;YACb,YAAY,EAAE,IAAI;YAClB,gEAAgE;YAChE,6CAA6C;YAC7C,MAAM,EAAE,aAAE,CAAC,YAAY,CAAC,MAAM;YAC9B,MAAM,EAAE,aAAE,CAAC,UAAU,CAAC,MAAM;YAC5B,gBAAgB,EAAE,aAAE,CAAC,oBAAoB,CAAC,MAAM;SACjD;KACF,CAAC,CAAC;AACL,CAAC;AAjBD,sCAiBC","sourcesContent":["import { Project, ts } from 'ts-morph';\n\n/**\n * Create a ts-morph Project configured for reading messenger capability types.\n *\n * Both discovery strategies share this: `scan` adds every file it can find so\n * the checker can resolve cross-file references, while `root-messenger` adds\n * only the entry files and lets the checker pull in the rest.\n *\n * @returns A new ts-morph Project.\n */\nexport function createProject(): Project {\n  return new Project({\n    compilerOptions: {\n      allowJs: false,\n      noEmit: true,\n      // Match the project's permissive defaults — we only need symbol\n      // resolution, not full typechecking, so a project's own strictness\n      // settings shouldn't be able to fail the docs build.\n      strict: false,\n      skipLibCheck: true,\n      // Explicit module options so cross-file symbol resolution works\n      // regardless of the host process's tsconfig.\n      target: ts.ScriptTarget.ESNext,\n      module: ts.ModuleKind.ESNext,\n      moduleResolution: ts.ModuleResolutionKind.NodeJs,\n    },\n  });\n}\n"]}

package/dist/ts-project.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ts-project.d.cts","sourceRoot":"","sources":["../src/ts-project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAM,iBAAiB;AAEvC;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAiBvC"}

package/dist/ts-project.d.mts

@@ -1,12 +0,0 @@
-import { Project } from "ts-morph";
-/**
- * Create a ts-morph Project configured for reading messenger capability types.
- *
- * Both discovery strategies share this: `scan` adds every file it can find so
- * the checker can resolve cross-file references, while `root-messenger` adds
- * only the entry files and lets the checker pull in the rest.
- *
- * @returns A new ts-morph Project.
- */
-export declare function createProject(): Project;
-//# sourceMappingURL=ts-project.d.mts.map

package/dist/ts-project.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ts-project.d.mts","sourceRoot":"","sources":["../src/ts-project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAM,iBAAiB;AAEvC;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAiBvC"}

package/dist/ts-project.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"ts-project.mjs","sourceRoot":"","sources":["../src/ts-project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,iBAAiB;AAEvC;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,OAAO,CAAC;QACjB,eAAe,EAAE;YACf,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,IAAI;YACZ,gEAAgE;YAChE,mEAAmE;YACnE,qDAAqD;YACrD,MAAM,EAAE,KAAK;YACb,YAAY,EAAE,IAAI;YAClB,gEAAgE;YAChE,6CAA6C;YAC7C,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM;YAC9B,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM;YAC5B,gBAAgB,EAAE,EAAE,CAAC,oBAAoB,CAAC,MAAM;SACjD;KACF,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { Project, ts } from 'ts-morph';\n\n/**\n * Create a ts-morph Project configured for reading messenger capability types.\n *\n * Both discovery strategies share this: `scan` adds every file it can find so\n * the checker can resolve cross-file references, while `root-messenger` adds\n * only the entry files and lets the checker pull in the rest.\n *\n * @returns A new ts-morph Project.\n */\nexport function createProject(): Project {\n  return new Project({\n    compilerOptions: {\n      allowJs: false,\n      noEmit: true,\n      // Match the project's permissive defaults — we only need symbol\n      // resolution, not full typechecking, so a project's own strictness\n      // settings shouldn't be able to fail the docs build.\n      strict: false,\n      skipLibCheck: true,\n      // Explicit module options so cross-file symbol resolution works\n      // regardless of the host process's tsconfig.\n      target: ts.ScriptTarget.ESNext,\n      module: ts.ModuleKind.ESNext,\n      moduleResolution: ts.ModuleResolutionKind.NodeJs,\n    },\n  });\n}\n"]}

package/dist/types.cjs

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.cjs.map

package/dist/types.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.cjs","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * A documented parameter for an action handler or event payload — name from\n * the JSDoc `@param` tag, description from the tag's comment body.\n */\nexport type DocumentedParameter = {\n  name: string;\n  description: string;\n};\n\n/**\n * Information about a messenger action or event extracted from its type\n * in a source file.\n */\nexport type MessengerCapabilityPacket = {\n  /** The capability type's TypeScript identifier, e.g. `NetworkControllerGetStateAction`. */\n  typeName: string;\n  /** The capability's messenger key, e.g. `NetworkController:getState`. */\n  typeString: string;\n  /** Whether the capability is an action (request/response) or an event (broadcast). */\n  kind: 'action' | 'event';\n  /** Cleaned description body — content above the first JSDoc tag. */\n  jsDoc: string;\n  /**\n   * Documented parameters — populated from `@param` tags, in source order.\n   * For actions these describe the handler's arguments; for events they\n   * describe the payload tuple's positional elements.\n   */\n  params: DocumentedParameter[];\n  /** Documented return value — populated from a `@returns` tag, if any. */\n  returns: string;\n  /** Raw type text of the handler (action) or payload (event). */\n  handlerOrPayload: string;\n  /** Path to the file the capability was declared in, relative to the project root. */\n  sourceFile: string;\n  /** 1-based line number of the capability declaration. */\n  line: number;\n  /** Whether the capability is marked `@deprecated`. */\n  deprecated: boolean;\n};\n\n/**\n * A namespace's actions and events, after dedup and sorting.\n */\nexport type NamespaceGroup = {\n  namespace: string;\n  actions: MessengerCapabilityPacket[];\n  events: MessengerCapabilityPacket[];\n};\n"]}