Add codemod to propagate JSDoc comments to dual signatures

.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
 
@@ -61,6 +62,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:

.github/workflows/snapshot.yml

@@ -16,8 +16,10 @@ jobs:
       - uses: actions/checkout@v4
       - name: Install dependencies
         uses: ./.github/actions/setup
+      - name: Run codemods
+        run: pnpm codemod
       - name: Build package
         run: pnpm build
       - name: Create snapshot
         id: snapshot
-        run: pnpx [email protected].17 publish --pnpm --comment=off ./packages/*
+        run: pnpx [email protected].28 publish --pnpm --comment=off ./packages/*

package.json

@@ -8,6 +8,7 @@
   "scripts": {
     "clean": "node scripts/clean.mjs",
     "codegen": "pnpm --recursive --parallel run codegen",
+    "codemod": "node scripts/codemod.mjs",
     "build": "tsc -b tsconfig.build.json && pnpm --recursive --parallel run build",
     "circular": "node scripts/circular.mjs",
     "test": "vitest",
@@ -20,7 +21,7 @@
     "dtslint": "pnpm --recursive --parallel run dtslint",
     "dtslint-clean": "dtslint --installAll",
     "changeset-version": "changeset version && node scripts/version.mjs",
-    "changeset-publish": "pnpm build && TEST_DIST= pnpm vitest && changeset publish"
+    "changeset-publish": "pnpm codemod && pnpm lint-fix && pnpm build && TEST_DIST= pnpm vitest && changeset publish"
   },
   "resolutions": {
     "dependency-tree": "^10.0.9",
@@ -51,13 +52,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 +71,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/codemod.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"
+})

scripts/codemods/jsdoc.ts

@@ -0,0 +1,72 @@
+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) => {
+      // Don't override comments if they already exist
+      if (!Array.isArray(path.node.comments)) {
+        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) => {
+        // Don't override comments if they already exist
+        if (!Array.isArray(param.comments)) {
+          param.comments = comments
+        }
+      })
+    })
+  })
+
+  return root.toSource()
+}