@knapsack/spec-utils 4.78.11--canary.074d651.0 → 4.78.11

package/dist/utils.vtest.js

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import ts from 'typescript';
+import { getSetFlags } from './utils.js';
+describe('utils tests', () => {
+    it('getSetFlags single flag', () => {
+        const single = getSetFlags({
+            enumObject: ts.SymbolFlags,
+            flags: ts.SymbolFlags.Property,
+        });
+        expect(single).toEqual(['Property']);
+    });
+    it('getSetFlags multiple flags', () => {
+        const multiple = getSetFlags({
+            enumObject: ts.SymbolFlags,
+            flags: 
+            // eslint-disable-next-line no-bitwise
+            ts.SymbolFlags.FunctionScopedVariable |
+                ts.SymbolFlags.BlockScopedVariable,
+        });
+        expect(multiple).toEqual([
+            'FunctionScopedVariable',
+            'BlockScopedVariable',
+        ]);
+    });
+    it('single flag with multiple flags extracted', () => {
+        // an "Accessor" is both a "GetAccessor" and a "SetAccessor"
+        const single = getSetFlags({
+            enumObject: ts.SymbolFlags,
+            flags: ts.SymbolFlags.Accessor,
+        });
+        expect(single).toEqual([
+            'GetAccessor',
+            'SetAccessor',
+        ]);
+    });
+});
+//# sourceMappingURL=utils.vtest.js.map

package/dist/utils.vtest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.vtest.js","sourceRoot":"","sources":["../src/utils.vtest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACjC,MAAM,MAAM,GAAG,WAAW,CAAC;YACzB,UAAU,EAAE,EAAE,CAAC,WAAW;YAC1B,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ;SAC/B,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,CAAyB,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QACpC,MAAM,QAAQ,GAAG,WAAW,CAAC;YAC3B,UAAU,EAAE,EAAE,CAAC,WAAW;YAC1B,KAAK;YACH,sCAAsC;YACtC,EAAE,CAAC,WAAW,CAAC,sBAAsB;gBACrC,EAAE,CAAC,WAAW,CAAC,mBAAmB;SACrC,CAAC,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC;YACvB,wBAAwB;YACxB,qBAAqB;SACI,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACnD,4DAA4D;QAC5D,MAAM,MAAM,GAAG,WAAW,CAAC;YACzB,UAAU,EAAE,EAAE,CAAC,WAAW;YAC1B,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ;SAC/B,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC;YACrB,aAAa;YACb,aAAa;SACU,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@knapsack/spec-utils",
   "description": "",
-  "version": "4.78.11--canary.074d651.0",
+  "version": "4.78.11",
   "type": "module",
   "exports": {
     ".": {
@@ -20,17 +20,17 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@knapsack/utils": "4.78.11--canary.074d651.0",
+    "@knapsack/utils": "4.78.11",
     "typescript": "^5.8.3"
   },
   "devDependencies": {
-    "@knapsack/angular-sandbox-components": "4.78.11--canary.074d651.0",
-    "@knapsack/eslint-config-starter": "4.78.11--canary.074d651.0",
-    "@knapsack/file-utils": "4.78.11--canary.074d651.0",
-    "@knapsack/prettier-config": "4.78.11--canary.074d651.0",
-    "@knapsack/sandbox-components": "4.78.11--canary.074d651.0",
-    "@knapsack/types": "4.78.11--canary.074d651.0",
-    "@knapsack/typescript-config-starter": "4.78.11--canary.074d651.0",
+    "@knapsack/angular-sandbox-components": "4.78.11",
+    "@knapsack/eslint-config-starter": "4.78.11",
+    "@knapsack/file-utils": "4.78.11",
+    "@knapsack/prettier-config": "4.78.11",
+    "@knapsack/sandbox-components": "4.78.11",
+    "@knapsack/types": "4.78.11",
+    "@knapsack/typescript-config-starter": "4.78.11",
     "@mui/material": "^5.17.1",
     "@types/node": "^20.17.24",
     "eslint": "^8.57.0",
@@ -45,5 +45,5 @@
     "directory": "apps/client/libs/spec-utils",
     "type": "git"
   },
-  "gitHead": "074d65186e102cdf467592eae259a8c9f99e1136"
+  "gitHead": "01537987f1d45ce95020236b80582736288d7506"
 }

