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

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

@@ -1,58 +0,0 @@
-import type { MessengerCapabilityPacket } from "./types.cjs";
-/**
- * A reference to a type in a file, written as `<file>#<TypeName>`.
- */
-export type RootTypeReference = {
-    /** Path to the declaring file, relative to the project root. */
-    filePath: string;
-    /** Name of the type alias within that file. */
-    typeName: string;
-};
-/**
- * Options for {@link discoverFromRootMessenger}.
- */
-type RootMessengerDiscoveryOptions = {
-    /** Absolute path to the project to scan. */
-    projectPath: string;
-    /** Type aliasing the union of every action on the root messenger. */
-    actions: RootTypeReference;
-    /** Type aliasing the union of every event on the root messenger. */
-    events: RootTypeReference;
-};
-/**
- * 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 = {
-    /** Declared inline in the union, so there is no name or JSDoc to document. */
-    unnamed: string[];
-    /** Named, but of a shape the extractor rejects. */
-    unextractable: string[];
-};
-/**
- * The result of {@link discoverFromRootMessenger}.
- */
-type RootMessengerDiscoveryResult = {
-    /** Every capability extracted, actions before events. */
-    packets: MessengerCapabilityPacket[];
-    /** Capabilities that couldn't be documented. */
-    skipped: SkippedCapabilities;
-};
-/**
- * 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 parseRootTypeReference(reference: string): RootTypeReference;
-/**
- * Enumerate every action and event reachable from a project's root messenger.
- *
- * @param options - Discovery options.
- * @returns The extracted capabilities plus anything skipped.
- */
-export declare function discoverFromRootMessenger(options: RootMessengerDiscoveryOptions): RootMessengerDiscoveryResult;
-export {};
-//# sourceMappingURL=root-messenger-discovery.d.cts.map

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":"AAaA,OAAO,KAAK,EAAE,yBAAyB,EAAE,oBAAmB;AAW5D;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,KAAK,6BAA6B,GAAG;IACnC,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,OAAO,EAAE,iBAAiB,CAAC;IAC3B,oEAAoE;IACpE,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,KAAK,mBAAmB,GAAG;IACzB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mDAAmD;IACnD,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,KAAK,4BAA4B,GAAG;IAClC,yDAAyD;IACzD,OAAO,EAAE,yBAAyB,EAAE,CAAC;IACrC,gDAAgD;IAChD,OAAO,EAAE,mBAAmB,CAAC;CAC9B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,CAiB3E;AAqOD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,6BAA6B,GACrC,4BAA4B,CA6B9B"}

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

@@ -1,58 +0,0 @@
-import type { MessengerCapabilityPacket } from "./types.mjs";
-/**
- * A reference to a type in a file, written as `<file>#<TypeName>`.
- */
-export type RootTypeReference = {
-    /** Path to the declaring file, relative to the project root. */
-    filePath: string;
-    /** Name of the type alias within that file. */
-    typeName: string;
-};
-/**
- * Options for {@link discoverFromRootMessenger}.
- */
-type RootMessengerDiscoveryOptions = {
-    /** Absolute path to the project to scan. */
-    projectPath: string;
-    /** Type aliasing the union of every action on the root messenger. */
-    actions: RootTypeReference;
-    /** Type aliasing the union of every event on the root messenger. */
-    events: RootTypeReference;
-};
-/**
- * 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 = {
-    /** Declared inline in the union, so there is no name or JSDoc to document. */
-    unnamed: string[];
-    /** Named, but of a shape the extractor rejects. */
-    unextractable: string[];
-};
-/**
- * The result of {@link discoverFromRootMessenger}.
- */
-type RootMessengerDiscoveryResult = {
-    /** Every capability extracted, actions before events. */
-    packets: MessengerCapabilityPacket[];
-    /** Capabilities that couldn't be documented. */
-    skipped: SkippedCapabilities;
-};
-/**
- * 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 parseRootTypeReference(reference: string): RootTypeReference;
-/**
- * Enumerate every action and event reachable from a project's root messenger.
- *
- * @param options - Discovery options.
- * @returns The extracted capabilities plus anything skipped.
- */
-export declare function discoverFromRootMessenger(options: RootMessengerDiscoveryOptions): RootMessengerDiscoveryResult;
-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":"AAaA,OAAO,KAAK,EAAE,yBAAyB,EAAE,oBAAmB;AAW5D;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,KAAK,6BAA6B,GAAG;IACnC,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,OAAO,EAAE,iBAAiB,CAAC;IAC3B,oEAAoE;IACpE,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,KAAK,mBAAmB,GAAG;IACzB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mDAAmD;IACnD,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,KAAK,4BAA4B,GAAG;IAClC,yDAAyD;IACzD,OAAO,EAAE,yBAAyB,EAAE,CAAC;IACrC,gDAAgD;IAChD,OAAO,EAAE,mBAAmB,CAAC;CAC9B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,CAiB3E;AAqOD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,6BAA6B,GACrC,4BAA4B,CA6B9B"}

