@knapsack/spec-utils 4.78.13--canary.5646.9581069.0 → 4.78.13

package/src/analyze-symbol.ts

@@ -0,0 +1,213 @@
+import ts from 'typescript';
+import { analyzeType } from './analyze-type.js';
+import { SymbolInfo, TypeInfo } from './types.js';
+import { getSetFlags } from './utils.js';
+
+export function analyzeSymbol({
+  symbol,
+  checker,
+  symbolsVisited = new Set(),
+}: {
+  symbol: ts.Symbol;
+  checker: ts.TypeChecker;
+  /** use to prevent infinite recursion */
+  symbolsVisited?: Set<ts.Symbol>;
+}): SymbolInfo {
+  symbolsVisited.add(symbol);
+  const type = symbol.valueDeclaration
+    ? checker.getTypeOfSymbolAtLocation(symbol, symbol.valueDeclaration)
+    : checker.getTypeOfSymbol(symbol);
+  const description = ts.displayPartsToString(
+    symbol.getDocumentationComment(checker),
+  );
+  const jsDocTags = symbol.getJsDocTags().map(({ name, text }) => ({
+    name,
+    text: text ? ts.displayPartsToString(text) : undefined,
+  }));
+  const {
+    // Here in case a `Node` is needed
+    valueDeclaration: node,
+  } = symbol;
+
+  const symbolFlags = getSetFlags({
+    flags: symbol.flags,
+    enumObject: ts.SymbolFlags,
+  });
+  const typeFlags = getSetFlags({
+    flags: type.flags,
+    enumObject: ts.TypeFlags,
+  });
+  const isOptional = symbolFlags.includes('Optional');
+  const isArray = checker.isArrayType(type) || checker.isArrayLikeType(type);
+
+  // set in `if` blocks below
+  let typeInfo: TypeInfo;
+  const baseSymbolInfo: Omit<SymbolInfo, 'typeInfo'> = {
+    tsMetadata: {
+      symbol,
+      type,
+      symbolFlags,
+    },
+    jsDoc:
+      description || jsDocTags.length
+        ? {
+            description,
+            jsDocTags,
+          }
+        : undefined,
+    name: symbol.getName(),
+  };
+
+  // Data I have seen in debugger, but am not sure how to safely access:
+  // type.members - reliably indicates an "object" by providing a Map of Symbols of its properties. The check for Object below is not as reliable since everything in JS is an object.
+  // type.objectFlags - seems to indicate the type of the object, but not sure how to safely access it.
+
+  /**
+   * A function can have multiple call signatures - this is done when using "overloads", like this:
+   * ```ts
+   * export function sayHello(msg: string[]): string;
+   * export function sayHello(msg: string): string;
+   * export function sayHello(msg: unknown): string {
+   *   return `Hello ${Array.isArray(msg) ? msg.join(' ') : msg}`;
+   * }
+   * ```
+   *
+   * Handling that seems like too much (and doubtfully useful) so we only handle the first call signature.
+   */
+  const [callSignature] = type.getCallSignatures();
+  // consider using over `callSignature`
+  const _isFunction = symbolFlags.includes('Function');
+  // if it's callable, it's a function
+  if (callSignature) {
+    const returnType = callSignature.getReturnType();
+    const typeParameters = callSignature.getTypeParameters();
+    typeInfo = {
+      type: 'function',
+      parameters: callSignature.parameters
+        .filter((paramSymbol) => !symbolsVisited.has(paramSymbol))
+        .map((paramSymbol) => {
+          return analyzeSymbol({
+            symbol: paramSymbol,
+            checker,
+            symbolsVisited,
+          });
+        }),
+      typeParameters: typeParameters?.map((typeParameter) => {
+        return analyzeType({ type: typeParameter, checker });
+      }),
+      // returnType: returnType
+      //   ? analyzeType({ type: returnType, checker })
+      //   : undefined,
+      returnType: analyzeType({ type: returnType, checker }),
+      tsRawType: checker.typeToString(
+        type,
+        node, // remove if it looks weird
+        ts.TypeFormatFlags.NoTruncation,
+      ),
+      isOptional,
+      tsMetadata: {
+        typeFlags: getSetFlags({
+          flags: type.flags,
+          enumObject: ts.TypeFlags,
+        }),
+        type,
+      },
+    };
+  } else if (symbolFlags.includes('Class')) {
+    const [constructSignature] = type.getConstructSignatures();
+    const prototype = type.getProperty('prototype');
+    if (!prototype) {
+      throw new Error(`${symbol.getName()} has no prototype`);
+    }
+    typeInfo = {
+      type: 'class',
+      tsRawType: checker.typeToString(
+        type,
+        undefined,
+        ts.TypeFormatFlags.NoTruncation,
+      ),
+      isOptional,
+      tsMetadata: {
+        typeFlags: getSetFlags({
+          flags: type.flags,
+          enumObject: ts.TypeFlags,
+        }),
+        type,
+      },
+      prototype: analyzeSymbol({
+        symbol: prototype,
+        checker,
+        symbolsVisited,
+      }),
+      properties: type.getProperties().reduce((acc, propSymbol) => {
+        if (symbolsVisited.has(propSymbol)) return acc;
+        const symbolInfo = analyzeSymbol({
+          symbol: propSymbol,
+          checker,
+          symbolsVisited,
+        });
+        acc[symbolInfo.name] = symbolInfo;
+        return acc;
+      }, {} as Extract<TypeInfo, { type: 'object' }>['properties']),
+      // constructorReturnType: constructSignature
+      //   ? analyzeType({ type: constructSignature.getReturnType(), checker })
+      //   : undefined,
+      constructorReturnType: analyzeType({
+        type: constructSignature.getReturnType(),
+        checker,
+      }),
+
+      constructorParameters: constructSignature
+        ?.getParameters()
+        .map((constructParam) => {
+          return analyzeSymbol({
+            symbol: constructParam,
+            checker,
+            symbolsVisited,
+          });
+        }),
+    };
+  } else if (
+    // this check could be better: lots of things are `ts.TypeFlags.Object`
+    typeFlags.includes('Object') &&
+    // here we exclude things that are technically `ts.TypeFlags.Object` but are not "objects" in JS
+    !isArray
+  ) {
+    typeInfo = {
+      type: 'object',
+      tsRawType: checker.typeToString(
+        type,
+        undefined,
+        ts.TypeFormatFlags.NoTruncation,
+      ),
+      properties: type.getProperties().reduce((acc, propSymbol) => {
+        if (symbolsVisited.has(propSymbol)) return acc;
+        const symbolInfo = analyzeSymbol({
+          symbol: propSymbol,
+          checker,
+          symbolsVisited,
+        });
+        acc[symbolInfo.name] = symbolInfo;
+        return acc;
+      }, {} as Extract<TypeInfo, { type: 'object' }>['properties']),
+      isOptional,
+      tsMetadata: {
+        typeFlags: getSetFlags({
+          flags: type.flags,
+          enumObject: ts.TypeFlags,
+        }),
+        type,
+      },
+    };
+  } else {
+    typeInfo = analyzeType({
+      type,
+      checker,
+      isOptional,
+    });
+  }
+  return {
+    ...baseSymbolInfo,
+    typeInfo,
+  };
+}

