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

package/dist/extraction.mjs

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