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

package/src/convert-to-spec.ts

@@ -0,0 +1,196 @@
+import type {
+  PropertyTypes,
+  StringProp,
+  BooleanProp,
+  NumberProp,
+  ObjectProp,
+  FunctionProp,
+} from '@knapsack/types';
+import { TypeInfo } from './types.js';
+
+export function convertToSpec({
+  typeInfo,
+  trustRequiredProps,
+}: {
+  typeInfo: TypeInfo;
+  trustRequiredProps: boolean;
+}): {
+  prop: PropertyTypes | null;
+  isOptional: boolean;
+} {
+  const { isOptional = false } = typeInfo;
+  switch (typeInfo.type) {
+    case 'object': {
+      const { properties } = typeInfo;
+      const required: string[] = [];
+      return {
+        isOptional,
+        prop: {
+          type: 'object',
+          required,
+          properties: Object.entries(properties).reduce(
+            (acc, [propName, { typeInfo: propTypeInfo, jsDoc }]) => {
+              const details = convertToSpec({
+                typeInfo: propTypeInfo,
+                trustRequiredProps,
+              });
+              if (!details.prop) return acc;
+
+              acc[propName] = details.prop;
+              if (jsDoc?.description) {
+                acc[propName].description = jsDoc.description;
+              }
+              if (!details.isOptional && trustRequiredProps) {
+                required.push(propName);
+              }
+              return acc;
+            },
+            {} as ObjectProp['properties'],
+          ),
+        } satisfies ObjectProp,
+      };
+    }
+    case 'array': {
+      const { items } = typeInfo;
+      const { prop } = convertToSpec({
+        typeInfo: items,
+        trustRequiredProps,
+      });
+      return {
+        isOptional,
+        prop: {
+          type: 'array',
+          // Use the converted items type if available, fallback to object type for complex types
+          items:
+            prop || ({ type: 'object', properties: {} } satisfies ObjectProp),
+          ...(typeInfo.tsRawType && { tsType: typeInfo.tsRawType }),
+        },
+      };
+    }
+    case 'string': {
+      return {
+        isOptional,
+        prop: {
+          type: 'string',
+        } satisfies StringProp,
+      };
+    }
+    case 'number': {
+      return {
+        isOptional,
+        prop: {
+          type: 'number',
+        } satisfies NumberProp,
+      };
+    }
+    case 'boolean': {
+      return {
+        isOptional,
+        prop: {
+          type: 'boolean',
+        } satisfies BooleanProp,
+      };
+    }
+    case 'union': {
+      const { items } = typeInfo;
+
+      // Handle string literal unions
+      const isUnionOfStrings = items.every(
+        (item): item is Extract<TypeInfo, { type: 'stringLiteral' }> =>
+          item.type === 'stringLiteral' || item.type === 'string',
+      );
+
+      // Handle number literal unions
+      const isUnionOfNumbers = items.every(
+        (item): item is Extract<TypeInfo, { type: 'numberLiteral' }> =>
+          item.type === 'numberLiteral' || item.type === 'number',
+      );
+
+      if (isUnionOfStrings) {
+        return {
+          isOptional,
+          prop: {
+            type: 'string',
+            enum: items
+              .filter(
+                (item): item is Extract<TypeInfo, { type: 'stringLiteral' }> =>
+                  item.type === 'stringLiteral',
+              )
+              .map((item) => item.value),
+          },
+        };
+      }
+
+      if (isUnionOfNumbers) {
+        return {
+          isOptional,
+          prop: {
+            type: 'number',
+            enum: items
+              .filter(
+                (item): item is Extract<TypeInfo, { type: 'numberLiteral' }> =>
+                  item.type === 'numberLiteral',
+              )
+              .map((item) => item.value),
+          },
+        };
+      }
+
+      return {
+        isOptional,
+        prop: null,
+      };
+    }
+    case 'function': {
+      return {
+        isOptional,
+        prop: {
+          typeof: 'function',
+          // ...(typeInfo.tsRawType && { tsType: typeInfo.tsRawType }),
+          tsType: typeInfo.tsRawType,
+        } satisfies FunctionProp,
+      };
+    }
+    case 'misc': {
+      // if there is type info in the tsRawType we try to convert it
+      if (typeInfo.tsRawType) {
+        // Create a new TypeInfo based on the tsRawType
+        const derivedTypeInfo = {
+          type: typeInfo.tsRawType,
+          isOptional,
+          tsRawType: typeInfo.tsRawType,
+          tsMetadata: typeInfo.tsMetadata,
+        } as TypeInfo;
+
+        return convertToSpec({
+          typeInfo: derivedTypeInfo,
+          trustRequiredProps,
+        });
+      }
+
+      return {
+        isOptional,
+        prop: null,
+      };
+    }
+    case 'numberLiteral':
+    case 'stringLiteral':
+    case 'class':
+    case 'unknown':
+    case 'any': {
+      return {
+        isOptional,
+        prop: null,
+      };
+    }
+
+    default: {
+      const _exhaustiveCheck: never = typeInfo;
+
+      return {
+        isOptional,
+        prop: null,
+      };
+    }
+  }
+}

