@runtime-type-inspector/transpiler 2.2.2 → 2.2.4

package/index.cjs

@@ -258,11 +258,47 @@
 	  return typeof key === "symbol" ? key : String(key);
 	}
 
+	/**
+	 * @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] === '.') {
 	    var elementType = type.slice(3);
 	    return {
@@ -270,6 +306,8 @@
 	      elementType: elementType
 	    };
 	  }
+	  // (2)
+	  // Array<...>
 	  if (type.startsWith("Array<") && type.endsWith('>')) {
 	    var typeSlice = type.slice(6, -1);
 	    var _elementType = expandTypeDepFree(typeSlice);
@@ -278,6 +316,7 @@
 	      elementType: _elementType
 	    };
 	  }
+	  // Promise<...>
 	  if (type.startsWith("Promise<") && type.endsWith('>')) {
 	    var _typeSlice = type.slice(8, -1);
 	    var _elementType2 = expandTypeDepFree(_typeSlice);
@@ -286,6 +325,7 @@
 	      elementType: _elementType2
 	    };
 	  }
+	  // (3) Object<...> or Record<...>
 	  if ((type.startsWith("Object<") || type.startsWith("Record<")) && type.endsWith('>')) {
 	    var recordSlice = type.slice(7, -1);
 	    var firstComma = recordSlice.indexOf(',');
@@ -300,8 +340,9 @@
 	      val: expandTypeDepFree(val)
 	    };
 	  }
+	  // (4) {...}
 	  if (type[0] === '{' && type[type.length - 1] === '}') {
-	    var propertiesArray = type.slice(1, -1).split(',');
+	    var propertiesArray = type.slice(1, -1).split(','); // ['entity: Entity', ' app: AppBase']
 	    var properties = {};
 	    propertiesArray.forEach(function (_) {
 	      var _$split$map = _.split(":").map(function (_) {
@@ -321,6 +362,7 @@
 	      properties: properties
 	    };
 	  }
+	  // (5) expand unions
 	  var members = type.split("|");
 	  if (members.length >= 2) {
 	    members.forEach(function (_, i) {
@@ -331,6 +373,8 @@
 	      members: members.map(expandTypeDepFree)
 	    };
 	  }
+	  // (6) expand [] Arrays
+	  // Test arrays: new pc.Mat3().set([1, 2, 3, "asd"])
 	  if (type.endsWith("[]")) {
 	    var _typeSlice2 = type.slice(0, -2);
 	    return {
@@ -338,13 +382,15 @@
 	      elementType: expandTypeDepFree(_typeSlice2)
 	    };
 	  }
+	  // (7) expand tuples
 	  if (type[0] === '[' && type[type.length - 1] === ']') {
-	    var elements = type.slice(1, -1).split(',');
+	    var 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 ')) {
 	    var argument = expandTypeDepFree(type.substring(7));
 	    return {
@@ -361,6 +407,14 @@
 	  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':
@@ -374,12 +428,23 @@
 	  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 = {
@@ -392,46 +457,68 @@
 	  }
 	  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) {
 	  var expandType = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : expandTypeDepFree;
+	  // Parse something like: @param {Object} [kwargs={}] Optional arguments.
 	  var regex = /@param \{(.*?)\} ([\[\]a-zA-Z0-9_$=\{\}\.'" ]+)/g;
 	  var matches = _toConsumableArray(src.matchAll(regex));
+	  /** @type {Record<string, any>} */
 	  var params = Object.create(null);
 	  matches.forEach(function (_) {
 	    var type = expandType(_[1].trim());
 	    var name = _[2].trim();
 	    var 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
 	      var 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();
 	    var simplifiedType = simplifyType(type, optional);
 	    var parts = name.split(".");
 	    if (parts.length === 3) {
-	      var parts0 = parts[0];
-	      var parts1 = parts[1];
-	      var parts2 = parts[2];
+	      // Something like: @param {number[]} settings.render.skyboxRotation - Rotation of skybox.
+	      var parts0 = parts[0]; // settings
+	      var parts1 = parts[1]; // render
+	      var parts2 = parts[2]; // skyboxRotation
 	      var toptype = params[parts0];
 	      toptype.properties[parts1].properties = toptype.properties[parts1].properties || {};
 	      toptype.properties[parts1].properties[parts2] = simplifiedType;
 	    } else if (parts.length === 2) {
-	      var _parts = parts[0];
-	      var _parts2 = parts[1];
+	      // Something like: @param {number} description[].components
+	      var _parts = parts[0]; // description[]
+	      var _parts2 = parts[1]; // components
 	      if (_parts.endsWith('[]')) {
-	        _parts = _parts.slice(0, -2);
+	        _parts = _parts.slice(0, -2); // description[] -> description
 	      }
+
 	      var _toptype = params[_parts];
 	      if ((_toptype === null || _toptype === void 0 ? void 0 : _toptype.type) === "union") {
 	        var typeObject = _toptype.members.find(function (_) {
 	          return (_ === null || _ === void 0 ? void 0 : _.type) === 'object';
 	        });
 	        typeObject.properties[_parts2] = simplifiedType;
+	        //typeObject.properties = simplifiedType; // todo add test case
 	      } else if ((_toptype === null || _toptype === void 0 ? void 0 : _toptype.type) === "array") {
 	        _toptype.elementType.properties[_parts2] = simplifiedType;
 	      } else if ((_toptype === null || _toptype === void 0 ? void 0 : _toptype.type) === "object") {
@@ -456,6 +543,12 @@
 	  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) {
 	  var expandType = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : expandTypeDepFree;
 	  var regex = /@type \{(.*?)\}/g;
@@ -463,23 +556,49 @@
 	  if (matches.length === 1) {
 	    var match = matches[0];
 	    var type = expandType(match[1]);
-	    var simplifiedType = simplifyType(type, false);
+	    var 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();
 	  var 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
 	    var 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)
 	  var 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) {
 	  var firstCurly = line.indexOf('{');
 	  var k = firstCurly + 1;
@@ -501,6 +620,17 @@
 	    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) {
 	  var type = comment.type,
 	    value = comment.value;
@@ -523,13 +653,16 @@
 	          def = _extractCurlyContent.content,
 	          nextIndex = _extractCurlyContent.nextIndex;
 	        var 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;
 	        }
@@ -542,6 +675,7 @@
 	          _extractNameAndOption2 = _slicedToArray(_extractNameAndOption, 2),
 	          _name = _extractNameAndOption2[0],
 	          optional = _extractNameAndOption2[1];
+	        // console.log({name, optional, propType});
 	        var finalType = simplifyType(propType, optional);
 	        if (((_lastTypedef = lastTypedef) === null || _lastTypedef === void 0 ? void 0 : _lastTypedef.type) === 'object') {
 	          lastTypedef.properties[_name] = finalType;
@@ -560,23 +694,46 @@
 	  }
 	}
 
+	/**
+	 * @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) {
 	  var 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);
 	}
 
-	var Stringifier = function () {
+	/**
+	 * @typedef {import("@babel/types").Node} Node
+	 */
+	/**
+	 * Class for converting AST into string.
+	 */
+	var Stringifier = /*#__PURE__*/function () {
 	  function Stringifier() {
 	    _classCallCheck(this, Stringifier);
 	    _defineProperty(this, "forceCurly", false);
+	    /** @type {Node[]} */
 	    _defineProperty(this, "parents", []);
 	    _defineProperty(this, "lastCommentBlockIndex", -1);
 	    _defineProperty(this, "lastCommentLineIndex", -1);
@@ -584,9 +741,19 @@
 	  }
 	  _createClass(Stringifier, [{
 	    key: "toSource",
-	    value: function toSource(node) {
+	    value:
+	    /**
+	     * @param {Node} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
+	    function 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 '';
 	      }
 	      var leadingComments = node.leadingComments,
@@ -598,6 +765,7 @@
 	      var out = '';
 	      var comments = '';
 	      if (leadingComments) {
+	        // comments += this.mapToSource(leadingComments).join('');
 	        comments = this.leadingCommentsToSource(leadingComments);
 	      }
 	      if (node !== null && node !== void 0 && (_node$extra = node.extra) !== null && _node$extra !== void 0 && _node$extra.parenthesized) {
@@ -608,9 +776,17 @@
 	      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.
+	     */
 	  }, {
 	    key: "toSource_",
 	    value: function toSource_(node) {
@@ -637,21 +813,30 @@
 	  }, {
 	    key: "parentProvidesSpaces",
 	    value: function parentProvidesSpaces(reverseIndex) {
+	      // May look like: .../ArrayExpression/StringLiteral/CommentLine
 	      var parents = this.parents;
 	      var parent = parents[parents.length - reverseIndex];
+	      // console.log("Got parent", parent.type);
 	      return (parent === null || parent === void 0 ? void 0 : parent.type) === 'ArrayExpression';
 	    }
 	  }, {
 	    key: "CommentBlock",
-	    value: function CommentBlock(node) {
+	    value:
+	    /**
+	     * @param {import("@babel/types").CommentBlock} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
+	    function CommentBlock(node) {
 	      var loc = node.loc;
 	      var value = node.value;
 	      if (this.lastCommentBlockIndex === loc.start.index) {
+	        // console.log("CommentBlock> ignore double");
 	        return '';
 	      }
 	      this.lastCommentBlockIndex = loc.start.index;
 	      var spaces = this.spaces;
 	      var out = '';
+	      /** @todo add option for number-of-spaces */
 	      var dedicatedLine = spaces.length === loc.start.column;
 	      if (dedicatedLine) {
 	        out += spaces;
@@ -659,6 +844,7 @@
 	      var 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 || _this$parents$at === void 0 ? void 0 : _this$parents$at.type) === 'AssignmentExpression') {
 	          spaces += '  ';
 	        }
@@ -666,9 +852,13 @@
 	      }
 	      out += '/*';
 	      if (value.includes('\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(function (_) {
 	          return _.length;
-	        }).map(function (line, i) {
+	        }) // skip empty lines
+	        // Skip spaces in first line for /**
+	        .map(function (line, i) {
 	          return (i ? spaces + ' ' : '') + line;
 	        }).join('\n');
 	        out += "".concat(value, "\n").concat(spaces, " */");
@@ -684,10 +874,16 @@
 	    }
 	  }, {
 	    key: "CommentLine",
-	    value: function CommentLine(node) {
+	    value:
+	    /**
+	     * @param {import("@babel/types").CommentLine} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
+	    function CommentLine(node) {
 	      var value = node.value,
 	        loc = node.loc;
 	      if (this.lastCommentLineIndex === loc.start.index) {
+	        // console.log("CommentLine> ignore double");
 	        return '';
 	      }
 	      this.lastCommentLineIndex = loc.start.index;
@@ -712,6 +908,8 @@
 	      var out = leadingComments.map(function (_) {
 	        return _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;
 	      }
@@ -729,6 +927,7 @@
 	          if (trailingComment.type === 'CommentBlock') {
 	            var loc = trailingComment.loc;
 	            var dedicatedLine = this.spaces.length === loc.start.column;
+	            // out += ` /*dedicatedLine=${dedicatedLine}*/ `;
 	            if (dedicatedLine) {
 	              out += '\n';
 	            } else {
@@ -744,10 +943,16 @@
 	      }
 	      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.
+	     */
 	  }, {
 	    key: "commentToSource",
 	    value: function commentToSource(comment, pos) {
 	      if (comment.type === 'CommentBlock') {
+	        //if (pos === 'leading') {}
 	        return this.CommentBlock(comment);
 	      } else if (comment.type === 'CommentLine') {
 	        return this.CommentLine(comment);
@@ -756,6 +961,12 @@
 	      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.
+	     */
 	  }, {
 	    key: "toSourceCurly",
 	    value: function toSourceCurly(node) {
@@ -768,7 +979,10 @@
 	      var 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';
@@ -794,6 +1008,10 @@
 	      var 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.
+	     */
 	  }, {
 	    key: "mapToSource",
 	    value: function mapToSource(arr) {
@@ -802,6 +1020,16 @@
 	        return _this2.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.
+	     */
 	  }, {
 	    key: "generateTypeChecks",
 	    value: function generateTypeChecks(node) {
@@ -809,7 +1037,11 @@
 	    }
 	  }, {
 	    key: "spaces",
-	    get: function get() {
+	    get:
+	    /**
+	     * @type {string} A string of two spaces per indentation.
+	     */
+	    function get() {
 	      return '  '.repeat(this.numSpaces);
 	    }
 	  }, {
@@ -823,18 +1055,32 @@
 	      }).join('/');
 	      return "".concat(spaces, "// got ").concat(n, " spaces for ").concat(path, "\n");
 	    }
+	    /**
+	     * > await something();
+	     *
+	     * @param {import("@babel/types").AwaitExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "AwaitExpression",
 	    value: function AwaitExpression(node) {
 	      var argument = node.argument;
 	      return "await ".concat(this.toSource(argument));
 	    }
+	    /**
+	     * @param {import("@babel/types").ClassBody} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ClassBody",
 	    value: function ClassBody(node) {
 	      var body = node.body;
 	      return this.mapToSource(body).join('\n');
 	    }
+	    /**
+	     * @param {import("@babel/types").ClassMethod} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ClassMethod",
 	    value: function ClassMethod(node) {
@@ -876,6 +1122,10 @@
 	      out += this.toSource(body);
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").ClassExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ClassExpression",
 	    value: function ClassExpression(node) {
@@ -884,6 +1134,7 @@
 	        body = node.body;
 	      var 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) {
@@ -894,6 +1145,10 @@
 	      out += "{\n".concat(c, "\n}");
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").ClassDeclaration} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ClassDeclaration",
 	    value: function ClassDeclaration(node) {
@@ -915,6 +1170,10 @@
 	      out += '\n}\n';
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").ClassPrivateMethod} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ClassPrivateMethod",
 	    value: function ClassPrivateMethod(node) {
@@ -951,6 +1210,15 @@
 	      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.
+	     */
 	  }, {
 	    key: "ClassProperty",
 	    value: function ClassProperty(node) {
@@ -958,7 +1226,7 @@
 	        computed = node.computed,
 	        value = node.value;
 	        node.leadingComments;
-	      var static_ = node.static;
+	      var static_ = node.static; // JS keyword is problematic in object destructuring
 	      var a = this.toSource(key);
 	      var b = this.toSource(value);
 	      var out = this.spaces;
@@ -976,6 +1244,10 @@
 	      out += ';';
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").ClassPrivateProperty} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ClassPrivateProperty",
 	    value: function ClassPrivateProperty(node) {
@@ -993,6 +1265,10 @@
 	      out += ';';
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").ContinueStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ContinueStatement",
 	    value: function ContinueStatement(node) {
@@ -1004,11 +1280,24 @@
 	      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.
+	     */
 	  }, {
 	    key: "FunctionDeclarationParams",
 	    value: function FunctionDeclarationParams(params) {
 	      return '(' + this.mapToSource(params).join(', ') + ')';
 	    }
+	    /**
+	     * @param {import("@babel/types").FunctionDeclaration} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "FunctionDeclaration",
 	    value: function FunctionDeclaration(node) {
@@ -1030,9 +1319,14 @@
 	      out += this.toSource(body);
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").FunctionExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "FunctionExpression",
 	    value: function FunctionExpression(node) {
+	      // Leading comments for asd=function(){} are in ExpressionStatement
 	      var async = node.async,
 	        body = node.body,
 	        generator = node.generator,
@@ -1056,6 +1350,10 @@
 	      }
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").ArrowFunctionExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ArrowFunctionExpression",
 	    value: function ArrowFunctionExpression(node) {
@@ -1075,6 +1373,10 @@
 	      out += this.toSource(body);
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").BigIntLiteral} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "BigIntLiteral",
 	    value: function BigIntLiteral(node) {
@@ -1082,6 +1384,10 @@
 	        node.value;
 	      return extra.raw;
 	    }
+	    /**
+	     * @param {import("@babel/types").BlockStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "BlockStatement",
 	    value: function BlockStatement(node) {
@@ -1091,6 +1397,7 @@
 	      var out = '';
 	      out += ' {';
 	      this.numSpaces++;
+	      // Handle Directive/DirectiveLiteral like 'use strict';
 	      if (directives && directives.length) {
 	        out += '\n';
 	        out += this.mapToSource(directives).join('\n') + '\n';
@@ -1098,8 +1405,10 @@
 	      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;
 	      }
@@ -1107,12 +1416,24 @@
 	      out += '}';
 	      return out;
 	    }
+	    /**
+	     * > 'use strict';
+	     *
+	     * @param {import("@babel/types").Directive} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "Directive",
 	    value: function Directive(node) {
 	      var value = node.value;
 	      return this.toSource(value);
 	    }
+	    /**
+	     * > 'use strict';
+	     *
+	     * @param {import("@babel/types").DirectiveLiteral} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "DirectiveLiteral",
 	    value: function DirectiveLiteral(node) {
@@ -1121,6 +1442,10 @@
 	      var spaces = this.spaces;
 	      return "".concat(spaces).concat(extra.raw, ";");
 	    }
+	    /**
+	     * @param {import("@babel/types").ReturnStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ReturnStatement",
 	    value: function ReturnStatement(node) {
@@ -1131,11 +1456,19 @@
 	      }
 	      return spaces + 'return ' + this.toSource(argument) + ';';
 	    }
+	    /**
+	     * @param {import("@babel/types").Identifier} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "Identifier",
 	    value: function Identifier(node) {
 	      return node.name;
 	    }
+	    /**
+	     * @param {import("@babel/types").IfStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "IfStatement",
 	    value: function IfStatement(node) {
@@ -1144,7 +1477,10 @@
 	        test = node.test;
 	      var spaces = this.spaces;
 	      var out = '';
+	      //if (this.parentType !== "IfStatement")
+	      //{
 	      out += spaces;
+	      //}
 	      out += "if (".concat(this.toSource(test), ")");
 	      out += this.toSourceCurly(consequent);
 	      if (alternate) {
@@ -1152,6 +1488,10 @@
 	      }
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").LabeledStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "LabeledStatement",
 	    value: function LabeledStatement(node) {
@@ -1164,6 +1504,15 @@
 	      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.
+	     */
 	  }, {
 	    key: "UnaryExpression",
 	    value: function UnaryExpression(node) {
@@ -1174,6 +1523,7 @@
 	      if (!prefix) {
 	        console.warn("Stringifier#UnaryExpression> never considered !prefix", node);
 	      }
+	      // Add a space for: typeof/delete/void
 	      var c = operator.charCodeAt(0);
 	      var op = operator;
 	      if (c >= 97 && c <= 122) {
@@ -1183,6 +1533,10 @@
 	      out += this.toSource(argument);
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").MemberExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "MemberExpression",
 	    value: function MemberExpression(node) {
@@ -1194,6 +1548,10 @@
 	      }
 	      return "".concat(this.toSource(object), ".").concat(this.toSource(property));
 	    }
+	    /**
+	     * @param {import("@babel/types").MetaProperty} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "MetaProperty",
 	    value: function MetaProperty(node) {
@@ -1203,12 +1561,26 @@
 	      var rhs = this.toSource(property);
 	      return "".concat(lhs, ".").concat(rhs);
 	    }
+	    /**
+	     * @param {import("@babel/types").ExpressionStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ExpressionStatement",
 	    value: function ExpressionStatement(node) {
 	      var expression = node.expression;
+	      /**
+	       * 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.
+	     */
 	  }, {
 	    key: "CallExpression",
 	    value: function CallExpression(node) {
@@ -1224,6 +1596,14 @@
 	      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.
+	     */
 	  }, {
 	    key: "ObjectExpression",
 	    value: function ObjectExpression(node) {
@@ -1245,6 +1625,10 @@
 	      out += '}';
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").ObjectProperty} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ObjectProperty",
 	    value: function ObjectProperty(node) {
@@ -1272,11 +1656,19 @@
 	      out += right;
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").BooleanLiteral} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "BooleanLiteral",
 	    value: function BooleanLiteral(node) {
 	      return node.value.toString();
 	    }
+	    /**
+	     * @param {import("@babel/types").AssignmentExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "AssignmentExpression",
 	    value: function AssignmentExpression(node) {
@@ -1285,8 +1677,13 @@
 	        right = node.right;
 	      var left_ = this.toSource(left);
 	      var right_ = this.toSource(right);
+	      // operator is for example: = |= &=
 	      return "".concat(left_, " ").concat(operator, " ").concat(right_);
 	    }
+	    /**
+	     * @param {import("@babel/types").BinaryExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "BinaryExpression",
 	    value: function BinaryExpression(node) {
@@ -1297,11 +1694,19 @@
 	      var right_ = this.toSource(right);
 	      return "".concat(left_, " ").concat(operator, " ").concat(right_);
 	    }
+	    /**
+	     * @param {import("@babel/types").ThisExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ThisExpression",
 	    value: function ThisExpression(node) {
 	      return 'this';
 	    }
+	    /**
+	     * @param {import("@babel/types").ArrayExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ArrayExpression",
 	    value: function ArrayExpression(node) {
@@ -1324,6 +1729,10 @@
 	      out += '\n' + this.spaces + ']';
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").VariableDeclaration} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "VariableDeclaration",
 	    value: function VariableDeclaration(node) {
@@ -1337,6 +1746,10 @@
 	      }
 	      return "".concat(spaces).concat(kind, " ").concat(this.mapToSource(declarations).join(', ')).concat(semicolon);
 	    }
+	    /**
+	     * @param {import("@babel/types").VariableDeclarator} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "VariableDeclarator",
 	    value: function VariableDeclarator(node) {
@@ -1347,6 +1760,10 @@
 	      }
 	      return this.toSource(id);
 	    }
+	    /**
+	     * @param {import("@babel/types").ConditionalExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ConditionalExpression",
 	    value: function ConditionalExpression(node) {
@@ -1355,6 +1772,12 @@
 	        test = node.test;
 	      return "".concat(this.toSource(test), " ? ").concat(this.toSource(consequent), " : ").concat(this.toSource(alternate));
 	    }
+	    /**
+	     * if (...)
+	     *
+	     * @param {import("@babel/types").LogicalExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "LogicalExpression",
 	    value: function LogicalExpression(node) {
@@ -1371,6 +1794,12 @@
 	      }
 	      return "".concat(l, " ").concat(operator, " ").concat(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.
+	     */
 	  }, {
 	    key: "ForStatement",
 	    value: function ForStatement(node) {
@@ -1385,6 +1814,12 @@
 	      var b = this.toSourceCurly(body);
 	      return "".concat(spaces, "for (").concat(i, "; ").concat(t, "; ").concat(u, ")").concat(b);
 	    }
+	    /**
+	     * showAST("++i")
+	     *
+	     * @param {import("@babel/types").UpdateExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "UpdateExpression",
 	    value: function UpdateExpression(node) {
@@ -1396,6 +1831,10 @@
 	      }
 	      return "".concat(this.toSource(argument)).concat(operator);
 	    }
+	    /**
+	     * @param {import("@babel/types").NewExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "NewExpression",
 	    value: function NewExpression(node) {
@@ -1405,6 +1844,12 @@
 	      var args = this.mapToSource(args_).join(', ');
 	      return "new ".concat(c, "(").concat(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.
+	     */
 	  }, {
 	    key: "TemplateLiteral",
 	    value: function TemplateLiteral(node) {
@@ -1420,12 +1865,20 @@
 	      out += '`';
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").TemplateElement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "TemplateElement",
 	    value: function TemplateElement(node) {
 	      var value = node.value;
 	      return value.raw;
 	    }
+	    /**
+	     * @param {import("@babel/types").ParenthesizedExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ParenthesizedExpression",
 	    value: function ParenthesizedExpression(node) {
@@ -1442,23 +1895,39 @@
 	      out += '\n' + this.spaces + ')';
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").PrivateName} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "PrivateName",
 	    value: function PrivateName(node) {
 	      var id = node.id;
 	      return "#".concat(this.toSource(id));
 	    }
+	    /**
+	     * @param {import("@babel/types").ExportAllDeclaration} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ExportAllDeclaration",
 	    value: function ExportAllDeclaration(node) {
 	      return "export * from ".concat(node.source.extra.raw, ";");
 	    }
+	    /**
+	     * @param {import("@babel/types").ExportNamespaceSpecifier} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ExportNamespaceSpecifier",
 	    value: function ExportNamespaceSpecifier(node) {
 	      var exported = node.exported;
 	      return '* as ' + this.toSource(exported);
 	    }
+	    /**
+	     * @param {import("@babel/types").ExportNamedDeclaration} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ExportNamedDeclaration",
 	    value: function ExportNamedDeclaration(node) {
@@ -1486,6 +1955,7 @@
 	            out += '}';
 	          } else {
 	            out += 'export {\n';
+	            // todo: fix spacing system
 	            out += this.mapToSource(specifiers).map(function (_) {
 	              return "  ".concat(_this3.spaces).concat(_);
 	            }).join(',\n');
@@ -1505,6 +1975,10 @@
 	      }
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").ExportDefaultDeclaration} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ExportDefaultDeclaration",
 	    value: function ExportDefaultDeclaration(node) {
@@ -1512,6 +1986,10 @@
 	      var a = this.toSource(declaration);
 	      return "export default ".concat(a, ";");
 	    }
+	    /**
+	     * @param {import("@babel/types").ExportSpecifier} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ExportSpecifier",
 	    value: function ExportSpecifier(node) {
@@ -1523,13 +2001,24 @@
 	      if (left === right) {
 	        return "".concat(spaces).concat(left);
 	      }
+	      // For example:
+	      // PostEffect: PostEffect$1\n
+	      // createMesh: createMesh$1\n
 	      return "".concat(spaces).concat(right, " as ").concat(left);
 	    }
+	    /**
+	     * @param {import("@babel/types").Super} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "Super",
 	    value: function Super(node) {
 	      return 'super';
 	    }
+	    /**
+	     * @param {import("@babel/types").ForInStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ForInStatement",
 	    value: function ForInStatement(node) {
@@ -1542,6 +2031,10 @@
 	      var b = this.toSourceCurly(body);
 	      return "".concat(spaces, "for (").concat(l, " in ").concat(r, ")").concat(b);
 	    }
+	    /**
+	     * @param {import("@babel/types").ThrowStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ThrowStatement",
 	    value: function ThrowStatement(node) {
@@ -1550,6 +2043,10 @@
 	      var arg = this.toSource(argument);
 	      return "".concat(spaces, "throw ").concat(arg, ";");
 	    }
+	    /**
+	     * @param {import("@babel/types").WhileStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "WhileStatement",
 	    value: function WhileStatement(node) {
@@ -1560,6 +2057,10 @@
 	      var b = this.toSourceCurly(body);
 	      return "".concat(spaces, "while (").concat(t, ")").concat(b);
 	    }
+	    /**
+	     * @param {import("@babel/types").BreakStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "BreakStatement",
 	    value: function BreakStatement(node) {
@@ -1571,6 +2072,10 @@
 	      out += ';';
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").ForOfStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ForOfStatement",
 	    value: function ForOfStatement(node) {
@@ -1585,6 +2090,13 @@
 	      var a = await_ ? 'await ' : '';
 	      return "".concat(spaces, "for ").concat(a, "(").concat(l, " of ").concat(r, ")").concat(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.
+	     */
 	  }, {
 	    key: "ArrayPattern",
 	    value: function ArrayPattern(node) {
@@ -1592,6 +2104,10 @@
 	      var e = this.mapToSource(elements).join(', ');
 	      return "[".concat(e, "]");
 	    }
+	    /**
+	     * @param {import("@babel/types").SwitchStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "SwitchStatement",
 	    value: function SwitchStatement(node) {
@@ -1604,6 +2120,10 @@
 	      out += spaces + '}';
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").SwitchCase} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "SwitchCase",
 	    value: function SwitchCase(node) {
@@ -1617,26 +2137,49 @@
 	      }
 	      return "".concat(spaces, "default:\n").concat(c);
 	    }
+	    /**
+	     * @param {import("@babel/types").RegExpLiteral} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "RegExpLiteral",
 	    value: function RegExpLiteral(node) {
+	      // parseSync("/test/gm")
+	      // todo figure out why it always exposes node.value === undefined... oversight in Babel?
 	      var extra = node.extra;
 	        node.value;
 	        node.pattern;
 	        node.flags;
 	      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.
+	     */
 	  }, {
 	    key: "SequenceExpression",
 	    value: function SequenceExpression(node) {
 	      var expressions = node.expressions;
 	      return this.mapToSource(expressions).join(', ');
 	    }
+	    /**
+	     * showAST("if (true);");
+	     *
+	     * @param {import("@babel/types").EmptyStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "EmptyStatement",
 	    value: function EmptyStatement(node) {
 	      return ';';
 	    }
+	    /**
+	     * @param {import("@babel/types").SpreadElement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "SpreadElement",
 	    value: function SpreadElement(node) {
@@ -1644,9 +2187,15 @@
 	      var a = this.toSource(argument);
 	      return "...".concat(a);
 	    }
+	    /**
+	     * @param {import("@babel/types").ObjectMethod} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ObjectMethod",
 	    value: function 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'
 	      node.method;
 	        var key = node.key,
 	        computed = node.computed,
@@ -1660,6 +2209,10 @@
 	        console.warn("ObjectMethod> id !== null is unhandled", node);
 	        debugger;
 	      }
+	      // if (method) {
+	      //   console.warn("ObjectMethod> node was a method", node);
+	      //   debugger;
+	      // }
 	      var out = this.spaces;
 	      if (generator) {
 	        out += '*';
@@ -1686,6 +2239,11 @@
 	      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.
+	     */
 	  }, {
 	    key: "ObjectPattern",
 	    value: function ObjectPattern(node) {
@@ -1706,6 +2264,16 @@
 	      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.
+	     */
 	  }, {
 	    key: "OptionalMemberExpression",
 	    value: function OptionalMemberExpression(node) {
@@ -1715,6 +2283,7 @@
 	        optional = node.optional;
 	      var a = this.toSource(object);
 	      var b = this.toSource(property);
+	      // Basically four cases: computed=true/false optional=true/false, 00, 01, 10, 11
 	      if (!computed && !optional) {
 	        return "".concat(a, ".").concat(b);
 	      } else if (!computed && optional) {
@@ -1722,8 +2291,17 @@
 	      } else if (computed && !optional) {
 	        return "".concat(a, "[").concat(b, "]");
 	      }
+	      // Can only be case 4 now (computed && optional):
 	      return "".concat(a, "?.[").concat(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.
+	     */
 	  }, {
 	    key: "OptionalCallExpression",
 	    value: function OptionalCallExpression(node) {
@@ -1737,6 +2315,10 @@
 	      }
 	      return "".concat(a, "(").concat(b, ")");
 	    }
+	    /**
+	     * @param {import("@babel/types").DoWhileStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "DoWhileStatement",
 	    value: function DoWhileStatement(node) {
@@ -1750,6 +2332,10 @@
 	      out += " while (".concat(this.toSource(test), ");");
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").TryStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "TryStatement",
 	    value: function TryStatement(node) {
@@ -1767,6 +2353,10 @@
 	      }
 	      return out;
 	    }
+	    /**
+	     * @param {import("@babel/types").CatchClause} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "CatchClause",
 	    value: function CatchClause(node) {
@@ -1777,29 +2367,49 @@
 	        var p = this.toSource(param);
 	        return " catch (".concat(p, ") ").concat(b);
 	      }
+	      // Example: try { 1n / 0 } catch {}
 	      return " catch ".concat(b);
 	    }
+	    /**
+	     * @param {import("@babel/types").RestElement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "RestElement",
 	    value: function RestElement(node) {
 	      var argument = node.argument;
 	      return "...".concat(this.toSource(argument));
 	    }
+	    /**
+	     * @param {import("@babel/types").DebuggerStatement} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "DebuggerStatement",
 	    value: function DebuggerStatement(node) {
 	      return "".concat(this.spaces, "debugger;");
 	    }
+	    /**
+	     * @param {import("@babel/types").Import} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "Import",
 	    value: function Import(node) {
 	      return 'import';
 	    }
+	    /**
+	     * @param {import("@babel/types").ImportDeclaration} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ImportDeclaration",
 	    value: function ImportDeclaration(node) {
 	      var specifiers = node.specifiers,
 	        source = node.source;
+	      // ImportNamespaceSpecifier: import * as a   from "b";
+	      // ImportDefaultSpecifier  : import      a   from "b";
+	      // ImportSpecifier         : import {    a } from "b";
 	      var a = this.mapToSource(specifiers).join(', ');
 	      var b = this.toSource(source);
 	      if (specifiers.length === 0) {
@@ -1810,6 +2420,10 @@
 	      }
 	      return "import {".concat(a, "} from ").concat(b, ";");
 	    }
+	    /**
+	     * @param {import("@babel/types").ImportSpecifier} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ImportSpecifier",
 	    value: function ImportSpecifier(node) {
@@ -1822,37 +2436,61 @@
 	      }
 	      return a;
 	    }
+	    /**
+	     * @param {import("@babel/types").ImportDefaultSpecifier} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ImportDefaultSpecifier",
 	    value: function ImportDefaultSpecifier(node) {
 	      var local = node.local;
 	      return this.toSource(local);
 	    }
+	    /**
+	     * @param {import("@babel/types").ImportNamespaceSpecifier} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ImportNamespaceSpecifier",
 	    value: function ImportNamespaceSpecifier(node) {
 	      var local = node.local;
 	      return "* as ".concat(this.toSource(local));
 	    }
+	    /**
+	     * @param {import("@babel/types").File} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "File",
 	    value: function File(node) {
 	      return this.toSource(node.program) + '\n';
 	    }
+	    /**
+	     * @param {import("@babel/types").Program} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "Program",
 	    value: function Program(node) {
 	      var body = node.body,
 	        directives = node.directives;
 	      var 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.
+	     */
 	  }, {
 	    key: "StringLiteral",
 	    value: function StringLiteral(node) {
 	      var extra = node.extra;
+	      // Never experienced this so far, but types are types...
 	      if (!extra) {
 	        debugger;
 	        return '';
@@ -1863,11 +2501,19 @@
 	      }
 	      return extra.raw;
 	    }
+	    /**
+	     * @param {import("@babel/types").NumericLiteral} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "NumericLiteral",
 	    value: function NumericLiteral(node) {
 	      return node.extra.raw;
 	    }
+	    /**
+	     * @param {import("@babel/types").AssignmentPattern} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "AssignmentPattern",
 	    value: function AssignmentPattern(node) {
@@ -1875,11 +2521,19 @@
 	        right = node.right;
 	      return "".concat(this.toSource(left), " = ").concat(this.toSource(right));
 	    }
+	    /**
+	     * @param {import("@babel/types").NullLiteral} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "NullLiteral",
 	    value: function NullLiteral(node) {
 	      return 'null';
 	    }
+	    /**
+	     * @param {import("@babel/types").TaggedTemplateExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "TaggedTemplateExpression",
 	    value: function TaggedTemplateExpression(node) {
@@ -1889,6 +2543,10 @@
 	      var q = this.toSource(quasi);
 	      return t + q;
 	    }
+	    /**
+	     * @param {import("@babel/types").YieldExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "YieldExpression",
 	    value: function YieldExpression(node) {
@@ -1905,9 +2563,25 @@
 	  return Stringifier;
 	}();
 
-	var Asserter = function (_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.
+	 */
+	var Asserter = /*#__PURE__*/function (_Stringifier) {
 	  _inherits(Asserter, _Stringifier);
 	  var _super = _createSuper(Asserter);
+	  /**
+	   * @param {Options} [options] - The options.
+	   */
 	  function Asserter() {
 	    var _this;
 	    var _ref = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {},
@@ -1919,9 +2593,12 @@
 	      expandType = _ref$expandType === void 0 ? expandTypeDepFree : _ref$expandType,
 	      filename = _ref.filename,
 	      _ref$addHeader = _ref.addHeader,
-	      addHeader = _ref$addHeader === void 0 ? true : _ref$addHeader;
+	      addHeader = _ref$addHeader === void 0 ? true : _ref$addHeader,
+	      _ref$ignoreLocations = _ref.ignoreLocations,
+	      ignoreLocations = _ref$ignoreLocations === void 0 ? [] : _ref$ignoreLocations;
 	    _classCallCheck(this, Asserter);
 	    _this = _super.call(this);
+	    /** @type {Record<string, Stat>} */
 	    _defineProperty(_assertThisInitialized(_this), "stats", {
 	      'ArrowFunctionExpression': {
 	        checked: 0,
@@ -1968,17 +2645,28 @@
 	        unchecked: 0
 	      }
 	    });
+	    /** @type {Record<string, object>} */
 	    _defineProperty(_assertThisInitialized(_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;
 	    return _this;
 	  }
 	  _createClass(Asserter, [{
 	    key: "ArrowFunctionExpression",
-	    value: function ArrowFunctionExpression(node) {
+	    value:
+	    /**
+	     * 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.
+	     */
+	    function ArrowFunctionExpression(node) {
 	      var async = node.async,
 	        body = node.body,
 	        generator = node.generator,
@@ -2002,6 +2690,11 @@
 	      }
 	      return out;
 	    }
+	    /**
+	     * @override
+	     * @param {import("@babel/types").ClassDeclaration} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "ClassDeclaration",
 	    value: function ClassDeclaration(node) {
@@ -2011,6 +2704,14 @@
 	      out += "".concat(this.spaces, "registerClass(").concat(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.
+	     */
 	  }, {
 	    key: "findParentOfType",
 	    value: function findParentOfType(node, type) {
@@ -2024,6 +2725,13 @@
 	        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.
+	     */
 	  }, {
 	    key: "getHeader",
 	    value: function getHeader() {
@@ -2035,9 +2743,19 @@
 	        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'.
+	     */
 	  }, {
 	    key: "getLeadingCommentsNodeForArrowFunctionExpression",
 	    value: function getLeadingCommentsNodeForArrowFunctionExpression(node) {
@@ -2049,9 +2767,16 @@
 	      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;
 	        }
@@ -2061,6 +2786,10 @@
 	        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.
+	     */
 	  }, {
 	    key: "warn",
 	    value: function warn() {
@@ -2081,9 +2810,16 @@
 	      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;
 	        }
@@ -2092,7 +2828,26 @@
 	        }
 	        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`.
+	     */
 	  }, {
 	    key: "getJSDoc",
 	    value: function getJSDoc(node) {
@@ -2101,10 +2856,12 @@
 	      }
 	      var _node = node,
 	        leadingComments = _node.leadingComments;
+	      // Receive the leadingComments from the ExpressionStatement, not the FunctionExpression itself.
 	      if (node.type === 'FunctionExpression') {
 	        var tmp = this.getLeadingCommentsNodeForFunctionExpression(node);
 	        leadingComments = tmp === null || tmp === void 0 ? void 0 : tmp.leadingComments;
 	      }
+	      // Receive the leadingComments from ExportNamedDeclaration, if FunctionDeclaration has none
 	      if (!leadingComments) {
 	        if (node.type === 'FunctionDeclaration') {
 	          var exportNamedDeclaration = this.findParentOfType(node, 'ExportNamedDeclaration');
@@ -2135,6 +2892,15 @@
 	        }
 	      }
 	    }
+	    /**
+	     * 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.
+	     */
 	  }, {
 	    key: "getNameOfParam",
 	    value: function getNameOfParam(param) {
@@ -2159,17 +2925,27 @@
 	    value: function 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.
+	     */
 	  }, {
 	    key: "getStatsForNode",
 	    value: function getStatsForNode(node) {
 	      var stats = this.stats;
 	      var type = nodeIsFunction(node) ? node.type : this.parentType;
 	      if (type === 'ClassMethod') {
-	        var parent = this.parent;
+	        var parent = /** @type {ClassMethod} */
+	        this.parent;
 	        var kind = parent.kind;
 	        return stats["ClassMethod#".concat(kind)];
 	      } else if (type === 'ClassPrivateMethod') {
-	        var _parent = this.parent;
+	        var _parent = /** @type {ClassPrivateMethod} */
+	        this.parent;
 	        var _kind = _parent.kind;
 	        return stats["ClassPrivateMethod#".concat(_kind)];
 	      }
@@ -2183,6 +2959,17 @@
 	      }
 	      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.
+	     */
 	  }, {
 	    key: "nodeHasParamName",
 	    value: function nodeHasParamName(node, name) {
@@ -2215,6 +3002,18 @@
 	        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.
+	     */
 	  }, {
 	    key: "generateTypeChecks",
 	    value: function generateTypeChecks(node) {
@@ -2224,6 +3023,7 @@
 	        return '';
 	      }
 	      var jsdoc = this.getJSDoc(node);
+	      // return '// ' + JSON.stringify(jsdoc) + '\n';
 	      var stat = this.getStatsForNode(node);
 	      if (!jsdoc) {
 	        stat.unchecked++;
@@ -2233,6 +3033,12 @@
 	      var spaces = this.spaces;
 	      var out = '';
 	      var first = true;
+	      var 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`;
 	      var _loop = function _loop(name) {
 	          var type = jsdoc[name];
 	          var hasParam = _this2.nodeHasParamName(node, name);
@@ -2249,11 +3055,24 @@
 	              var isObjectPattern = param.type === 'ObjectPattern';
 	              var isArrayPattern = param.type === 'ArrayPattern';
 	              var 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[".concat(paramIndex, "]");
 	              } else if (param.type === 'AssignmentPattern') {
 	                var _loc = _this2.getName(node);
 	                if (param.left.type === 'ArrayPattern' && type.type === 'array') {
+	                  // Add a type assertion for each element of the ArrayPattern
 	                  var _iterator = _createForOfIteratorHelper(param.left.elements),
 	                    _step;
 	                  try {
@@ -2272,8 +3091,9 @@
 	                  } finally {
 	                    _iterator.f();
 	                  }
-	                  return 0;
+	                  return 0; // continue
 	                } else if (param.left.type === 'ObjectPattern' && type.type === 'object') {
+	                  // Add a type assertion for each property of the ObjectPattern
 	                  var _iterator2 = _createForOfIteratorHelper(param.left.properties),
 	                    _step2;
 	                  try {
@@ -2302,15 +3122,15 @@
 	                  } finally {
 	                    _iterator2.f();
 	                  }
-	                  return 0;
+	                  return 0; // continue
 	                }
 	                _this2.warn("generateTypeChecks> ".concat(_loc, "> todo implement"), "AssignmentPattern for parameter ".concat(name));
-	                return 0;
+	                return 0; // continue
 	              }
 	            } else {
 	              var _loc2 = _this2.getName(node);
 	              _this2.warn("generateTypeChecks> ".concat(_loc2, "> Missing param: ").concat(name));
-	              return 0;
+	              return 0; // continue
 	            }
 	          }
 	          var t = JSON.stringify(type, null, 2).replaceAll('\n', '\n' + spaces);
@@ -2323,6 +3143,8 @@
 	          }
 	          var loc = _this2.getName(node);
 	          var prevCheck = '';
+	          // JSDoc doesn't support multiple function signatures yet, but this is
+	          // exactly what we would need to deal with ObjectPool'ing
 	          if (loc === 'ContactPoint#constructor' || loc === 'ContactResult#constructor' || loc === 'SingleContactResult#constructor') {
 	            prevCheck = 'arguments.length !== 0 && ';
 	          }
@@ -2340,15 +3162,25 @@
 	      }
 	      return out;
 	    }
+	    /**
+	     * @param {Node} node - The Babel AST node.
+	     * @returns {string} Best possible human-readable name of given node.
+	     */
 	  }, {
 	    key: "getNameForFunctionExpression",
 	    value: function getNameForFunctionExpression(node) {
 	      var 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);
 	      }
 	      var expressionStatement = this.findParentOfType(node, 'ExpressionStatement');
 	      if (expressionStatement) {
+	        // There are many kinds of expressions
+	        // type Expression = ArrayExpression | AssignmentExpression | BinaryExpression | CallExpression | ...
 	        var left = expressionStatement.expression.left;
 	        if (left) {
 	          return this.toSource(left);
@@ -2357,6 +3189,10 @@
 	      }
 	      return 'unnamed function expression';
 	    }
+	    /**
+	     * @param {Node} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "getName",
 	    value: function getName(node) {
@@ -2400,6 +3236,11 @@
 	          return '/*MISSING*/';
 	      }
 	    }
+	    /**
+	     * @override
+	     * @param {import("@babel/types").BinaryExpression} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
 	  }, {
 	    key: "BinaryExpression",
 	    value: function BinaryExpression(node) {
@@ -2418,7 +3259,14 @@
 	    }
 	  }, {
 	    key: "File",
-	    value: function File(node) {
+	    value:
+	    /**
+	     * @override
+	     * @param {import("@babel/types").File} node - The Babel AST node.
+	     * @returns {string} Stringification of the node.
+	     */
+	    function File(node) {
+	      // @todo figure out why errors is in Babel node and not in @babel/types...
 	      var program = node.program,
 	        comments = node.comments;
 	      if (comments) {
@@ -2436,6 +3284,7 @@
 	          _iterator3.f();
 	        }
 	      }
+	      //console.log("this.typedefs", this.typedefs);
 	      var out = '';
 	      for (var name in this.typedefs) {
 	        var typedef = this.typedefs[name];
@@ -2450,7 +3299,24 @@
 	  return Asserter;
 	}(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 {
 	    var asserter = new Asserter(options);
 	    var ast = parser.parse(src, {
@@ -2465,28 +3331,45 @@
 	  }
 	}
 
+	/**
+	 * @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);
 	}
 
 	var 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) {
 	  var stringifier = new Stringifier();
 	  var ast = parser.parse(code, {
@@ -2499,6 +3382,11 @@
 	  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) {
 	  var l = parser.parse(left, {
 	    sourceType: 'module'
@@ -2512,19 +3400,70 @@
 	  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) {
 	  var 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 = ".concat(str, ";");
-	  var ast = ts.createSourceFile('repl.ts', str, ts.ScriptTarget.Latest, true);
+	  var 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) {
 	  var typeArguments = node.typeArguments,
 	    typeName = node.typeName;
@@ -2570,18 +3509,22 @@
 	    KeyOfKeyword = _ts$SyntaxKind.KeyOfKeyword,
 	    ConstructorType = _ts$SyntaxKind.ConstructorType,
 	    NamedTupleMember = _ts$SyntaxKind.NamedTupleMember;
+	  // console.log({typeArguments, typeName, kind_, node});
 	  switch (node.kind) {
 	    case BigIntKeyword:
 	      return {
 	        type: 'bigint'
 	      };
 	    case BigIntLiteral:
-	      var literal = node.text.slice(0, -1);
+	      var literal = node.text.slice(0, -1); // Remove the "n"
 	      return {
 	        type: 'bigint',
 	        literal: literal
 	      };
 	    case ConditionalType:
+	      // Keys on node:
+	      // ['pos', 'end', 'flags', 'modifierFlagsCache', 'transformFlags', 'parent', 'kind', 'checkType',
+	      // 'extendsType', 'trueType', 'falseType', 'locals', 'nextContainer']
 	      var checkType = toSourceTS(node.checkType);
 	      var extendsType = toSourceTS(node.extendsType);
 	      var trueType = toSourceTS(node.trueType);
@@ -2629,6 +3572,8 @@
 	        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:
 	      var type = node.type ? toSourceTS(node.type) : 'any';
 	      var name = toSourceTS(node.name);
@@ -2761,6 +3706,7 @@
 	      return toSourceTS(node.literal);
 	    case AnyKeyword:
 	    case BooleanKeyword:
+	    // ts.SyntaxKind[parseType("*").kind] === 'JSDocAllType'
 	    case JSDocAllType:
 	    case NullKeyword:
 	    case NumericLiteral:
@@ -2779,10 +3725,17 @@
 	        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');
@@ -2791,17 +3744,58 @@
 	  }
 	}
 
+	/**
+	 * @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) {
 	  var 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 = ".concat(str, ";");
 	  var ast = parser.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':
@@ -2814,10 +3808,34 @@
 	        type: 'bigint',
 	        literal: 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':
 	      {
 	        var 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');
@@ -2901,6 +3919,9 @@
 	        type: 'object',
 	        properties: 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':
@@ -2910,25 +3931,36 @@
 	      };
 	    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':
@@ -2937,6 +3969,7 @@
 	        properties: {}
 	      };
 	    case 'ParenthesizedType':
+	      // fall-through for parentheses
 	      return toSourceBabelTS(node.type);
 	    case 'LastTypeNode':
 	      return toSourceBabelTS(node.qualifier);