package/src/analyze-type.ts

@@ -0,0 +1,316 @@
+import ts from 'typescript';
+import { TypeInfo, TypeInfoCommon } from './types.js';
+import { getSetFlags } from './utils.js';
+
+// Cache for type IDs to improve performance
+const typeIdMap = new WeakMap<ts.Type, string>();
+
+/**
+ * Generates a consistent identifier for a TypeScript type
+ * Uses the type's string representation to ensure identical types get the same ID
+ */
+function getTypeId(type: ts.Type, checker: ts.TypeChecker): string {
+  // Check if we already have an ID for this type
+  const existingId = typeIdMap.get(type);
+  if (existingId) {
+    return existingId;
+  }
+
+  // Generate a new ID based on the type's string representation
+  // This ensures identical types get the same ID
+  const typeString = checker.typeToString(
+    type,
+    undefined,
+    // eslint-disable-next-line no-bitwise
+    ts.TypeFormatFlags.NoTruncation,
+  );
+
+  // Add some additional information to help distinguish types
+  // that might have the same string representation
+  const idComponents = [typeString];
+
+  // Add symbol name if available
+  const symbol = type.getSymbol();
+  if (symbol) {
+    idComponents.push(symbol.getName());
+  }
+
+  // Add type flags to help distinguish types
+  idComponents.push(String(type.flags));
+
+  const newId = idComponents.join('_');
+  typeIdMap.set(type, newId);
+  return newId;
+}
+
+/**
+ * Analyzes a TypeScript type and returns a structured TypeInfo representation
+ */
+export function analyzeType({
+  type,
+  checker,
+  isOptional,
+  visitedTypes = new Map<string, TypeInfo>(),
+  depth = 0,
+  /**
+   * The maximum depth of type analysis.
+   * This is used to avoid infinite recursion.
+   */
+  maxDepth = 3,
+}: {
+  type: ts.Type;
+  checker: ts.TypeChecker;
+  isOptional?: boolean;
+  visitedTypes?: Map<string, TypeInfo>;
+  depth?: number;
+  maxDepth?: number;
+}): TypeInfo {
+  // Generate a unique key for the type
+  const typeId = getTypeId(type, checker);
+
+  // Check if we've already analyzed this type
+  if (visitedTypes.has(typeId)) {
+    return visitedTypes.get(typeId)!;
+  }
+
+  const tsRawType = checker.typeToString(
+    type,
+    undefined,
+    // eslint-disable-next-line no-bitwise
+    ts.TypeFormatFlags.MultilineObjectLiterals |
+      ts.TypeFormatFlags.NoTruncation,
+  );
+  const typeFlags = getSetFlags({
+    flags: type.flags,
+    enumObject: ts.TypeFlags,
+  });
+  const typeInfoCommon: TypeInfoCommon = {
+    tsRawType,
+    tsMetadata: {
+      typeFlags,
+      type,
+    },
+    isOptional,
+  };
+
+  // If we've reached max depth, return a simplified type
+  if (depth >= maxDepth) {
+    const result: TypeInfo = {
+      type: 'misc',
+      ...typeInfoCommon,
+    };
+    visitedTypes.set(typeId, result);
+    return result;
+  }
+
+  let result: TypeInfo;
+
+  // Handle primitive types first
+  if (
+    tsRawType === 'number' ||
+    tsRawType === 'boolean' ||
+    tsRawType === 'string'
+  ) {
+    result = {
+      type: tsRawType,
+      ...typeInfoCommon,
+    };
+    visitedTypes.set(typeId, result);
+    return result;
+  }
+
+  // Handle literal types
+  if (type.isStringLiteral()) {
+    result = {
+      type: 'stringLiteral',
+      value: type.value,
+      ...typeInfoCommon,
+    };
+    visitedTypes.set(typeId, result);
+    return result;
+  }
+
+  if (type.isNumberLiteral()) {
+    result = {
+      type: 'numberLiteral',
+      value: type.value,
+      ...typeInfoCommon,
+    };
+    visitedTypes.set(typeId, result);
+    return result;
+  }
+
+  // Create a placeholder to avoid infinite recursion
+  const placeholder: TypeInfo = {
+    type: 'misc',
+    ...typeInfoCommon,
+  };
+  visitedTypes.set(typeId, placeholder);
+
+  // Handle unions
+  if (type.isUnion()) {
+    result = {
+      type: 'union',
+      items: type.types.map((t) =>
+        analyzeType({
+          type: t,
+          checker,
+          isOptional,
+          visitedTypes,
+          depth: depth + 1,
+          maxDepth,
+        }),
+      ),
+      ...typeInfoCommon,
+    };
+  }
+  // Handle arrays
+  else if (checker.isArrayType(type) || checker.isArrayLikeType(type)) {
+    const indexInfos = checker.getIndexInfosOfType(type);
+
+    result = {
+      type: 'array',
+      items:
+        indexInfos.length === 1
+          ? analyzeType({
+              type: indexInfos[0]?.type,
+              checker,
+              isOptional,
+              visitedTypes,
+              depth: depth + 1,
+              maxDepth,
+            })
+          : { type: 'misc', ...typeInfoCommon },
+      ...typeInfoCommon,
+    };
+  }
+  // Handle intersections
+  // This is where ForwardRef is being inferred
+  // @TODO: We need to find a way to handle depth here. Currently we bring in all of the properties
+  // from each type in the intersection, but we may want to limit the depth of the intersection
+  // to avoid bringing in too much.
+  // https://linear.app/knapsack/issue/KSP-5885/update-handling-of-intersection-types-in-spec-utils
+  else if (type.isIntersection()) {
+    const properties = type.getProperties();
+    if (properties.length > 0) {
+      const analyzedProperties = properties.reduce((acc, prop) => {
+        try {
+          // Get the type directly from the symbol - this is the most reliable method
+          const propType = checker.getTypeOfSymbol(prop);
+
+          if (propType) {
+            const propAnalysis = analyzeType({
+              type: propType,
+              checker,
+              // eslint-disable-next-line no-bitwise
+              isOptional: !!(prop.flags & ts.SymbolFlags.Optional),
+              visitedTypes,
+              depth: depth + 1,
+              maxDepth,
+            });
+
+            acc[prop.getName()] = {
+              name: prop.getName(),
+              typeInfo: propAnalysis,
+              tsMetadata: {
+                symbol: prop,
+                type: propType,
+                symbolFlags: getSetFlags({
+                  flags: prop.flags,
+                  enumObject: ts.SymbolFlags,
+                }),
+              },
+            };
+          }
+        } catch (error) {
+          console.debug(`Error analyzing property ${prop.getName()}: ${error}`);
+        }
+        return acc;
+      }, {} as Record<string, any>);
+
+      if (Object.keys(analyzedProperties).length > 0) {
+        result = {
+          type: 'object',
+          properties: analyzedProperties,
+          ...typeInfoCommon,
+        };
+      } else {
+        result = placeholder;
+      }
+    } else {
+      result = placeholder;
+    }
+  }
+  // Handle function types
+  else if (
+    typeFlags.includes('Object') &&
+    type.getCallSignatures().length > 0
+  ) {
+    result = {
+      type: 'function',
+      parameters: [],
+      returnType: { type: 'misc', ...typeInfoCommon },
+      ...typeInfoCommon,
+    };
+  }
+
+  // Handle object types
+  // @TODO: update handling of object type inference
+  // https://linear.app/knapsack/issue/KSP-5880/handle-arrays-of-objects-in-react-renderer-infer-spec
+  // else if (typeFlags.includes('Object')) {
+  //   const properties = type.getProperties();
+  //   if (properties.length > 0) {
+  //     const analyzedProperties = properties.reduce((acc, prop) => {
+  //       try {
+  //         const propType = checker.getTypeOfSymbol(prop);
+  //         if (propType) {
+  //           const propAnalysis = analyzeType({
+  //             type: propType,
+  //             checker,
+  //             // eslint-disable-next-line no-bitwise
+  //             isOptional: !!(prop.flags & ts.SymbolFlags.Optional),
+  //             visitedTypes,
+  //             depth: depth + 1,
+  //             maxDepth,
+  //           });
+  //           acc[prop.getName()] = {
+  //             name: prop.getName(),
+  //             typeInfo: propAnalysis,
+  //             tsMetadata: {
+  //               symbol: prop,
+  //               type: propType,
+  //               symbolFlags: getSetFlags({
+  //                 flags: prop.flags,
+  //                 enumObject: ts.SymbolFlags,
+  //               }),
+  //             },
+  //           };
+  //         }
+  //       } catch (error) {
+  //         console.debug(`Error analyzing property ${prop.getName()}: ${error}`);
+  //       }
+  //       return acc;
+  //     }, {} as Record<string, any>);
+
+  //     if (Object.keys(analyzedProperties).length > 0) {
+  //       result = {
+  //         type: 'object',
+  //         properties: analyzedProperties,
+  //         ...typeInfoCommon,
+  //       };
+  //     } else {
+  //       result = placeholder;
+  //     }
+  //   } else {
+  //     result = placeholder;
+  //   }
+  // }
+  // Default to misc type for anything we can't properly analyze
+  else {
+    result = placeholder;
+  }
+
+  // Update the cache with the actual result
+  visitedTypes.set(typeId, result);
+  return result;
+}

package/src/boot.ts

@@ -0,0 +1,31 @@
+import { createCompilerHost, createProgram, Program } from 'typescript';
+import { getTsConfigCompilerOptions } from './get-ts-config.js';
+
+export function prepTypeScriptBoot({
+  configSrc,
+}: {
+  configSrc: Parameters<typeof getTsConfigCompilerOptions>[0];
+}) {
+  const compilerOptions = getTsConfigCompilerOptions(configSrc);
+  const compilerHost = createCompilerHost(compilerOptions);
+  return { compilerOptions, compilerHost };
+}
+
+export function bootTypescript({
+  configSrc,
+  rootFiles,
+  oldProgram,
+}: {
+  configSrc: Parameters<typeof getTsConfigCompilerOptions>[0];
+  rootFiles: string[];
+  oldProgram?: Program;
+}) {
+  const { compilerOptions, compilerHost } = prepTypeScriptBoot({ configSrc });
+  const program = createProgram({
+    options: compilerOptions,
+    rootNames: rootFiles,
+    oldProgram,
+  });
+  const checker = program.getTypeChecker();
+  return { compilerHost, compilerOptions, program, checker };
+}