package/src/convert-to-spec.vtest.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest';
+import { convertToSpec } from './convert-to-spec.js';
+import { TypeInfo, SymbolInfo } from './types.js';
+
+// these two are up here to make TS happy
+const typeInfoStubBase = {
+  tsRawType: '',
+  tsMetadata: null as unknown as TypeInfo['tsMetadata'],
+};
+const tsMetadata = null as unknown as SymbolInfo['tsMetadata'];
+
+describe('convert-to-spec', () => {
+  it('handles string', () => {
+    const { prop } = convertToSpec({
+      typeInfo: {
+        type: 'string',
+        ...typeInfoStubBase,
+      },
+      trustRequiredProps: false,
+    });
+    expect(prop).toEqual({
+      type: 'string',
+    } satisfies typeof prop);
+  });
+
+  it('handles boolean', () => {
+    const { prop } = convertToSpec({
+      typeInfo: {
+        type: 'boolean',
+        ...typeInfoStubBase,
+      },
+      trustRequiredProps: false,
+    });
+    expect(prop).toEqual({
+      type: 'boolean',
+    } satisfies typeof prop);
+  });
+
+  it('handles object', () => {
+    const { prop } = convertToSpec({
+      typeInfo: {
+        type: 'object',
+        ...typeInfoStubBase,
+        properties: {
+          name: {
+            name: 'name',
+            typeInfo: {
+              type: 'string',
+              tsRawType: '',
+              tsMetadata: null as unknown as TypeInfo['tsMetadata'],
+            },
+            tsMetadata,
+          },
+          age: {
+            name: 'age',
+            typeInfo: {
+              isOptional: true,
+              type: 'number',
+              ...typeInfoStubBase,
+            },
+            tsMetadata,
+          },
+          shoePrefs: {
+            name: 'shoePrefs',
+            typeInfo: {
+              type: 'union',
+              ...typeInfoStubBase,
+              items: [
+                {
+                  type: 'stringLiteral',
+                  value: 'sandals',
+                  ...typeInfoStubBase,
+                },
+                { type: 'stringLiteral', value: 'boots', ...typeInfoStubBase },
+              ],
+            },
+            tsMetadata,
+          },
+        },
+      },
+      trustRequiredProps: true,
+    });
+    expect(prop).toEqual({
+      type: 'object',
+      required: ['name', 'shoePrefs'],
+      properties: {
+        name: {
+          type: 'string',
+        },
+        age: {
+          type: 'number',
+        },
+        shoePrefs: {
+          type: 'string',
+          enum: ['sandals', 'boots'],
+        },
+      },
+    } satisfies typeof prop);
+  });
+
+  it('handles array of objects', () => {
+    const { prop } = convertToSpec({
+      typeInfo: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: {
+              name: 'name',
+              typeInfo: {
+                type: 'string',
+                ...typeInfoStubBase,
+              },
+              tsMetadata,
+            },
+          },
+          ...typeInfoStubBase,
+        },
+        ...typeInfoStubBase,
+      },
+      trustRequiredProps: false,
+    });
+    expect(prop).toEqual({
+      type: 'array',
+      items: {
+        type: 'object',
+        required: [],
+        properties: {
+          name: {
+            type: 'string',
+          },
+        },
+      },
+    } satisfies typeof prop);
+  });
+});

