bio-dts 0.6.1 → 0.8.0

package/README.md

@@ -6,7 +6,9 @@ Utilities to generate sane and clean type definitions from JavaScript files.
 
 ## About
 
-This module provides `pre` and `post` processing helpers to a type definition pipeline, as well as a simple [generator cli](#usage).
+This module provides `pre` and `post` processing helpers to a type definition pipeline.
+
+You can use it [via API](#api) or through a simple [generator cli](#usage).
 
 
 ## Usage

package/lib/parsers/jsdoc.js

@@ -86,7 +86,7 @@ export function parse(str) {
     i = skipWhitespace(str, j);
 
     // parse type
-    if ([ 'param', 'return', 'returns', 'typedef' ].includes(tag.name)) {
+    if ([ 'param', 'return', 'returns', 'typedef', 'template' ].includes(tag.name)) {
 
       let match = findClose(str, i, '{', '}');
 
@@ -98,7 +98,7 @@ export function parse(str) {
     }
 
     // parse param
-    if ([ 'param', 'typedef' ].includes(tag.name)) {
+    if ([ 'param', 'typedef', 'template' ].includes(tag.name)) {
 
       let match = tag.name === 'param' && findClose(str, i, '[', ']');
 

package/lib/post-transform.js

@@ -82,6 +82,56 @@ export default function transform(src) {
     }));
   }
 
+  function getDocumentedParams(node, params = [], comment = null) {
+
+    if (!comment) {
+      return params;
+    }
+
+    const doc = comment.value.replace(/\n\s+/g, '\n ');
+
+    // parse known parameters
+    // ignore hierarchical (sub-type) params
+    const knownParams =
+      parseJSDoc(doc)
+        .filter(tag => tag.name === 'param' && !tag.param.name.includes('.'))
+        .map(tag => tag.param.name);
+
+    if (!knownParams.length) {
+      return params;
+    }
+
+    let i = 0;
+    let j = 0;
+
+    const filteredParams = [];
+
+    while (j < knownParams.length) {
+
+      let expectedName = knownParams[j];
+      let param = params[i++];
+
+      if (!param) {
+        throw error(node, `documented parameter <${ expectedName }> not found`);
+      }
+
+      if (param.name === 'this') {
+        filteredParams.push(param);
+        continue;
+      }
+
+      const actualName = param.argument?.name || param.name;
+
+      if (actualName !== expectedName) {
+        throw error(node, `documented parameter <${ expectedName }> differs from actual parameter <${ actualName }>`);
+      }
+
+      filteredParams.push(param);
+      j++;
+    }
+
+    return filteredParams;
+  }
 
   /**
    * Ensure optional args methods are properly escaped
@@ -96,36 +146,34 @@ export default function transform(src) {
       value: node
     } = nodePath;
 
-    const fnDeclaration = (
-      node.type === 'TSDeclareMethod' ||
-      node.type === 'TSDeclareFunction'
-    );
+    const functionKind = getFunctionKind(node);
 
-    const fnDefinition = (
-      node?.typeAnnotation?.typeAnnotation?.type === 'TSFunctionType'
-    );
-
-    if (!fnDeclaration && !fnDefinition) {
+    if (!functionKind) {
       return;
     }
 
-    const params = fnDeclaration
-      ? node.params
-      : node?.typeAnnotation?.typeAnnotation?.parameters;
+    const params = functionKind === 'TSFunctionType'
+      ? node.typeAnnotation?.typeAnnotation?.parameters
+      : node.params;
+
+    const typeParameters = functionKind === 'TSFunctionType'
+      ? node.typeAnnotation?.typeAnnotation?.typeParameters
+      : node.typeParameters;
+
+    const returnType = functionKind === 'TSFunctionType'
+      ? node.typeAnnotation?.typeAnnotation?.typeAnnotation
+      : node.returnType;
 
-    const returnType = fnDeclaration
-      ? node.returnType
-      : node?.typeAnnotation?.typeAnnotation?.typeAnnotation;
+    const hostPath = getHostPath(nodePath);
 
-    const hostPath = (
-      [ 'ExportDefaultDeclaration', 'ExportNamedDeclaration' ].includes(nodePath.parentPath.value.type)
-        ? nodePath.parentPath
-        : nodePath
-    );
+    const commentPaths = hostPath.get('comments');
+
+    // last comment is significant
+    const commentPath = commentPaths?.value && commentPaths.get(commentPaths.value.length - 1) || { value: null };
 
     const {
       variations
-    } = params.slice().reverse().reduce((res, param) => {
+    } = getDocumentedParams(hostPath.value, params, commentPath.value).slice().reverse().reduce((res, param) => {
 
       let {
         required,
@@ -179,11 +227,6 @@ export default function transform(src) {
       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 = {
@@ -207,7 +250,10 @@ export default function transform(src) {
         returnType: returnType ? b.tsTypeAnnotation.from({
           ...returnType
         }) : null,
-        comments: hostPath === nodePath ? variationComments : []
+        comments: hostPath === nodePath ? variationComments : [],
+        typeParameters: typeParameters ? b.tsTypeParameterDeclaration.from({
+          ...typeParameters
+        }) : null
       });
 
       return (
@@ -227,6 +273,216 @@ export default function transform(src) {
   }
 
 
+  /**
+   * Ensures we don't re-export external declarations
+   *
+   * @example
+   *
+   * ```javascript
+   * export type Woop = import('./Woop').default;
+   *
+   * // ===>
+   *
+   * type Woop = import('./Woop').default;
+   * ```
+   *
+   * @param {import('./util.js').Path} nodePath
+   *
+   * @return {any[]} replacements
+   */
+  function fixTypeExport(nodePath) {
+
+    const {
+      value: node
+    } = nodePath;
+
+    if (
+      node.type !== 'ExportNamedDeclaration' ||
+      node.declaration?.typeAnnotation?.type !== 'TSImportType'
+    ) {
+      return;
+    }
+
+    replace(nodePath, nodePath.get('declaration').value);
+  }
+
+  /**
+   * Ensure that only documented method parameters are used.
+   *
+   * @param {Path} nodePath
+   *
+   * @return {boolean} true if modified
+   */
+  function removeUnknownParams(nodePath) {
+
+    const {
+      value: node
+    } = nodePath;
+
+    const functionKind = getFunctionKind(node);
+
+    if (!functionKind) {
+      return;
+    }
+
+    const params = functionKind === 'TSFunctionType'
+      ? nodePath.get('typeAnnotation', 'typeAnnotation', 'parameters')
+      : nodePath.get('params');
+
+    const hostPath = getHostPath(nodePath);
+
+    const commentPaths = hostPath.get('comments');
+
+    // last comment is significant
+    const commentPath = commentPaths?.value && commentPaths.get(commentPaths.value.length - 1) || { value: null };
+
+    const knownParams = getDocumentedParams(hostPath.value, params.value, commentPath.value);
+
+    let replaced = false;
+
+    for (const idx in params.value || []) {
+      if (!knownParams[idx]) {
+        replace(params.get(idx));
+        replaced = true;
+      }
+    }
+
+    return replaced;
+  }
+
+  /**
+   * Generate method overloads based on `@overlord` annotated JSDoc comments.
+   *
+   * Our strategy is to parse for separate `@overlord` annotated tags,
+   * use the meta-data, and generate a completely new method from it.
+   *
+   * @param {Path} nodePath
+   *
+   * @return {boolean} true if modified
+   */
+  function generateOverloads(nodePath) {
+
+    const {
+      value: node
+    } = nodePath;
+
+    const functionKind = getFunctionKind(node);
+
+    if (!functionKind) {
+      return;
+    }
+
+    const hostPath = getHostPath(nodePath);
+
+    const commentPaths = hostPath.get('comments');
+
+    const comments = (commentPaths?.value || []);
+
+    // scan for potential overloads
+    const overloads = comments.reduce((overloads, comment, idx) => {
+      const commentText = comment.value;
+
+      if (commentText.includes('@overlord') || idx === comments.length - 1) {
+        const tags = parseJSDoc(comment.value);
+
+        const paramTags = tags.filter(t => t.name === 'param');
+        const templateTags = tags.filter(t => t.name === 'template');
+        const returnTags = tags.filter(t => t.name === 'return' || t.name === 'returns');
+
+        if (returnTags.length > 1) {
+          throw error(hostPath.value, 'must specify zero or one @return(s) type in @overload fn');
+        }
+
+        return [
+          ...overloads,
+          {
+            comment,
+            templateTags,
+            paramTags,
+            returnTag: returnTags[0]
+          }
+        ];
+      }
+
+      return overloads;
+    }, []);
+
+    if (overloads.length < 2) {
+      return;
+    }
+
+    const replacements = overloads.slice().reverse().map(overload => {
+
+      const {
+        comment,
+        templateTags,
+        paramTags,
+        returnTag
+      } = overload;
+
+      const methodCode = `/*${cleanComment(comment).value}*/
+declare function p${
+  templateTags.length ? '<' + templateTags.map(
+    t => [
+      t.param.name,
+      t.type ? 'extends ' + t.type.value.slice(1, -1) : null
+    ].filter(f => f).join(' ')
+  ).join(',') + '>' : ''
+}(${
+  paramTags.map(p => {
+
+    return [
+      p.param.name,
+      p.param.value.startsWith('[') ? '?' : null,
+      ': ',
+      p.type.value.slice(1, -1)
+    ].filter(f => f).join('');
+  }).join(',')
+}) : ${ returnTag ? returnTag.type.value.slice(1, -1) : 'void' };`;
+
+      const func = parseDts(methodCode).program.body[0];
+
+      const builder = {
+        'ClassProperty': b.tsDeclareMethod,
+        'TSDeclareFunction': b.tsDeclareFunction,
+        'TSDeclareMethod': b.tsDeclareMethod
+      }[node.type];
+
+      const hostBuilder = {
+        'ExportNamedDeclaration': b.exportNamedDeclaration,
+        'ExportDefaultDeclaration': b.exportDefaultDeclaration
+      }[hostPath.value.type];
+
+      const newNode = builder.from({
+        key: node.key,
+        params: func.params,
+        id: node.id,
+        declare: node.declare || false,
+        returnType: func.returnType ? b.tsTypeAnnotation.from({
+          ...func.returnType
+        }) : null,
+        comments: hostPath === nodePath ? func.comments : [],
+        typeParameters: func.typeParameters ? b.tsTypeParameterDeclaration.from({
+          ...func.typeParameters
+        }) : null
+      });
+
+      return (
+        hostBuilder
+          ? hostBuilder.from({
+            ...hostPath.value,
+            declaration: newNode,
+            comments: func.comments
+          })
+          : newNode
+      );
+    });
+
+    replace(hostPath, ...replacements);
+
+    return replacements;
+  }
+
   function cleanComment(comment) {
 
     const replacements = [];
@@ -237,7 +493,10 @@ export default function transform(src) {
     for (const tag of tags) {
 
       // remove full line including the non-TS tag
-      if (/class|constructor|template|method|typedef|property/.test(tag.name)) {
+      if (
+        /class|constructor|template|method|typedef|property|this|overlord/.test(tag.name) ||
+        tag.param?.name?.includes('.')
+      ) {
         replacements.push([ { start: tag.start - 4, end: tag.end } ]);
 
         continue;
@@ -304,20 +563,27 @@ export default function transform(src) {
       return replace(path);
     }
 
+    if (generateOverloads(path)) {
+      return false;
+    }
+
     if (fixOptionalArgsMethods(path)) {
       return false;
     }
 
+    removeUnknownParams(path);
     cleanComments(path);
+
+    fixTypeExport(path);
   });
 
   for (const [ path, args ] of replacements) {
     try {
       path.replace(...args);
     } catch (err) {
-      console.error('Failed to replace path', path, ...args);
+      console.error('Failed to replace path', path, ...args, err);
 
-      throw err;
+      throw error(path.value, 'failed to replace path: ' + err.message);
     }
   }
 
@@ -342,4 +608,61 @@ function traverse(path, cb) {
 
     traverse(path.get(key), cb);
   }
+}
+
+
+/**
+ * @param {any} node
+ * @return {'TSDeclareMethod' | 'TSDeclareFunction' | 'TSFunctionType' | null}
+ */
+function getFunctionKind(node) {
+
+  if (
+    node.type === 'TSDeclareMethod'
+  ) {
+    return 'TSDeclareMethod';
+  }
+
+  if (node.type === 'TSDeclareFunction') {
+    return 'TSDeclareFunction';
+  }
+
+  if (
+    node.typeAnnotation?.typeAnnotation?.type === 'TSFunctionType'
+  ) {
+    return 'TSFunctionType';
+  }
+
+  return null;
+}
+
+/**
+ * Return host path for node (with attached comments).
+ *
+ * @param {Path} nodePath
+ *
+ * @return {Path}
+ */
+function getHostPath(nodePath) {
+  return [ 'ExportDefaultDeclaration', 'ExportNamedDeclaration' ].includes(nodePath.parentPath.value.type)
+    ? nodePath.parentPath
+    : nodePath;
+}
+
+/**
+ * @param {Node} node
+ *
+ * @return {string}
+ */
+function error(node, message) {
+
+  const {
+    loc: {
+      start
+    }
+  } = node;
+
+  const loc = `[line ${start.line + 1}, column ${start.column + 1}]`;
+
+  return new Error(`${message} ${loc}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bio-dts",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Generate sane and clean types from JavaScript sources",
   "type": "module",
   "main": "index.js",