bio-dts 0.13.0 → 0.14.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023-present Nico Rehwaldt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -58,3 +58,8 @@ generateTypes(files, {
   outDir: 'dist'
 }, typescript);
 ```
+
+
+## License
+
+MIT

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,37 +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);
 
     if (fileName.toLowerCase().endsWith('.d.ts')) {
       try {
-        text = postTransform(text);
+        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 (isNamedParam(param) && 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) {
 
@@ -292,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) {
 
@@ -315,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) {
 
@@ -362,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) {
 
@@ -503,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;
       }
@@ -553,7 +559,7 @@ declare function p${
   }
 
   /**
-   * @param {Path<any>} nodePath
+   * @param { Path<any> } nodePath
    */
   function cleanComments(nodePath) {
 
@@ -646,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) {
 
@@ -673,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)
@@ -690,7 +696,7 @@ function isNamedParam(param) {
 /**
  * @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,9 +1,10 @@
 {
   "name": "bio-dts",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Generate sane and clean types from JavaScript sources",
   "type": "module",
-  "bin": "bin/cmd.js",
+  "bin": "./bin/cmd.js",
+  "main": "./index.js",
   "exports": {
     ".": "./index.js",
     "./lib/*.js": "./lib/*.js",
@@ -14,8 +15,10 @@
     "lint": "eslint .",
     "check-types": "tsc --noEmit",
     "test": "mocha test",
-    "test:dts:default": "node bin/cmd.js --outDir test/fixtures/snapshots/default -r test/fixtures",
-    "test:dts:declaration-map": "node bin/cmd.js --declarationMap --outDir test/fixtures/snapshots/declaration-map -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",
@@ -24,21 +27,22 @@
   "author": "Nico Rehwaldt",
   "license": "MIT",
   "dependencies": {
-    "@babel/parser": "^7.26.3",
-    "recast": "^0.23.9",
+    "@babel/parser": "^7.28.5",
+    "recast": "^0.23.11",
     "tiny-glob": "^0.2.9"
   },
   "devDependencies": {
-    "@babel/types": "^7.23.9",
+    "@babel/types": "^7.28.5",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^20.17.12",
-    "chai": "^5.1.2",
+    "@types/node": "^24.10.4",
+    "chai": "^6.2.1",
     "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"
+    "mocha": "^11.7.5",
+    "npm-run-all2": "^8.0.4",
+    "typescript": "^5.9.3"
   },
+  "sideEffects": false,
   "files": [
     "bin",
     "lib",

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);
-}