package/src/get-exports.ts

@@ -0,0 +1,70 @@
+import { join } from 'node:path';
+import { resolveTsModule } from './resolve.js';
+import { bootTypescript } from './boot.js';
+
+function getTsExportsUncached({
+  fileName,
+  pkgPathAliases,
+  resolveFromDir = process.cwd(),
+}: {
+  fileName: string;
+  pkgPathAliases?: Record<string, string>;
+  resolveFromDir?: string;
+}) {
+  const { resolvedFileName } = resolveTsModule({
+    containingFile: join(resolveFromDir, 'containing-file.ts'),
+    moduleName: fileName,
+    pkgPathAliases,
+  });
+  const { program, checker } = bootTypescript({
+    rootFiles: [resolvedFileName],
+    configSrc: {
+      type: 'preset',
+      preset: 'bundler',
+    },
+  });
+  const files = program.getSourceFiles();
+  const file = files.find((f) => f.fileName === resolvedFileName);
+  if (!file) {
+    throw new Error(`File ${fileName} not found`);
+  }
+
+  const moduleSymbol = checker.getSymbolAtLocation(file);
+  if (!moduleSymbol) {
+    throw new Error(`Module symbol for ${fileName} not found`);
+  }
+
+  return {
+    exports: checker.getExportsOfModule(moduleSymbol),
+    checker,
+  };
+}
+
+const cache = new Map<string, ReturnType<typeof getTsExportsUncached>>();
+const timeouts = new Map<string, NodeJS.Timeout>();
+// clear the timeout when the process is terminated so process.exit() doesn't hang
+process.on('SIGTERM', () => {
+  for (const timeout of timeouts.values()) {
+    clearTimeout(timeout);
+  }
+});
+
+export function getTsExports(opt: Parameters<typeof getTsExportsUncached>[0]) {
+  if (process.env.NODE_ENV === 'test') {
+    return getTsExportsUncached(opt);
+  }
+  const key = JSON.stringify(opt);
+
+  const exports = cache.get(key);
+  if (exports) {
+    return exports;
+  }
+
+  const result = getTsExportsUncached(opt);
+  cache.set(key, result);
+  timeouts.set(
+    key,
+    setTimeout(() => cache.delete(key), 5_000),
+  );
+  return result;
+}

package/src/get-ts-config.ts

@@ -0,0 +1,96 @@
+import ts, {
+  sys as tsSys,
+  findConfigFile,
+  readConfigFile,
+  parseJsonConfigFileContent,
+  getDefaultCompilerOptions,
+  CompilerOptions,
+} from 'typescript';
+import { dirname } from 'node:path';
+
+export function getTsConfigJson({
+  basePath = process.cwd(),
+}: {
+  basePath?: string;
+} = {}) {
+  // Find tsconfig.json file
+  const tsConfigPath = findConfigFile(
+    basePath,
+    tsSys.fileExists,
+    'tsconfig.json',
+  );
+
+  if (!tsConfigPath) {
+    throw new Error(
+      `No tsconfig.json file found searching up from ${basePath} `,
+    );
+  }
+
+  // Read tsconfig.json file
+  const tsconfigFile = readConfigFile(tsConfigPath, tsSys.readFile);
+  if (tsconfigFile.error) {
+    throw new Error(
+      `Failed to read tsconfig.json file: ${tsconfigFile.error.messageText}`,
+    );
+  }
+
+  // Resolve extends
+  const tsConfig = parseJsonConfigFileContent(
+    tsconfigFile.config,
+    tsSys,
+    dirname(tsConfigPath),
+  );
+
+  return { tsConfig, tsConfigPath };
+}
+
+export function getTsConfigCompilerOptions(
+  configSrc:
+    | {
+        type: 'resolveTsConfigJson';
+        basePath?: string;
+      }
+    | {
+        type: 'inline';
+        config: CompilerOptions;
+      }
+    | {
+        type: 'preset';
+        preset: 'default' | 'modern' | 'bundler';
+      },
+): CompilerOptions {
+  switch (configSrc.type) {
+    case 'resolveTsConfigJson':
+      return getTsConfigJson({ basePath: configSrc.basePath }).tsConfig.options;
+    case 'inline': {
+      return configSrc.config;
+    }
+    case 'preset': {
+      switch (configSrc.preset) {
+        case 'default': {
+          return getDefaultCompilerOptions();
+        }
+        case 'bundler': {
+          return {
+            module: ts.ModuleKind.ESNext,
+            moduleResolution: ts.ModuleResolutionKind.Bundler,
+          };
+        }
+        case 'modern': {
+          return {
+            module: ts.ModuleKind.NodeNext,
+            moduleResolution: ts.ModuleResolutionKind.NodeNext,
+          };
+        }
+        default: {
+          const _exhaustiveCheck: never = configSrc.preset;
+          throw new Error(`Unknown preset: ${configSrc.preset}`);
+        }
+      }
+    }
+    default: {
+      const _exhaustiveCheck: never = configSrc;
+      throw new Error(`Unknown config source: ${JSON.stringify(configSrc)}`);
+    }
+  }
+}

