Add ESM support configuration for Jest and update Octokit plugin imports

.babelrc

@@ -7,3 +7,4 @@
         }
     }
 }
+

docs/esm-support.md

@@ -0,0 +1,121 @@
+# ESM Support
+
+This document explains the current ESM (ECMAScript Modules) support in this project and how to work with ESM dependencies.
+
+## Current State
+
+This project is configured to support ESM dependencies while maintaining compatibility with Jest for testing. The key configurations are:
+
+### Jest Configuration (`jest.config.js`)
+
+```javascript
+export default {
+  // ... other config ...
+  transformIgnorePatterns: [
+    'node_modules/(?!(@octokit)/)'
+  ]
+}
+```
+
+This configuration tells Jest to transform (using Babel) any packages in `node_modules` that match the pattern `@octokit/*`. This allows the project to use ESM packages from the Octokit ecosystem.
+
+### Babel Configuration (`.babelrc`)
+
+```json
+{
+    "env": {
+        "test": {
+            "plugins": [
+                "@babel/plugin-transform-modules-commonjs"
+            ]
+        }
+    }
+}
+```
+
+This configuration tells Babel to transform ESM imports to CommonJS when running in the test environment (`NODE_ENV=test`).
+
+## Supported Packages
+
+The following types of packages are supported:
+
+1. **CommonJS packages** - Work natively
+2. **Dual-mode packages** (ESM + CommonJS) - Work with the current configuration as long as they provide a CommonJS entry point (e.g., `@octokit/[email protected]`)
+3. **Pure ESM packages with CommonJS fallback** - Work if they provide `dist-node` or similar CommonJS builds
+
+## Known Limitations
+
+### Pure ESM Packages (e.g., `@octokit/[email protected]+`)
+
+Pure ESM packages that only provide an ESM entry point (with `"type": "module"` and only `"exports"` field pointing to ESM code) are **not currently supported** with this Jest configuration.
+
+The `@octokit/[email protected]` package is a pure ESM package and encounters issues because:
+1. It has `"type": "module"` in its package.json
+2. It only provides an `"exports"` field with ESM entry points
+3. Jest's Babel transform cannot properly resolve and transform the nested ESM dependencies
+
+## Code Changes Made for ESM Compatibility
+
+### Import Statement Updates
+
+The import statement for `@octokit/plugin-retry` was updated to use the correct named export:
+
+**Before:**
+```javascript
+import {octokitRetry} from '@octokit/plugin-retry'
+```
+
+**After:**
+```javascript
+import {retry} from '@octokit/plugin-retry'
+```
+
+This matches the actual export name from the package and works with both v6 (CommonJS) and future ESM versions.
+
+### Usage Updates
+
+All usages were updated accordingly:
+
+```javascript
+const octokit = github.getOctokit(token, {
+  userAgent: `github/branch-deploy@${VERSION}`,
+  additionalPlugins: [retry]  // Changed from octokitRetry
+})
+```
+
+## Future: Full ESM Support
+
+To support pure ESM packages (like `@octokit/[email protected]+`), the project would need to either:
+
+### Option 1: Convert to Full ESM (Recommended but requires significant changes)
+
+1. Add `"type": "module"` to `package.json`
+2. Update all test files to import Jest globals from `@jest/globals`:
+   ```javascript
+   import {jest, test, expect, beforeEach} from '@jest/globals'
+   ```
+3. Use `NODE_OPTIONS="--experimental-vm-modules"` when running Jest
+4. Update Jest config to:
+   ```javascript
+   export default {
+     testEnvironment: 'node',
+     transform: {},
+     // Remove transformIgnorePatterns as ESM works natively
+   }
+   ```
+
+### Option 2: Use a Custom Resolver (Partial solution)
+
+Create a custom Jest resolver that maps pure ESM packages to their bundled versions or creates shims. This is complex and maintenance-intensive.
+
+### Option 3: Wait for Jest Native ESM Support
+
+Jest's ESM support is still experimental. Future versions of Jest may provide better native ESM support without requiring `--experimental-vm-modules`.
+
+## Current Recommendation
+
+For now, stay with dual-mode or CommonJS-compatible versions of dependencies (e.g., `@octokit/[email protected]`). The current configuration is "ESM-ready" and will make future migration easier when:
+1. Jest has better native ESM support, or
+2. The team decides to convert the entire project to ESM
+
+The code changes made (using `{retry}` import) are compatible with both current and future ESM versions of the packages.

jest.config.js

@@ -0,0 +1,17 @@
+export default {
+  coverageReporters: ['json-summary', 'text', 'lcov'],
+  collectCoverage: true,
+  collectCoverageFrom: ['./src/**'],
+  coverageThreshold: {
+    global: {
+      lines: 100,
+      statements: 100,
+      branches: 100,
+      functions: 100
+    }
+  },
+  testEnvironment: 'node',
+  // Allow Jest to transform @octokit packages from node_modules
+  // This enables support for ESM packages from the Octokit ecosystem
+  transformIgnorePatterns: ['node_modules/(?!(@octokit)/)']
+}

package.json

@@ -27,33 +27,14 @@
   "dependencies": {
     "@actions/core": "^1.11.1",
     "@actions/github": "^6.0.1",
-    "@octokit/plugin-retry": "^6.0.1",
-    "@octokit/rest": "^20.1.0",
+    "@octokit/plugin-retry": "^6.1.0",
     "@octokit/request": "^10.0.5",
+    "@octokit/rest": "^20.1.0",
     "dedent-js": "^1.0.1",
     "github-username-regex-js": "^1.0.0",
     "nunjucks": "^3.2.4",
     "yargs-parser": "^21.1.1"
   },
-  "jest": {
-    "coverageReporters": [
-      "json-summary",
-      "text",
-      "lcov"
-    ],
-    "collectCoverage": true,
-    "collectCoverageFrom": [
-      "./src/**"
-    ],
-    "coverageThreshold": {
-      "global": {
-        "lines": 100,
-        "statements": 100,
-        "branches": 100,
-        "functions": 100
-      }
-    }
-  },
   "devDependencies": {
     "@babel/core": "^7.28.4",
     "@babel/plugin-transform-modules-commonjs": "^7.27.1",

src/functions/admin.js

@@ -1,7 +1,7 @@
 import * as core from '@actions/core'
 import * as github from '@actions/github'
 import githubUsernameRegex from 'github-username-regex-js'
-import {octokitRetry} from '@octokit/plugin-retry'
+import {retry} from '@octokit/plugin-retry'
 import {COLORS} from './colors'
 import {API_HEADERS} from './api-headers'
 
@@ -23,7 +23,7 @@ async function orgTeamCheck(actor, orgTeams) {
 
   // Create a new octokit client with the admins_pat and the retry plugin
   const octokit = github.getOctokit(adminsPat, {
-    additionalPlugins: [octokitRetry]
+    additionalPlugins: [retry]
   })
 
   // Loop through all org/team names

src/functions/post.js

@@ -1,5 +1,5 @@
 import * as core from '@actions/core'
-import {octokitRetry} from '@octokit/plugin-retry'
+import {retry} from '@octokit/plugin-retry'
 import * as github from '@actions/github'
 import {context} from '@actions/github'
 
@@ -71,7 +71,7 @@ export async function post() {
     // Create an octokit client with the retry plugin
     const octokit = github.getOctokit(token, {
       userAgent: `github/branch-deploy@${VERSION}`,
-      additionalPlugins: [octokitRetry]
+      additionalPlugins: [retry]
     })
 
     core.info(`🧑‍🚀 commit SHA: ${COLORS.highlight}${data.sha}${COLORS.reset}`)