package/src/align/align.vtest.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, assert } from 'vitest';
+import { realpath } from 'node:fs/promises';
+import { getJsExportNames, resolvePath } from '@knapsack/file-utils';
+import { resolveTsModule } from '../resolve.js';
+import { getTsExports } from '../get-exports.js';
+import { paths } from './utils.js';
+
+describe.for(paths)(`$path`, ({ path }) => {
+  it('resolves to same file path', async () => {
+    const { absolutePath } = await resolvePath({
+      path,
+      resolveType: 'types',
+    });
+    const { resolvedFileName } = resolveTsModule({
+      moduleName: path,
+      containingFile: import.meta.filename,
+    });
+    expect(await realpath(resolvedFileName)).toBe(await realpath(absolutePath));
+  });
+
+  it(
+    'finds same export names in ts and js',
+    {
+      timeout: 10_000,
+    },
+    async () => {
+      const { exports } = getTsExports({
+        fileName: path,
+      });
+      const exportNamesFromTs = exports.map((e) => e.getName());
+
+      const { exports: exportNamesFromJs } = await getJsExportNames({
+        path,
+      });
+
+      // the ts details will contain things like types that the js details don't
+      // this makes sure that all we found in js is also found in ts
+      const exportNamesFromJsSet = new Set(exportNamesFromJs);
+      exportNamesFromTs.forEach((e) => {
+        exportNamesFromJsSet.delete(e);
+      });
+      if (path === '@mui/material') {
+        // pulling these out b/c they fail test, but we got the other ones
+        exportNamesFromJsSet.delete('FormLabelRoot');
+        exportNamesFromJsSet.delete('private_createMixins');
+        exportNamesFromJsSet.delete('usePagination');
+      }
+      assert.isEmpty(
+        exportNamesFromJsSet,
+        `found ${exportNamesFromJsSet.size} extra exports in js: ${[
+          ...exportNamesFromJsSet,
+        ].join(', ')}`,
+      );
+    },
+  );
+});

package/src/align/get-exports.bench.ts

@@ -0,0 +1,28 @@
+import { bench, describe } from 'vitest';
+import { getJsExportNames } from '@knapsack/file-utils';
+import { getTsExports } from '../get-exports.js';
+import { paths } from './utils.js';
+
+paths.forEach(({ path }) => {
+  describe(path, () => {
+    bench(
+      'getTsExports',
+      async () => {
+        getTsExports({
+          fileName: path,
+        });
+      },
+      {},
+    );
+
+    bench(
+      'getJsExportNames',
+      async () => {
+        await getJsExportNames({
+          path,
+        });
+      },
+      {},
+    );
+  });
+});

package/src/align/resolve.bench.ts

@@ -0,0 +1,20 @@
+import { describe, bench } from 'vitest';
+import { resolvePath } from '@knapsack/file-utils';
+import { resolveTsModule } from '../resolve.js';
+import { paths } from './utils.js';
+
+paths.forEach(({ path }) => {
+  describe(path, () => {
+    bench('resolveTsModule', () => {
+      resolveTsModule({
+        containingFile: import.meta.filename,
+        moduleName: path,
+      });
+    });
+    bench('resolvePath', async () => {
+      await resolvePath({
+        path,
+      });
+    });
+  });
+});

package/src/align/utils.ts

@@ -0,0 +1,14 @@
+export const paths = [
+  {
+    path: '@knapsack/sandbox-components/react',
+  },
+  {
+    path: '@knapsack/angular-sandbox-components',
+  },
+  {
+    path: '@mui/material',
+  },
+  {
+    path: '@knapsack/utils',
+  },
+] as const;

package/src/analyze-exports.sandbox-components.vtest.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeExports } from './analyze-exports.js';
+import { assertTypeInfo } from './utils.js';
+
+describe('analyze-exports sandbox components', () => {
+  it('analyzes react exports', () => {
+    const exports = analyzeExports({
+      fileName: '@knapsack/sandbox-components/react',
+    });
+    const { Button } = exports;
+    expect(Button).toBeTruthy();
+    assertTypeInfo(Button.typeInfo, 'function');
+    const { parameters } = Button.typeInfo;
+    const [props] = parameters;
+    assertTypeInfo(props.typeInfo, 'object');
+    const { properties } = props.typeInfo;
+    const { size } = properties;
+    assertTypeInfo(size.typeInfo, 'union');
+    const { items } = size.typeInfo;
+    const sizeValues = items
+      .map((item) => {
+        assertTypeInfo(item, 'stringLiteral');
+        return item.value;
+      })
+      .sort();
+    expect(sizeValues).toEqual(['large', 'medium', 'small'].sort());
+  });
+
+  it('analyzes angular exports', () => {
+    const exports = analyzeExports({
+      fileName: '@knapsack/angular-sandbox-components',
+    });
+    const { KsButtonComponent } = exports;
+    expect(KsButtonComponent).toBeTruthy();
+    assertTypeInfo(KsButtonComponent.typeInfo, 'class');
+    const { prototype } = KsButtonComponent.typeInfo;
+    assertTypeInfo(prototype.typeInfo, 'object');
+    const { hasArrow, click, size, handleClick } =
+      prototype.typeInfo.properties;
+    assertTypeInfo(hasArrow.typeInfo, 'boolean');
+    assertTypeInfo(handleClick.typeInfo, 'function');
+    expect(click.typeInfo.tsRawType).toBe('EventEmitter<void>');
+    assertTypeInfo(size.typeInfo, 'union');
+    const { items } = size.typeInfo;
+    const sizeValues = items
+      .map((item) => {
+        assertTypeInfo(item, 'stringLiteral');
+        return item.value;
+      })
+      .sort();
+    expect(sizeValues).toEqual(['large', 'medium', 'small'].sort());
+  });
+});

