Add JSDoc comments for typing info (#13)

Helps to check contributions follow the babel API

Author: andrewiggins

index.js

@@ -1,4 +1,19 @@
-/** Check if node is a template literal with no expressions (e.g., `foo`) */
+/** @import { PluginObj, NodePath } from '@babel/core' */
+/** @import { Node, Property, Method, MemberExpression, TemplateLiteral } from '@babel/types' */
+/** @import { Visitor } from '@babel/traverse' */
+/** @typedef {typeof import('@babel/types')} BabelTypes */
+
+/**
+ * @typedef {Object} PluginOptions
+ * @property {Record<string, string>} [rename] - A map of property names to rename
+ */
+
+/**
+ * Check if node is a template literal with no expressions (e.g., `foo`)
+ * @param {BabelTypes} t - The Babel types object
+ * @param {Node} node - The AST node to check
+ * @returns {boolean} True if the node is a constant template literal
+ */
 function isConstantTemplateLiteral(t, node) {
   return (
     t.isTemplateLiteral(node) &&
@@ -7,17 +22,29 @@ function isConstantTemplateLiteral(t, node) {
   );
 }
 
-/** Create a template literal node with no expressions (e.g., `foo`) */
+/**
+ * Create a template literal node with no expressions (e.g., `foo`)
+ * @param {BabelTypes} t - The Babel types object
+ * @param {string} value - The string value for the template literal
+ * @returns {TemplateLiteral} The template literal node
+ */
 function constantTemplateLiteral(t, value) {
   return t.templateLiteral(
     [t.templateElement({ raw: value, cooked: value }, true)],
     []
   );
 }
 
+/**
+ * Babel plugin that renames properties, methods, and member expressions.
+ * @param {{ types: BabelTypes }} babel - The Babel object
+ * @param {PluginOptions} [options] - Plugin options
+ * @returns {PluginObj} The Babel plugin object
+ */
 module.exports = function ({ types: t }, options = {}) {
   const rename = options.rename || {};
 
+  /** @type {Map<string, string>} */
   const nameMap = new Map();
   Object.keys(rename).forEach((key) => {
     const value = rename[key];
@@ -29,10 +56,16 @@ module.exports = function ({ types: t }, options = {}) {
     nameMap.set(key, value);
   });
 
+  /**
+   * Visitor for Property and Method nodes that renames keys.
+   * @type {Visitor}
+   */
   const replacePropertyOrMethod = {
+    /** @param {NodePath<Property | Method>} path */
     exit(path) {
       const node = path.node;
 
+      /** @type {string | undefined} */
       let name;
       if (t.isIdentifier(node.key) && !node.computed) {
         name = node.key.name;
@@ -64,9 +97,11 @@ module.exports = function ({ types: t }, options = {}) {
       Property: replacePropertyOrMethod,
       Method: replacePropertyOrMethod,
       MemberExpression: {
+        /** @param {NodePath<MemberExpression>} path */
         exit(path) {
           const node = path.node;
 
+          /** @type {string | undefined} */
           let name;
           if (t.isIdentifier(node.property) && !node.computed) {
             name = node.property.name;
@@ -81,6 +116,7 @@ module.exports = function ({ types: t }, options = {}) {
             return;
           }
 
+          /** @type {MemberExpression} */
           let newNode;
           if (t.isValidIdentifier(newName)) {
             newNode = t.memberExpression(node.object, t.identifier(newName));

package.json

@@ -12,7 +12,9 @@
   "scripts": {
     "test": "vitest --run",
     "test:watch": "vitest",
-    "lint": "eslint --max-warnings 0 --ignore-path .gitignore ."
+    "lint": "yarn run tsc && yarn run eslint",
+    "tsc": "tsc --noEmit --allowJs --checkJs --esModuleInterop --skipLibCheck index.js test/index.test.js",
+    "eslint": "eslint --max-warnings 0 --ignore-path .gitignore ."
   },
   "peerDependencies": {
     "@babel/core": "^7.0.0-0"
@@ -23,6 +25,7 @@
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-prettier": "^4.2.1",
     "prettier": "^2.7.1",
+    "typescript": "^5.9.3",
     "vitest": "^0.24.3"
   }
 }

yarn.lock

@@ -1392,6 +1392,11 @@ type-fest@^0.20.2:
   resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-0.20.2.tgz#1bf207f4b28f91583666cb5fbd327887301cd5f4"
   integrity sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==
 
+typescript@^5.9.3:
+  version "5.9.3"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.9.3.tgz#5b4f59e15310ab17a216f5d6cf53ee476ede670f"
+  integrity sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==
+
 update-browserslist-db@^1.0.9:
   version "1.0.10"
   resolved "https://registry.yarnpkg.com/update-browserslist-db/-/update-browserslist-db-1.0.10.tgz#0f54b876545726f17d00cd9a2561e6dade943ff3"