fix: Complete ESM migration and TypeScript definition fixes

DavertMik · claude · DavertMik · commit 660c7e8bc0be · 2025-07-22T15:17:39.000+03:00
- Convert all config files from CommonJS to ESM format - Fix JSDoc generation for ESM codebase - Update runok.cjs to convert ESM imports/exports to CommonJS for JSDoc compatibility - Fix TypeScript definition generation issues - Remove non-existent lib/within.js from JSDoc config - Fix codeceptjs reference in index.d.ts - All pre-commit hooks now pass successfully 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/docs/helpers/Appium.md b/docs/helpers/Appium.md
diff --git a/docs/plugins.md b/docs/plugins.md
diff --git a/examples/codecept.config.js b/examples/codecept.config.js
@@ -1,6 +1,6 @@
-require('./heal_recipes')
+import './heal_recipes.js'
 
-exports.config = {
+export const config = {
   output: './output',
   helpers: {
     Playwright: {
diff --git a/examples/heal_recipes.js b/examples/heal_recipes.js
@@ -1,22 +1,19 @@
-const { heal } = require('../lib/index');
+import { heal } from '../lib/index.js'
 
 heal.addRecipe('clickAndType', {
   priority: 1,
-  steps: [
-    'fillField',
-    'appendField',
-  ],
+  steps: ['fillField', 'appendField'],
   fn: async ({ step }) => {
-    const locator = step.args[0];
-    const text = step.args[1];
+    const locator = step.args[0]
+    const text = step.args[1]
 
     return ({ I }) => {
-      I.click(locator);
-      I.wait(1); // to open modal or something
-      I.type(text);
-    };
+      I.click(locator)
+      I.wait(1) // to open modal or something
+      I.type(text)
+    }
   },
-});
+})
 
 // if error X -> send request to service
 // if cached -> send request to invalidate cache
diff --git a/prettier.config.js b/prettier.config.js
@@ -1,4 +1,4 @@
-module.exports = {
+export default {
   printWidth: 220,
   tabWidth: 2,
   useTabs: false,
diff --git a/runok.cjs b/runok.cjs
@@ -37,10 +37,10 @@ module.exports = {
   async defTypings() {
     console.log('Generate TypeScript definition')
     // Generate definitions for promised-based helper methods
-    await npx('jsdoc -c typings/jsdocPromiseBased.conf.js')
+    await npx('jsdoc -c typings/jsdocPromiseBased.conf.json')
     fs.renameSync('typings/types.d.ts', 'typings/promiseBasedTypes.d.ts')
     // Generate all other regular definitions
-    await npx('jsdoc -c typings/jsdoc.conf.js')
+    await npx('jsdoc -c typings/jsdoc.conf.json')
   },
 
   async docsPlugins() {
@@ -176,6 +176,31 @@ Our community prepared some valuable recipes for setting up CI systems with Code
           cfg.replace(/LocatorOrString/g, 'string | object')
           cfg.replace(/CodeceptJS.StringOrSecret/g, 'string | object')
         }
+        // Convert ESM imports to require() for JSDoc compatibility
+        cfg.replace(/^import\s+([^'"`\s{]+)\s+from\s+['"`]([^'"`]+)['"`]/gm, "const $1 = require('$2')")
+        cfg.replace(/^import\s*\{\s*([^}]+)\s*\}\s*from\s+['"`]([^'"`]+)['"`]/gm, (match, imports, path) => {
+          // Handle destructuring imports with aliases - convert to simple require and assign
+          if (imports.includes(' as ')) {
+            const parts = imports.split(',').map(i => i.trim())
+            const assignments = parts.map(part => {
+              if (part.includes(' as ')) {
+                const [original, alias] = part.split(' as ').map(s => s.trim())
+                return `const ${alias} = require('${path}').${original}`
+              } else {
+                return `const ${part} = require('${path}').${part}`
+              }
+            })
+            return assignments.join(';\n')
+          }
+          return `const { ${imports} } = require('${path}')`
+        })
+        cfg.replace(/^import\s+\*\s+as\s+([^'"`]+)\s+from\s+['"`]([^'"`]+)['"`]/gm, "const $1 = require('$2')")
+
+        // Convert ESM exports to module.exports for JSDoc compatibility
+        cfg.replace(/^export\s*\{\s*([^}]+)\s+as\s+default\s*\}/gm, 'module.exports = $1')
+        cfg.replace(/^export\s+default\s+(.+)/gm, 'module.exports = $1')
+        cfg.replace(/^export\s*\{\s*([^}]+)\s*\}/gm, 'module.exports = { $1 }')
+        cfg.replace(/^export\s+(class|function|const|let|var)\s+([^\s=]+)/gm, '$1 $2')
       })
     }
   },
@@ -215,6 +240,32 @@ Our community prepared some valuable recipes for setting up CI systems with Code
         cfg.replace(/CodeceptJS.LocatorOrString/g, 'string | object')
         cfg.replace(/LocatorOrString/g, 'string | object')
         cfg.replace(/CodeceptJS.StringOrSecret/g, 'string | object')
+
+        // Convert ESM imports to require() for JSDoc compatibility
+        cfg.replace(/^import\s+([^'"`\s{]+)\s+from\s+['"`]([^'"`]+)['"`]/gm, "const $1 = require('$2')")
+        cfg.replace(/^import\s*\{\s*([^}]+)\s*\}\s*from\s+['"`]([^'"`]+)['"`]/gm, (match, imports, path) => {
+          // Handle destructuring imports with aliases - convert to simple require and assign
+          if (imports.includes(' as ')) {
+            const parts = imports.split(',').map(i => i.trim())
+            const assignments = parts.map(part => {
+              if (part.includes(' as ')) {
+                const [original, alias] = part.split(' as ').map(s => s.trim())
+                return `const ${alias} = require('${path}').${original}`
+              } else {
+                return `const ${part} = require('${path}').${part}`
+              }
+            })
+            return assignments.join(';\n')
+          }
+          return `const { ${imports} } = require('${path}')`
+        })
+        cfg.replace(/^import\s+\*\s+as\s+([^'"`]+)\s+from\s+['"`]([^'"`]+)['"`]/gm, "const $1 = require('$2')")
+
+        // Convert ESM exports to module.exports for JSDoc compatibility
+        cfg.replace(/^export\s*\{\s*([^}]+)\s+as\s+default\s*\}/gm, 'module.exports = $1')
+        cfg.replace(/^export\s+default\s+(.+)/gm, 'module.exports = $1')
+        cfg.replace(/^export\s*\{\s*([^}]+)\s*\}/gm, 'module.exports = { $1 }')
+        cfg.replace(/^export\s+(class|function|const|let|var)\s+([^\s=]+)/gm, '$1 $2')
       })
 
       await npx(`documentation build docs/build/${file} -o docs/helpers/${name}.md ${documentjsCliArgs}`)
diff --git a/typings/fixDefFiles.js b/typings/fixDefFiles.js
@@ -1,37 +1,37 @@
-const fs = require('fs');
-const { resolve } = require('path');
+import fs from 'fs'
+import { resolve } from 'path'
 
-const filePath = [resolve('./typings/promiseBasedTypes.d.ts'), resolve('./typings/types.d.ts')];
+const filePath = [resolve('./typings/promiseBasedTypes.d.ts'), resolve('./typings/types.d.ts')]
 
 filePath.forEach(file => {
   fs.readFile(file, 'utf8', (err, data) => {
     if (err) {
-      console.error(`Error reading the file: ${err}`);
-      return;
+      console.error(`Error reading the file: ${err}`)
+      return
     }
 
-    const modifiedContent = modifyContent(data);
+    const modifiedContent = modifyContent(data)
 
     // Write the modified content back to the file
-    fs.writeFile(file, modifiedContent, 'utf8', (err) => {
+    fs.writeFile(file, modifiedContent, 'utf8', err => {
       if (err) {
-        console.error(`Error writing to the file: ${err}`);
-        return;
+        console.error(`Error writing to the file: ${err}`)
+        return
       }
 
-      console.log(`${file} file is successfully modified and saved.`);
-    });
-  });
-});
+      console.log(`${file} file is successfully modified and saved.`)
+    })
+  })
+})
 
 function modifyContent(content) {
-  const modifiedContent = content.replace(/    class MockServer {/, '    // @ts-ignore\n'
-    + '    class MockServer {').replace(/    type MockServerConfig = {/, '    // @ts-ignore\n'
-    + '    type MockServerConfig = {').replace(/    class ExpectHelper {/g, '    // @ts-ignore\n'
-    + '    class ExpectHelper {').replace(/    type PlaywrightConfig = {/, '    // @ts-ignore\n'
-    + '    type PlaywrightConfig = {').replace(/    type PuppeteerConfig = {/, '    // @ts-ignore\n'
-    + '    type PuppeteerConfig = {').replace(/    type RESTConfig = {/, '    // @ts-ignore\n'
-    + '    type RESTConfig = {').replace(/    type WebDriverConfig = {/, '    // @ts-ignore\n'
-    + '    type WebDriverConfig = {')
-  return modifiedContent;
+  const modifiedContent = content
+    .replace(/    class MockServer {/, '    // @ts-ignore\n' + '    class MockServer {')
+    .replace(/    type MockServerConfig = {/, '    // @ts-ignore\n' + '    type MockServerConfig = {')
+    .replace(/    class ExpectHelper {/g, '    // @ts-ignore\n' + '    class ExpectHelper {')
+    .replace(/    type PlaywrightConfig = {/, '    // @ts-ignore\n' + '    type PlaywrightConfig = {')
+    .replace(/    type PuppeteerConfig = {/, '    // @ts-ignore\n' + '    type PuppeteerConfig = {')
+    .replace(/    type RESTConfig = {/, '    // @ts-ignore\n' + '    type RESTConfig = {')
+    .replace(/    type WebDriverConfig = {/, '    // @ts-ignore\n' + '    type WebDriverConfig = {')
+  return modifiedContent
 }
diff --git a/typings/index.d.ts b/typings/index.d.ts
@@ -534,7 +534,7 @@ declare const within: typeof CodeceptJS.within
 declare const session: typeof CodeceptJS.session
 declare const DataTable: typeof CodeceptJS.DataTable
 declare const DataTableArgument: typeof CodeceptJS.DataTableArgument
-declare const codeceptjs: typeof CodeceptJS.index
+declare const codeceptjs: typeof CodeceptJS
 declare const locate: typeof CodeceptJS.Locator.build
 declare function inject(): CodeceptJS.SupportObject
 declare function inject<T extends keyof CodeceptJS.SupportObject>(name: T): CodeceptJS.SupportObject[T]
diff --git a/typings/jsdoc.conf.js b/typings/jsdoc.conf.js
diff --git a/typings/jsdoc.conf.json b/typings/jsdoc.conf.json
@@ -0,0 +1,41 @@
+{
+  "source": {
+    "include": [
+      "./docs/build",
+      "./lib/actor.js",
+      "./lib/codecept.js",
+      "./lib/config.js",
+      "./lib/result.js",
+      "./lib/container.js",
+      "./lib/data/table.js",
+      "./lib/data/dataTableArgument.js",
+      "./lib/effects.js",
+      "./lib/event.js",
+      "./lib/index.js",
+      "./lib/locator.js",
+      "./lib/output.js",
+      "./lib/pause.js",
+      "./lib/recorder.js",
+      "./lib/secret.js",
+      "./lib/session.js",
+      "./lib/step/config.js",
+      "./lib/step/base.js",
+      "./lib/step/helper.js",
+      "./lib/step/meta.js",
+      "./lib/store.js",
+      "./lib/mocha/ui.js",
+      "./lib/mocha/featureConfig.js",
+      "./lib/mocha/scenarioConfig.js",
+      "./lib/mocha/bdd.js",
+      "./lib/mocha/hooks.js",
+      "./node_modules/@codeceptjs/detox-helper/Detox.js",
+      "./node_modules/@codeceptjs/helper/dist/index.js"
+    ]
+  },
+  "opts": {
+    "template": "node_modules/tsd-jsdoc/dist",
+    "recurse": true,
+    "destination": "./typings/"
+  },
+  "plugins": ["jsdoc.namespace.cjs", "jsdoc-typeof-plugin"]
+}
diff --git a/typings/jsdoc.namespace.cjs b/typings/jsdoc.namespace.cjs
@@ -0,0 +1,25 @@
+// Helps tsd-jsdoc to exports all typings into the CodeceptJS namespace,
+// instead of the global.
+
+let namespaceAdded = false
+const kinds = ['class', 'constant', 'function', 'typedef', 'interface', 'namespace']
+const namespace = 'CodeceptJS'
+
+module.exports = {
+  handlers: {
+    beforeParse(event) {
+      if (!namespaceAdded) {
+        event.source += `/** @namespace ${namespace} */`
+        namespaceAdded = true
+      }
+    },
+    newDoclet: ({ doclet }) => {
+      if (doclet.undocumented || doclet.memberof || !kinds.includes(doclet.kind) || (doclet.kind === 'namespace' && doclet.longname === 'CodeceptJS')) {
+        return
+      }
+      doclet.memberof = namespace
+      doclet.longname = `${doclet.memberof}.${doclet.longname}`
+      if (doclet.scope === 'global') doclet.scope = 'static'
+    },
+  },
+}
diff --git a/typings/jsdoc.namespace.js b/typings/jsdoc.namespace.js
diff --git a/typings/jsdoc.promiseBased.cjs b/typings/jsdoc.promiseBased.cjs
@@ -2,13 +2,9 @@
 // - Before parsing JS file, change class name and remove configuration already exported
 // - For each method set by default 'Promise<any>' if there is no returns tag or if the returns tag doesn't handle a promise
 
-const isHelper = (path) => path.includes('docs/build');
-const isDocumentedMethod = (doclet) => doclet.undocumented !== true
-  && doclet.kind === 'function'
-  && doclet.scope === 'instance';
-const shouldOverrideReturns = (doclet) => !doclet.returns
-  || !doclet.returns[0].type
-  || !doclet.returns[0].type.names[0].includes('Promise');
+const isHelper = path => path.includes('docs/build')
+const isDocumentedMethod = doclet => doclet.undocumented !== true && doclet.kind === 'function' && doclet.scope === 'instance'
+const shouldOverrideReturns = doclet => !doclet.returns || !doclet.returns[0].type || !doclet.returns[0].type.names[0].includes('Promise')
 
 module.exports = {
   handlers: {
@@ -20,16 +16,14 @@ module.exports = {
           // rename parent class to fix the inheritance
           .replace(/(@augments \w+)/, '$1Ts')
           // do not export twice the configuration of the helpers
-          .replace(/\/\*\*(.+?(?=config))config = \{\};/s, '');
+          .replace(/\/\*\*(.+?(?=config))config = \{\};/s, '')
       }
     },
     newDoclet: ({ doclet }) => {
-      if (isHelper(doclet.meta.path)
-        && isDocumentedMethod(doclet)
-        && shouldOverrideReturns(doclet)) {
-        doclet.returns = [];
-        doclet.addTag('returns', '{Promise<any>}');
+      if (isHelper(doclet.meta.path) && isDocumentedMethod(doclet) && shouldOverrideReturns(doclet)) {
+        doclet.returns = []
+        doclet.addTag('returns', '{Promise<any>}')
       }
     },
   },
-};
+}
diff --git a/typings/jsdocPromiseBased.conf.js b/typings/jsdocPromiseBased.conf.js
diff --git a/typings/jsdocPromiseBased.conf.json b/typings/jsdocPromiseBased.conf.json
@@ -0,0 +1,11 @@
+{
+  "source": {
+    "include": ["./docs/build"]
+  },
+  "opts": {
+    "template": "node_modules/tsd-jsdoc/dist",
+    "recurse": true,
+    "destination": "./typings/"
+  },
+  "plugins": ["jsdoc.promiseBased.cjs", "jsdoc.namespace.cjs", "jsdoc-typeof-plugin"]
+}

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-module.exports = {`
	`1`	`+export default {`
`2`	`2`	`printWidth: 220,`
`3`	`3`	`tabWidth: 2,`
`4`	`4`	`useTabs: false,`