package/src/analyze-exports.ts

@@ -0,0 +1,54 @@
+import { arrayToDictionary } from '@knapsack/utils';
+import { analyzeSymbol } from './analyze-symbol.js';
+import { getTsExports } from './get-exports.js';
+
+export function analyzeExports({
+  fileName,
+  pkgPathAliases,
+  resolveFromDir,
+}: {
+  fileName: string;
+  pkgPathAliases?: Record<string, string>;
+  resolveFromDir?: string;
+}) {
+  const { exports, checker } = getTsExports({
+    fileName,
+    pkgPathAliases,
+    resolveFromDir,
+  });
+  return arrayToDictionary(
+    exports.map((symbol) =>
+      analyzeSymbol({
+        symbol,
+        checker,
+      }),
+    ),
+    'name',
+  );
+}
+
+export function analyzeExport({
+  fileName,
+  exportName,
+  pkgPathAliases,
+  resolveFromDir,
+}: {
+  fileName: string;
+  exportName: string;
+  pkgPathAliases?: Record<string, string>;
+  resolveFromDir?: string;
+}) {
+  const { exports, checker } = getTsExports({
+    fileName,
+    pkgPathAliases,
+    resolveFromDir,
+  });
+  const theExport = exports.find((e) => e.getName() === exportName);
+  if (!theExport) {
+    throw new Error(`Export ${exportName} not found in ${fileName}`);
+  }
+  return analyzeSymbol({
+    symbol: theExport,
+    checker,
+  });
+}

