bio-dts 0.2.1 → 0.4.0

package/bin/cmd.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import ts from 'typescript';
+import Module from 'node:module';
 
 import glob from 'tiny-glob';
 
@@ -10,6 +10,9 @@ import fs from 'node:fs';
 import generateTypes from '../lib/generate-types.js';
 
 async function run() {
+
+  const ts = getTypescript();
+
   const args = process.argv.slice(2);
 
   const {
@@ -44,18 +47,12 @@ async function run() {
 
   for (const fileName of fileNames) {
 
-    try {
-      if (fs.statSync(fileName).isDirectory) {
-
-        const globbedFiles = await glob(globPattern, { cwd: fileName, filesOnly: true });
-
-        files.push(...globbedFiles.map(f => path.join(fileName, f)));
-      } else {
-        files.push(fileName);
-      }
-    } catch (err) {
+    if (isDir(fileName)) {
+      const globbedFiles = await glob(globPattern, { cwd: fileName, filesOnly: true });
 
-      // ignore
+      files.push(...globbedFiles.map(f => path.join(fileName, f)));
+    } else {
+      files.push(fileName);
     }
   }
 
@@ -72,6 +69,34 @@ async function run() {
   console.log('Done.');
 }
 
+function isDir(fileName) {
+
+  try {
+    return fs.statSync(fileName).isDirectory();
+  } catch (err) {
+
+    // ignore
+    return false;
+  }
+}
+
+function getTypescript() {
+
+  const cwd = process.cwd();
+
+  const createRequire = Module.createRequire || Module.createRequireFromPath;
+
+  const requireLocal = createRequire(
+    path.join(cwd, '__placeholder__.js')
+  );
+
+  try {
+    return requireLocal('typescript');
+  } catch (err) {
+    throw new Error(`failed to load <typescript> from <${ cwd }>`);
+  }
+}
+
 run().catch(err => {
   console.error(err);
 

package/lib/parsers/jsdoc.js

@@ -0,0 +1,159 @@
+function skipWhitespace(str, pos) {
+  let i = pos;
+
+  let char;
+  for (; (char = str.charAt(i)) && char !== '\n' && /\s/.test(char); i++) {
+
+    // ignore
+  }
+
+  return i;
+}
+
+function skipText(str, pos) {
+  let i = pos;
+  let char;
+
+  for (; (char = str.charAt(i)) && /\S/.test(char); i++) {
+
+    // ignore
+  }
+
+  return i;
+}
+
+function findClose(str, pos, openChar, closeChar) {
+
+  if (str.charAt(pos) !== openChar) {
+    return false;
+  }
+
+  let char;
+
+  let i = pos;
+
+  let open = 0;
+
+  while ((char = str.charAt(i++))) {
+    switch (char) {
+    case openChar:
+      open++;
+      break;
+    case closeChar:
+      if (--open === 0) {
+        return {
+          start: pos,
+          end: i,
+          value: str.substring(pos, i)
+        };
+      }
+      break;
+    }
+  }
+}
+
+function findNewline(str, pos) {
+
+  let i = pos;
+  let char;
+
+  for (; (char = str.charAt(i)) && /[^\n]/.test(char); i++) {
+
+    // ignore
+  }
+
+  return i;
+}
+
+export function parse(str) {
+
+  var i = 0, j;
+
+  var tags = [];
+  var tag;
+
+  while ((i = str.indexOf('@', i)) && i !== -1) {
+    j = i + 1;
+    tag = {
+      start: i
+    };
+
+    // parse tag name
+    j = skipText(str, i);
+
+    tag.name = str.substring(i + 1, j);
+
+    i = skipWhitespace(str, j);
+
+    // parse type
+    if ([ 'param', 'return', 'returns', 'typedef' ].includes(tag.name)) {
+
+      let match = findClose(str, i, '{', '}');
+
+      if (match) {
+        tag.type = match;
+
+        i = skipWhitespace(str, match.end);
+      }
+    }
+
+    // parse param
+    if ([ 'param', 'typedef' ].includes(tag.name)) {
+
+      let match = tag.name === 'param' && findClose(str, i, '[', ']');
+
+      if (match) {
+        tag.param = match;
+
+        const contents = tag.param.contents = str.substring(match.start + 1, match.end - 1);
+        const idxEq = contents.indexOf('=');
+
+        tag.param.name = idxEq !== -1 ? contents.substring(0, idxEq) : contents;
+      } else {
+        j = skipText(str, i);
+
+        tag.param = {
+          start: i,
+          end: j,
+          name: str.substring(i, j),
+          value: str.substring(i, j)
+        };
+      }
+
+      i = skipWhitespace(str, tag.param.end);
+    }
+
+    j = findNewline(str, i);
+
+    tag.description = i !== j ? {
+      start: i,
+      end: j,
+      value: str.substring(i, j)
+    } : null;
+
+    tag.end = j;
+
+    tags.push(tag);
+
+    i = j + 1;
+  }
+
+  return tags;
+}
+
+export function dbg(str, pos) {
+
+  const arr = Array.from(str);
+
+  arr.splice(pos, 0, '|');
+
+  return arr.join('');
+}
+
+export function replace(str, range, contents) {
+  const arr = Array.from(str);
+
+  arr.splice(range.start, range.end - range.start, contents);
+
+  return arr.join('');
+}

package/lib/post-transform.js

@@ -1,5 +1,14 @@
 import { isArray, isNode, keys, parseDts, path, print } from './util.js';
 
+import {
+  builders as b
+} from 'ast-types';
+
+import {
+  parse as parseJSDoc,
+  replace as replaceJSDoc
+} from './parsers/jsdoc.js';
+
 
 /**
  * @param { { name: string, comments?: any[] } }
@@ -28,41 +37,265 @@ export default function transform(src) {
   const ast = parseDts(src);
   const body = path(ast).get('program', 'body');
 
+  const replacements = [];
+
+  function replace(path, ...args) {
+    replacements.push([ path, args ]);
+
+    return false;
+  }
+
+  function keepCommentParams(commentPath, params) {
+
+    const replacements = [];
+
+    const comment = commentPath.value;
+
+    const doc = comment.value.replace(/\n\s+/g, '\n ');
+    const tags = parseJSDoc(doc);
+
+    for (const tag of tags) {
+
+      // remove param not mentioned anymore
+      if (tag.name === 'param' && params.every(p => p.name !== tag.param.name)) {
+        replacements.push([ { start: tag.start - 4, end: tag.end } ]);
+
+        continue;
+      }
+    }
+
+    const newDoc = replacements.slice().reverse().reduce((newDoc, r) => {
+
+      const [ { start, end }, replacement = '' ] = r;
+
+      return replaceJSDoc(newDoc, { start, end }, replacement);
+    }, doc);
+
+    const builder = {
+      'CommentBlock': b.commentBlock,
+      'CommentLine': b.commentLine
+    }[comment.type];
+
+    return cleanComment(builder.from({
+      ...comment,
+      value: newDoc
+    }));
+  }
+
+  function fixOptionalArgsMethods(nodePath) {
+
+    const {
+      value: node
+    } = nodePath;
+
+    if (node.type !== 'TSDeclareMethod' && node.type !== 'TSDeclareFunction') {
+      return;
+    }
+
+    const hostPath = nodePath.parentPath.value.type === 'ExportNamedDeclaration'
+      ? nodePath.parentPath
+      : nodePath;
+
+    const {
+      variations
+    } = node.params.slice().reverse().reduce((res, param) => {
+
+      let {
+        required,
+        variations
+      } = res;
+
+      // required before optional
+      if (param.optional && required) {
+        variations = [
+          ...variations.map(v => v.slice()),
+          ...variations.map(v => v.slice())
+        ];
+
+        variations.forEach((variation, idx) => {
+
+          if (idx < variations.length / 2) {
+            variation.push(b.identifier.from({
+              ...param,
+              optional: false
+            }));
+          }
+        });
+      } else {
+
+        if (!param.optional) {
+          required = true;
+        }
+
+        variations.forEach((variation) => {
+          const builder = {
+            'RestElement': b.restElement,
+            'Identifier': b.identifier
+          }[param.type];
+
+          variation.push(builder.from(param));
+        });
+      }
+
+      return {
+        required,
+        variations
+      };
+    }, {
+      variations: [
+        []
+      ],
+      required: false
+    });
+
+    if (variations.length === 1) {
+      return;
+    }
+
+    const commentPaths = hostPath.get('comments');
+
+    // last comment is significant
+    const commentPath = commentPaths?.value && commentPaths.get(commentPaths.value.length - 1) || { value: null };
+
+    const replacements = variations.slice().reverse().map(variation => {
+
+      const builder = {
+        'TSDeclareFunction': b.tsDeclareFunction,
+        'TSDeclareMethod': b.tsDeclareMethod
+      }[node.type];
+
+      const variationComments = commentPath.value ? [ keepCommentParams(commentPath, variation) ] : [ ];
+
+      const newNode = builder.from({
+        ...node,
+        params: variation.slice().reverse(),
+        comments: hostPath === nodePath ? variationComments : []
+      });
+
+      return (
+        hostPath === nodePath
+          ? newNode
+          : b.exportNamedDeclaration.from({
+            ...hostPath.value,
+            declaration: newNode,
+            comments: variationComments
+          })
+      );
+    });
+
+    replace(hostPath, ...replacements);
+
+    return replacements;
+  }
+
+
+  function cleanComment(comment) {
+
+    const replacements = [];
+
+    const doc = comment.value.replace(/\n\s+/g, '\n ');
+    const tags = parseJSDoc(doc);
+
+    for (const tag of tags) {
+
+      // remove full line including the non-TS tag
+      if (/class|constructor|template|method|typedef/.test(tag.name)) {
+        replacements.push([ { start: tag.start - 4, end: tag.end } ]);
+
+        continue;
+      }
+
+      if (tag.type) {
+        replacements.push([ { start: tag.type.start - 1, end: tag.type.end }, '' ]);
+      }
+
+      if (tag.param) {
+
+        // [foo=10] => foo
+        replacements.push([ tag.param, tag.param.name ]);
+      }
+    }
+
+    const newDoc = replacements.slice().reverse().reduce((newDoc, r) => {
+
+      const [ { start, end }, replacement = '' ] = r;
+
+      return replaceJSDoc(newDoc, { start, end }, replacement);
+    }, doc);
+
+    // remove entirely, if empty
+    if (!newDoc.replace(/[/*\s]/g, '')) {
+      return null;
+    } else {
+      return b.commentBlock.from({
+        type: 'CommentBlock',
+        leading: true,
+        value: newDoc
+      });
+    }
+  }
+
+  /**
+   * @param {import('./util.js').Path} nodePath
+   */
+  function cleanComments(nodePath) {
+
+    // clean JSDoc comments: remove annotation, fixup type parameters
+    const comments = nodePath.get('comments') || { value: [] };
+
+    for (const key of keys(comments.value || []).reverse()) {
+      const comment = comments.get(key);
+
+      const newComment = cleanComment(comment.value);
+      if (newComment) {
+        replace(comment, newComment);
+      } else {
+        replace(comment);
+      }
+    }
+  }
+
   traverse(body, function(path) {
 
+    const {
+      value
+    } = path;
+
     // filter private members
-    if (!isPublic(path.value)) {
-      path.replace();
+    if (!isPublic(value)) {
+      return replace(path);
     }
 
-    // TODO(nikku): transform illegal typescript methods into override calls
+    if (fixOptionalArgsMethods(path)) {
+      return false;
+    }
 
-    // TODO(nikku): remove annotations
-    //
-    // * @typedef
-    // * @class
-    // * @constructor
+    cleanComments(path);
   });
 
+  for (const [ path, args ] of replacements) {
+    path.replace(...args);
+  }
+
   return print(ast).code;
 }
 
 function traverse(path, cb) {
-  cb(path);
+  const val = path.value;
 
-  if (path.parentPath) {
-    const val = path.value;
-
-    if (!isNode(val) && !isArray(val)) {
-      return;
-    }
+  if (!isNode(val) && !isArray(val)) {
+    return;
+  }
 
-    for (const key of keys(val).reverse()) {
-      if ([ 'loc', 'start', 'end' ].includes(key)) {
-        continue;
-      }
+  if (cb(path) === false) {
+    return;
+  }
 
-      traverse(path.get(key), cb);
+  for (const key of keys(val).reverse()) {
+    if ([ 'loc', 'start', 'end' ].includes(key)) {
+      continue;
     }
+
+    traverse(path.get(key), cb);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bio-dts",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Generate sane and clean types from JavaScript sources",
   "type": "module",
   "main": "index.js",
@@ -16,14 +16,14 @@
   "dependencies": {
     "@babel/parser": "^7.21.2",
     "recast": "^0.22.0",
-    "tiny-glob": "^0.2.9",
-    "typescript": "^4.9.5"
+    "tiny-glob": "^0.2.9"
   },
   "devDependencies": {
     "chai": "^4.3.7",
     "eslint": "^8.36.0",
     "eslint-plugin-bpmn-io": "^1.0.0",
-    "mocha": "^10.2.0"
+    "mocha": "^10.2.0",
+    "typescript": "^5.0.2"
   },
   "files": [
     "bin",