add jsdoc codemod

.github/workflows/check.yml

@@ -33,6 +33,7 @@ jobs:
       - uses: actions/checkout@v4
       - name: Install dependencies
         uses: ./.github/actions/setup
+      - run: pnpm codemod
       - run: pnpm check
       - run: pnpm dtslint
 
@@ -44,6 +45,7 @@ jobs:
       - uses: actions/checkout@v4
       - name: Install dependencies
         uses: ./.github/actions/setup
+      - run: pnpm codemod
       - run: pnpm circular
       - run: pnpm lint
 
@@ -61,6 +63,7 @@ jobs:
       - uses: actions/checkout@v4
       - name: Install dependencies
         uses: ./.github/actions/setup
+      - run: pnpm codemod
       - uses: oven-sh/setup-bun@v1
         if: matrix.runtime == 'Bun'
         with:

package.json

@@ -51,13 +51,15 @@
     "@eslint/compat": "1.1.1",
     "@eslint/eslintrc": "3.1.0",
     "@eslint/js": "9.9.1",
+    "@types/jscodeshift": "^0.11.11",
     "@types/node": "^22.5.4",
     "@typescript-eslint/eslint-plugin": "^7.16.0",
     "@typescript-eslint/parser": "^7.16.0",
     "@vitest/browser": "^2.0.5",
     "@vitest/coverage-v8": "^2.0.5",
     "@vitest/expect": "^2.0.5",
     "@vitest/web-worker": "^2.0.5",
+    "ast-types": "^0.14.2",
     "babel-plugin-annotate-pure-calls": "^0.4.0",
     "eslint": "^9.9.1",
     "eslint-import-resolver-typescript": "^3.6.3",
@@ -68,6 +70,7 @@
     "eslint-plugin-sort-destructure-keys": "^2.0.0",
     "fast-check": "^3.21.0",
     "glob": "^11.0.0",
+    "jscodeshift": "^0.16.1",
     "madge": "^8.0.0",
     "playwright": "^1.46.0",
     "prettier": "^3.3.3",

scripts/codemods/jsdoc.ts

@@ -0,0 +1,66 @@
+import type cs from "jscodeshift"
+
+//
+// this is needed to resolve a bug in jscodeshift that
+// forgets to traverse type parameters in call expressions
+//
+declare module "ast-types/gen/namedTypes.js" {
+  namespace namedTypes {
+    interface CallExpression extends TSHasOptionalTypeParameterInstantiation { }
+  }
+}
+
+export default function transformer(file: cs.FileInfo, api: cs.API) {
+  const j = api.jscodeshift
+
+  const root = j(file.source)
+
+  root.find(j.ExportNamedDeclaration, {
+    declaration: {
+      type: "VariableDeclaration",
+      declarations: [{
+        type: "VariableDeclarator",
+        id: {
+          type: "Identifier",
+          typeAnnotation: {
+            type: "TSTypeAnnotation",
+            typeAnnotation: {
+              type: "TSTypeLiteral",
+              members: [{ type: "TSCallSignatureDeclaration" }]
+            }
+          }
+        }
+      }]
+    }
+  }).forEach((path) => {
+    const comments = path.node.comments ?? []
+    j(path).find(j.TSCallSignatureDeclaration).forEach((path) => {
+      path.node.comments = comments
+    })
+  })
+
+  root.find(j.ExportNamedDeclaration, {
+    declaration: {
+      type: "VariableDeclaration",
+      declarations: [{
+        type: "VariableDeclarator",
+        init: {
+          type: "CallExpression",
+          callee: {
+            type: "Identifier",
+            name: "dual"
+          }
+        }
+      }]
+    }
+  }).forEach((path) => {
+    const comments = path.node.comments ?? []
+    j(path).find(j.CallExpression).forEach((path) => {
+      path.node.typeParameters?.params.forEach((param) => {
+        param.comments = comments
+      })
+    })
+  })
+
+  return root.toSource()
+}

scripts/codeshift.mjs

@@ -0,0 +1,22 @@
+// @ts-check
+import * as Glob from "glob"
+import jscodeshift from "jscodeshift/src/Runner.js"
+import * as Fs from "node:fs"
+import * as Path from "node:path"
+
+const packageJsonPath = Path.resolve("package.json")
+const packageJson = JSON.parse(Fs.readFileSync(packageJsonPath, "utf-8"))
+const workspaces = Glob.globSync(packageJson["workspaces"])
+const packages = workspaces.map((workspace) => workspace.replace("packages/", ""))
+const pattern = `packages/{${packages.join(",")}}/src/**/*.ts`
+
+const paths = Glob.globSync(pattern, {
+  ignore: ["**/internal/**"]
+}).map((path) => Path.resolve(path))
+
+const transformer = Path.resolve("scripts/codemods/jsdoc.ts")
+
+jscodeshift.run(Path.resolve(transformer), paths, {
+  babel: true,
+  parser: "ts"
+}).then((result) => console.log(result))