package/src/analyze-exports.vtest.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect } from 'vitest';
+import { join } from 'node:path';
+import { analyzeExports } from './analyze-exports.js';
+import { assertTypeInfo } from './utils.js';
+
+const tsDetailsSrc = join(import.meta.dirname, '../src/test-fixtures/index.ts');
+const tsDetailsDts = join(
+  import.meta.dirname,
+  '../dist/test-fixtures/index.d.ts',
+);
+
+[tsDetailsSrc, tsDetailsDts].forEach((fileName) => {
+  const ext = fileName.endsWith('.d.ts') ? '.d.ts' : '.ts';
+  const exports = analyzeExports({ fileName });
+
+  describe(`analyze-exports tests for ${ext} files`, () => {
+    it(`gets export names`, () => {
+      const results = analyzeExports({
+        fileName,
+      });
+      const exportNames = Object.keys(results);
+      expect(exportNames).toContain('complexFuncTypes');
+      expect(exportNames).toContain('doIt');
+    });
+
+    it(`handles basics: number`, () => {
+      const { typeInfo } = exports.aNumber;
+      expect(typeInfo.type).toBe('number');
+    });
+
+    it(`handles string union`, () => {
+      const { typeInfo } = exports.stringUnion;
+      assertTypeInfo(typeInfo, 'union');
+      const { items } = typeInfo;
+      const sizes = items.map((item) => {
+        if (item.type !== 'stringLiteral') {
+          throw new Error(
+            `Expected type to be stringLiteral, got ${item.type}`,
+          );
+        }
+        return item.value;
+      });
+      expect(sizes).toEqual(['small', 'medium', 'large']);
+    });
+
+    it(`handles string via type alias`, () => {
+      const { typeInfo } = exports.stringViaTypeAlias;
+      expect(typeInfo.type).toBe('string');
+    });
+
+    it(`handles jsdoc`, () => {
+      const { jsDoc } = exports.complexFuncTypes;
+      if (!jsDoc) {
+        throw new Error('jsDoc is undefined');
+      }
+      expect(jsDoc.description).toBe('Some basic types');
+      expect(jsDoc.jsDocTags.length).toBe(1);
+      expect(jsDoc.jsDocTags).toEqual([
+        { name: 'link', text: 'https://www.example.com' },
+      ] satisfies typeof jsDoc.jsDocTags);
+    });
+
+    it(`handles basics: string[]`, () => {
+      const { typeInfo } = exports.anArrayOfStrings;
+      assertTypeInfo(typeInfo, 'array');
+      expect(typeInfo.items.type).toBe('string');
+      expect(typeInfo.tsRawType).toBe('string[]');
+    });
+
+    it(`handles basics: object`, () => {
+      const { typeInfo } = exports.anObject;
+      assertTypeInfo(typeInfo, 'object');
+      const {
+        properties: { a, b, c },
+      } = typeInfo;
+      expect(a.typeInfo.type).toBe('number');
+      expect(b.typeInfo.type).toBe('string');
+      assertTypeInfo(c.typeInfo, 'array');
+      expect(c.typeInfo.items.type).toBe('string');
+      expect(c.typeInfo.tsRawType).toBe('string[]');
+    });
+
+    it(`handles function with basic parameters`, () => {
+      const { typeInfo } = exports.aFunction;
+      assertTypeInfo(typeInfo, 'function');
+      const { parameters, returnType, tsRawType } = typeInfo;
+      if (!returnType) {
+        throw new Error('returnType is undefined');
+      }
+      const [param] = parameters;
+      expect(tsRawType).toBe('(a: number) => number');
+      expect(param.name).toBe('a');
+      expect(param.typeInfo.type).toBe('number');
+      expect(returnType.type).toBe('number');
+    });
+
+    it(`handles async function with basic parameters`, () => {
+      const { typeInfo } = exports.asyncFunction;
+      assertTypeInfo(typeInfo, 'function');
+      const { parameters, returnType, tsRawType } = typeInfo;
+      if (!returnType) {
+        throw new Error('returnType is undefined');
+      }
+      const [param] = parameters;
+      expect(param.name).toBe('a');
+      expect(param.typeInfo.type).toBe('number');
+      expect(tsRawType).toBe('(a: number) => Promise<number>');
+      expect(returnType.type).toBe('misc');
+    });
+
+    it(`handles function with complex parameters`, () => {
+      const { typeInfo } = exports.complexFuncTypes;
+      assertTypeInfo(typeInfo, 'function');
+      const [param] = typeInfo.parameters;
+      expect(param.name).toBe('obj');
+      assertTypeInfo(param.typeInfo, 'object');
+      const { properties } = param.typeInfo;
+      Object.entries(properties).forEach(([key, { typeInfo: propInfo }]) => {
+        switch (key) {
+          case 'aString': {
+            expect(propInfo.type).toBe('string');
+            expect(propInfo.isOptional).toBe(false);
+            break;
+          }
+          case 'anOptionalString': {
+            expect(propInfo.type).toBe('string');
+            expect(propInfo.isOptional).toBe(true);
+            break;
+          }
+          case 'aBoolean': {
+            expect(propInfo.type).toBe('boolean');
+            expect(propInfo.isOptional).toBe(false);
+            break;
+          }
+          case 'someSizes': {
+            assertTypeInfo(propInfo, 'union');
+            const sizes = propInfo.items.map((item) => {
+              assertTypeInfo(item, 'stringLiteral');
+              return item.value;
+            });
+            expect(sizes).toEqual(['small', 'medium', 'large']);
+            break;
+          }
+          case 'anArray': {
+            assertTypeInfo(propInfo, 'array');
+            expect(propInfo.items.type).toBe('string');
+            break;
+          }
+          case 'aFunc': {
+            assertTypeInfo(propInfo, 'function');
+            const { parameters, returnType } = propInfo;
+            if (!returnType) {
+              throw new Error('returnType is undefined');
+            }
+            const [p] = parameters;
+            expect(p.name).toBe('a');
+            expect(p.typeInfo.type).toBe('string');
+            expect(returnType.type).toBe('string');
+            break;
+          }
+          case 'anotherFunc': {
+            assertTypeInfo(propInfo, 'function');
+            const { parameters } = propInfo;
+            const [p] = parameters;
+            expect(p.name).toBe('opt');
+            assertTypeInfo(p.typeInfo, 'object');
+            const { onFoo } = p.typeInfo.properties;
+            assertTypeInfo(onFoo.typeInfo, 'function');
+            const [onFooParam] = onFoo.typeInfo.parameters;
+            expect(onFooParam.name).toBe('a');
+            expect(onFooParam.typeInfo.type).toBe('string');
+            break;
+          }
+        }
+      });
+    });
+  });
+});