feat: extract generic types and nullable information as separate fields (#88)

Author: just-boris

fixtures/test-utils/advanced-types/index.ts

@@ -8,6 +8,10 @@ export class TestUtilWrapper {
     return [];
   }
 
+  findSomething(): TestUtilWrapper | null {
+    return Math.random() > 0.5 ? new TestUtilWrapper() : null;
+  }
+
   /**
    * Generic arguments
    */

fixtures/test-utils/exports/cards.ts

@@ -0,0 +1,20 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { ElementWrapper } from './core';
+
+class CardWrapper extends ElementWrapper {
+  findHeader() {
+    return new ElementWrapper();
+  }
+
+  findContent() {
+    return new ElementWrapper();
+  }
+}
+
+export class CardsWrapper extends ElementWrapper {
+  findItems() {
+    return [new CardWrapper(), new CardWrapper()];
+  }
+}

fixtures/test-utils/exports/index.ts

@@ -2,3 +2,4 @@
 // SPDX-License-Identifier: Apache-2.0
 export { AlertWrapper } from './alert';
 export { ButtonWrapper } from './button';
+export { CardsWrapper } from './cards';

src/components/type-utils.ts

@@ -10,6 +10,13 @@ export function isOptional(type: ts.Type) {
   return !!type.types.find(t => t.flags & ts.TypeFlags.Undefined);
 }
 
+export function isNullable(type: ts.Type) {
+  if (!type.isUnionOrIntersection()) {
+    return false;
+  }
+  return !!type.types.find(t => t.flags & ts.TypeFlags.Null);
+}
+
 export function unwrapNamespaceDeclaration(declaration: ts.Declaration | undefined) {
   if (!declaration) {
     return [];
@@ -114,3 +121,16 @@ export function printFlags(flags: number, mapping: Record<number, string>) {
     .map(([key, value]) => value)
     .join(' | ');
 }
+
+export function extractTypeArguments(type: ts.Type, checker: ts.TypeChecker) {
+  const typeParameters = checker.getTypeArguments(type as ts.TypeReference);
+
+  if (typeParameters.length <= 0) {
+    return { typeName: stringifyType(type, checker) };
+  }
+  const symbol = type.getSymbol();
+  if (!symbol) {
+    throw new Error(`Unknown generic type without symbol: ${stringifyType(type, checker)}`);
+  }
+  return { typeParameters, typeName: symbol.getName() };
+}

src/test-utils-new/extractor.ts

@@ -1,8 +1,15 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 import ts from 'typescript';
-import { extractDeclaration, getDescription, isOptional, stringifyType } from '../components/type-utils';
-import { TestUtilsDoc } from '../test-utils/interfaces';
+import {
+  extractDeclaration,
+  extractTypeArguments,
+  getDescription,
+  isNullable,
+  isOptional,
+  stringifyType,
+} from '../components/type-utils';
+import { TestUtilsDoc } from './interfaces';
 
 function getInheritedFrom(declaration: ts.Declaration, currentClassName: string) {
   if (!ts.isMethodDeclaration(declaration) || !ts.isClassDeclaration(declaration.parent) || !declaration.parent.name) {
@@ -63,12 +70,23 @@ export default function extractDocumentation(
         continue;
       }
       const type = checker.getTypeAtLocation(declaration);
+      // report each function signature as a separate method
       for (const signature of type.getCallSignatures()) {
-        // report each function signature as a separate method
+        const returnType = signature.getReturnType();
+        // non-nullable type of `void` is `never`
+        const realReturnType = returnType.flags & ts.TypeFlags.Void ? returnType : returnType.getNonNullableType();
+        const { typeName, typeParameters } = extractTypeArguments(realReturnType, checker);
+
         classDefinition.methods.push({
           name: property.getName(),
           description: getDescription(property.getDocumentationComment(checker), declaration).text,
-          returnType: { name: stringifyType(signature.getReturnType(), checker) },
+          returnType: {
+            name: typeName,
+            isNullable: isNullable(returnType),
+            typeArguments: typeParameters?.map(typeArgument => ({
+              name: stringifyType(typeArgument, checker),
+            })),
+          },
           parameters: signature.parameters.map(parameter => {
             const paramType = checker.getTypeAtLocation(extractDeclaration(parameter));
             return {

src/test-utils-new/index.ts

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import pathe from 'pathe';
 import { bootstrapTypescriptProject } from '../bootstrap/typescript';
 import extractDocumentation from './extractor';
-import { TestUtilsDoc } from '../test-utils/interfaces';
+import { TestUtilsDoc } from './interfaces';
 
 export interface TestUtilsVariantOptions {
   root: string;

src/test-utils-new/interfaces.ts

@@ -8,11 +8,17 @@ export interface Parameter {
   defaultValue?: string;
 }
 
+interface TypeArgument {
+  name: string;
+}
+
 export interface TestUtilMethod {
   name: string;
   description?: string;
   returnType?: {
     name: string;
+    isNullable: boolean;
+    typeArguments?: Array<TypeArgument>;
   };
   parameters: Array<Parameter>;
   inheritedFrom?: {

test/test-utils/__snapshots__/doc-generation.test.ts.snap

@@ -22,7 +22,24 @@ exports[`Generate documentation > deal with more complex types 1`] = `
     "name": "findAll",
     "parameters": [],
     "returnType": {
-      "name": "Array<HTMLElement>",
+      "isNullable": false,
+      "name": "Array",
+      "typeArguments": [
+        {
+          "name": "HTMLElement",
+        },
+      ],
+    },
+  },
+  {
+    "description": undefined,
+    "inheritedFrom": undefined,
+    "name": "findSomething",
+    "parameters": [],
+    "returnType": {
+      "isNullable": true,
+      "name": "TestUtilWrapper",
+      "typeArguments": undefined,
     },
   },
   {
@@ -41,7 +58,9 @@ exports[`Generate documentation > deal with more complex types 1`] = `
       },
     ],
     "returnType": {
+      "isNullable": false,
       "name": "void",
+      "typeArguments": undefined,
     },
   },
   {
@@ -60,7 +79,9 @@ exports[`Generate documentation > deal with more complex types 1`] = `
       },
     ],
     "returnType": {
+      "isNullable": false,
       "name": "void",
+      "typeArguments": undefined,
     },
   },
   {
@@ -79,7 +100,9 @@ exports[`Generate documentation > deal with more complex types 1`] = `
       },
     ],
     "returnType": {
+      "isNullable": false,
       "name": "void",
+      "typeArguments": undefined,
     },
   },
 ]

test/test-utils/doc-generation.test.ts

@@ -19,14 +19,14 @@ describe('Generate documentation', () => {
 
     const noOpMethod = methods.find(method => method.name === 'noOp');
     expect(noOpMethod).toBeDefined();
-    expect(noOpMethod?.returnType).toEqual({ name: 'void' });
+    expect(noOpMethod?.returnType).toEqual({ name: 'void', isNullable: false });
     expect(noOpMethod?.parameters).toEqual([]);
     expect(noOpMethod?.description).toBeUndefined();
     expect(noOpMethod?.inheritedFrom).toBeUndefined();
 
     const findStringMethod = methods.find(method => method.name === 'findString');
     expect(findStringMethod).toBeDefined();
-    expect(findStringMethod?.returnType).toEqual({ name: 'string' });
+    expect(findStringMethod?.returnType).toEqual({ name: 'string', isNullable: false });
     expect(findStringMethod?.parameters).toEqual([]);
     expect(findStringMethod?.description).toBe(
       'Finds a string.\n\nThe function may look trivial but people have been losing their words\nsince centuries.'
@@ -35,14 +35,14 @@ describe('Generate documentation', () => {
 
     const setStringMethod = methods.find(method => method.name === 'setString');
     expect(setStringMethod).toBeDefined();
-    expect(setStringMethod?.returnType).toEqual({ name: 'void' });
+    expect(setStringMethod?.returnType).toEqual({ name: 'void', isNullable: false });
     expect(setStringMethod?.parameters).toMatchSnapshot();
     expect(setStringMethod?.description).toBe('Short Text');
     expect(setStringMethod?.inheritedFrom).toBeUndefined();
 
     const findObjectMethod = methods.find(method => method.name === 'findObject');
     expect(findObjectMethod).toBeDefined();
-    expect(findObjectMethod?.returnType).toEqual({ name: 'TestReturnType' });
+    expect(findObjectMethod?.returnType).toEqual({ name: 'TestReturnType', isNullable: false });
     expect(findObjectMethod?.parameters).toEqual([]);
     expect(findObjectMethod?.description).toBe('Short Text.\n\nLong Text.');
     expect(findObjectMethod?.inheritedFrom).toBeUndefined();
@@ -57,7 +57,7 @@ describe('Generate documentation', () => {
     expect(classDoc.name).toBe('TestUtilWrapper');
 
     const methods = classDoc.methods;
-    expect(methods.length).toBe(4);
+    expect(methods.length).toBe(5);
     expect(methods).toMatchSnapshot();
   });
 
@@ -85,11 +85,13 @@ describe('Generate documentation', () => {
 
   test('deal with re-exports', () => {
     const results = buildTestUtilsProject('exports');
-    expect(results.map(classDoc => classDoc.name)).toEqual(['AlertWrapper', 'ButtonWrapper']);
+    expect(results.map(classDoc => classDoc.name)).toEqual(['AlertWrapper', 'ButtonWrapper', 'CardsWrapper']);
     const alertWrapper = results.find(classDoc => classDoc.name === 'AlertWrapper')!;
     expect(alertWrapper.methods.map(method => method.name)).toEqual(['findContent']);
     const buttonWrapper = results.find(classDoc => classDoc.name === 'ButtonWrapper')!;
     expect(buttonWrapper.methods.map(method => method.name)).toEqual(['findText']);
+    const cardsWrapper = results.find(classDoc => classDoc.name === 'CardsWrapper')!;
+    expect(cardsWrapper.methods.map(method => method.name)).toEqual(['findItems']);
   });
 
   test('default value rendering', () => {
@@ -110,7 +112,7 @@ describe('Generate documentation', () => {
             defaultValue: "'first'",
           },
         ],
-        returnType: { name: 'void' },
+        returnType: { name: 'void', isNullable: false },
       },
       {
         name: 'openDropdown',
@@ -122,7 +124,7 @@ describe('Generate documentation', () => {
             defaultValue: 'false',
           },
         ],
-        returnType: { name: 'void' },
+        returnType: { name: 'void', isNullable: false },
       },
       {
         name: 'selectOption',
@@ -134,7 +136,7 @@ describe('Generate documentation', () => {
             defaultValue: '1',
           },
         ],
-        returnType: { name: 'void' },
+        returnType: { name: 'void', isNullable: false },
       },
     ]);
   });

test/test-utils/test-helpers.ts

@@ -1,7 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 import { documentTestUtilsNew, TestUtilsVariantOptions } from '../../src/test-utils-new';
-import { TestUtilsDoc } from '../../src/test-utils/interfaces';
+import { TestUtilsDoc } from '../../src/test-utils-new/interfaces';
 
 export function buildTestUtilsProject(
   name: string,