@hs-web-team/eslint-config-node 3.0.0-next.7 → 3.0.0

package/CLAUDE.md

@@ -26,8 +26,13 @@ When testing changes to this package in downstream projects, you'll typically:
 ### Core Configuration File
 - **`index.js`**: The main ESLint configuration export using ESLint 9's flat config format
   - Uses `@eslint/js`, `typescript-eslint`, and `globals` packages
-  - Exports two separate configurations: one for JavaScript files (`**/*.{js,mjs,cjs}`) and one for TypeScript files (`**/*.{ts,mts,cts,tsx}`)
-  - JavaScript config uses `js/recommended`, TypeScript config uses `tseslint.configs.recommended`
+  - Exports an array of configuration objects (flat config format)
+  - Structure:
+    1. Global ignores object
+    2. `js.configs.recommended` for JavaScript baseline
+    3. JavaScript-specific config for `**/*.{js,mjs,cjs}` files
+    4. Spreads `tseslint.configs.recommended` for TypeScript baseline
+    5. TypeScript-specific config for `**/*.{ts,mts,cts,tsx}` files
   - Includes Node.js, ES2022, and Jest globals
   - Common ignores: `node_modules`, `.serverless`, `.webpack`, `dist`, `eslint.config.js`
   - Key custom rules: `no-console` (allows info/warn/error), `max-len` (120 chars), camelcase disabled

package/README.md

@@ -22,21 +22,19 @@ This is a list of ESLint rules that are recommended for use with **Hubspot Marke
 2. Add to `eslint.config.js` in project root directory
 
     ```typescript
-    import { defineConfig } from 'eslint/config';
     import wtConfig from '@hs-web-team/eslint-config-node';
 
-    export default defineConfig([
+    export default [
       ...wtConfig,
-    ]);
+    ];
     ```
 
 3. Extend the eslint on a project basis by adding rules to `eslint.config.js` e.g.
 
     ```typescript
-    import { defineConfig } from 'eslint/config';
     import wtConfig from '@hs-web-team/eslint-config-node';
 
-    export default defineConfig([
+    export default [
       // Add project-specific ignores here
       {
         ignores: ['dist/**'],
@@ -48,7 +46,7 @@ This is a list of ESLint rules that are recommended for use with **Hubspot Marke
         },
       },
       ...wtConfig, // This will include the shared rules from @hs-web-team/eslint-config-node
-    ]);
+    ];
     ```
 
 ## Where to use it

package/docs/MIGRATION-V3.md

@@ -4,13 +4,16 @@
 
 > **Note**
 >
-> This migration requires a manual review of the changes and also that you run your project in Node.js v22 or higher.
+> This migration requires Node.js v22 or higher and a **manual migration** from `.eslintrc` to `eslint.config.mjs`.
 
 - [ ] Upgrade to Node.js v22 or higher
