@runtime-type-inspector/transpiler 2.2.2 → 2.2.4

package/index.mjs

@@ -1,11 +1,47 @@
 import { parse } from '@babel/parser';
 import ts from 'typescript';
 
+/**
+ * @todo expandTypeDepFree doesn't support "complicated" types.
+ * For actual builds, we use expandType() anyway (which is based on TypeScript).
+ * But since TypeScript is a huge dependency, I'm looking into BabelFlow/BabelTypescript parser.
+ * Comparing AST's like this usually helps to find bugs or potential issues,
+ * while we can benchmark for best performance too.
+ * @example
+ * const tooComplex = 'Array<string|{chunks?: undefined|Array<{language: string|null, timestamp: Array<number|null>, text: string}>}>';
+ * console.log(expandTypeDepFree(tooComplex));
+ */
+/**
+ * @typedef {object} ExpandTypeReturnValue
+ * @property {'array' | 'union' | 'record' | 'tuple' | 'object' | 'promise' | 'typeof'} type - The type.
+ * @property {object | string} [elementType] - For Array.
+ * @property {object | string} [key] - For Record<key, val>
+ * @property {object | string} [val] - For Record<key, val>
+ * @property {(object | string)[]} [members] - For unions.
+ * @property {object | string} [properties] - For objects.
+ * @property {(object | string)[]} [elements] - For tuples.
+ * @property {object | string} [argument] - For typeof.
+ */
+/**
+ * 'DepFree' refers to the fact that this function has no dependencies,
+ * while `expandType` depends on TypeScript itself for maximum compatibility.
+ * @example
+ * expandTypeDepFree('(123)                   '); // Outputs: '123'
+ * expandTypeDepFree('Array<number>           '); // Outputs: { type: 'array', elementType: 'number' }
+ * expandTypeDepFree('Array<(123) >           '); // Outputs: { type: 'array', elementType: '123' }
+ * expandTypeDepFree('  ( ( 123 ) )           '); // Outputs: '123'
+ * expandTypeDepFree('  (string ) |(number )  '); // Outputs: { type: 'union', members: ['string', 'number'] }
+ * expandTypeDepFree(' ((  Object  ) )        '); // Outputs: { type: 'object', properties: {} }
+ * @param {string} type - The input type to expand.
+ * @returns {string | ExpandTypeReturnValue} Object containing parsed information from type string.
+ */
 function expandTypeDepFree(type) {
   type = type.trim();
+  // '(123)' -> '123'
   while (!type.includes('|') && type[0] === '(' && type[type.length - 1] === ')') {
     type = type.slice(1, -1).trim();
   }
+  // (1) Rest parameters like ...string
   if (type[0] === '.' && type[1] === '.' && type[2] === '.') {
     const elementType = type.slice(3);
     return {
@@ -13,6 +49,8 @@ function expandTypeDepFree(type) {
       elementType
     };
   }
+  // (2)
+  // Array<...>
   if (type.startsWith("Array<") && type.endsWith('>')) {
     const typeSlice = type.slice(6, -1);
     const elementType = expandTypeDepFree(typeSlice);
@@ -21,6 +59,7 @@ function expandTypeDepFree(type) {
       elementType
     };
   }
+  // Promise<...>
   if (type.startsWith("Promise<") && type.endsWith('>')) {
     const typeSlice = type.slice(8, -1);
     const elementType = expandTypeDepFree(typeSlice);
@@ -29,6 +68,7 @@ function expandTypeDepFree(type) {
       elementType
     };
   }
+  // (3) Object<...> or Record<...>
   if ((type.startsWith("Object<") || type.startsWith("Record<")) && type.endsWith('>')) {
     const recordSlice = type.slice(7, -1);
     const firstComma = recordSlice.indexOf(',');
@@ -43,8 +83,9 @@ function expandTypeDepFree(type) {
       val: expandTypeDepFree(val)
     };
   }
+  // (4) {...}
   if (type[0] === '{' && type[type.length - 1] === '}') {
-    const propertiesArray = type.slice(1, -1).split(',');
+    const propertiesArray = type.slice(1, -1).split(','); // ['entity: Entity', ' app: AppBase']
     const properties = {};
     propertiesArray.forEach(_ => {
       const [propName, propType] = _.split(":").map(_ => _.trim());
@@ -59,6 +100,7 @@ function expandTypeDepFree(type) {
       properties
     };
   }
+  // (5) expand unions
   const members = type.split("|");
   if (members.length >= 2) {
     members.forEach((_, i) => members[i] = _.trim());
@@ -67,6 +109,8 @@ function expandTypeDepFree(type) {
       members: members.map(expandTypeDepFree)
     };
   }
+  // (6) expand [] Arrays
+  // Test arrays: new pc.Mat3().set([1, 2, 3, "asd"])
   if (type.endsWith("[]")) {
     const typeSlice = type.slice(0, -2);
     return {
@@ -74,13 +118,15 @@ function expandTypeDepFree(type) {
       elementType: expandTypeDepFree(typeSlice)
     };
   }
+  // (7) expand tuples
   if (type[0] === '[' && type[type.length - 1] === ']') {
-    const elements = type.slice(1, -1).split(',');
+    const elements = type.slice(1, -1).split(','); // ['null', ' Texture', ' Texture', ' Texture', ' Texture', ' Texture', ' Texture']
     return {
       type: 'tuple',
       elements: elements.map(expandTypeDepFree)
     };
   }
+  // (8) expand typeof expressions
   if (type.startsWith('typeof ')) {
     const argument = expandTypeDepFree(type.substring(7));
     return {
@@ -97,6 +143,14 @@ function expandTypeDepFree(type) {
   return type;
 }
 
+/** @typedef {import('@babel/types').Node} Node */
+/** @typedef {import('@babel/types').Function} Function */
+/**
+ * Checks if the provided node is a function-like structure.
+ *
+ * @param {Node} node - The Babel AST node to be tested.
+ * @returns {node is Function} - `true` if the node is a function-like structure, otherwise `false`.
+ */
 function nodeIsFunction(node) {
   switch (node.type) {
     case 'ArrowFunctionExpression':
@@ -110,12 +164,23 @@ function nodeIsFunction(node) {
   return false;
 }
 
+/**
+ * @typedef DocType
+ * @property {boolean} optional - Type is optional.
+ */
+/**
+ * @param {string | DocType} type - The type.
+ * @param {boolean} optional - Optionality
+ * @returns {string | DocType} The simplified type.
+ */
 function simplifyType(type, optional) {
+  // If it's already an object, just set optionality.
   if (type instanceof Object) {
     type.optional = optional;
   } else if (typeof type === 'string') {
     type = type.trim();
     if (type !== 'object' && type !== 'object[]' && type !== 'union' && !optional) {
+      // console.log("simplify", type);
       return type;
     }
     type = {
@@ -128,43 +193,65 @@ function simplifyType(type, optional) {
   }
   if (type.type === 'object' && type.properties && Object.keys(type.properties).length === 0) {
     delete type.properties;
+    // console.log("delete empty", type);
   }
+
   return type;
 }
 
+/**
+ * Parses JSDoc comments to extract parameter type information.
+ *
+ * @param {string} src - The JSDoc comment string to parse.
+ * @param {Function} [expandType] - An optional function to process the types found in the JSDoc.
+ * @returns {Record<string, any> | undefined} An object mapping parameter names to their parsed types, or undefined if no parameters are found.
+ */
 function parseJSDoc(src, expandType = expandTypeDepFree) {
+  // Parse something like: @param {Object} [kwargs={}] Optional arguments.
   const regex = /@param \{(.*?)\} ([\[\]a-zA-Z0-9_$=\{\}\.'" ]+)/g;
   const matches = [...src.matchAll(regex)];
+  /** @type {Record<string, any>} */
   const params = Object.create(null);
   matches.forEach(_ => {
     const type = expandType(_[1].trim());
     let name = _[2].trim();
     let optional = false;
+    // Examples:
+    //   name: [kwargs={}] The configuration parameters.
+    //   name: [d = 1.0] Sample spacing
     if (name[0] === '[') {
+      // Possible improvement: counting opening/closing brackets for perfect match
       const closer = name.lastIndexOf(']');
+      // Afterwards name will be: d = 1.0
       name = name.substring(1, closer);
+      // mark it for the type:
       optional = true;
     }
+    // Strip the rest (either leftover of optional value or description)
     name = name.split(' ')[0].split('=')[0].trim();
     const simplifiedType = simplifyType(type, optional);
     const parts = name.split(".");
     if (parts.length === 3) {
-      const parts0 = parts[0];
-      const parts1 = parts[1];
-      const parts2 = parts[2];
+      // Something like: @param {number[]} settings.render.skyboxRotation - Rotation of skybox.
+      const parts0 = parts[0]; // settings
+      const parts1 = parts[1]; // render
+      const parts2 = parts[2]; // skyboxRotation
       const toptype = params[parts0];
       toptype.properties[parts1].properties = toptype.properties[parts1].properties || {};
       toptype.properties[parts1].properties[parts2] = simplifiedType;
     } else if (parts.length === 2) {
-      let parts0 = parts[0];
-      const parts1 = parts[1];
+      // Something like: @param {number} description[].components
+      let parts0 = parts[0]; // description[]
+      const parts1 = parts[1]; // components
       if (parts0.endsWith('[]')) {
-        parts0 = parts0.slice(0, -2);
+        parts0 = parts0.slice(0, -2); // description[] -> description
       }
+
       const toptype = params[parts0];
       if ((toptype == null ? void 0 : toptype.type) === "union") {
         const typeObject = toptype.members.find(_ => (_ == null ? void 0 : _.type) === 'object');
         typeObject.properties[parts1] = simplifiedType;
+        //typeObject.properties = simplifiedType; // todo add test case
       } else if ((toptype == null ? void 0 : toptype.type) === "array") {
         toptype.elementType.properties[parts1] = simplifiedType;
       } else if ((toptype == null ? void 0 : toptype.type) === "object") {
@@ -189,29 +276,61 @@ function parseJSDoc(src, expandType = expandTypeDepFree) {
   return params;
 }
 
+/**
+ * @param {string} src - JSDoc comment of the setter.
+ * @param {Function} expandType - The expandType function.
+ * @returns {string | DocType | undefined} The parsed and possibly expanded type from
+ * the JSDoc comment, or undefined if parsing fails to find `@type`.
+ */
 function parseJSDocSetter(src, expandType = expandTypeDepFree) {
   const regex = /@type \{(.*?)\}/g;
   const matches = [...src.matchAll(regex)];
   if (matches.length === 1) {
     const match = matches[0];
     const type = expandType(match[1]);
-    const simplifiedType = simplifyType(type, false);
+    const simplifiedType = simplifyType(type, /* optional */false);
     return simplifiedType;
   }
 }
 
+/**
+ * Extracts the parameter name and its optionality from a JSDoc parameter string.
+ *
+ * This function takes a rest parameter string from a JSDoc comment, trims it, and determines the parameter's
+ * name and whether it is optional. The optionality is inferred based on the presence of square brackets around
+ * the parameter name.
+ *
+ * @param {string} rest - The rest part of a JSDoc parameter string to parse.
+ * @returns {[string, boolean]} A tuple where the first element is the name of the parameter,
+ * and the second element is a boolean indicating if the parameter is optional.
+ */
 function extractNameAndOptionality(rest) {
   rest = rest.trim();
   let optional = false;
+  // Examples:
+  //   name: [kwargs={}] The configuration parameters.
+  //   name: [d = 1.0] Sample spacing
   if (rest[0] === '[') {
+    // Possible improvement: counting opening/closing brackets for perfect match
     const closer = rest.lastIndexOf(']');
+    // Afterwards name will be: d = 1.0
     rest = rest.substring(1, closer);
+    // mark it for the type:
     optional = true;
   }
+  // Strip the rest (either leftover of optional value or description)
   const name = rest.split(' ')[0].split('=')[0].trim();
   return [name, optional];
 }
 
+/**
+ * Extracts the content of a string that is delimited by curly braces.
+ * @example
+ * extractCurlyContent('{ {inner} }'); // Returns: {content: ' {inner} ', nextIndex: 11}
+ * @param {string} line - The string to extract from.
+ * @returns {{content: string, nextIndex: number}} An object containing the extracted content,
+ * and the index of the character immediately following the closing curly brace.
+ */
 function extractCurlyContent(line) {
   const firstCurly = line.indexOf('{');
   let k = firstCurly + 1;
@@ -233,6 +352,17 @@ function extractCurlyContent(line) {
     nextIndex: k + 1
   };
 }
+/**
+ * Parses JSDoc comments to extract and expand typedefs and their associated properties.
+ *
+ * It iterates through the lines of a `CommentBlock` from the Babel AST, looking for `@typedef` and `@property`
+ * annotations. When it finds a typedef, it stores it in the `typedefs` record. When it finds a property,
+ * it adds it to the last found typedef if it is an object type.
+ * @param {Record<string, object>} typedefs - An object to store typedefs, mapping type names to their expanded definitions.
+ * @param {Console["warn"]} warn - A warn function used for emitting warnings about non-extensible types.
+ * @param {import("@babel/types").Comment} comment - A comment extracted from Babel's AST, expected to be a CommentBlock containing type definitions.
+ * @param {Function} expandType - A function that takes a type expression as a string and returns a structured representation of the type.
+ */
 function parseJSDocTypedef(typedefs, warn, comment, expandType) {
   const {
     type,
@@ -254,13 +384,16 @@ function parseJSDocTypedef(typedefs, warn, comment, expandType) {
         nextIndex
       } = extractCurlyContent(line);
       let name = line.substring(nextIndex).trim();
+      // Drop description
       name = name.split(' ')[0];
       lastTypedef = expandType(def);
+      // Ignore @typedef's that only refer to themselves in another file (see typedef-overwrite test)
       if (lastTypedef !== name) {
         typedefs[name] = lastTypedef;
       }
     } else if (line.startsWith('@property')) {
       var _lastTypedef;
+      // class @property
       if (!lastTypedef) {
         continue;
       }
@@ -271,6 +404,7 @@ function parseJSDocTypedef(typedefs, warn, comment, expandType) {
       const rest = line.substring(nextIndex);
       const propType = expandType(content);
       const [name, optional] = extractNameAndOptionality(rest);
+      // console.log({name, optional, propType});
       const finalType = simplifyType(propType, optional);
       if (((_lastTypedef = lastTypedef) == null ? void 0 : _lastTypedef.type) === 'object') {
         lastTypedef.properties[name] = finalType;
@@ -284,30 +418,62 @@ function parseJSDocTypedef(typedefs, warn, comment, expandType) {
   }
 }
 
+/**
+ * @typedef Stat
+ * @property {number} checked - How often assertions were added to this kind of node.
+ * @property {number} unchecked - How often no assertions were added to this kind of node.
+ */
+/**
+ * @param {Stat} stat - the Stat.
+ */
 function statReset(stat) {
   stat.checked = 0;
   stat.unchecked = 0;
 }
 
+/**
+ * @example
+ * trimEndSpaces('test   \n   '); // Returns: 'test   \n'
+ * @param {string} str - The input string.
+ * @returns {string} Output string without spaces at the end.
+ */
 function trimEndSpaces(str) {
   let i = str.length - 1;
+  // decrement index while character is a space
   while (str[i] === ' ') {
     i--;
   }
+  // return string from 0 to non-space character
   return str.slice(0, i + 1);
 }
 
+/**
+ * @typedef {import("@babel/types").Node} Node
+ */
+/**
+ * Class for converting AST into string.
+ */
 class Stringifier {
   constructor() {
     this.forceCurly = false;
+    /** @type {Node[]} */
     this.parents = [];
     this.lastCommentBlockIndex = -1;
     this.lastCommentLineIndex = -1;
     this.numSpaces = 0;
   }
+  /**
+   * @param {Node} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   toSource(node) {
     var _node$extra;
+    // handle this case only temporarily
     if (node === null) {
+      // Contexts like:
+      // Object.assign(Channel3d.prototype, {
+      //   setPosition: function /*null*/(position) {
+      //return '/*null*/';
       return '';
     }
     const {
@@ -321,6 +487,7 @@ class Stringifier {
     let out = '';
     let comments = '';
     if (leadingComments) {
+      // comments += this.mapToSource(leadingComments).join('');
       comments = this.leadingCommentsToSource(leadingComments);
     }
     if (node != null && (_node$extra = node.extra) != null && _node$extra.parenthesized) {
@@ -331,9 +498,17 @@ class Stringifier {
     if (trailingComments) {
       out += this.trailingCommentsToSource(trailingComments);
     }
+    // leadingComments and trailingComments lead to duplicates, not always tho
+    //if (node && node.trailingComments) {
+    //  out += this.mapToSource(node.trailingComments).join('\n') + '\n';
+    //}
     this.parents.pop();
     return out;
   }
+  /**
+   * @param {Node} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   toSource_(node) {
     if (!node) {
       return '';
@@ -356,12 +531,18 @@ class Stringifier {
     return `rtiUnhandled("${node.type}");\n`;
   }
   parentProvidesSpaces(reverseIndex) {
+    // May look like: .../ArrayExpression/StringLiteral/CommentLine
     const {
       parents
     } = this;
     const parent = parents[parents.length - reverseIndex];
+    // console.log("Got parent", parent.type);
     return (parent == null ? void 0 : parent.type) === 'ArrayExpression';
   }
+  /**
+   * @param {import("@babel/types").CommentBlock} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   CommentBlock(node) {
     const {
       loc
@@ -370,6 +551,7 @@ class Stringifier {
       value
     } = node;
     if (this.lastCommentBlockIndex === loc.start.index) {
+      // console.log("CommentBlock> ignore double");
       return '';
     }
     this.lastCommentBlockIndex = loc.start.index;
@@ -377,6 +559,7 @@ class Stringifier {
       spaces
     } = this;
     let out = '';
+    /** @todo add option for number-of-spaces */
     const dedicatedLine = spaces.length === loc.start.column;
     if (dedicatedLine) {
       out += spaces;
@@ -384,6 +567,7 @@ class Stringifier {
     const multiLine = loc.start.line !== loc.end.line;
     if (multiLine) {
       var _this$parents$at;
+      // console.log(this.parents.at(-2)?.type === 'AssignmentExpression');
       if (((_this$parents$at = this.parents.at(-2)) == null ? void 0 : _this$parents$at.type) === 'AssignmentExpression') {
         spaces += '  ';
       }
@@ -391,7 +575,11 @@ class Stringifier {
     }
     out += '/*';
     if (value.includes('\n')) {
-      value = trimEndSpaces(value.replace(/^\s*\*/gm, '*')).split('\n').filter(_ => _.length).map((line, i) => (i ? spaces + ' ' : '') + line).join('\n');
+      // A bit tricky to handle multiline comments,
+      // we have to remove the given indentation level.
+      value = trimEndSpaces(value.replace(/^\s*\*/gm, '*')).split('\n').filter(_ => _.length) // skip empty lines
+      // Skip spaces in first line for /**
+      .map((line, i) => (i ? spaces + ' ' : '') + line).join('\n');
       out += `${value}\n${spaces} */`;
     } else {
       out += `${value}*/`;
@@ -403,12 +591,17 @@ class Stringifier {
     }
     return out;
   }
+  /**
+   * @param {import("@babel/types").CommentLine} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   CommentLine(node) {
     const {
       value,
       loc
     } = node;
     if (this.lastCommentLineIndex === loc.start.index) {
+      // console.log("CommentLine> ignore double");
       return '';
     }
     this.lastCommentLineIndex = loc.start.index;
@@ -430,6 +623,8 @@ class Stringifier {
   }
   leadingCommentsToSource(leadingComments) {
     let out = leadingComments.map(_ => this.commentToSource(_, 'leading')).join('');
+    // The comments "took" the spaces, which e.g. ArrayExpression added,
+    // so we have to add them back now for parents that provide spaces.
     if (this.parentProvidesSpaces(2)) {
       out += this.spaces;
     }
@@ -443,6 +638,7 @@ class Stringifier {
           loc
         } = trailingComment;
         const dedicatedLine = this.spaces.length === loc.start.column;
+        // out += ` /*dedicatedLine=${dedicatedLine}*/ `;
         if (dedicatedLine) {
           out += '\n';
         } else {
@@ -453,8 +649,14 @@ class Stringifier {
     }
     return out;
   }
+  /**
+   * @param {*} comment - The comment "node" (not a real Babel Node node though, hence this special treatment)
+   * @param {'leading'|'trailing'} pos - The position, either 'leading' or 'trailing'.
+   * @returns {string} The comment "node" as a string.
+   */
   commentToSource(comment, pos) {
     if (comment.type === 'CommentBlock') {
+      //if (pos === 'leading') {}
       return this.CommentBlock(comment);
     } else if (comment.type === 'CommentLine') {
       return this.CommentLine(comment);
@@ -463,6 +665,12 @@ class Stringifier {
     debugger;
     return '';
   }
+  /**
+   * Only add { and } when requested (e.g. for Asserter).
+   * showAST("if (true) 2;") vs showAST("if (true) {2}")
+   * @param {Node} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   toSourceCurly(node) {
     if (!this.forceCurly) {
       return this.toSource(node);
@@ -475,7 +683,10 @@ class Stringifier {
     let out = '';
     if (needCurly) {
       out += ' {\n';
+      //out += spaces + `/* toSourceCurly> needCurly=${needCurly} type=${type}
+      //parents=${parents.map(_=>_.type).join('->')}*/\n`;
     }
+
     out += this.toSource(node);
     if (needCurly) {
       out += '\n';
@@ -495,12 +706,29 @@ class Stringifier {
     const t = this.parentType;
     return t !== "ForStatement" && t !== "ForInStatement" && t !== "ForOfStatement";
   }
+  /**
+   * @param {Node[]} arr - Array of nodes to convert.
+   * @returns {string[]} Array of strings for each node.
+   */
   mapToSource(arr) {
     return arr.map(_ => this.toSource(_));
   }
+  /**
+   * Generates a string representing type checks for a given Babel AST node.
+   *
+   * Note: This method serves as a stub and should be overridden in subclasses.
+   * The actual implementation is expected to be provided in Asserter.mjs, where
+   * it would create runtime type assertions based on the AST node provided.
+   *
+   * @param {Node} node - The Babel AST node for which to generate type checks.
+   * @returns {string} A placeholder string, as this stub implementation does nothing; expected to be overridden.
+   */
   generateTypeChecks(node) {
     return '';
   }
+  /**
+   * @type {string} A string of two spaces per indentation.
+   */
   get spaces() {
     return '  '.repeat(this.numSpaces);
   }
@@ -513,18 +741,32 @@ class Stringifier {
     const path = parents.map(_ => _.type).join('/');
     return `${spaces}// got ${n} spaces for ${path}\n`;
   }
+  /**
+   * > await something();
+   *
+   * @param {import("@babel/types").AwaitExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   AwaitExpression(node) {
     const {
       argument
     } = node;
     return `await ${this.toSource(argument)}`;
   }
+  /**
+   * @param {import("@babel/types").ClassBody} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ClassBody(node) {
     const {
       body
     } = node;
     return this.mapToSource(body).join('\n');
   }
+  /**
+   * @param {import("@babel/types").ClassMethod} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ClassMethod(node) {
     const {
       static: static_,
@@ -566,6 +808,10 @@ class Stringifier {
     out += this.toSource(body);
     return out;
   }
+  /**
+   * @param {import("@babel/types").ClassExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ClassExpression(node) {
     const {
       id,
@@ -574,6 +820,7 @@ class Stringifier {
     } = node;
     let out = 'class ';
     if (id !== null) {
+      // Babel: strange API, either null or undefined... pick a type, maybe oversight/bug
       out += this.toSource(id) + ' ';
     }
     if (superClass !== null) {
@@ -584,6 +831,10 @@ class Stringifier {
     out += `{\n${c}\n}`;
     return out;
   }
+  /**
+   * @param {import("@babel/types").ClassDeclaration} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ClassDeclaration(node) {
     const {
       id,
@@ -605,6 +856,10 @@ class Stringifier {
     out += '\n}\n';
     return out;
   }
+  /**
+   * @param {import("@babel/types").ClassPrivateMethod} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ClassPrivateMethod(node) {
     const {
       static: static_,
@@ -641,6 +896,15 @@ class Stringifier {
     out += this.toSource(body);
     return out;
   }
+  /**
+   * > asd;
+   * > asd = 1;
+   * > static asd;
+   * > static asd = 1;
+   *
+   * @param {import("@babel/types").ClassProperty} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ClassProperty(node) {
     const {
       key,
@@ -648,7 +912,7 @@ class Stringifier {
       value,
       leadingComments
     } = node;
-    const static_ = node.static;
+    const static_ = node.static; // JS keyword is problematic in object destructuring
     const a = this.toSource(key);
     const b = this.toSource(value);
     let out = this.spaces;
@@ -666,6 +930,10 @@ class Stringifier {
     out += ';';
     return out;
   }
+  /**
+   * @param {import("@babel/types").ClassPrivateProperty} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ClassPrivateProperty(node) {
     const {
       static: static_,
@@ -683,6 +951,10 @@ class Stringifier {
     out += ';';
     return out;
   }
+  /**
+   * @param {import("@babel/types").ContinueStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ContinueStatement(node) {
     const {
       label
@@ -694,9 +966,22 @@ class Stringifier {
     out += ';';
     return out;
   }
+  /**
+   * Converts an array of Babel AST nodes representing function parameters into a comma-separated string.
+   *
+   * Each parameter node is converted to its source representation and combined into a single
+   * string suitable for inserting into a function declaration's parentheses.
+   *
+   * @param {Node[]} params - An array of Babel AST nodes representing the function parameters to be stringified.
+   * @returns {string} A string representing the serialized parameters, enclosed in parentheses.
+   */
   FunctionDeclarationParams(params) {
     return '(' + this.mapToSource(params).join(', ') + ')';
   }
+  /**
+   * @param {import("@babel/types").FunctionDeclaration} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   FunctionDeclaration(node) {
     const {
       async,
@@ -718,13 +1003,18 @@ class Stringifier {
     out += this.toSource(body);
     return out;
   }
+  /**
+   * @param {import("@babel/types").FunctionExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   FunctionExpression(node) {
+    // Leading comments for asd=function(){} are in ExpressionStatement
     const {
       async,
       body,
       generator,
-      id,
-      params
+      id /*, leadingComments*/,
+      params /*, extra*/
     } = node;
     let out = '';
     if (node.leadingComments) {
@@ -744,12 +1034,16 @@ class Stringifier {
     }
     return out;
   }
+  /**
+   * @param {import("@babel/types").ArrowFunctionExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ArrowFunctionExpression(node) {
     const {
       async,
       body,
       generator,
-      params
+      params /*, extra*/
     } = node;
     let out = '';
     if (async) {
@@ -763,6 +1057,10 @@ class Stringifier {
     out += this.toSource(body);
     return out;
   }
+  /**
+   * @param {import("@babel/types").BigIntLiteral} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   BigIntLiteral(node) {
     const {
       extra,
@@ -770,6 +1068,10 @@ class Stringifier {
     } = node;
     return extra.raw;
   }
+  /**
+   * @param {import("@babel/types").BlockStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   BlockStatement(node) {
     const {
       body,
@@ -779,6 +1081,7 @@ class Stringifier {
     let out = '';
     out += ' {';
     this.numSpaces++;
+    // Handle Directive/DirectiveLiteral like 'use strict';
     if (directives && directives.length) {
       out += '\n';
       out += this.mapToSource(directives).join('\n') + '\n';
@@ -786,8 +1089,10 @@ class Stringifier {
     out += this.generateTypeChecks(node);
     if (body.length) {
       if (out.length === 2) {
+        // 2 is ' {'
         out += '\n';
       }
+      // out += '/*'+out.length+'*/';
       out += this.mapToSource(body).join('\n') + '\n';
       out += spaces;
     }
@@ -795,12 +1100,24 @@ class Stringifier {
     out += '}';
     return out;
   }
+  /**
+   * > 'use strict';
+   *
+   * @param {import("@babel/types").Directive} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   Directive(node) {
     const {
       value
     } = node;
     return this.toSource(value);
   }
+  /**
+   * > 'use strict';
+   *
+   * @param {import("@babel/types").DirectiveLiteral} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   DirectiveLiteral(node) {
     const {
       extra,
@@ -811,6 +1128,10 @@ class Stringifier {
     } = this;
     return `${spaces}${extra.raw};`;
   }
+  /**
+   * @param {import("@babel/types").ReturnStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ReturnStatement(node) {
     const {
       argument
@@ -823,9 +1144,17 @@ class Stringifier {
     }
     return spaces + 'return ' + this.toSource(argument) + ';';
   }
+  /**
+   * @param {import("@babel/types").Identifier} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   Identifier(node) {
     return node.name;
   }
+  /**
+   * @param {import("@babel/types").IfStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   IfStatement(node) {
     const {
       alternate,
@@ -834,7 +1163,10 @@ class Stringifier {
     } = node;
     const spaces = this.spaces;
     let out = '';
+    //if (this.parentType !== "IfStatement")
+    //{
     out += spaces;
+    //}
     out += `if (${this.toSource(test)})`;
     out += this.toSourceCurly(consequent);
     if (alternate) {
@@ -842,6 +1174,10 @@ class Stringifier {
     }
     return out;
   }
+  /**
+   * @param {import("@babel/types").LabeledStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   LabeledStatement(node) {
     const {
       body,
@@ -856,6 +1192,15 @@ class Stringifier {
     out += spaces + this.toSource(body);
     return out;
   }
+  /**
+   * @example
+   * ts = require("typescript");
+   * ts.createSourceFile("repl.ts", "a = 1", ts.ScriptTarget.Latest);
+   * ts.createSourceFile("repl.ts", "!!(a = 1 + 2)", ts.ScriptTarget.Latest);
+   * showAST('!!(a = 1)');
+   * @param {import("@babel/types").UnaryExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   UnaryExpression(node) {
     let out = '';
     const {
@@ -866,6 +1211,7 @@ class Stringifier {
     if (!prefix) {
       console.warn("Stringifier#UnaryExpression> never considered !prefix", node);
     }
+    // Add a space for: typeof/delete/void
     const c = operator.charCodeAt(0);
     let op = operator;
     if (c >= 97 && c <= 122) {
@@ -875,6 +1221,10 @@ class Stringifier {
     out += this.toSource(argument);
     return out;
   }
+  /**
+   * @param {import("@babel/types").MemberExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   MemberExpression(node) {
     const {
       computed,
@@ -886,6 +1236,10 @@ class Stringifier {
     }
     return `${this.toSource(object)}.${this.toSource(property)}`;
   }
+  /**
+   * @param {import("@babel/types").MetaProperty} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   MetaProperty(node) {
     const {
       meta,
@@ -895,12 +1249,26 @@ class Stringifier {
     const rhs = this.toSource(property);
     return `${lhs}.${rhs}`;
   }
+  /**
+   * @param {import("@babel/types").ExpressionStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ExpressionStatement(node) {
     const {
       expression
     } = node;
+    /**
+     * Not just a fall-through, adds a semicolon when it has semantic meaning.
+     * E.g. invalid:
+     * (function() {})()
+     * (function() {})()
+     */
     return this.spaces + this.toSource(expression) + ';';
   }
+  /**
+   * @param {import("@babel/types").CallExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   CallExpression(node) {
     const {
       callee,
@@ -916,6 +1284,14 @@ class Stringifier {
     out += ")";
     return out;
   }
+  /**
+   * We replicate the exact AST for validation:
+   * x = 1;
+   * y = {x,}
+   * z = {y};
+   * @param {import("@babel/types").ObjectExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ObjectExpression(node) {
     const {
       properties,
@@ -937,6 +1313,10 @@ class Stringifier {
     out += '}';
     return out;
   }
+  /**
+   * @param {import("@babel/types").ObjectProperty} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ObjectProperty(node) {
     const {
       computed,
@@ -964,9 +1344,17 @@ class Stringifier {
     out += right;
     return out;
   }
+  /**
+   * @param {import("@babel/types").BooleanLiteral} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   BooleanLiteral(node) {
     return node.value.toString();
   }
+  /**
+   * @param {import("@babel/types").AssignmentExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   AssignmentExpression(node) {
     const {
       left,
@@ -975,8 +1363,13 @@ class Stringifier {
     } = node;
     const left_ = this.toSource(left);
     const right_ = this.toSource(right);
+    // operator is for example: = |= &=
     return `${left_} ${operator} ${right_}`;
   }
+  /**
+   * @param {import("@babel/types").BinaryExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   BinaryExpression(node) {
     const {
       left,
@@ -987,9 +1380,17 @@ class Stringifier {
     const right_ = this.toSource(right);
     return `${left_} ${operator} ${right_}`;
   }
+  /**
+   * @param {import("@babel/types").ThisExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ThisExpression(node) {
     return 'this';
   }
+  /**
+   * @param {import("@babel/types").ArrayExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ArrayExpression(node) {
     const {
       elements,
@@ -1012,6 +1413,10 @@ class Stringifier {
     out += '\n' + this.spaces + ']';
     return out;
   }
+  /**
+   * @param {import("@babel/types").VariableDeclaration} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   VariableDeclaration(node) {
     const {
       declarations,
@@ -1025,6 +1430,10 @@ class Stringifier {
     }
     return `${spaces}${kind} ${this.mapToSource(declarations).join(', ')}${semicolon}`;
   }
+  /**
+   * @param {import("@babel/types").VariableDeclarator} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   VariableDeclarator(node) {
     const {
       id,
@@ -1035,6 +1444,10 @@ class Stringifier {
     }
     return this.toSource(id);
   }
+  /**
+   * @param {import("@babel/types").ConditionalExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ConditionalExpression(node) {
     const {
       alternate,
@@ -1043,6 +1456,12 @@ class Stringifier {
     } = node;
     return `${this.toSource(test)} ? ${this.toSource(consequent)} : ${this.toSource(alternate)}`;
   }
+  /**
+   * if (...)
+   *
+   * @param {import("@babel/types").LogicalExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   LogicalExpression(node) {
     const {
       left,
@@ -1059,6 +1478,12 @@ class Stringifier {
     }
     return `${l} ${operator} ${r}`;
   }
+  /**
+   * TODO TEST: can init be undefined in for(;;)
+   *
+   * @param {import("@babel/types").ForStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ForStatement(node) {
     const {
       init,
@@ -1073,6 +1498,12 @@ class Stringifier {
     const b = this.toSourceCurly(body);
     return `${spaces}for (${i}; ${t}; ${u})${b}`;
   }
+  /**
+   * showAST("++i")
+   *
+   * @param {import("@babel/types").UpdateExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   UpdateExpression(node) {
     const {
       operator,
@@ -1084,6 +1515,10 @@ class Stringifier {
     }
     return `${this.toSource(argument)}${operator}`;
   }
+  /**
+   * @param {import("@babel/types").NewExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   NewExpression(node) {
     const {
       callee,
@@ -1093,6 +1528,12 @@ class Stringifier {
     const args = this.mapToSource(args_).join(', ');
     return `new ${c}(${args})`;
   }
+  /**
+   * @example
+   * console.log(ast2json(parseSync("`${1} b ${2+3}c`").program.body[0]));
+   * @param {import("@babel/types").TemplateLiteral} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   TemplateLiteral(node) {
     const {
       expressions,
@@ -1108,12 +1549,20 @@ class Stringifier {
     out += '`';
     return out;
   }
+  /**
+   * @param {import("@babel/types").TemplateElement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   TemplateElement(node) {
     const {
       value
     } = node;
     return value.raw;
   }
+  /**
+   * @param {import("@babel/types").ParenthesizedExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ParenthesizedExpression(node) {
     const {
       expression,
@@ -1130,21 +1579,37 @@ class Stringifier {
     out += '\n' + this.spaces + ')';
     return out;
   }
+  /**
+   * @param {import("@babel/types").PrivateName} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   PrivateName(node) {
     const {
       id
     } = node;
     return `#${this.toSource(id)}`;
   }
+  /**
+   * @param {import("@babel/types").ExportAllDeclaration} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ExportAllDeclaration(node) {
     return `export * from ${node.source.extra.raw};`;
   }
+  /**
+   * @param {import("@babel/types").ExportNamespaceSpecifier} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ExportNamespaceSpecifier(node) {
     const {
       exported
     } = node;
     return '* as ' + this.toSource(exported);
   }
+  /**
+   * @param {import("@babel/types").ExportNamedDeclaration} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ExportNamedDeclaration(node) {
     const {
       declaration,
@@ -1171,6 +1636,7 @@ class Stringifier {
           out += '}';
         } else {
           out += 'export {\n';
+          // todo: fix spacing system
           out += this.mapToSource(specifiers).map(_ => `  ${this.spaces}${_}`).join(',\n');
           out += '\n';
           out += this.spaces;
@@ -1188,6 +1654,10 @@ class Stringifier {
     }
     return out;
   }
+  /**
+   * @param {import("@babel/types").ExportDefaultDeclaration} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ExportDefaultDeclaration(node) {
     const {
       declaration
@@ -1195,6 +1665,10 @@ class Stringifier {
     const a = this.toSource(declaration);
     return `export default ${a};`;
   }
+  /**
+   * @param {import("@babel/types").ExportSpecifier} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ExportSpecifier(node) {
     const {
       exported,
@@ -1208,11 +1682,22 @@ class Stringifier {
     if (left === right) {
       return `${spaces}${left}`;
     }
+    // For example:
+    // PostEffect: PostEffect$1\n
+    // createMesh: createMesh$1\n
     return `${spaces}${right} as ${left}`;
   }
+  /**
+   * @param {import("@babel/types").Super} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   Super(node) {
     return 'super';
   }
+  /**
+   * @param {import("@babel/types").ForInStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ForInStatement(node) {
     const {
       left,
@@ -1227,6 +1712,10 @@ class Stringifier {
     const b = this.toSourceCurly(body);
     return `${spaces}for (${l} in ${r})${b}`;
   }
+  /**
+   * @param {import("@babel/types").ThrowStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ThrowStatement(node) {
     const {
       argument
@@ -1237,6 +1726,10 @@ class Stringifier {
     const arg = this.toSource(argument);
     return `${spaces}throw ${arg};`;
   }
+  /**
+   * @param {import("@babel/types").WhileStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   WhileStatement(node) {
     const {
       test,
@@ -1249,6 +1742,10 @@ class Stringifier {
     const b = this.toSourceCurly(body);
     return `${spaces}while (${t})${b}`;
   }
+  /**
+   * @param {import("@babel/types").BreakStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   BreakStatement(node) {
     const {
       label
@@ -1260,6 +1757,10 @@ class Stringifier {
     out += ';';
     return out;
   }
+  /**
+   * @param {import("@babel/types").ForOfStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ForOfStatement(node) {
     const {
       await: await_,
@@ -1276,6 +1777,13 @@ class Stringifier {
     const a = await_ ? 'await ' : '';
     return `${spaces}for ${a}(${l} of ${r})${b}`;
   }
+  /**
+   * for (const [a, b] in c)
+   * --> [a, b] is the array pattern
+   *
+   * @param {import("@babel/types").ArrayPattern} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ArrayPattern(node) {
     const {
       elements
@@ -1283,6 +1791,10 @@ class Stringifier {
     const e = this.mapToSource(elements).join(', ');
     return `[${e}]`;
   }
+  /**
+   * @param {import("@babel/types").SwitchStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   SwitchStatement(node) {
     const {
       discriminant,
@@ -1297,6 +1809,10 @@ class Stringifier {
     out += spaces + '}';
     return out;
   }
+  /**
+   * @param {import("@babel/types").SwitchCase} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   SwitchCase(node) {
     const {
       consequent,
@@ -1312,7 +1828,13 @@ class Stringifier {
     }
     return `${spaces}default:\n${c}`;
   }
+  /**
+   * @param {import("@babel/types").RegExpLiteral} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   RegExpLiteral(node) {
+    // parseSync("/test/gm")
+    // todo figure out why it always exposes node.value === undefined... oversight in Babel?
     const {
       extra,
       value,
@@ -1321,15 +1843,32 @@ class Stringifier {
     } = node;
     return extra.raw;
   }
+  /**
+   * for (var i=0, n=arr.length; i<n; i++)
+   * sequence expression: var i=0, n=arr.length
+   *
+   * @param {import("@babel/types").SequenceExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   SequenceExpression(node) {
     const {
       expressions
     } = node;
     return this.mapToSource(expressions).join(', ');
   }
+  /**
+   * showAST("if (true);");
+   *
+   * @param {import("@babel/types").EmptyStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   EmptyStatement(node) {
     return ';';
   }
+  /**
+   * @param {import("@babel/types").SpreadElement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   SpreadElement(node) {
     const {
       argument
@@ -1337,7 +1876,13 @@ class Stringifier {
     const a = this.toSource(argument);
     return `...${a}`;
   }
+  /**
+   * @param {import("@babel/types").ObjectMethod} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ObjectMethod(node) {
+    // @todo PR in Babel why method/id is a key in node... (seems like a bug/oversight)
+    // method === true just indicates kind === 'method'
     const {
       method,
       key,
@@ -1353,6 +1898,10 @@ class Stringifier {
       console.warn("ObjectMethod> id !== null is unhandled", node);
       debugger;
     }
+    // if (method) {
+    //   console.warn("ObjectMethod> node was a method", node);
+    //   debugger;
+    // }
     let out = this.spaces;
     if (generator) {
       out += '*';
@@ -1379,6 +1928,11 @@ class Stringifier {
     out += this.toSource(body);
     return out;
   }
+  /**
+   * E.g. function testComma({x,y,z,}) {}
+   * @param {import("@babel/types").ObjectPattern} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ObjectPattern(node) {
     const {
       properties,
@@ -1399,6 +1953,16 @@ class Stringifier {
     out += '}';
     return out;
   }
+  /**
+   * > x?.y
+   * > x?.y.z
+   * > x[y?.z]
+   * > x?.[y?.z]
+   * > b?.file?.variants[variant]
+   *
+   * @param {import("@babel/types").OptionalMemberExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   OptionalMemberExpression(node) {
     const {
       object,
@@ -1408,6 +1972,7 @@ class Stringifier {
     } = node;
     const a = this.toSource(object);
     const b = this.toSource(property);
+    // Basically four cases: computed=true/false optional=true/false, 00, 01, 10, 11
     if (!computed && !optional) {
       return `${a}.${b}`;
     } else if (!computed && optional) {
@@ -1415,8 +1980,17 @@ class Stringifier {
     } else if (computed && !optional) {
       return `${a}[${b}]`;
     }
+    // Can only be case 4 now (computed && optional):
     return `${a}?.[${b}]`;
   }
+  /**
+   * > version?.indexOf('$');
+   * > version?.indexOf?.('$');
+   * > this.passEncoder?.pushDebugGroup(name);
+   *
+   * @param {import("@babel/types").OptionalCallExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   OptionalCallExpression(node) {
     const {
       callee,
@@ -1430,6 +2004,10 @@ class Stringifier {
     }
     return `${a}(${b})`;
   }
+  /**
+   * @param {import("@babel/types").DoWhileStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   DoWhileStatement(node) {
     const {
       body,
@@ -1445,6 +2023,10 @@ class Stringifier {
     out += ` while (${this.toSource(test)});`;
     return out;
   }
+  /**
+   * @param {import("@babel/types").TryStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   TryStatement(node) {
     const {
       block,
@@ -1462,6 +2044,10 @@ class Stringifier {
     }
     return out;
   }
+  /**
+   * @param {import("@babel/types").CatchClause} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   CatchClause(node) {
     const {
       param,
@@ -1472,25 +2058,45 @@ class Stringifier {
       const p = this.toSource(param);
       return ` catch (${p}) ${b}`;
     }
+    // Example: try { 1n / 0 } catch {}
     return ` catch ${b}`;
   }
+  /**
+   * @param {import("@babel/types").RestElement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   RestElement(node) {
     const {
       argument
     } = node;
     return `...${this.toSource(argument)}`;
   }
+  /**
+   * @param {import("@babel/types").DebuggerStatement} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   DebuggerStatement(node) {
     return `${this.spaces}debugger;`;
   }
+  /**
+   * @param {import("@babel/types").Import} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   Import(node) {
     return 'import';
   }
+  /**
+   * @param {import("@babel/types").ImportDeclaration} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ImportDeclaration(node) {
     const {
       specifiers,
       source
     } = node;
+    // ImportNamespaceSpecifier: import * as a   from "b";
+    // ImportDefaultSpecifier  : import      a   from "b";
+    // ImportSpecifier         : import {    a } from "b";
     const a = this.mapToSource(specifiers).join(', ');
     const b = this.toSource(source);
     if (specifiers.length === 0) {
@@ -1501,6 +2107,10 @@ class Stringifier {
     }
     return `import {${a}} from ${b};`;
   }
+  /**
+   * @param {import("@babel/types").ImportSpecifier} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ImportSpecifier(node) {
     const {
       imported,
@@ -1513,35 +2123,59 @@ class Stringifier {
     }
     return a;
   }
+  /**
+   * @param {import("@babel/types").ImportDefaultSpecifier} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ImportDefaultSpecifier(node) {
     const {
       local
     } = node;
     return this.toSource(local);
   }
+  /**
+   * @param {import("@babel/types").ImportNamespaceSpecifier} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ImportNamespaceSpecifier(node) {
     const {
       local
     } = node;
     return `* as ${this.toSource(local)}`;
   }
+  /**
+   * @param {import("@babel/types").File} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   File(node) {
     return this.toSource(node.program) + '\n';
   }
+  /**
+   * @param {import("@babel/types").Program} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   Program(node) {
     const {
-      body,
+      /*sourceType, interpreter,*/body,
       directives
     } = node;
     let out = '';
+    // @todo I would like to keep comments above and below,
+    // but below one is currently dropped (does't matter for AST)
+    // See: test/typechecking/directive.mjs
     out += this.mapToSource(directives);
     out += this.mapToSource(body).join('\n');
     return out;
   }
+  /**
+   * @param {import("@babel/types").StringLiteral} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   StringLiteral(node) {
     const {
       extra
     } = node;
+    // Never experienced this so far, but types are types...
     if (!extra) {
       debugger;
       return '';
@@ -1552,9 +2186,17 @@ class Stringifier {
     }
     return extra.raw;
   }
+  /**
+   * @param {import("@babel/types").NumericLiteral} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   NumericLiteral(node) {
     return node.extra.raw;
   }
+  /**
+   * @param {import("@babel/types").AssignmentPattern} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   AssignmentPattern(node) {
     const {
       left,
@@ -1562,9 +2204,17 @@ class Stringifier {
     } = node;
     return `${this.toSource(left)} = ${this.toSource(right)}`;
   }
+  /**
+   * @param {import("@babel/types").NullLiteral} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   NullLiteral(node) {
     return 'null';
   }
+  /**
+   * @param {import("@babel/types").TaggedTemplateExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   TaggedTemplateExpression(node) {
     const {
       tag,
@@ -1574,6 +2224,10 @@ class Stringifier {
     const q = this.toSource(quasi);
     return t + q;
   }
+  /**
+   * @param {import("@babel/types").YieldExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   YieldExpression(node) {
     const {
       delegate,
@@ -1588,15 +2242,33 @@ class Stringifier {
   }
 }
 
+/** @typedef {import('@babel/types').Node              } Node               */
+/** @typedef {import("@babel/types").ClassMethod       } ClassMethod        */
+/** @typedef {import("@babel/types").ClassPrivateMethod} ClassPrivateMethod */
+/** @typedef {import('./stat.mjs').Stat                } Stat               */
+/**
+ * @typedef {object} Options
+ * @property {boolean} [forceCurly] - Determines whether curly braces are enforced in Stringifier.
+ * @property {boolean} [validateDivision] - Indicates whether division operations should be validated.
+ * @property {Function} [expandType] - A function that expands shorthand types into full descriptions.
+ * @property {string} [filename] - The name of a file to which the instance pertains.
+ * @property {boolean} [addHeader] - Whether to add import declarations headers. Defaults to true.
+ * @property {string[]} [ignoreLocations] - Ignore these locations because they are known false-positives.
+ */
 class Asserter extends Stringifier {
+  /**
+   * @param {Options} [options] - The options.
+   */
   constructor({
     forceCurly = true,
     validateDivision = true,
     expandType = expandTypeDepFree,
     filename,
-    addHeader = true
+    addHeader = true,
+    ignoreLocations = []
   } = {}) {
     super();
+    /** @type {Record<string, Stat>} */
     this.stats = {
       'ArrowFunctionExpression': {
         checked: 0,
@@ -1643,19 +2315,29 @@ class Asserter extends Stringifier {
         unchecked: 0
       }
     };
+    /** @type {Record<string, object>} */
     this.typedefs = {};
     this.forceCurly = forceCurly;
     this.validateDivision = validateDivision;
+    // @todo collect every type + manually validate as test set
+    // + implement expandType using Babel Flow type parser aswell
     this.expandType = expandType;
     this.filename = filename;
     this.addHeader = addHeader;
-  }
+    this.ignoreLocations = ignoreLocations;
+  }
+  /**
+   * We expand type-asserted ArrowFunctionExpressions in order to add type assertions.
+   * @override
+   * @param {import("@babel/types").ArrowFunctionExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ArrowFunctionExpression(node) {
     const {
       async,
       body,
       generator,
-      params
+      params /*, extra*/
     } = node;
     let out = '';
     if (async) {
@@ -1676,6 +2358,11 @@ class Asserter extends Stringifier {
     }
     return out;
   }
+  /**
+   * @override
+   * @param {import("@babel/types").ClassDeclaration} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   ClassDeclaration(node) {
     const {
       id
@@ -1685,6 +2372,14 @@ class Asserter extends Stringifier {
     out += `${this.spaces}registerClass(${id_});`;
     return out;
   }
+  /**
+   * Finds the closest ancestor of the given node that matches the specified type.
+   *
+   * @param {Node} node - The starting node to search from.
+   * @param {T} type - Type name of the node to search for.
+   * @template {Node['type']} T
+   * @returns {Extract<Node, {type: T}>|undefined} The first ancestor node of the specified type, or undefined if none is found.
+   */
   findParentOfType(node, type) {
     const currentIndex = this.parents.findLastIndex(_ => _ === node);
     return this.parents.findLast((_, i) => {
@@ -1694,6 +2389,13 @@ class Asserter extends Stringifier {
       return _.type === type;
     });
   }
+  /**
+   * Alternatively "import * as rti from ..." would also prevent "Unused external imports" warning...
+   * or keeping log of every single call during RTI parsing.
+   * @todo
+   * Once we went over every node, we can see if we really require registerTypef, registerClass etc.
+   * @returns {string} The import declaration header for importing RTI.
+   */
   getHeader() {
     if (!this.addHeader) {
       return '';
@@ -1703,9 +2405,19 @@ class Asserter extends Stringifier {
       header += ", validateDivision";
     }
     header += ", registerTypedef, registerClass} from '@runtime-type-inspector/runtime';\n";
+    // Prevent tree-shaking in UMD build so we can always "add a breakpoint here".
     header += "export * from '@runtime-type-inspector/runtime';\n";
     return header;
   }
+  /**
+   * Retrieves the node associated with the leading comments for an arrow function expression.
+   *
+   * This method travels up the syntax tree from the given node to find a parent node with leading comments.
+   * This search is bounded by function boundaries or a 'CallExpression' node, as per the logic defined within the loop.
+   * @param {Node} node - The node representing the arrow function expression for which to find the leading comments node.
+   * @returns {Node|undefined} The node that contains the leading comments, or `undefined`
+   * if none is found before reaching a different function or 'CallExpression'.
+   */
   getLeadingCommentsNodeForArrowFunctionExpression(node) {
     const {
       parents
@@ -1715,9 +2427,16 @@ class Asserter extends Stringifier {
     if (parent.leadingComments) {
       return parent;
     }
+    // Skip now, if we find another function first,
+    // there is no JSDoc for our function anymore.
+    // Not interested in our start node if it didn't
+    // contain leadingComments.
     i--;
     while (i >= 0) {
       parent = parents[i];
+      //if (parent.type === 'CallExpression') {
+      //  break;
+      //}
       if (nodeIsFunction(parent)) {
         break;
       }
@@ -1727,6 +2446,10 @@ class Asserter extends Stringifier {
       i--;
     }
   }
+  /**
+   * Emits a warning message to the console, optionally prefixed with the instance's filename.
+   * @param {...any} args - A list of arguments to be passed to the console.warn function.
+   */
   warn(...args) {
     if (this.filename) {
       console.warn("[WARN]", this.filename);
@@ -1742,9 +2465,16 @@ class Asserter extends Stringifier {
     if (parent.leadingComments) {
       return parent;
     }
+    // Skip now, if we find another function first,
+    // there is no JSDoc for our function anymore.
+    // Not interested in our start node if it didn't
+    // contain leadingComments.
     i--;
     while (i >= 0) {
       parent = parents[i];
+      //if (parent.type === 'CallExpression') {
+      //  break;
+      //}
       if (nodeIsFunction(parent)) {
         break;
       }
@@ -1753,7 +2483,26 @@ class Asserter extends Stringifier {
       }
       i--;
     }
-  }
+    /** @todo convert all files in test/typechecking/*.mjs into full unit tests */
+    // Old way:
+    // if (node.leadingComments) {
+    //   return node.leadingComments;
+    // }
+    // node = this.findParentOfType(node, 'ExpressionStatement');
+    // if (!node) {
+    //   /**
+    //    * @todo Need more refactoring, see missing type-assertions in test/typechecking/good-old-es5.mjs
+    //    */
+    //   node = this.parents.findLast(_ => _.type === 'VariableDeclaration');
+    //   if (!node) {
+    //     return;
+    //   }
+    // }
+  }
+  /**
+   * @param {Node} node - The Babel AST node.
+   * @returns {undefined | {}} The return value of `parseJSDoc`.
+   */
   getJSDoc(node) {
     if (node.type === 'BlockStatement') {
       node = this.parent;
@@ -1761,10 +2510,12 @@ class Asserter extends Stringifier {
     let {
       leadingComments
     } = node;
+    // Receive the leadingComments from the ExpressionStatement, not the FunctionExpression itself.
     if (node.type === 'FunctionExpression') {
       const tmp = this.getLeadingCommentsNodeForFunctionExpression(node);
       leadingComments = tmp == null ? void 0 : tmp.leadingComments;
     }
+    // Receive the leadingComments from ExportNamedDeclaration, if FunctionDeclaration has none
     if (!leadingComments) {
       if (node.type === 'FunctionDeclaration') {
         const exportNamedDeclaration = this.findParentOfType(node, 'ExportNamedDeclaration');
@@ -1797,6 +2548,15 @@ class Asserter extends Stringifier {
       }
     }
   }
+  /**
+   * Retrieves the name of a parameter from a Babel AST node.
+   *
+   * This function expects a node representing a function parameter and attempts to extract
+   * the parameter's name directly or from an AssignmentPattern.
+   *
+   * @param {Node} param - The AST node representing the function parameter from which to extract the name.
+   * @returns {string} The name of the parameter as a string, or the parameter's source code if the extraction fails.
+   */
   getNameOfParam(param) {
     if (param.type === 'Identifier') {
       return param.name;
@@ -1815,19 +2575,29 @@ class Asserter extends Stringifier {
   statsPrint() {
     console.table(this.stats);
   }
+  /**
+   * Retrieves statistical information for a given Babel AST node of this instance.
+   *
+   * @param {Node} node - The Babel AST node for which the statistical data is retrieved.
+   * @returns {Stat} An object containing the statistical data for the specified node. If the
+   * node type is unhandled, defaults to returning a dummy object with 'checked' and 'unchecked'
+   * properties both set to 0.
+   */
   getStatsForNode(node) {
     const {
       stats
     } = this;
     const type = nodeIsFunction(node) ? node.type : this.parentType;
     if (type === 'ClassMethod') {
-      const parent = this.parent;
+      const parent = /** @type {ClassMethod} */
+      this.parent;
       const {
         kind
       } = parent;
       return stats[`ClassMethod#${kind}`];
     } else if (type === 'ClassPrivateMethod') {
-      const parent = this.parent;
+      const parent = /** @type {ClassPrivateMethod} */
+      this.parent;
       const {
         kind
       } = parent;
@@ -1843,6 +2613,17 @@ class Asserter extends Stringifier {
     }
     return stat;
   }
+  /**
+   * Checks if a provided Babel AST node has a parameter with the given name.
+   *
+   * This function will look at the node's parameters if available and determine whether
+   * one of them matches the provided name. Supports various parameter types such as Identifiers
+   * and AssignmentPatterns.
+   *
+   * @param {Node} node - The Babel AST node to inspect. If it's a BlockStatement, the parent node is used instead.
+   * @param {string} name - The name of the parameter to look for within the node's parameters.
+   * @returns {boolean} True if the node has a parameter with the given name; false otherwise.
+   */
   nodeHasParamName(node, name) {
     if (node.type === 'BlockStatement') {
       node = this.parent;
@@ -1878,6 +2659,18 @@ class Asserter extends Stringifier {
       return false;
     });
   }
+  /**
+   * Generates a string containing type checks for a given Babel AST node based on associated JSDoc information.
+   *
+   * This function analyzes the node and its JSDoc annotations to construct runtime type
+   * check expressions. It handles various parameter patterns and outputs code that performs
+   * actual type assertions. If a node does not correspond to any known or supported pattern,
+   * it returns an empty string.
+   *
+   * @override
+   * @param {Node} node - The Babel AST node for which to generate type checks.
+   * @returns {string} A string of code with type check assertions, based on the JSDoc comments associated with the given node.
+   */
   generateTypeChecks(node) {
     const {
       parent
@@ -1886,6 +2679,7 @@ class Asserter extends Stringifier {
       return '';
     }
     const jsdoc = this.getJSDoc(node);
+    // return '// ' + JSON.stringify(jsdoc) + '\n';
     const stat = this.getStatsForNode(node);
     if (!jsdoc) {
       stat.unchecked++;
@@ -1897,6 +2691,12 @@ class Asserter extends Stringifier {
     } = this;
     let out = '';
     let first = true;
+    const loc = this.getName(node);
+    if (this.ignoreLocations.includes(loc)) {
+      return '// IGNORE RTI TYPE VALIDATIONS, KNOWN ISSUES\n';
+    }
+    //out += `${spaces}/*${spaces}  node.type=${node.type}\n${spaces}
+    //  ${JSON.stringify(jsdoc)}\n${parent}\n${spaces}*/\n`;
     for (let name in jsdoc) {
       const type = jsdoc[name];
       const hasParam = this.nodeHasParamName(node, name);
@@ -1911,11 +2711,24 @@ class Asserter extends Stringifier {
           const isObjectPattern = param.type === 'ObjectPattern';
           const isArrayPattern = param.type === 'ArrayPattern';
           const isSupportedPattern = isObjectPattern || isArrayPattern;
+          // There are four kinds of patterns:
+          //   ObjectPattern:
+          //     function test({x = 123}) {return x;} test({x: 456});
+          //   ArrayPattern:
+          //     function test([x = 123]) {return x;}; test([456]);
+          //   AssignmentPattern made up of ObjectPattern:
+          //     function test({x = 123} = {}) {return x;} test();
+          //   AssignmentPattern made up of ArrayPattern:
+          //     function test([x = 123] = []) {return x;} test();
           if (isSupportedPattern) {
+            // The name doesn't matter any longer, because any pattern inherently
+            // drops the identifier from the AST. But we can access it
+            // via arguments[paramIndex] anyway.
             name = `arguments[${paramIndex}]`;
           } else if (param.type === 'AssignmentPattern') {
             const _loc = this.getName(node);
             if (param.left.type === 'ArrayPattern' && type.type === 'array') {
+              // Add a type assertion for each element of the ArrayPattern
               for (const element of param.left.elements) {
                 if (element.type !== 'Identifier') {
                   this.warn('Only Identifier case handled right now');
@@ -1927,6 +2740,7 @@ class Asserter extends Stringifier {
               }
               continue;
             } else if (param.left.type === 'ObjectPattern' && type.type === 'object') {
+              // Add a type assertion for each property of the ObjectPattern
               for (const property of param.left.properties) {
                 if (property.key.type !== 'Identifier') {
                   this.warn('ObjectPattern> Only Identifier case handled right now');
@@ -1965,27 +2779,39 @@ class Asserter extends Stringifier {
         }
         t = '"' + this.toSource(classDecl.id) + '"';
       }
-      const loc = this.getName(node);
+      const _loc3 = this.getName(node);
       let prevCheck = '';
-      if (loc === 'ContactPoint#constructor' || loc === 'ContactResult#constructor' || loc === 'SingleContactResult#constructor') {
+      // JSDoc doesn't support multiple function signatures yet, but this is
+      // exactly what we would need to deal with ObjectPool'ing
+      if (_loc3 === 'ContactPoint#constructor' || _loc3 === 'ContactResult#constructor' || _loc3 === 'SingleContactResult#constructor') {
         prevCheck = 'arguments.length !== 0 && ';
       }
       if (first) {
         out += '\n';
         first = false;
       }
-      out += `${spaces}if (${prevCheck}!assertType(${name}, ${t}, '${loc}', '${name}')) {\n`;
+      out += `${spaces}if (${prevCheck}!assertType(${name}, ${t}, '${_loc3}', '${name}')) {\n`;
       out += `${spaces}  youCanAddABreakpointHere();\n${spaces}}\n`;
     }
     return out;
   }
+  /**
+   * @param {Node} node - The Babel AST node.
+   * @returns {string} Best possible human-readable name of given node.
+   */
   getNameForFunctionExpression(node) {
     const objectProperty = this.findParentOfType(node, 'ObjectProperty');
     if (objectProperty) {
+      // See good-old-es5.mjs example for a test case
+      // TODO: Make an even better name based on Object.assign(ScopeSpace.prototype
+      // Ideally we would figure out the name: ScopeSpace#resolve
+      // Currently we only find "resolve" (still better than 'unnamed function expression'...)
       return this.toSource(objectProperty.key);
     }
     const expressionStatement = this.findParentOfType(node, 'ExpressionStatement');
     if (expressionStatement) {
+      // There are many kinds of expressions
+      // type Expression = ArrayExpression | AssignmentExpression | BinaryExpression | CallExpression | ...
       const {
         left
       } = expressionStatement.expression;
@@ -1996,6 +2822,10 @@ class Asserter extends Stringifier {
     }
     return 'unnamed function expression';
   }
+  /**
+   * @param {Node} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   getName(node) {
     const toSource = this.toSource.bind(this);
     if (node.type === 'BlockStatement') {
@@ -2036,6 +2866,11 @@ class Asserter extends Stringifier {
         return '/*MISSING*/';
     }
   }
+  /**
+   * @override
+   * @param {import("@babel/types").BinaryExpression} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   BinaryExpression(node) {
     if (!this.validateDivision) {
       return super.BinaryExpression(node);
@@ -2052,9 +2887,15 @@ class Asserter extends Stringifier {
     }
     return `${left_} ${operator} ${right_}`;
   }
+  /**
+   * @override
+   * @param {import("@babel/types").File} node - The Babel AST node.
+   * @returns {string} Stringification of the node.
+   */
   File(node) {
+    // @todo figure out why errors is in Babel node and not in @babel/types...
     const {
-      program,
+      /*errors,*/program,
       comments
     } = node;
     if (comments) {
@@ -2063,6 +2904,7 @@ class Asserter extends Stringifier {
         parseJSDocTypedef(this.typedefs, warn, comment, this.expandType);
       }
     }
+    //console.log("this.typedefs", this.typedefs);
     let out = '';
     for (const name in this.typedefs) {
       const typedef = this.typedefs[name];
@@ -2075,7 +2917,24 @@ class Asserter extends Stringifier {
   }
 }
 
+/**
+ * Simple facade which does all the processing. Processes the input
+ * source string, adding runtime type checks based on JSDoc comments.
+ *
+ * This function takes JavaScript source code as input, parses it to an AST, traverses the
+ * AST to find type annotations in JSDoc comments, and generates appropriate runtime type
+ * assertions. These are then inserted into the source, producing a new version of the code
+ * that includes runtime type checking based on the original JSDoc annotations.
+ *
+ * @param {string} src - The input source code containing JSDoc comments to be processed
+ * for type checks.
+ * @param {import('./Asserter.mjs').Options} [options] - Configuration options that dictate
+ * how the processing is performed.
+ * @returns {string} The transformed source code with inserted runtime type checks, or the
+ * original source code commented with an error if processing fails.
+ */
 function addTypeChecks(src, options) {
+  console.log("GOT OPTIONS", options);
   try {
     const asserter = new Asserter(options);
     const ast = parse(src, {
@@ -2090,28 +2949,45 @@ function addTypeChecks(src, options) {
   }
 }
 
+/**
+ * @param {object} ast - The Babel AST.
+ * @returns {string} String representation in JSON format for debugging/inspecting the AST.
+ */
 function ast2json(ast) {
   return JSON.stringify(ast, function (name, val) {
     if (name === "loc" || name === "start" || name === "end") {
-      return;
+      return; // remove
     }
-    return val;
+
+    return val; // keep
   }, 2);
 }
 
 const drop = ['loc', 'start', 'end', 'leadingComments', 'trailingComments', 'innerComments', 'innerComments', 'comments'];
+/**
+ * @example
+ * setRight(ast2jsonForComparison(parseSync("/** *"))); // Close comment with / after last *
+ * @param {object} ast - The Babel AST.
+ * @returns {string} String representation in JSON format for debugging/inspecting the AST.
+ */
 function ast2jsonForComparison(ast) {
   return JSON.stringify(ast, function (name, val) {
     if (name === 'trailingComma' || name === 'parenStart') {
       return 'offset removed for better comparison';
     }
     if (drop.includes(name)) {
-      return undefined;
+      return undefined; // remove
     }
-    return val;
+
+    return val; // keep
   }, 2);
 }
 
+/**
+ * A roundtrip between code -> AST -> code to validate Stringifier.
+ * @param {string} code - The code.
+ * @returns {string | undefined} The new and once parsed and stringified code.
+ */
 function code2ast2code(code) {
   const stringifier = new Stringifier();
   const ast = parse(code, {
@@ -2124,6 +3000,11 @@ function code2ast2code(code) {
   return out;
 }
 
+/**
+ * @param {string} left - Left source code.
+ * @param {string} right - Right source code.
+ * @returns {boolean} Whether source codes are identical on the AST level.
+ */
 function compareAST(left, right) {
   const l = parse(left, {
     sourceType: 'module'
@@ -2137,19 +3018,70 @@ function compareAST(left, right) {
   return test;
 }
 
+/**
+ * Transforms a type string into a structured type representation.
+ *
+ * This function parses a given type string and converts it into a TypeScript
+ * Abstract Syntax Tree (AST), then uses that AST to return a structured type
+ * representation that can be further utilized or interpreted.
+ *
+ * @todo Better handling of weird case: Array<>
+ * @example
+ * const {expandType} = await import("./src-transpiler/expandType.mjs");
+ * expandType('[string, Array|AnyTypedArray, number[]]|[ONNXTensor]');
+ * expandType('(123)                    '); // Outputs: '123'
+ * expandType('  ( ( 123 ) )            '); // Outputs: '123'
+ * expandType('Array<number>            '); // Outputs: {type: 'array', elementType: 'number'}
+ * expandType('Array<(123) >            '); // Outputs: {type: 'array', elementType: '123'}
+ * expandType('Array<"abc" | 123>       '); // Outputs: {type: 'array', elementType: {type: 'union', members: ['"abc"', '123']}}
+ * expandType('  (string ) |(number )   '); // Outputs: {type: 'union', members: [ 'string', 'number']}
+ * expandType(' "apples" | ( "bananas") '); // Outputs: {type: 'union', members: [ '"apples"', '"bananas"']}
+ * expandType('123?                     '); // Outputs: {"type":"union","members":["123","null"]}
+ * expandType('123|null                 '); // Outputs: {"type":"union","members":["123","null"]}
+ * expandType('Map<string, any>         '); // Outputs:
+ * expandType('typeof Number            '); // Outputs:
+ * @param {string} type - The type string to be expanded into a structured representation.
+ * @todo Share type with expandTypeBabelTS and expandTypeDepFree
+ * @returns {string | {type: string, [key: string]: any} | undefined} The structured type
+ * representation obtained from parsing and converting the provided type string.
+ */
 function expandType(type) {
   const ast = parseType(type);
   return toSourceTS(ast);
 }
+/**
+ * @todo I want to use for example: import('typescript').Node
+ * But the TS types make no sense to me so far ... need to investigate more.
+ * @typedef TypeScriptType
+ * @property {object[]|undefined} typeArguments - The type arguments.
+ * @property {import('typescript').Node} typeName - The type name.
+ * @property {number} kind - The kind for `ts.SyntaxKind[kind]`.
+ */
+/**
+ * @param {string} str - The type string.
+ * @returns {TypeScriptType} - The node containing all the information about the input type string.
+ */
 function parseType(str) {
+  // TS doesn't like ... notation in this context
   if (str.startsWith('...')) {
-    str = str.slice(3);
-    str += '[]';
+    str = str.slice(3); // remove dots
+    str += '[]'; // turn into array
   }
+  // type tmp = (...string) => 123; to have a function context
   str = `type tmp = ${str};`;
-  const ast = ts.createSourceFile('repl.ts', str, ts.ScriptTarget.Latest, true);
+  const ast = ts.createSourceFile('repl.ts', str, ts.ScriptTarget.Latest, true /*setParentNodes*/);
   return ast.statements[0].type;
 }
+/**
+ * Converts a TypeScript AST node to a source string representation or to an intermediate object describing the type.
+ *
+ * This function handles various TypeScript AST node types and converts them into a string
+ * or an object representing the type.
+ *
+ * @param {TypeScriptType} node - The TypeScript AST node to convert.
+ * @returns {string | {type: string, [key: string]: any} | undefined} The source string or an object with type information based on the node,
+ * or `undefined` if the node kind is not handled.
+ */
 function toSourceTS(node) {
   const {
     typeArguments,
@@ -2193,23 +3125,31 @@ function toSourceTS(node) {
     IndexedAccessType,
     RestType,
     TypeQuery,
+    // parseType('typeof Number')
     TypeOperator,
+    // parseType('keyof typeof obj')
     KeyOfKeyword,
+    // "operator" key in TypeOperator node
     ConstructorType,
+    // parseType('new (...args: any[]) => any');
     NamedTupleMember
   } = ts.SyntaxKind;
+  // console.log({typeArguments, typeName, kind_, node});
   switch (node.kind) {
     case BigIntKeyword:
       return {
         type: 'bigint'
       };
     case BigIntLiteral:
-      const literal = node.text.slice(0, -1);
+      const literal = node.text.slice(0, -1); // Remove the "n"
       return {
         type: 'bigint',
         literal
       };
     case ConditionalType:
+      // Keys on node:
+      // ['pos', 'end', 'flags', 'modifierFlagsCache', 'transformFlags', 'parent', 'kind', 'checkType',
+      // 'extendsType', 'trueType', 'falseType', 'locals', 'nextContainer']
       const checkType = toSourceTS(node.checkType);
       const extendsType = toSourceTS(node.extendsType);
       const trueType = toSourceTS(node.trueType);
@@ -2257,6 +3197,8 @@ function toSourceTS(node) {
         type: 'union',
         members: [t, 'null']
       };
+    // todo work out more: const jsdoc = `(...a: ...number) => 123
+    // TS even thinks it's two parameters... just go for array/[]
     case Parameter:
       const type = node.type ? toSourceTS(node.type) : 'any';
       const name = toSourceTS(node.name);
@@ -2389,6 +3331,7 @@ function toSourceTS(node) {
       return toSourceTS(node.literal);
     case AnyKeyword:
     case BooleanKeyword:
+    // ts.SyntaxKind[parseType("*").kind] === 'JSDocAllType'
     case JSDocAllType:
     case NullKeyword:
     case NumericLiteral:
@@ -2407,10 +3350,17 @@ function toSourceTS(node) {
         properties: {}
       };
     case ParenthesizedType:
+      // fall-through for parentheses
       return toSourceTS(node.type);
     case LastTypeNode:
       return toSourceTS(node.qualifier);
     default:
+      // const test = {};
+      // Object.entries(ts.SyntaxKind).forEach(([name, id]) => {
+      //     test[id] = (test[id] || []);
+      //     test[id].push(name);
+      // });
+      // console.log(test);
       console.warn('toSourceTS> unhandled kind - make sure to understand you cannot reverse TS enums');
       console.warn('if they contain range aliases, for example:');
       console.warn('ts.SyntaxKind.NumericLiteral === ts.SyntaxKind.FirstLiteralToken');
@@ -2419,17 +3369,58 @@ function toSourceTS(node) {
   }
 }
 
+/**
+ * @todo Better handling of weird case: Array<>
+ * @example
+ * const {expandTypeBabelTS} = await import("./src-transpiler/expandTypeBabelTS.mjs");
+ * expandTypeBabelTS('[string, Array|AnyTypedArray, number[]]|[ONNXTensor]');
+ * expandTypeBabelTS('(123)                    '); // Outputs: '123'
+ * expandTypeBabelTS('  ( ( 123 ) )            '); // Outputs: '123'
+ * expandTypeBabelTS('Array<number>            '); // Outputs: {type: 'array', elementType: 'number'}
+ * expandTypeBabelTS('Array<(123) >            '); // Outputs: {type: 'array', elementType: '123'}
+ * expandTypeBabelTS('Array<"abc" | 123>       '); // Outputs: {type: 'array', elementType: {type: 'union', members: ['"abc"', '123']}}
+ * expandTypeBabelTS('  (string ) |(number )   '); // Outputs: {type: 'union', members: [ 'string', 'number']}
+ * expandTypeBabelTS(' "apples" | ( "bananas") '); // Outputs: {type: 'union', members: [ '"apples"', '"bananas"']}
+ * expandTypeBabelTS('123?                     '); // Outputs: {type: 'union', members: ['123', 'null']}
+ * expandTypeBabelTS('123|null                 '); // Outputs: {type: 'union', members: ['123', 'null']}
+ * expandTypeBabelTS('Map<string, any>         '); // Outputs: {type: 'map', key: 'string', val: 'any'}
+ * expandTypeBabelTS("(a: number, b: number) => number")
+ * @param {string} type - The input type.
+ * @returns {string|object|undefined} - See `toSourceBabelTS`.
+ */
 function expandTypeBabelTS(type) {
   const ast = parseTypeBabelTS(type);
   return toSourceBabelTS(ast);
 }
+/**
+ * @param {string} str - The type string.
+ * @returns {import('@babel/types').Node} - The node containing all the information about the input type string.
+ */
 function parseTypeBabelTS(str) {
+  // TS doesn't like ... notation in this context
+  //if (str.startsWith('...')) {
+  //  str = str.slice(3); // remove dots
+  //  str += '[]'; // turn into array
+  //}
+  // type tmp = (...string) => 123; to have a function context
   str = `type tmp = ${str};`;
   const ast = parse(str, {
     plugins: ['typescript']
   });
   return ast.program.body[0].typeAnnotation;
 }
+/**
+ * Converts a Babel AST node to its source string representation or structured type object.
+ *
+ * This function handles a variety of node types provided by Babel and converts them into a string
+ * or an intermediate object representing the type, depending on the complexity of the type described by the node.
+ *
+ * @param {import('@babel/types').Node} node - The Babel AST node to convert.
+ * @returns {string|object|undefined} - A string, object representing a structured type, or `undefined` for unhandled types.
+ * Depending on the node, it may return a simple type string (e.g., `"string"` for `TSStringKeyword`),
+ * a structured type object (e.g., a record type for `TSTypeReference` with type arguments),
+ * or `undefined` if the encountered type is not handled. Unhandled types trigger a warning and enter a debugger statement.
+ */
 function toSourceBabelTS(node) {
   switch (node.type) {
     case 'TSBigIntKeyword':
@@ -2442,10 +3433,34 @@ function toSourceBabelTS(node) {
         type: 'bigint',
         literal
       };
+    // expandTypeBabelTS("(a: number, b: number) => number")
+    /**
+     * @todo the parameters are given as identifiers with "typeAnnotation"
+     */
+    // case 'TSFunctionType':
+    //   const parameters = node.parameters.map(toSourceBabelTS);
+    //   // I wish Babel AST would be like tsc AST here:
+    //   // parseType("(a: number, b: number) => number").parameters[0].kind === ts.SyntaxKind.Parameter
+    //   return {type: 'function', parameters};
+    // Fix first: https://github.com/babel/babel/issues/16073
+    //case 'JSDocNullableType':
+    //  const t = toSourceBabelTS(node.type);
+    //  return {type: 'union', members: [t, 'null']};
+    // todo work out more: const jsdoc = `(...a: ...number) => 123
+    // TS even thinks it's two parameters... just go for array/[]
+    //case 'Parameter':
+    //  const type = node.type ? toSourceBabelTS(node.type) : 'any';
+    //  const name = toSourceBabelTS(node.name);
+    //  const ret = {type, name};
+    //  if (node.dotDotDotToken) {
+    //    return {type: 'array', elementType: ret};
+    //  }
+    //  return ret;
     case 'TSTypeReference':
       {
         const name = toSourceBabelTS(node.typeName);
         if (!node.typeParameters) {
+          // console.log(`node.typeName.name=${node.typeName.name} name=${name}`, node);
           return node.typeName.name;
         }
         console.assert(node.typeParameters.type === 'TSTypeParameterInstantiation');
@@ -2529,6 +3544,9 @@ function toSourceBabelTS(node) {
         type: 'object',
         properties
       };
+    // case 'PropertySignature':
+    //   console.warn('toSourceBabelTS> should not happen, handled by TypeLiteral directly');
+    //   return `${toSourceBabelTS(node.name)}: ${toSourceBabelTS(node.type)}`;
     case 'Identifier':
       return node.name;
     case 'TSArrayType':
@@ -2538,25 +3556,36 @@ function toSourceBabelTS(node) {
       };
     case 'TSLiteralType':
       return toSourceBabelTS(node.literal);
+    // expandTypeBabelTS("any")
     case 'TSAnyKeyword':
       return 'any';
+    // expandTypeBabelTS("boolean")
     case 'TSBooleanKeyword':
       return 'boolean';
+    // expandTypeBabelTS('true | false');
     case 'BooleanLiteral':
       return node.value.toString();
+    // ts.SyntaxKind[parseType("*").kind] === 'JSDocAllType'
+    // But Babel-TS doesn't parse it atm
+    //case 'JSDocAllType':
+    // expandTypeBabelTS('null')
     case 'TSNullKeyword':
       return 'null';
+    // expandTypeBabelTS('123')
     case 'NumericLiteral':
     case 'StringLiteral':
       return node.extra.raw;
+    // expandTypeBabelTS('undefined')
     case 'TSUndefinedKeyword':
       return 'undefined';
     case 'TSUnknownKeyword':
       return 'unknown';
     case 'TSNeverKeyword':
       return 'never';
+    // parseTypeBabelTS('void');
     case 'TSVoidKeyword':
       return 'void';
+    // expandTypeBabelTS('this')
     case 'TSThisType':
       return 'this';
     case 'ObjectKeyword':
@@ -2565,6 +3594,7 @@ function toSourceBabelTS(node) {
         properties: {}
       };
     case 'ParenthesizedType':
+      // fall-through for parentheses
       return toSourceBabelTS(node.type);
     case 'LastTypeNode':
       return toSourceBabelTS(node.qualifier);