bio-dts 0.12.0 → 0.14.0

package/README.md

@@ -34,7 +34,7 @@ Checkout the [test fixtures](./test/fixtures) for full coverage.
 
 ## API
 
-```javascript
+```js
 import {
   preTransform,
   postTransform,

package/bin/cmd.js

@@ -26,12 +26,14 @@ async function run() {
 
   const verbose = _verbose ? _verboseGrep || true : false;
   const recursive = args.includes('--recursive') || args.includes('-r');
+  const lax = args.includes('--lax');
 
   if (help) {
     console.log(`Usage: bio-dts [options] [...filesOrGlobs]
 
   Options:
     --recursive, -r    recurse into directories
+    --lax              relax certain checks (when running on generated code)
     --verbose          enable verbose logging
 
     Additional options will be passed to the typescript generator.
@@ -73,7 +75,7 @@ async function run() {
 
   const {
     diagnostics
-  } = generateTypes(files, generateOptions, ts);
+  } = generateTypes(files, generateOptions, ts, { lax });
 
   const errors = diagnostics.filter(d => d.category === ts.DiagnosticCategory.Error);
 

package/lib/generate-types.js

@@ -16,18 +16,22 @@ import postTransform from './post-transform.js';
 
 /**
  * @param { string[] } fileNames
- * @param { CompilerOptions } options
+ * @param { CompilerOptions } compilerOptions
  * @param { TypeScript } ts
+ * @param { { lax: boolean } } generateOptions
  */
-export default function generateTypes(fileNames, options, ts) {
+export default function generateTypes(fileNames, compilerOptions, ts, generateOptions) {
 
   if (!ts) {
     throw new Error('must provide <ts=TypeScript>');
   }
 
+  // CompilerOptions.JsxEmit.None = 0
+  const jsx = compilerOptions.jsx !== 0;
+
   const names = new Set(fileNames.map((p) => path.resolve(p)));
 
-  const host = ts.createCompilerHost(options);
+  const host = ts.createCompilerHost(compilerOptions);
 
   // @ts-expect-error
   host._readFile = host.readFile;
@@ -43,16 +47,16 @@ export default function generateTypes(fileNames, options, ts) {
     let src = host._readFile(fileName);
 
     if (names.has(path.resolve(fileName))) {
-      isVerbose(options, fileName) && console.debug('[generate-types] [pre]', fileName, src);
+      isVerbose(compilerOptions, fileName) && console.debug('[generate-types] [pre]', fileName, src);
 
       try {
-        src = preTransform(src);
+        src = preTransform(src, { jsx });
       } catch (err) {
         console.error(`[generate-types] [pre] failed to parse ${fileName} with contents ${src}`, err);
         throw err;
       }
 
-      isVerbose(options, fileName) && console.debug('[generate-types] [pre] [generated]', fileName, src);
+      isVerbose(compilerOptions, fileName) && console.debug('[generate-types] [pre] [generated]', fileName, src);
     }
 
     return src;
@@ -62,35 +66,41 @@ export default function generateTypes(fileNames, options, ts) {
   host._writeFile = host.writeFile;
 
   host.writeFile = (fileName, text, ...args) => {
-    isVerbose(options, fileName) && console.debug('[generate-types] [post]', fileName, text);
+    isVerbose(compilerOptions, fileName) && console.debug('[generate-types] [post]', fileName, text);
 
-    try {
-      text = postTransform(text);
-    } catch (err) {
-      console.error(`[generate-types] [post] failed to parse ${fileName} with contents ${text}`, err);
-      throw err;
-    }
+    if (fileName.toLowerCase().endsWith('.d.ts')) {
+      try {
+        text = postTransform(text, generateOptions);
+      } catch (err) {
+        console.error(`[generate-types] [post] failed to parse ${fileName} with contents ${text}`, err);
+        throw err;
+      }
 
-    isVerbose(options, fileName) && console.debug('[generate-types] [post] [generated]', fileName, text);
+      isVerbose(compilerOptions, fileName) && console.debug('[generate-types] [post] [generated]', fileName, text);
+    }
 
     // @ts-expect-error
     host._writeFile(fileName, text, ...args);
   };
 
-  const program = ts.createProgram(fileNames, options, host);
+  const program = ts.createProgram(fileNames, compilerOptions, host);
 
   return program.emit();
 }
 
-function isVerbose(options, fileName) {
+/**
+ * @param { CompilerOptions } compilerOptions
+ * @param { any } fileName
+ */
+function isVerbose(compilerOptions, fileName) {
 
-  if (typeof options.verbose === 'boolean') {
-    return options.verbose;
+  if (typeof compilerOptions.verbose === 'boolean') {
+    return compilerOptions.verbose;
   }
 
-  if (typeof options.verbose === 'undefined') {
+  if (typeof compilerOptions.verbose === 'undefined') {
     return false;
   }
 
-  return fileName.includes(options.verbose);
+  return fileName.includes(compilerOptions.verbose);
 }

package/lib/parsers/typescript.js

@@ -1 +1,57 @@
-export * from 'recast/parsers/typescript.js';
+import { parser } from 'recast/parsers/babel.js';
+import getBabelOptions from 'recast/parsers/_babel_options.js';
+
+/**
+ * @typedef { import('recast/parsers/_babel_options.js').Overrides } Overrides
+ *
+ * @typedef { import('@babel/parser').ParserPlugin } ParserPlugin
+ *
+ * @typedef { { jsx: boolean } } ParseOptions
+ */
+
+/**
+ * @param { string } source
+ * @param { ParserPlugin[] } plugins
+ * @param { Overrides } [options]
+ *
+ * @return { import('@babel/types').File }
+ */
+function _parse(source, plugins, options) {
+  const babelOptions = getBabelOptions.default(options);
+
+  for (const plugin of plugins) {
+    babelOptions.plugins.push(plugin);
+  }
+
+  return parser.parse(source, babelOptions);
+}
+
+/**
+ * @param { string } source
+ * @param { Overrides } [options]
+ *
+ * @return { import('@babel/types').File }
+ */
+export function js(source, options) {
+  return _parse(source, [ 'typescript' ], options);
+}
+
+/**
+ * @param { string } source
+ * @param { Overrides } [options]
+ *
+ * @return { import('@babel/types').File }
+ */
+export function jsx(source, options) {
+  return _parse(source, [ 'typescript', 'jsx' ], options);
+}
+
+/**
+ * @param { string } source
+ * @param { Overrides } [options]
+ *
+ * @return { import('@babel/types').File }
+ */
+export function dts(source, options) {
+  return _parse(source, [ [ 'typescript', { dts: true } ] ], options);
+}

package/lib/post-transform.js

@@ -18,7 +18,7 @@ import {
 /**
  * @param { { name: string, key?: { name?: string }, comments?: any[] } } m
  *
- * @return {boolean}
+ * @return { boolean }
  */
 function isPublic(m) {
 
@@ -34,10 +34,16 @@ function isPublic(m) {
 }
 
 /**
- * @param {string} src
- * @return {string}
+ * @param { string } src
+ * @param { { lax: boolean } } [options]
+ *
+ * @return { string }
  */
-export default function transform(src) {
+export default function transform(src, options) {
+
+  const {
+    lax = false
+  } = options || {};
 
   const ast = parseDts(src);
   const body = path(ast).get('program', 'body');
@@ -127,11 +133,11 @@ export default function transform(src) {
 
       const actualName = param.argument?.name || param.name;
 
-      if (actualName !== expectedName) {
+      if (!lax && isNamedParam(param) && actualName !== expectedName) {
         throw error(node, `documented parameter <${ expectedName }> differs from actual parameter <${ actualName }>`);
       }
 
-      filteredParams.push(param);
+      filteredParams.push({ ...param, name: expectedName });
       j++;
     }
 
@@ -141,9 +147,9 @@ export default function transform(src) {
   /**
    * Ensure optional args methods are properly escaped
    *
-   * @param {Path<any>} nodePath
+   * @param { Path<any> } nodePath
    *
-   * @return {any[]} replacements
+   * @return { any[] } replacements
    */
   function fixOptionalArgsMethods(nodePath) {
 
@@ -210,7 +216,8 @@ export default function transform(src) {
         variations.forEach((variation) => {
           const builder = {
             'RestElement': b.restElement,
-            'Identifier': b.identifier
+            'Identifier': b.identifier,
+            'ObjectPattern': b.objectPattern
           }[param.type];
 
           variation.push(builder.from(param));
@@ -291,9 +298,9 @@ export default function transform(src) {
    * type Woop = import('./Woop').default;
    * ```
    *
-   * @param {Path<any>} nodePath
+   * @param { Path<any> } nodePath
    *
-   * @return {any[]} replacements
+   * @return { any[] } replacements
    */
   function fixTypeExport(nodePath) {
 
@@ -314,9 +321,9 @@ export default function transform(src) {
   /**
    * Ensure that only documented method parameters are used.
    *
-   * @param {Path<any>} nodePath
+   * @param { Path<any> } nodePath
    *
-   * @return {boolean} true if modified
+   * @return { boolean } true if modified
    */
   function removeUnknownParams(nodePath) {
 
@@ -361,9 +368,9 @@ export default function transform(src) {
    * Our strategy is to parse for separate `@overlord` annotated tags,
    * use the meta-data, and generate a completely new method from it.
    *
-   * @param {Path<any>} nodePath
+   * @param { Path<any> } nodePath
    *
-   * @return {boolean} true if modified
+   * @return { boolean } true if modified
    */
   function generateOverloads(nodePath) {
 
@@ -502,10 +509,10 @@ declare function p${
 
       // remove full line including the non-TS tag
       if (
-        /class|constructor|template|method|typedef|property|this|overlord|overload/.test(tag.name) ||
+        /class|function|extends|type|constructor|template|method|typedef|property|this|overlord|overload/.test(tag.name) ||
         tag.param?.name?.includes('.')
       ) {
-        replacements.push([ { start: tag.start - 4, end: tag.end } ]);
+        replacements.push([ { start: Math.max(0, tag.start - 4), end: tag.end } ]);
 
         continue;
       }
@@ -552,7 +559,7 @@ declare function p${
   }
 
   /**
-   * @param {Path<any>} nodePath
+   * @param { Path<any> } nodePath
    */
   function cleanComments(nodePath) {
 
@@ -645,8 +652,8 @@ function traverse(path, cb) {
 
 
 /**
- * @param {any} node
- * @return {'TSDeclareMethod' | 'TSDeclareFunction' | 'TSFunctionType' | null}
+ * @param { any } node
+ * @return { 'TSDeclareMethod' | 'TSDeclareFunction' | 'TSFunctionType' | null }
  */
 function getFunctionKind(node) {
 
@@ -672,9 +679,9 @@ function getFunctionKind(node) {
 /**
  * Return host path for node (with attached comments).
  *
- * @param {Path<any>} nodePath
+ * @param { Path<any> } nodePath
  *
- * @return {Path<any>}
+ * @return { Path<any> }
  */
 function getHostPath(nodePath) {
   return [ 'ExportDefaultDeclaration', 'ExportNamedDeclaration' ].includes(nodePath.parentPath.value.type)
@@ -682,10 +689,14 @@ function getHostPath(nodePath) {
     : nodePath;
 }
 
+function isNamedParam(param) {
+  return param.type === 'Identifier' || param.type == 'RestElement';
+}
+
 /**
  * @param { { loc: { start: { line: number, column: number } } } } node
  *
- * @return {Error}
+ * @return { Error }
  */
 function error(node, message) {
 

package/lib/pre-transform.js

@@ -1,5 +1,14 @@
 import { matcher, parse, path, print } from './util.js';
 
+/**
+ * @template T
+ * @typedef { import('./util.js').Path<T> } Path
+ */
+
+import {
+  parse as parseJSDoc
+} from './parsers/jsdoc.js';
+
 import {
   builders as b
 } from 'ast-types';
@@ -149,13 +158,14 @@ function splitComment(cls) {
 }
 
 /**
- * @param {string} src
+ * @param { string } src
+ * @param { { jsx?: boolean } } [parseOptions]
  *
  * @return {string}
  */
-export default function transform(src) {
+export default function transform(src, parseOptions = {}) {
 
-  const ast = parse(src);
+  const ast = parse(src, parseOptions);
   const body = path(ast).get('program', 'body');
 
   const inheritsImports = findInheritsImports(body);
@@ -316,7 +326,14 @@ function findConstructors(nodes) {
 
     const name = identifier.value.name;
 
-    if (/^[A-Z]/.test(name)) {
+    // a class component
+    //
+    // * must start with upper letter
+    // * must not be tagged as @function
+    // * must not return something
+    //
+    if (isClassName(name) && !isFunctionTagged(node) && !isReturning(ctor)) {
+
       return {
         name,
         ctor,
@@ -326,6 +343,52 @@ function findConstructors(nodes) {
   }).filter(n => n);
 }
 
+/**
+ * @param { string } name
+ *
+ * @return {boolean}
+ */
+function isClassName(name) {
+
+  return /^[A-Z]/.test(name);
+}
+
+/**
+ * @param { Path<any> } nodePath
+ *
+ * @return { boolean }
+ */
+function isFunctionTagged(nodePath) {
+  const commentPaths = nodePath.get('comments');
+
+  // last comment is significant
+  const commentPath = commentPaths?.value && commentPaths.get(commentPaths.value.length - 1) || { value: null };
+
+  const doc = commentPath?.value?.value?.replace(/\n\s+/g, '\n ') || '';
+
+  if (!doc) {
+    return false;
+  }
+
+  const functionTagged = parseJSDoc(doc).some(tag => tag.name === 'function');
+
+  return functionTagged;
+}
+
+/**
+ * @param { Path<any> } ctorPath
+ *
+ * @return { boolean }
+ */
+function isReturning(ctorPath) {
+
+  const returnStatements = matcher`
+    return $1;
+  `;
+
+  return returnStatements(ctorPath.get('body', 'body')).length > 0;
+}
+
 function findStaticMembers(cls, nodes) {
 
   const names = matcher`

package/lib/util.js

@@ -7,7 +7,6 @@ import { Path as PathConstructor } from 'ast-types';
  */
 
 import * as typescriptParser from './parsers/typescript.js';
-import * as typescriptDtsParser from './parsers/typescript-dts.js';
 
 const DBG = /match/.test(process?.env?.LOG_DEBUG);
 
@@ -50,20 +49,30 @@ export function hasProperty(obj, property) {
 }
 
 /**
- * @param {string} code
+ * @param { string } code
+ * @param { { jsx?: boolean } } [parseOptions]
  *
  * @return {any}
  */
-export function parse(code) {
+export function parse(code, parseOptions) {
+  const parser = {
+    parse: parseOptions?.jsx ? typescriptParser.jsx : typescriptParser.js
+  };
+
   return recastParse(code, {
-    parser: typescriptParser,
+    parser,
     ...formatOptions
   });
 }
 
 export function parseDts(code) {
+
+  const parser = {
+    parse: typescriptParser.dts
+  };
+
   return recastParse(code, {
-    parser: typescriptDtsParser,
+    parser,
     ...formatOptions
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bio-dts",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Generate sane and clean types from JavaScript sources",
   "type": "module",
   "bin": "bin/cmd.js",
@@ -10,11 +10,14 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "all": "run-s lint check-types test test:dts",
+    "all": "run-s lint check-types test test:dts:*",
     "lint": "eslint .",
     "check-types": "tsc --noEmit",
     "test": "mocha test",
-    "test:dts": "node bin/cmd.js --outDir test/fixtures/snapshots -r test/fixtures"
+    "test:dts:default": "node bin/cmd.js --outDir test/fixtures/snapshots/default -r test/fixtures/pre",
+    "test:dts:jsx": "node bin/cmd.js --jsx preserve --outDir test/fixtures/snapshots/jsx -r test/fixtures/jsx",
+    "test:dts:declaration-map": "node bin/cmd.js --declarationMap --outDir test/fixtures/snapshots/declaration-map -r test/fixtures/pre",
+    "test:dts:lax": "node bin/cmd.js --declarationMap --lax --outDir test/fixtures/snapshots/lax -r test/fixtures/lax"
   },
   "repository": {
     "type": "git",
@@ -23,20 +26,20 @@
   "author": "Nico Rehwaldt",
   "license": "MIT",
   "dependencies": {
-    "@babel/parser": "^7.26.3",
-    "recast": "^0.23.9",
+    "@babel/parser": "^7.28.4",
+    "recast": "^0.23.11",
     "tiny-glob": "^0.2.9"
   },
   "devDependencies": {
-    "@babel/types": "^7.23.9",
+    "@babel/types": "^7.28.4",
     "@types/mocha": "^10.0.10",
     "@types/node": "^20.17.12",
     "chai": "^5.1.2",
     "eslint": "^8.56.0",
     "eslint-plugin-bpmn-io": "^1.0.0",
     "mocha": "^10.8.2",
-    "npm-run-all2": "^7.0.2",
-    "typescript": "^5.7.3"
+    "npm-run-all2": "^8.0.4",
+    "typescript": "^5.9.2"
   },
   "files": [
     "bin",

package/lib/parsers/typescript-dts.js

@@ -1,19 +0,0 @@
-import { parser } from 'recast/parsers/babel.js';
-import getBabelOptions from 'recast/parsers/_babel_options.js';
-
-/**
- * @typedef { import('recast/parsers/_babel_options.js').Overrides } Overrides
- */
-
-/**
- * @param {string} source
- * @param {Overrides} [options]
- *
- * @return {import('@babel/types').File}
- */
-export function parse(source, options) {
-
-  const babelOptions = getBabelOptions.default(options);
-  babelOptions.plugins.push([ 'typescript', { dts: true } ]);
-  return parser.parse(source, babelOptions);
-}