-- [ ] Upgrade all dependencies to the latest version
-- [ ] Update the package `npm install @hs-web-team/eslint-config-node@latest`
-- [ ] Run the script `npx @eslint/migrate-config .eslintrc`
+- [ ] Update the package: `npm install -D @hs-web-team/eslint-config-node@latest`
+- [ ] **Remove** `@hs-web-team/eslint-config-ts` from dependencies (no longer needed - TypeScript support is now included)
+- [ ] Remove the `--ext .js,.ts` flag from the ESLint command in your project's package.json
+- [ ] Manually create `eslint.config.mjs` (see [Manual Migration Guide](#manual-migration-guide) below)
+- [ ] Delete `.eslintrc` file
 - [ ] Run `npm run lint` to check for any errors
+- [ ] Fix any linting errors
 - [ ] Commit the changes
 - [ ] Create a PR
 - [ ] Get it approved
@@ -20,5 +23,268 @@
 
 > **Important**
 >
-> Bear in mind that this migration will remove the `.eslintrc` file and replace it with `eslint.config.js`.
-> Also the automated migration might fail to migrate some of the rules, so you may need to manually adjust the `eslint.config.js` file.
+> The automated migration script (`npx @eslint/migrate-config .eslintrc`) **will not work** for most projects migrating from ESLint 8 to ESLint 9. You must manually create the new `eslint.config.js` file.
+>
+> This is because:
+> - ESLint 9 uses a completely different flat config format
+> - The `@hs-web-team/eslint-config-ts` package is no longer needed (TypeScript support is built-in)
+> - Many ESLint plugins have changed their configuration APIs
+
+## Manual Migration Guide
+
+### Before: Typical `.eslintrc` file
+
+```json
+{
+  "extends": [
+    "@hs-web-team/eslint-config-node",
+    "@hs-web-team/eslint-config-ts"
+  ],
+  "rules": {
+    "no-restricted-syntax": 0,
+    "no-console": 0,
+    "no-param-reassign": 0,
+    "no-await-in-loop": 0,
+    "max-classes-per-file": 0,
+    "import/no-extraneous-dependencies": 0,
+    "@typescript-eslint/no-unused-vars": ["error", { "vars": "all", "args": "after-used", "ignoreRestSiblings": true }],
+    "@typescript-eslint/no-unnecessary-condition": "error"
+  },
+  "overrides": [
+    {
+      "files": ["*.test.ts", "*.spec.ts"],
+      "rules": {
+        "no-unused-expressions": "off"
+      }
+    }
+  ],
+  "env": {
+    "jest": true
+  },
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "globals": {
+    "window": true
+  }
+}
+```
+
+### After: New `eslint.config.mjs` file
+
+```javascript
+import wtConfig from '@hs-web-team/eslint-config-node';
+import tseslint from 'typescript-eslint';
+
+export default [
+  // Spread the base config (includes both JS and TS configs)
+  ...wtConfig,
+
+  // Add custom rules for all files
+  {
+    rules: {
+      'no-restricted-syntax': 'off',
+      'no-console': 'off',
+      'no-param-reassign': 'off',
+      'no-await-in-loop': 'off',
+      'max-classes-per-file': 'off',
+      'import/no-extraneous-dependencies': 'off',
+    },
+  },
+
+  // TypeScript-specific rules (applied only to TS files)
+  {
+    files: ['**/*.{ts,mts,cts,tsx}'],
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { vars: 'all', args: 'after-used', ignoreRestSiblings: true }
+      ],
+      '@typescript-eslint/no-unnecessary-condition': 'error',
+    },
+  },
+
+  // Test file overrides
+  {
+    files: ['**/*.test.{ts,js}', '**/*.spec.{ts,js}'],
+    rules: {
+      'no-unused-expressions': 'off',
+    },
+  },
+
+  // Global variables (if needed)
+  {
+    languageOptions: {
+      globals: {
+        window: 'readonly',
+      },
+    },
+  },
+];
+```
+
+### Key Migration Changes
+
+1. **No separate TypeScript config needed**: TypeScript support is now included in `@hs-web-team/eslint-config-node`, so you can remove `@hs-web-team/eslint-config-ts` from your dependencies.
+
+2. **Environment variables**: The `env` property is replaced with `languageOptions.globals`. Jest globals are already included in the base config, so you don't need to specify them again.
+
+3. **Parser options**: Move `parserOptions` inside `languageOptions.parserOptions` and apply only to TypeScript files.
+
+4. **Overrides become separate objects**: Instead of `overrides` array, create separate configuration objects with `files` patterns.
+
+5. **Use `'off'` instead of `0`**: While numbers still work, the string values (`'off'`, `'warn'`, `'error'`) are more readable.
+
+6. **Import as ES module**: Use `import` instead of `require`.
+
+## Extending the Configuration
+
+Once you've completed the migration, you can easily extend the configuration for specific needs:
+
+### Adding Rules for Specific File Patterns
+
+```javascript
+import wtConfig from '@hs-web-team/eslint-config-node';
+
+export default [
+  ...wtConfig,
+  {
+    files: ['src/**/*.js'],
+    rules: {
+      'no-restricted-imports': ['error', 'lodash'],
+    },
+  },
+];
+```
+
+### Adding Custom Plugins
+
+```javascript
+import wtConfig from '@hs-web-team/eslint-config-node';
+import securityPlugin from 'eslint-plugin-security';
+
+export default [
+  ...wtConfig,
+  {
+    plugins: {
+      security: securityPlugin,
+    },
+    rules: {
+      'security/detect-object-injection': 'warn',
+    },
+  },
+];
+```
+
+### Adding Custom Ignores
+
+```javascript
+import wtConfig from '@hs-web-team/eslint-config-node';
+
+export default [
+  ...wtConfig,
+  {
+    ignores: [
+      '**/coverage/**',
+      '**/build/**',
+      '**/*.config.js',
+    ],
+  },
+];
+```
+
+### Complex Example with Multiple Customizations
+
+```javascript
+import wtConfig from '@hs-web-team/eslint-config-node';
+import importPlugin from 'eslint-plugin-import';
+
+export default [
+  ...wtConfig,
+
+  // Global overrides
+  {
+    rules: {
+      'no-console': 'off',
+      'max-len': ['error', { code: 100 }],
+    },
+  },
+
+  // Import plugin configuration
+  {
+    plugins: {
+      import: importPlugin,
+    },
+    rules: {
+      'import/order': ['error', { 'newlines-between': 'always' }],
+      'import/no-duplicates': 'error',
+    },
+  },
+
+  // TypeScript-specific configuration
+  {
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+    rules: {
+      '@typescript-eslint/strict-boolean-expressions': 'error',
+    },
+  },
+
+  // Test files
+  {
+    files: ['**/*.test.{js,ts}', '**/__tests__/**'],
+    rules: {
+      'max-len': 'off',
+      'no-magic-numbers': 'off',
+    },
+  },
+
+  // Additional ignores
+  {
+    ignores: ['**/generated/**', '**/migrations/**'],
+  },
+];
+```
+
+## Common Issues
+
+### Module Type Warning
+
+If you created `eslint.config.js` instead of `eslint.config.mjs`, you may see this warning when running ESLint:
+
+```bash
+(node:40504) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///path/to/your/project/eslint.config.js?mtime=1762786140088 is not specified and it doesn't parse as CommonJS.
+Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
+To eliminate this warning, add "type": "module" to /path/to/your/project/package.json.
+```
+
+**Why this happens:** This ESLint config package uses ES modules (`"type": "module"`), and your `eslint.config.js` imports it using ES module syntax. If your project's `package.json` doesn't specify the module type, Node.js has to parse the file twice, causing the warning.
+
+**Solution (choose one):**
+
+**Option 1 (Recommended for CommonJS projects):** Rename the config file to explicitly mark it as an ES module:
+
+```bash
+mv eslint.config.js eslint.config.mjs
+```
+
+This is the recommended approach because it doesn't require any changes to your existing codebase.
+
+**Option 2 (Only if already using ES modules):** Add to your project's `package.json`:
+
+```jsonc
+{
+  "type": "module"
+}
+```
+
+> **Warning:** Option 2 requires migrating your entire project from CommonJS to ES modules. All `.js` files must use ES module syntax (import/export) or be renamed to `.cjs`. Only use this option if your project is already using ES modules throughout.

package/index.js

@@ -1,7 +1,6 @@
 import js from '@eslint/js';
 import globals from 'globals';
 import tseslint from 'typescript-eslint';
-import { defineConfig } from 'eslint/config';
 
 // Base rules for all JavaScript files
 const baseRules = {
@@ -47,26 +46,30 @@ const commonIgnores = [
   'eslint.config.js',
 ];
 
-export default defineConfig([
+export default [
+  // Global ignores
+  {
+    ignores: commonIgnores,
+  },
   // Base config for all JavaScript files
+  js.configs.recommended,
   {
     files: ['**/*.{js,mjs,cjs}'],
-    plugins: { js },
-    extends: ['js/recommended'],
     languageOptions: {
       globals: {...globals.node, ...globals.es2022, ...globals.jest},
     },
-    ignores: commonIgnores,
     rules: baseRules,
   },
-  // TypeScript config that extends the base config
+  // TypeScript config - restrict to TypeScript files only
+  ...tseslint.configs.recommended.map(config => ({
+    ...config,
+    files: ['**/*.{ts,mts,cts,tsx}'],
+  })),
   {
     files: ['**/*.{ts,mts,cts,tsx}'],
-    ...tseslint.configs.recommended,
-    // You can add or override rules specific to TypeScript here
-    rules: {
-      ...baseRules,
-      // Add any TypeScript-specific rules here
+    languageOptions: {
+      globals: {...globals.node, ...globals.es2022, ...globals.jest},
     },
+    rules: baseRules,
   },
-]);
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hs-web-team/eslint-config-node",
-  "version": "3.0.0-next.7",
+  "version": "3.0.0",
   "description": "HubSpot Marketing WebTeam ESLint rules for Node.js",
   "main": "index.js",
   "type": "module",
@@ -28,13 +28,15 @@
   },
   "homepage": "https://github.com/HubSpotWebTeam/wt-eslint-node#readme",
   "dependencies": {
-    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/eslintrc": "^3.3.3",
     "@eslint/js": "^9.39.1",
     "@typescript-eslint/eslint-plugin": "^8.46.3",
     "@typescript-eslint/parser": "^8.46.3",
+    "eslint": "^9.39.1",
+    "eslint-formatter-checkstyle": "^9.0.1",
     "globals": "^16.5.0",
-    "prettier": "^3.6.2",
     "jiti": "^2.6.1",
-    "typescript-eslint": "^8.46.3"
+    "prettier": "^3.7.3",
+    "typescript-eslint": "^8.48.0"
   }
 }