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

package/dist/extraction.cjs

@@ -1,754 +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.extractFromSourceFile = exports.extractFromMessengerCapabilityTypeDeclaration = exports.classifyMessengerCapabilityTypeDeclaration = void 0;
-const path = __importStar(require("node:path"));
-const ts_morph_1 = require("ts-morph");
-// ---------------------------------------------------------------------------
-// NOTE: `ts-morph` is used heavily in this file to parse and extract
-// information from TypeScript files. Although this library is not well
-// documented, it wraps the TypeScript AST fairly well, and you can get a good
-// sense of the AST by using this website: <https://ts-ast-viewer.com>
-// ---------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
-// JSDoc utilities
-// ---------------------------------------------------------------------------
-/**
- * Convert `{@link X}` references inside a JSDoc comment string to plain
- * backtick code spans and escape any remaining (out-of-backtick) curly braces.
- * This way the output is safe to render in a MDX document.
- *
- * @param text - The raw text to normalize.
- * @returns The text with `@link` resolved and stray braces escaped.
- */
-function escapeJsDocTextForMdx(text) {
-    const withLinksResolved = text.replace(/\{@link\s+([^}]+)\}/gu, '`$1`');
-    // Escape the characters MDX reads as syntax rather than text: `{` and `}`
-    // open an expression, and `<` opens a JSX tag — so an unescaped return type
-    // like `Promise<Foo[]>` fails the site build. Content already inside a code
-    // span is left alone.
-    return withLinksResolved.replace(/`[^`]*`|([{}<])/gu, (match, special) => special === undefined ? match : `\\${special}`);
-}
-/**
- * Extract the comment text of a JSDoc tag — the part that comes after the tag
- * and any identifier, e.g. "Some param" in "@param foo Some param" —
- * normalizing whitespace to a single space so we can better control how it's
- * rendered within the site.
- *
- * @param tag - The JSDoc tag.
- * @returns The flattened comment text.
- */
-function extractJsDocTagComment(tag) {
-    return (tag.getCommentText() ?? '').replace(/\s+/gu, ' ').trim();
-}
-/**
- * Strip the conventional `- ` separator from the start of a `@param` tag's
- * comment.
- *
- * @param comment - The flattened comment text from a `@param` tag.
- * @returns The comment with any leading `- ` (or `– `, `— `) removed.
- */
-function stripJsDocParamSeparator(comment) {
-    return comment.replace(/^[-–—]\s*/u, '');
-}
-/**
- * Extract JSDoc from a TypeScript AST node and decompose it into the parts we
- * need to render docs:
- *
- * - `description` — the body above the first tag, with `@deprecated` comments
- *   appended as `**Deprecated:** <comment>` lines and normalized for MDX
- *   (curly braces escaped, `{@link}` resolved),
- * - `params` — every `@param` tag in source order, with name and description,
- * - `returns` — the `@returns` tag's comment, or empty string if absent.
- *
- * Other tags (`@see`, `@throws`, `@template`, `@example`) are dropped.
- *
- * @param node - The AST node to extract JSDoc from (e.g. a type or a method).
- * @returns The decomposed JSDoc; empty strings/arrays when the node has no JSDoc.
- */
-function extractJsDoc(node) {
-    const jsDocs = node.getJsDocs();
-    if (jsDocs.length === 0) {
-        return { description: '', params: [], returns: '' };
-    }
-    const jsDoc = jsDocs[0];
-    const descriptionBody = jsDoc.getDescription().trim();
-    const deprecatedLines = [];
-    const params = [];
-    let returns = '';
-    for (const tag of jsDoc.getTags()) {
-        const tagName = tag.getTagName();
-        if (tagName === 'deprecated') {
-            const comment = extractJsDocTagComment(tag);
-            deprecatedLines.push(comment ? `**Deprecated:** ${comment}` : '**Deprecated:**');
-        }
-        else if (tagName === 'param' && ts_morph_1.Node.isJSDocParameterTag(tag)) {
-            const nameNode = tag.getNameNode();
-            const paramName = nameNode.getText();
-            if (!paramName) {
-                continue;
-            }
-            const comment = extractJsDocTagComment(tag);
-            params.push({
-                name: paramName,
-                description: escapeJsDocTextForMdx(stripJsDocParamSeparator(comment)),
-            });
-        }
-        else if (tagName === 'returns' || tagName === 'return') {
-            const comment = extractJsDocTagComment(tag);
-            returns = escapeJsDocTextForMdx(comment);
-        }
-    }
-    const description = escapeJsDocTextForMdx([descriptionBody, ...deprecatedLines]
-        .filter((line) => line.length > 0)
-        .join('\n'));
-    return { description, params, returns };
-}
-/**
- * Check whether a node has an `@deprecated` JSDoc tag.
- *
- * @param node - The AST node to check.
- * @returns True if the node has an `@deprecated` tag.
- */
-function hasDeprecatedJsDocTag(node) {
-    return node
-        .getJsDocs()
-        .flatMap((jsDoc) => jsDoc.getTags())
-        .some((tag) => tag.getTagName() === 'deprecated');
-}
-// ---------------------------------------------------------------------------
-// Type-resolution helpers (powered by ts-morph's type checker)
-// ---------------------------------------------------------------------------
-/**
- * Locates the type that represents a method on a class (e.g.
- * `Class['method']`), which itself comes from a messenger action handler.
- *
- * @param typeNode - The node that represents the indexed access.
- * @returns The found method declaration, or null.
- */
-function findClassMethodDeclaration(typeNode) {
-    // Fundamental check: if we don't have `Class['method']`, we can't do anything.
-    if (!ts_morph_1.Node.isIndexedAccessTypeNode(typeNode)) {
-        return null;
-    }
-    // The type that represents the class being accessed.
-    // EXAMPLE:
-    //   FooController['someMethod']
-    //   ^^^^^^^^^^^^^
-    const objectType = typeNode.getObjectTypeNode();
-    // The type that represents the property being accessed.
-    // EXAMPLE:
-    //   FooController['someMethod']
-    //                 ^^^^^^^^^^^^
-    const indexType = typeNode.getIndexTypeNode();
-    // To access a property on a type, it must be a type we can access properties of.
-    if (!ts_morph_1.Node.isTypeReference(objectType) ||
-        !ts_morph_1.Node.isLiteralTypeNode(indexType)) {
-        return null;
-    }
-    const indexLiteral = indexType.getLiteral();
-    // Names of methods must be static strings; they cannot be template strings.
-    if (!ts_morph_1.Node.isStringLiteral(indexLiteral) &&
-        !ts_morph_1.Node.isNoSubstitutionTemplateLiteral(indexLiteral)) {
-        return null;
-    }
-    const methodName = indexLiteral.getLiteralValue();
-    // Reject qualified-name type names, as we need a plain identifier to
-    // resolve the symbol.
-    // EXAMPLE:
-    //   import * as somePackage from '....js';
-    //   somePackage.FooController['someMethod']
-    //   ^^^^^^^^^^^^^^^^^^^^^^^^^
-    const classNameNode = objectType.getTypeName();
-    if (!ts_morph_1.Node.isIdentifier(classNameNode)) {
-        return null;
-    }
-    // Since we know we have a type reference, we can assume that we have a symbol.
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const localSymbol = classNameNode.getSymbol();
-    // If we have a type imported from another file, ensure that when we access
-    // the declaration, it's the type declaration in the other file, not the
-    // import declaration in this file.
-    // EXAMPLE:
-    //   import { FooController } from '@metamask/foo-controller';
-    //   FooController['someMethod']
-    //   ^^^^^^^^^^^^^
-    const symbol = localSymbol.getAliasedSymbol() ?? localSymbol;
-    for (const declaration of symbol.getDeclarations()) {
-        // We must have a class to treat the property on the object type as a
-        // method.
-        if (ts_morph_1.Node.isClassDeclaration(declaration)) {
-            const method = declaration.getMethod(methodName);
-            if (method) {
-                return method;
-            }
-        }
-    }
-    return null;
-}
-// ---------------------------------------------------------------------------
-// Method info
-// ---------------------------------------------------------------------------
-/**
- * Build the textual signature of a class method — its parameter list and
- * return type expressed as a TypeScript function type — so a handler that
- * references `Class['method']` can be rendered as `(arg: T) => R` instead of
- * the bare indexed-access syntax.
- *
- * @param method - The method declaration.
- * @returns The signature, e.g. `(id: number) => Promise<string>`.
- */
-function buildMethodSignature(method) {
-    const signatureParams = method
-        .getParameters()
-        .map((param) => {
-        const rest = param.isRestParameter() ? '...' : '';
-        const paramName = param.getNameNode().getText();
-        const optional = param.hasQuestionToken() ? '?' : '';
-        const typeNode = param.getTypeNode();
-        const paramType = typeNode ? typeNode.getText() : 'unknown';
-        return `${rest}${paramName}${optional}: ${paramType}`;
-    })
-        .join(', ');
-    const returnTypeNode = method.getReturnTypeNode();
-    const returnType = returnTypeNode ? returnTypeNode.getText() : 'void';
-    // For async methods, the declared return type already includes `Promise<>`,
-    // so we don't need to wrap again.
-    return `(${signatureParams}) => ${returnType}`;
-}
-/**
- * Tag a capability type declaration with the body shape it has, so the right
- * extractor can read it: 'constructor' for a capability-type-constructor
- * invocation such as `ControllerGetStateAction<...>`, 'object' otherwise.
- *
- * Callers must resolve unions and bare type references first, so that the
- * declaration reaching here is a leaf.
- *
- * @param declaration - The type alias or interface to classify.
- * @param kind - Whether to tag the declaration as 'action' or 'event'.
- * @returns The tagged declaration, or null for a qualified-name reference.
- */
-function classifyMessengerCapabilityTypeDeclaration(declaration, kind) {
-    // Interfaces always carry their members directly.
-    // EXAMPLE:
-    //   interface FooControllerSomeAction { ... }
-    if (ts_morph_1.Node.isInterfaceDeclaration(declaration)) {
-        return { bodyShape: 'object', kind, declaration };
-    }
-    const body = declaration.getTypeNode();
-    // A TypeReference body is a capability-type-constructor invocation (e.g.
-    // `ControllerGetStateAction<typeof name, State>`). Tag it so the constructor
-    // extractor can read `body` directly without re-checking its shape.
-    // EXAMPLE:
-    //   type FooControllerSomeAction = ControllerGetStateAction<...>
-    //                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    if (body && ts_morph_1.Node.isTypeReference(body)) {
-        // Reject qualified-name constructor type names, as we need a plain
-        // identifier to match the constructor by name.
-        // EXAMPLE:
-        //   import * as somePackage from '....js';
-        //   type FooControllerSomeAction = somePackage.ControllerGetStateAction<...>
-        //                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-        const constructorTypeName = body.getTypeName();
-        if (!ts_morph_1.Node.isIdentifier(constructorTypeName)) {
-            return null;
-        }
-        return {
-            bodyShape: 'constructor',
-            kind,
-            declaration,
-            body,
-            typeName: constructorTypeName,
-        };
-    }
-    // Anything else (a type literal, intersection, conditional, …) goes to the
-    // literal extractor, which knows how to read members off a type literal and
-    // rejects exotic shapes.
-    // EXAMPLE:
-    //   type FooControllerSomeAction = { ... }
-    //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    return { bodyShape: 'object', kind, declaration };
-}
-exports.classifyMessengerCapabilityTypeDeclaration = classifyMessengerCapabilityTypeDeclaration;
-/**
- * Looks for Messenger types in the source file (that is, those that are type
- * aliases whose names end with "Messenger"), then extracts the `Actions` and
- * `Events` parameters from these types.
- *
- * @param sourceFile - The TypeScript source file to scan.
- * @returns A list of objects that represent messenger types.
- */
-function findMessengerTypeAliases(sourceFile) {
-    const parsedMessengerTypeAliases = [];
-    for (const typeAlias of sourceFile.getTypeAliases()) {
-        if (!typeAlias.getName().endsWith('Messenger')) {
-            continue;
-        }
-        const body = typeAlias.getTypeNode();
-        // Basic check
-        if (!body || !ts_morph_1.Node.isTypeReference(body)) {
-            continue;
-        }
-        const typeArgs = body.getTypeArguments();
-        // Messenger types always have 3 type parameters
-        // (e.g. `Messenger<'FooController', Actions, Events>`)
-        if (typeArgs.length < 3) {
-            continue;
-        }
-        parsedMessengerTypeAliases.push({
-            actionsTypeParameter: typeArgs[1],
-            eventsTypeParameter: typeArgs[2],
-        });
-    }
-    return parsedMessengerTypeAliases;
-}
-/**
- * Walks the `Actions` and `Events` type parameters of the given messenger
- * types, extracted in a previous step, to find all type declarations (i.e.,
- * statements) that represent individual messenger actions or events.
- *
- * @param parsedMessengerTypeAliases - The list of objects representing
- * messenger types, parsed in a previous step.
- * @returns The list of type aliases that represent messenger capabilities among
- * the given messenger types.
- */
-function findAllMessengerCapabilityTypeDeclarations(parsedMessengerTypeAliases) {
-    const allCapabilityTypeDeclarations = [];
-    let allVisitedTypeDeclarations = new Set();
-    for (const { actionsTypeParameter, eventsTypeParameter, } of parsedMessengerTypeAliases) {
-        for (const [typeParameter, kind] of [
-            [actionsTypeParameter, 'action'],
-            [eventsTypeParameter, 'event'],
-        ]) {
-            const result = recursivelyFindMessengerCapabilityTypeDeclarations(typeParameter, kind, allVisitedTypeDeclarations);
-            allCapabilityTypeDeclarations.push(...result.capabilityTypeDeclarations);
-            allVisitedTypeDeclarations = result.visitedTypeDeclarations;
-        }
-    }
-    return allCapabilityTypeDeclarations;
-}
-/**
- * Recursively walks a `ts-morph` AST node — at first the `Actions` or `Events`
- * type parameter of a messenger type, and then a node within that parameter —
- * to find all type aliases that represent individual messenger actions or
- * events, no matter how deeply the type aliases exist in the tree or in which
- * file they are located.
- *
- * @param node - The `ts-morph` AST node to walk.
- * @param kind - Whether to tag found type aliases as 'action' or 'event'.
- * @param visitedTypeDeclarations - A variable that tracks visited type aliases
- * and prevents duplicates.
- * @returns The list of extracted messenger capability type aliases as well as
- * an updated version of `visitedTypeDeclarations`.
- */
-function recursivelyFindMessengerCapabilityTypeDeclarations(node, kind, visitedTypeDeclarations) {
-    const result = {
-        capabilityTypeDeclarations: [],
-        visitedTypeDeclarations: new Set([...visitedTypeDeclarations]),
-    };
-    // If `node` is a union type, walk each type within it.
-    // EXAMPLES:
-    //   type Actions = FooControllerSomeAction | FooControllerSomeOtherAction
-    //                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    //   type FooControllerActions = FooControllerSomeAction | FooControllerSomeOtherAction
-    //                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    if (ts_morph_1.Node.isUnionTypeNode(node)) {
-        for (const typeNode of node.getTypeNodes()) {
-            const innerResult = recursivelyFindMessengerCapabilityTypeDeclarations(typeNode, kind, result.visitedTypeDeclarations);
-            result.capabilityTypeDeclarations.push(...innerResult.capabilityTypeDeclarations);
-            for (const typeDeclaration of innerResult.visitedTypeDeclarations) {
-                result.visitedTypeDeclarations.add(typeDeclaration);
-            }
-        }
-        return result;
-    }
-    // If `node` is not a type reference, don't walk it.
-    // EXAMPLE:
-    //   // Bad
-    //   type Actions = { ... }
-    //                  ^^^^^^^
-    //   // Good
-    //   type Actions = FooControllerSomeAction;
-    //                  ^^^^^^^^^^^^^^^^^^^^^^^
-    //   // Good
-    //   type Actions = ControllerGetStateAction<...>;
-    //                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    if (!ts_morph_1.Node.isTypeReference(node)) {
-        return result;
-    }
-    const nameNode = node.getTypeName();
-    // Reject qualified-name type names, as we need a plain identifier to
-    // resolve the symbol.
-    // EXAMPLE:
-    //   import * as somePackage from '....js';
-    //   type Actions = somePackage.FooControllerSomeAction;
-    //                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    if (!ts_morph_1.Node.isIdentifier(nameNode)) {
-        return result;
-    }
-    // Since we know we have a type reference, we can assume that we have a symbol.
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const localSymbol = nameNode.getSymbol();
-    // If we have a type imported from another file, ensure that when we access
-    // the declaration, it's the type declaration in the other file, not the
-    // import declaration in this file.
-    // EXAMPLE:
-    //   import { FooControllerSomeAction } from '@metamask/foo-controller';
-    //   type Actions = FooControllerSomeAction;
-    //                  ^^^^^^^^^^^^^^^^^^^^^^^
-    const symbol = localSymbol.getAliasedSymbol() ?? localSymbol;
-    // At this point, we have a type *reference*, but we need to find the type
-    // *declaration*.
-    // For instance, if we have `FooControllerSomeAction`, we need to find
-    // the full `type FooControllerSomeAction = ...` statement.
-    for (const declaration of symbol.getDeclarations()) {
-        // Prevent duplicates
-        if (result.visitedTypeDeclarations.has(declaration)) {
-            continue;
-        }
-        result.visitedTypeDeclarations.add(declaration);
-        // If we have a type alias, then we have to handle a few scenarios.
-        // EXAMPLES:
-        //   type FooControllerMethodActions = ...
-        //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-        //   type FooControllerSomeAction = ...
-        //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-        if (ts_morph_1.Node.isTypeAliasDeclaration(declaration)) {
-            const body = declaration.getTypeNode();
-            // If the body is a union type or a plain type reference (not a utility
-            // type), walk it.
-            // EXAMPLES:
-            //   type FooControllerMethodActions = FooControllerSomeAction | FooControllerSomeOtherAction
-            //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-            //   type DelegationControllerMethodActions = DelegationControllerSignDelegationAction
-            //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-            if (body &&
-                (ts_morph_1.Node.isUnionTypeNode(body) ||
-                    (ts_morph_1.Node.isTypeReference(body) &&
-                        body.getTypeArguments().length === 0))) {
-                const innerResult = recursivelyFindMessengerCapabilityTypeDeclarations(body, kind, result.visitedTypeDeclarations);
-                result.capabilityTypeDeclarations.push(...innerResult.capabilityTypeDeclarations);
-                for (const typeDeclaration of innerResult.visitedTypeDeclarations) {
-                    result.visitedTypeDeclarations.add(typeDeclaration);
-                }
-                continue;
-            }
-            // Everything else is a leaf capability type — a capability-type-
-            // constructor invocation (e.g. `ControllerGetStateAction<typeof name,
-            // State>`) or a literal object type. Tag it so the matching extractor
-            // can read it without re-checking its shape.
-            // EXAMPLES:
-            //   type FooControllerSomeAction = ControllerGetStateAction<...>
-            //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-            //   type FooControllerSomeAction = { ... }
-            //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-            const classified = classifyMessengerCapabilityTypeDeclaration(declaration, kind);
-            if (classified) {
-                result.capabilityTypeDeclarations.push(classified);
-            }
-        }
-        // Interfaces always carry their members directly — tag for the literal
-        // extractor.
-        // EXAMPLE:
-        //   interface FooControllerSomeAction { ... }
-        //   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-        else if (ts_morph_1.Node.isInterfaceDeclaration(declaration)) {
-            result.capabilityTypeDeclarations.push({
-                bodyShape: 'object',
-                kind,
-                declaration,
-            });
-        }
-    }
-    return result;
-}
-// ---------------------------------------------------------------------------
-// Per-statement extraction
-// ---------------------------------------------------------------------------
-/**
- * Given the declaration of a messenger capability type, extract information
- * about it (action/event type string, handler/payload arguments and return
- * type, etc.)
- *
- * @param capabilityTypeDeclaration - The statement that declared the type for a
- * messenger action or event, extracted in a previous step.
- * @param projectPath - Project root, used for computing relative source paths.
- * @returns Information that may be extracted from the messenger capability type
- * (may be `null` if the type is ineligible for extraction).
- */
-function extractFromMessengerCapabilityTypeDeclaration(capabilityTypeDeclaration, projectPath) {
-    if (capabilityTypeDeclaration.bodyShape === 'constructor') {
-        return tryToExtractFromCapabilityTypeConstructor(capabilityTypeDeclaration, projectPath);
-    }
-    return tryToExtractFromMessengerCapabilityTypeLiteral(capabilityTypeDeclaration, projectPath);
-}
-exports.extractFromMessengerCapabilityTypeDeclaration = extractFromMessengerCapabilityTypeDeclaration;
-/**
- * If a messenger capability type is a type alias or interface and its body is
- * a literal object type — i.e. one of:
- *
- * - `{ type: '...'; handler: ... }` (action)
- * - `{ type: '...'; payload: ... }` (event)
- *
- * then this function extracts information about the type (action/event type
- * string, handler/payload arguments and return type, etc.)
- *
- * @param capabilityTypeDeclaration - The statement that declared the type for a
- * messenger action or event, extracted in a previous step.
- * @param projectPath - Project root, used for computing relative source paths.
- * @returns The extracted capability packet, or null if the shape of the type
- * doesn't match.
- */
-function tryToExtractFromMessengerCapabilityTypeLiteral(capabilityTypeDeclaration, projectPath) {
-    const { declaration, kind } = capabilityTypeDeclaration;
-    // We must have a object type alias or an interface, and the body must not be empty.
-    // EXAMPLES:
-    //   // Good
-    //   type FooControllerSomeAction = {
-    //     type: 'FooController:getState';
-    //     handler: FooController['getState'];
-    //   }
-    //   // Good
-    //   interface FooControllerSomeAction {
-    //     type: 'FooController:getState';
-    //     handler: FooController['getState'];
-    //   }
-    //   // Bad
-    //   type FooControllerSomeAction = {};
-    //   // Bad
-    //   interface FooControllerSomeAction {};
-    let members;
-    if (ts_morph_1.Node.isTypeAliasDeclaration(declaration)) {
-        const body = declaration.getTypeNode();
-        if (body && ts_morph_1.Node.isTypeLiteral(body)) {
-            members = body.getMembers();
-        }
-    }
-    else {
-        members = declaration.getMembers();
-    }
-    if (!members) {
-        return null;
-    }
-    const propertySignatures = members.filter(ts_morph_1.Node.isPropertySignature.bind(ts_morph_1.Node));
-    // Actions and events must have a `type`, and it must be a string.
-    const typeString = getMessengerCapabilityTypeString(propertySignatures);
-    if (!typeString) {
-        return null;
-    }
-    // Actions must have a `handler`, and events must have a `payload`.
-    const handlerOrPayloadProperty = findProperty(propertySignatures, kind === 'action' ? 'handler' : 'payload');
-    if (!handlerOrPayloadProperty) {
-        return null;
-    }
-    const handlerOrPayloadPropertyTypeNode = 
-    // We can assume the property has a type; otherwise it wouldn't compile.
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    handlerOrPayloadProperty.getTypeNode();
-    let handlerOrPayloadSignature = handlerOrPayloadPropertyTypeNode
-        .getText()
-        .trim();
-    const { description: jsDoc, params, returns } = extractJsDoc(declaration);
-    // For actions that represent methods (e.g. `Class['method']`), walk the
-    // handler type to find the underlying handler signature
-    // (e.g. `(id: number) => Promise<string>`).
-    if (kind === 'action') {
-        const methodDeclaration = findClassMethodDeclaration(handlerOrPayloadPropertyTypeNode);
-        if (methodDeclaration) {
-            handlerOrPayloadSignature = buildMethodSignature(methodDeclaration);
-        }
-    }
-    const sourceFile = declaration.getSourceFile();
-    return {
-        typeName: declaration.getName(),
-        typeString,
-        kind,
-        jsDoc,
-        params,
-        returns,
-        handlerOrPayload: handlerOrPayloadSignature,
-        sourceFile: path.relative(projectPath, sourceFile.getFilePath()),
-        line: declaration.getStartLineNumber(),
-        deprecated: hasDeprecatedJsDocTag(declaration),
-    };
-}
-/**
- * Searches the property signatures of a messenger capability type alias or
- * interface to find the value of the `type` property, and then resolves it to a
- * string (assuming it is already a string or a resolvable template literal).
- *
- * @param capabilityTypeProperties - The property signatures of the messenger
- * capability type.
- * @returns The extracted capability type string, or null if `type` cannot be
- * found in the members or it is an unexpected node.
- */
-function getMessengerCapabilityTypeString(capabilityTypeProperties) {
-    const typeProperty = findProperty(capabilityTypeProperties, 'type');
-    if (!typeProperty) {
-        return null;
-    }
-    // A `type` property without an explicit type wouldn't compile.
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const typeNode = typeProperty.getTypeNode();
-    // Ask the type checker to resolve the value of `type`. We're looking for
-    // `type` to be either a string literal or template literal.
-    //
-    // EXAMPLES:
-    //   type FooControllerSomeAction = {
-    //     type: 'FooController:someAction';
-    //           ^^^^^^^^^^^^^^^^^^^^^^^^^^
-    //   }
-    //   type FooControllerSomeAction = {
-    //     type: `FooController:someAction`;
-    //           ^^^^^^^^^^^^^^^^^^^^^^^^^^
-    //   }
-    //   type FooControllerSomeAction = {
-    //     type: `${typeof CONTROLLER_NAME}:someAction`;
-    //           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    //   }
-    const resolvedType = typeNode.getType();
-    if (resolvedType.isStringLiteral()) {
-        // Type assertion: There aren't any type guards we can use to narrow this
-        // type further.
-        const literalValue = resolvedType.getLiteralValueOrThrow();
-        // Messenger action/event types need to be namespaced.
-        if (literalValue.includes(':')) {
-            return literalValue;
-        }
-    }
-    return null;
-}
-/**
- * Finds a specific property in a list of property signatures for an object
- * type.
- *
- * @param propertySignatures - The property signatures of the messenger
- * capability type.
- * @param name - The property name to find.
- * @returns The property signature, or null.
- */
-function findProperty(propertySignatures, name) {
-    for (const property of propertySignatures) {
-        const propertyNameNode = property.getNameNode();
-        if (!ts_morph_1.Node.isIdentifier(propertyNameNode) ||
-            propertyNameNode.getText() !== name) {
-            continue;
-        }
-        return property;
-    }
-    return null;
-}
-/**
- * If a messenger capability type is a type alias for either the
- * `ControllerGetStateAction` or `ControllerStateChangeEvent` type constructors,
- * then this function extracts information about the type (action/event type
- * string, handler/payload arguments and return type, etc.)
- *
- * @param capabilityTypeDeclaration - The statement that declared the type for a
- * messenger action or event, extracted in a previous step.
- * @param projectPath - Project root, used for computing relative source paths.
- * @returns The extracted capability packet, or null if the shape of the type
- * doesn't match.
- */
-function tryToExtractFromCapabilityTypeConstructor(capabilityTypeDeclaration, projectPath) {
-    const { declaration, kind, body, typeName } = capabilityTypeDeclaration;
-    // The name of the utility type should be either `ControllerGetStateAction`
-    // (for actions) or `ControllerStateChangeEvent` (for events).
-    // EXAMPLES:
-    //   type FooControllerSomeAction = ControllerGetStateAction<...>
-    //   type FooControllerSomeEvent = ControllerStateChangeEvent<...>
-    const expectedConstructor = kind === 'action'
-        ? 'ControllerGetStateAction'
-        : 'ControllerStateChangeEvent';
-    if (typeName.getText() !== expectedConstructor) {
-        return null;
-    }
-    // The utility type should take two parameters.
-    // EXAMPLES:
-    //   type FooControllerSomeAction = ControllerGetStateAction<..., ...>
-    //   type FooControllerSomeEvent = ControllerStateChangeEvent<..., ...>
-    const typeArgs = body.getTypeArguments();
-    if (typeArgs.length < 2) {
-        return null;
-    }
-    const namespaceArgType = typeArgs[0].getType();
-    // The first parameter should be a string literal.
-    // EXAMPLES:
-    //   type FooControllerSomeAction = ControllerGetStateAction<'FooController', ...>
-    //   type FooControllerSomeAction = ControllerGetStateAction<typeof CONTROLLER_NAME, ...>
-    if (!namespaceArgType.isStringLiteral()) {
-        return null;
-    }
-    // Type assertion: There aren't any type guards we can use to narrow this type
-    // further.
-    const namespace = namespaceArgType.getLiteralValueOrThrow();
-    const typeString = kind === 'action' ? `${namespace}:getState` : `${namespace}:stateChange`;
-    const stateArgText = typeArgs[1].getText();
-    const handlerOrPayload = kind === 'action' ? `() => ${stateArgText}` : `[${stateArgText}, Patch[]]`;
-    const { description, params, returns } = extractJsDoc(declaration);
-    const sourceFile = declaration.getSourceFile();
-    return {
-        typeName: declaration.getName(),
-        typeString,
-        kind,
-        jsDoc: description,
-        params,
-        returns,
-        handlerOrPayload,
-        sourceFile: path.relative(projectPath, sourceFile.getFilePath()),
-        line: declaration.getStartLineNumber(),
-        deprecated: hasDeprecatedJsDocTag(declaration),
-    };
-}
-// ---------------------------------------------------------------------------
-// Public entry points
-// ---------------------------------------------------------------------------
-/**
- * Extract information (action/event type string, handler/payload arguments and
- * return type, etc.) about every messenger action or event type which is
- * reachable through all of a source file's `*Messenger` type declarations.
- *
- * The caller is responsible for ensuring `sourceFile` (plus any files it
- * imports from) belongs to a `ts-morph` Project so cross-file symbol resolution
- * works.
- *
- * @param sourceFile - The TypeScript source file to extract from.
- * @param projectPath - Project root, used for computing relative source paths.
- * @returns The extracted information about actions and events.
- */
-function extractFromSourceFile(sourceFile, projectPath) {
-    const messengerTypeAliases = findMessengerTypeAliases(sourceFile);
-    const capabilityTypeDeclarations = findAllMessengerCapabilityTypeDeclarations(messengerTypeAliases);
-    const messengerCapabilityPackets = [];
-    for (const capabilityTypeDeclaration of capabilityTypeDeclarations) {
-        const messengerCapabilityPacket = extractFromMessengerCapabilityTypeDeclaration(capabilityTypeDeclaration, projectPath);
-        if (messengerCapabilityPacket) {
-            messengerCapabilityPackets.push(messengerCapabilityPacket);
-        }
-    }
-    return messengerCapabilityPackets;
-}
-exports.extractFromSourceFile = extractFromSourceFile;
-//# sourceMappingURL=extraction.cjs.map