package/dist/root-messenger-discovery.mjs

@@ -1,206 +0,0 @@
-import * as path from "node:path";
-import { Node as NodeGuards, Project, ts } from "ts-morph";
-import { classifyMessengerCapabilityTypeDeclaration, extractFromMessengerCapabilityTypeDeclaration } from "./extraction.mjs";
-/**
- * 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 function parseRootTypeReference(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 };
-}
-/**
- * Create a ts-morph Project for resolving root messenger types.
- *
- * No file list is loaded: this strategy opens only the entry files and lets
- * the checker pull in the rest.
- *
- * @returns A new ts-morph Project.
- */
-function createRootMessengerProject() {
-    return new Project({
-        compilerOptions: {
-            noEmit: true,
-            // We 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,
-            target: ts.ScriptTarget.ESNext,
-            module: ts.ModuleKind.ESNext,
-            moduleResolution: ts.ModuleResolutionKind.NodeJs,
-        },
-    });
-}
-/**
- * Resolve the type alias a reference names.
- *
- * @param project - The ts-morph project to load the file into.
- * @param projectPath - Absolute path to the project root.
- * @param reference - The reference to resolve.
- * @param flagName - The CLI flag the reference came from, used in errors.
- * @returns The type alias declaration.
- * @throws If the file can't be read or declares no such type alias.
- */
-function resolveRootDeclaration(project, projectPath, reference, flagName) {
-    const absolutePath = path.resolve(projectPath, reference.filePath);
-    let sourceFile;
-    try {
-        sourceFile =
-            project.getSourceFile(absolutePath) ??
-                project.addSourceFileAtPath(absolutePath);
-    }
-    catch {
-        throw new Error(`Could not read ${absolutePath}, which was named by ${flagName}.`);
-    }
-    const declaration = sourceFile.getTypeAlias(reference.typeName);
-    if (!declaration) {
-        throw new Error(`No type alias named "${reference.typeName}" in ${reference.filePath}, which was named by ${flagName}.`);
-    }
-    return declaration;
-}
-/**
- * Find the named declaration behind a union constituent.
- *
- * @param constituent - The resolved constituent type.
- * @param rootDeclaration - The root union's own declaration.
- * @param isLoneConstituent - Whether this is the root's only constituent.
- * @returns The declaration, or undefined when the constituent is anonymous.
- */
-function findCapabilityDeclaration(constituent, rootDeclaration, isLoneConstituent) {
-    // Prefer the alias symbol: for a type alias it carries the name and JSDoc,
-    // where the plain symbol points at the anonymous object type. Skip an alias
-    // resolving back to the root union itself, which is what the checker reports
-    // for a lone generic instantiation such as `type Actions = Foo<Bar>`.
-    const aliasDeclarations = (constituent.getAliasSymbol()?.getDeclarations() ?? []).filter((node) => node !== rootDeclaration);
-    // An interface has no alias symbol, being its own declaration.
-    const declarations = aliasDeclarations.length > 0
-        ? aliasDeclarations
-        : (constituent.getSymbol()?.getDeclarations() ?? []);
-    const found = declarations.find((node) => NodeGuards.isTypeAliasDeclaration(node) ||
-        NodeGuards.isInterfaceDeclaration(node));
-    if (found) {
-        return found;
-    }
-    // Nothing named behind the type itself. When the root aliases a single
-    // generic instantiation, the declaration we want is the one its type node
-    // references — `Foo` in `type Actions = Foo<Bar>`. Only when it is the lone
-    // constituent, though: in a union, an anonymous member is genuinely
-    // anonymous, and attributing it to the wrapper would mislabel it.
-    return isLoneConstituent
-        ? findDeclarationFromRootTypeNode(rootDeclaration)
-        : undefined;
-}
-/**
- * Resolve the declaration referenced by a root alias's type node.
- *
- * @param rootDeclaration - The root union's own declaration.
- * @returns The referenced declaration, or undefined.
- */
-function findDeclarationFromRootTypeNode(rootDeclaration) {
-    const typeNode = rootDeclaration.getTypeNode();
-    if (!typeNode || !NodeGuards.isTypeReference(typeNode)) {
-        return undefined;
-    }
-    const localSymbol = typeNode.getTypeName().getSymbol();
-    const symbol = localSymbol?.getAliasedSymbol() ?? localSymbol;
-    return symbol
-        ?.getDeclarations()
-        .find((node) => NodeGuards.isTypeAliasDeclaration(node) ||
-        NodeGuards.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;
-}
-/**
- * Extract every documentable capability from one root union.
- *
- * @param rootDeclaration - The root union's declaration.
- * @param kind - Whether these are actions or events.
- * @param projectPath - Absolute path to the project root.
- * @param skipped - Labels collected as undocumentable constituents are found.
- * @param reference - The reference that named this type, used in errors.
- * @param flagName - The CLI flag the reference came from, used in errors.
- * @returns The extracted capabilities.
- * @throws If the union resolved to `any` or `unknown`.
- */
-function extractFromRootType(rootDeclaration, kind, projectPath, skipped, reference, flagName) {
-    const rootType = rootDeclaration.getTypeNodeOrThrow().getType();
-    // TypeScript absorbs `any | T` into `any` and `unknown | T` into `unknown`,
-    // so a single member the checker can't resolve — typically a failed import —
-    // erases every other capability in the union. Fail instead of emitting a
-    // catalog that looks complete but silently isn't.
-    if (rootType.isAny() || rootType.isUnknown()) {
-        throw new Error(`${reference.filePath}#${reference.typeName}, named by ${flagName}, ` +
-            `resolved to \`${rootType.getText()}\` rather than a union of ` +
-            `capabilities. This usually means an import in that file could not be ` +
-            `resolved; because TypeScript absorbs the rest of a union into ` +
-            `\`any\`, every other capability in it would be missing.`);
-    }
-    // A project with no capabilities of this kind aliases the union to `never`.
-    if (rootType.isNever()) {
-        return [];
-    }
-    const constituents = rootType.isUnion()
-        ? rootType.getUnionTypes()
-        : [rootType];
-    const packets = [];
-    for (const constituent of constituents) {
-        const declaration = findCapabilityDeclaration(constituent, rootDeclaration, constituents.length === 1);
-        if (!declaration) {
-            skipped.unnamed.push(summarizeType(constituent, rootDeclaration));
-            continue;
-        }
-        const classified = classifyMessengerCapabilityTypeDeclaration(declaration, kind);
-        const packet = classified &&
-            extractFromMessengerCapabilityTypeDeclaration(classified, projectPath);
-        if (!packet) {
-            const sourceFile = declaration.getSourceFile().getFilePath();
-            skipped.unextractable.push(`${declaration.getName()} (${path.relative(projectPath, sourceFile)}:${declaration.getStartLineNumber()})`);
-            continue;
-        }
-        packets.push(packet);
-    }
-    return packets;
-}
-/**
- * Enumerate every action and event reachable from a project's root messenger.
- *
- * @param options - Discovery options.
- * @returns The extracted capabilities plus anything skipped.
- */
-export function discoverFromRootMessenger(options) {
-    const { projectPath, actions, events } = options;
-    const project = createRootMessengerProject();
-    const skipped = { unnamed: [], unextractable: [] };
-    const packets = [];
-    for (const [reference, kind, flagName] of [
-        [actions, 'action', '--root-actions'],
-        [events, 'event', '--root-events'],
-    ]) {
-        const rootDeclaration = resolveRootDeclaration(project, projectPath, reference, flagName);
-        packets.push(...extractFromRootType(rootDeclaration, kind, projectPath, skipped, reference, flagName));
-    }
-    return { packets, skipped };
-}
-//# sourceMappingURL=root-messenger-discovery.mjs.map

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, Project, ts } from 'ts-morph';\n\nimport {\n  classifyMessengerCapabilityTypeDeclaration,\n  extractFromMessengerCapabilityTypeDeclaration,\n} from './extraction.js';\nimport type { MessengerCapabilityPacket } from './types.js';\n\n// ---------------------------------------------------------------------------\n// The `root-messenger` strategy: resolve the unions a project declares for its\n// root messenger and let the type checker enumerate them. Going through the\n// checker rather than the AST means a union works whether it is written by\n// hand or computed (e.g. derived from a registry via `ReturnType<...>`). Each\n// capability it reports is handed to the shared extractor in `extraction.ts`,\n// so the output matches what the `scan` strategy produces.\n// ---------------------------------------------------------------------------\n\n/**\n * A reference to a type in a file, written as `<file>#<TypeName>`.\n */\nexport type RootTypeReference = {\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 * Options for {@link discoverFromRootMessenger}.\n */\ntype RootMessengerDiscoveryOptions = {\n  /** Absolute path to the project to scan. */\n  projectPath: string;\n  /** Type aliasing the union of every action on the root messenger. */\n  actions: RootTypeReference;\n  /** Type aliasing the union of every event on the root messenger. */\n  events: RootTypeReference;\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  /** Declared inline in the union, so there is no name or JSDoc to document. */\n  unnamed: string[];\n  /** Named, but of a shape the extractor rejects. */\n  unextractable: string[];\n};\n\n/**\n * The result of {@link discoverFromRootMessenger}.\n */\ntype RootMessengerDiscoveryResult = {\n  /** Every capability extracted, actions before events. */\n  packets: MessengerCapabilityPacket[];\n  /** Capabilities that couldn't be documented. */\n  skipped: SkippedCapabilities;\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 parseRootTypeReference(reference: string): RootTypeReference {\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 * Create a ts-morph Project for resolving root messenger types.\n *\n * No file list is loaded: this strategy opens only the entry files and lets\n * the checker pull in the rest.\n *\n * @returns A new ts-morph Project.\n */\nfunction createRootMessengerProject(): TsMorphProject {\n  return new Project({\n    compilerOptions: {\n      noEmit: true,\n      // We need symbol resolution, not full typechecking, so a project's own\n      // strictness settings shouldn't be able to fail the docs build.\n      strict: false,\n      skipLibCheck: true,\n      target: ts.ScriptTarget.ESNext,\n      module: ts.ModuleKind.ESNext,\n      moduleResolution: ts.ModuleResolutionKind.NodeJs,\n    },\n  });\n}\n\n/**\n * Resolve the type alias a reference names.\n *\n * @param project - The ts-morph project to load the file into.\n * @param projectPath - Absolute path to the project root.\n * @param reference - The reference to resolve.\n * @param flagName - The CLI flag the reference came from, used in errors.\n * @returns The type alias declaration.\n * @throws If the file can't be read or declares no such type alias.\n */\nfunction resolveRootDeclaration(\n  project: TsMorphProject,\n  projectPath: string,\n  reference: RootTypeReference,\n  flagName: string,\n): TypeAliasDeclaration {\n  const absolutePath = path.resolve(projectPath, reference.filePath);\n\n  let sourceFile;\n  try {\n    sourceFile =\n      project.getSourceFile(absolutePath) ??\n      project.addSourceFileAtPath(absolutePath);\n  } catch {\n    throw new Error(\n      `Could not read ${absolutePath}, which was named by ${flagName}.`,\n    );\n  }\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 ${flagName}.`,\n    );\n  }\n\n  return declaration;\n}\n\n/**\n * Find the named declaration behind a union constituent.\n *\n * @param constituent - The resolved constituent type.\n * @param rootDeclaration - The root union's own declaration.\n * @param isLoneConstituent - Whether this is the root's only constituent.\n * @returns The declaration, or undefined when the constituent is anonymous.\n */\nfunction findCapabilityDeclaration(\n  constituent: Type,\n  rootDeclaration: TypeAliasDeclaration,\n  isLoneConstituent: boolean,\n): TypeAliasDeclaration | InterfaceDeclaration | undefined {\n  // Prefer the alias symbol: for a type alias it carries the name and JSDoc,\n  // where the plain symbol points at the anonymous object type. Skip an alias\n  // resolving back to the root union itself, which is what the checker reports\n  // for a lone generic instantiation such as `type Actions = Foo<Bar>`.\n  const aliasDeclarations = (\n    constituent.getAliasSymbol()?.getDeclarations() ?? []\n  ).filter((node) => node !== rootDeclaration);\n\n  // An interface has no alias symbol, being its own declaration.\n  const declarations =\n    aliasDeclarations.length > 0\n      ? aliasDeclarations\n      : (constituent.getSymbol()?.getDeclarations() ?? []);\n\n  const found = declarations.find(\n    (node): node is TypeAliasDeclaration | InterfaceDeclaration =>\n      NodeGuards.isTypeAliasDeclaration(node) ||\n      NodeGuards.isInterfaceDeclaration(node),\n  );\n  if (found) {\n    return found;\n  }\n\n  // Nothing named behind the type itself. When the root aliases a single\n  // generic instantiation, the declaration we want is the one its type node\n  // references — `Foo` in `type Actions = Foo<Bar>`. Only when it is the lone\n  // constituent, though: in a union, an anonymous member is genuinely\n  // anonymous, and attributing it to the wrapper would mislabel it.\n  return isLoneConstituent\n    ? findDeclarationFromRootTypeNode(rootDeclaration)\n    : undefined;\n}\n\n/**\n * Resolve the declaration referenced by a root alias's type node.\n *\n * @param rootDeclaration - The root union's own declaration.\n * @returns The referenced declaration, or undefined.\n */\nfunction findDeclarationFromRootTypeNode(\n  rootDeclaration: TypeAliasDeclaration,\n): TypeAliasDeclaration | InterfaceDeclaration | undefined {\n  const typeNode = rootDeclaration.getTypeNode();\n  if (!typeNode || !NodeGuards.isTypeReference(typeNode)) {\n    return undefined;\n  }\n\n  const localSymbol = typeNode.getTypeName().getSymbol();\n  const symbol = localSymbol?.getAliasedSymbol() ?? localSymbol;\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 * Extract every documentable capability from one root union.\n *\n * @param rootDeclaration - The root union's declaration.\n * @param kind - Whether these are actions or events.\n * @param projectPath - Absolute path to the project root.\n * @param skipped - Labels collected as undocumentable constituents are found.\n * @param reference - The reference that named this type, used in errors.\n * @param flagName - The CLI flag the reference came from, used in errors.\n * @returns The extracted capabilities.\n * @throws If the union resolved to `any` or `unknown`.\n */\nfunction extractFromRootType(\n  rootDeclaration: TypeAliasDeclaration,\n  kind: 'action' | 'event',\n  projectPath: string,\n  skipped: SkippedCapabilities,\n  reference: RootTypeReference,\n  flagName: string,\n): MessengerCapabilityPacket[] {\n  const rootType = rootDeclaration.getTypeNodeOrThrow().getType();\n\n  // TypeScript absorbs `any | T` into `any` and `unknown | T` into `unknown`,\n  // so a single member the checker can't resolve — typically a failed import —\n  // erases every other capability in the union. Fail instead of emitting a\n  // catalog that looks complete but silently isn't.\n  if (rootType.isAny() || rootType.isUnknown()) {\n    throw new Error(\n      `${reference.filePath}#${reference.typeName}, named by ${flagName}, ` +\n        `resolved to \\`${rootType.getText()}\\` rather than a union of ` +\n        `capabilities. This usually means an import in that file could not be ` +\n        `resolved; because TypeScript absorbs the rest of a union into ` +\n        `\\`any\\`, every other capability in it would be missing.`,\n    );\n  }\n\n  // A project with no capabilities of this kind aliases the union to `never`.\n  if (rootType.isNever()) {\n    return [];\n  }\n\n  const constituents = rootType.isUnion()\n    ? rootType.getUnionTypes()\n    : [rootType];\n  const packets: MessengerCapabilityPacket[] = [];\n\n  for (const constituent of constituents) {\n    const declaration = findCapabilityDeclaration(\n      constituent,\n      rootDeclaration,\n      constituents.length === 1,\n    );\n    if (!declaration) {\n      skipped.unnamed.push(summarizeType(constituent, rootDeclaration));\n      continue;\n    }\n\n    const classified = classifyMessengerCapabilityTypeDeclaration(\n      declaration,\n      kind,\n    );\n    const packet =\n      classified &&\n      extractFromMessengerCapabilityTypeDeclaration(classified, projectPath);\n    if (!packet) {\n      const sourceFile = declaration.getSourceFile().getFilePath();\n      skipped.unextractable.push(\n        `${declaration.getName()} (${path.relative(projectPath, sourceFile)}:${declaration.getStartLineNumber()})`,\n      );\n      continue;\n    }\n\n    packets.push(packet);\n  }\n\n  return packets;\n}\n\n/**\n * Enumerate every action and event reachable from a project's root messenger.\n *\n * @param options - Discovery options.\n * @returns The extracted capabilities plus anything skipped.\n */\nexport function discoverFromRootMessenger(\n  options: RootMessengerDiscoveryOptions,\n): RootMessengerDiscoveryResult {\n  const { projectPath, actions, events } = options;\n  const project = createRootMessengerProject();\n  const skipped: SkippedCapabilities = { unnamed: [], unextractable: [] };\n  const packets: MessengerCapabilityPacket[] = [];\n\n  for (const [reference, kind, flagName] of [\n    [actions, 'action', '--root-actions'],\n    [events, 'event', '--root-events'],\n  ] as const) {\n    const rootDeclaration = resolveRootDeclaration(\n      project,\n      projectPath,\n      reference,\n      flagName,\n    );\n    packets.push(\n      ...extractFromRootType(\n        rootDeclaration,\n        kind,\n        projectPath,\n        skipped,\n        reference,\n        flagName,\n      ),\n    );\n  }\n\n  return { packets, skipped };\n}\n"]}