package/src/get-ts-config.vtest.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { getTsConfigJson } from './get-ts-config.js';
+
+describe('get-ts-config', () => {
+  it('reads this pkg tsconfig.json', () => {
+    const { tsConfig } = getTsConfigJson({ basePath: import.meta.dirname });
+    expect(Object.keys(tsConfig.options).length).toBeGreaterThan(0);
+  });
+});

package/src/index.ts

@@ -0,0 +1,5 @@
+export { getTsConfigCompilerOptions } from './get-ts-config.js';
+export { resolveTsModule } from './resolve.js';
+export { analyzeExport, analyzeExports } from './analyze-exports.js';
+export type { TypeInfo, SymbolInfo } from './types.js';
+export { convertToSpec } from './convert-to-spec.js';

package/src/resolve.ts

@@ -0,0 +1,54 @@
+import ts, { resolveModuleName } from 'typescript';
+import { prepTypeScriptBoot } from './boot.js';
+
+function pkgPathAliasesToPaths(pkgPathAliases: Record<string, string>) {
+  if (!pkgPathAliases) return undefined;
+  return Object.entries(pkgPathAliases).reduce((acc, [alias, path]) => {
+    acc[alias] = [path];
+    acc[`${alias}/*`] = [`${path}/*`];
+    return acc;
+  }, {} as Record<string, string[]>);
+}
+
+export function resolveTsModule({
+  containingFile,
+  moduleName,
+  pkgPathAliases = {},
+}: {
+  moduleName: string;
+  containingFile: string;
+  pkgPathAliases?: Record<string, string>;
+}) {
+  const paths = pkgPathAliasesToPaths(
+    Object.fromEntries(
+      Object.entries(pkgPathAliases).map(([alias, pkgPath]) => {
+        const { resolvedFileName: pkgPathResolved } = resolveTsModule({
+          moduleName: pkgPath,
+          containingFile,
+        });
+        return [alias, pkgPathResolved];
+      }),
+    ),
+  );
+
+  const { compilerOptions, compilerHost } = prepTypeScriptBoot({
+    configSrc: {
+      type: 'inline',
+      config: {
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        module: ts.ModuleKind.NodeNext,
+        paths,
+      },
+    },
+  });
+  const { resolvedModule } = resolveModuleName(
+    moduleName,
+    containingFile,
+    compilerOptions,
+    compilerHost,
+  );
+  if (!resolvedModule) {
+    throw new Error(`Failed to resolve module: ${moduleName}`);
+  }
+  return resolvedModule;
+}

package/src/resolve.vtest.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { join } from 'node:path';
+import { resolveTsModule } from './resolve.js';
+
+describe('resolve module tests', () => {
+  it('resolves @knapsack/utils', () => {
+    const { resolvedFileName, isExternalLibraryImport } = resolveTsModule({
+      containingFile: import.meta.filename,
+      moduleName: '@knapsack/utils',
+    });
+
+    expect(resolvedFileName).toBeTruthy();
+    expect(resolvedFileName).toMatch(/\.d\.ts$/);
+    expect(resolvedFileName).toContain('utils/dist');
+    expect(isExternalLibraryImport).toBe(true);
+  });
+
+  it('resolves local ts file with .js extension', () => {
+    const { resolvedFileName } = resolveTsModule({
+      containingFile: import.meta.filename,
+      moduleName: './boot.js',
+    });
+
+    expect(resolvedFileName).toBe(join(import.meta.dirname, './boot.ts'));
+  });
+
+  it('resolves local ts file with .ts extension', () => {
+    const { resolvedFileName } = resolveTsModule({
+      containingFile: import.meta.filename,
+      moduleName: './boot.ts',
+    });
+
+    expect(resolvedFileName).toBe(join(import.meta.dirname, './boot.ts'));
+  });
+
+  it('resolves a local package.json', () => {
+    const { resolvedFileName } = resolveTsModule({
+      containingFile: import.meta.filename,
+      moduleName: '../package.json',
+    });
+
+    expect(resolvedFileName).toMatch(/package\.json$/);
+    expect(resolvedFileName).toBe(join(import.meta.dirname, '../package.json'));
+  });
+
+  it('resolves a local file', () => {
+    const { resolvedFileName } = resolveTsModule({
+      containingFile: import.meta.filename,
+      moduleName: '../.eslintrc.cjs',
+    });
+    expect(resolvedFileName).toBe(
+      join(import.meta.dirname, '../.eslintrc.cjs'),
+    );
+  });
+
+  it('resolves alias of @knapsack/utils', () => {
+    const { resolvedFileName } = resolveTsModule({
+      containingFile: import.meta.filename,
+      moduleName: 'foo',
+      pkgPathAliases: {
+        foo: '@knapsack/utils',
+      },
+    });
+
+    expect(resolvedFileName).toBeTruthy();
+    expect(resolvedFileName).toMatch(/\.d\.ts$/);
+    expect(resolvedFileName).toContain('utils/dist');
+  });
+});

package/src/test-fixtures/basics.ts

@@ -0,0 +1,17 @@
+/* eslint-disable @typescript-eslint/no-inferrable-types */
+
+export const foo = 'bar';
+export type AString = string;
+export const stringViaTypeAlias: AString = 'foo';
+export const aNumber: number = 1;
+export const aString: string = 'foo';
+export const aBoolean: boolean = true;
+export const anArrayOfNumbers: number[] = [1, 2, 3];
+export const anArrayOfStrings: string[] = ['foo', 'bar', 'baz'];
+export const anArrayOfBooleans: boolean[] = [true, false, true];
+export const stringUnion: 'small' | 'medium' | 'large' = 'small';
+export const anObject = {
+  a: 1,
+  b: 'Beep',
+  c: ['foo', 'bar', 'baz'],
+};

package/src/test-fixtures/functions.ts

@@ -0,0 +1,50 @@
+export const aFunction = (a: number) => a;
+export const asyncFunction = async (a: number) => a;
+
+/**
+ * The thing to do
+ * @param item - The item to do
+ * @link https://www.example.com
+ * @deprecated
+ */
+export function doIt({ item, isFast }: { isFast?: boolean; item: string }) {
+  return `${item} ${isFast ? 'fast' : 'slow'}`;
+}
+
+type AString = string;
+
+/**
+ * Some basic types
+ * @link https://www.example.com
+ */
+export function complexFuncTypes(obj: {
+  /** ima string */
+  aString: string;
+  aStringViaType: AString;
+  aNumber: number;
+  /** an optional string */
+  anOptionalString?: string;
+  /** a boolean */
+  aBoolean: boolean;
+  /** some sizes */
+  someSizes: 'small' | 'medium' | 'large';
+  /** an array of strings */
+  anArray: string[];
+  anObject: { aString: string };
+  aFunc: (a: string) => string;
+  anotherFunc: (opt: { foo: string; onFoo: (a: string) => string }) => {
+    b: string;
+  };
+}) {
+  return obj;
+}
+
+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}`;
+}
+
+export const sayBye = <T>(msg: T): string => {
+  return `Bye ${msg}`;
+};