@hs-web-team/eslint-config-node 4.0.0 → 4.1.0

package/.githooks/commit-msg

@@ -0,0 +1,28 @@
+#!/bin/sh
+
+commit_msg=$(head -1 "$1")
+
+# Skip merge and revert commits (auto-generated messages)
+case "$commit_msg" in
+  Merge\ *|Revert\ *) exit 0 ;;
+esac
+
+pattern="^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-zA-Z0-9_/-]+\))?!?: .+"
+
+if ! echo "$commit_msg" | grep -qE "$pattern"; then
+  echo ""
+  echo "ERROR: Commit message does not follow Conventional Commits format."
+  echo ""
+  echo "  Expected:  type(optional-scope): description"
+  echo "  Types:     feat | fix | docs | style | refactor | test | chore | ci | perf | revert | build"
+  echo ""
+  echo "  Examples:"
+  echo "    feat: add new rule for import order"
+  echo "    fix: correct comma-dangle config for browser"
+  echo "    feat!: drop support for Node 18  (breaking change -> major bump)"
+  echo "    feat(browser): add React 19 support"
+  echo ""
+  echo "  See: https://www.conventionalcommits.org"
+  echo ""
+  exit 1
+fi

package/.github/workflows/release-please.yml

@@ -0,0 +1,17 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

package/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "4.1.0"
+}

package/.stylelintrc.json

@@ -11,10 +11,14 @@
       }
     ],
     "scss/dollar-variable-pattern": null,
-    "scss/at-import-no-partial-leading-underscore": null,
-    "selector-class-pattern": null,
+    "selector-class-pattern": [
+      "^-?[a-z0-9]([a-z0-9]|-(?!-))*$",
+      {
+        "message": "Class names should only contain lowercase alphanumeric characters and hyphens, with no consecutive hyphens",
+        "severity": "warning"
+      }
+    ],
     "declaration-block-no-redundant-longhand-properties": null,
-    "scss/at-import-partial-extension": null,
     "alpha-value-notation": null,
     "scss/percent-placeholder-pattern": null,
     "scss/at-mixin-argumentless-call-parentheses": null,
@@ -35,6 +39,13 @@
       {
         "camelCaseSvgKeywords": true
       }
+    ],
+    "selector-disallowed-list": [
+      ["/(?:^|[\\s>+~])\\s*\\.-[a-z]/i"],
+      {
+        "message": "Modifier classes (starting with '-') must not be standalone selectors; always combine with a base class (e.g., .prefix-element.-modifier or &.-modifier in nested rules)",
+        "severity": "error"
+      }
     ]
   }
 }

package/README.md

@@ -13,6 +13,7 @@ This package provides ESLint rules and configurations for **Hubspot Marketing We
 - [Accessibility Testing](#accessibility-testing-optional)
 - [Where to use it](#where-to-use-it)
 - [Using the Prettier Scripts](#using-the-prettier-scripts)
+- [Contributing](#contributing)
 <!-- index-end -->
 
 ## Node.js Setup
@@ -199,3 +200,57 @@ See [MIGRATION-V2.md](./docs/MIGRATION-V2.md)
 ## Migration from v2 to v3
 
 See [MIGRATION-V3.md](./docs/MIGRATION-V3.md)
+
+## Contributing
+
+### Conventional Commits
+
+This repo uses [Conventional Commits](https://www.conventionalcommits.org) for all commit messages. A `commit-msg` git hook validates the format automatically — run `npm install` once to activate it.
+
+**Format:** `type(optional-scope): description`
+
+| Type | Use for | Version bump |
+|------|---------|-------------|
+| `feat` | New feature or config rule | Minor (`4.0.0` → `4.1.0`) |
+| `fix` | Bug fix or rule correction | Patch (`4.0.0` → `4.0.1`) |
+| `feat!` or `BREAKING CHANGE:` footer | Breaking API/config change | Major (`4.0.0` → `5.0.0`) |
+| `chore` | Dependency updates, tooling | No release |
+| `docs` | Documentation only | No release |
+| `refactor` | Internal restructuring | No release |
+| `ci` | CI/CD changes | No release |
+| `test` | Test changes | No release |
+
+**Examples:**
+
+```
+feat: add import/order rule to Node config
+fix: align browser comma-dangle with prettier defaults
+feat(browser): add React 19 peer dep support
+feat!: drop Node 18 support — requires Node 24+
+chore: bump typescript-eslint to v8.60
+docs: update Cypress usage examples
+```
+
+A breaking change can also be indicated by adding a `BREAKING CHANGE:` footer to any commit type:
+
+```
+feat: remove deprecated stylelint rules
+
+BREAKING CHANGE: Removed rules that were dropped in stylelint-scss@7.
+Projects relying on those rules must update their configs before upgrading.
+```
+
+### Release Process
+
+Releases are automated via [release-please](https://github.com/googleapis/release-please). No manual version bumping or GitHub release creation is needed.
+
+**How it works:**
+
+1. Merge PRs to `main` using conventional commit messages (see above).
+2. After each merge, release-please opens or updates a **Release PR** (titled `chore(main): release X.Y.Z`) that accumulates all unreleased changes, bumps `package.json`, and generates a `CHANGELOG.md` entry.
+3. When you are ready to publish, **merge the Release PR**.
+4. release-please creates a GitHub release and git tag automatically.
+5. The `release.yml` workflow fires on the new release and publishes to npm.
+
+**To release a prerelease (`-next.N`):**  
+Update the version in `package.json` manually on a branch (e.g. `4.1.0-next.0`) and create a GitHub release by hand — the existing `release.yml` workflow will publish it with the `next` tag on npm. Prereleases are not yet managed by release-please in this repo.

package/bin/check-peer-deps.cjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const projectRoot = process.env.INIT_CWD || process.env.npm_config_local_prefix;
+
+// Skip if we can't determine the consuming project's root, or if postinstall
+// is running inside this package's own development environment.
+if (!projectRoot || projectRoot === path.resolve(__dirname, '..')) {
+  process.exit(0);
+}
+
+const ownPkg = require('../package.json');
+
+const stylelintPeers = Object.entries(ownPkg.peerDependencies || {}).filter(([name]) =>
+  name.startsWith('stylelint')
+);
+
+// Extracts the minimum required major version from a semver range like ^17.0.0 or >=17.1.1.
+const minMajor = (range) => {
+  const match = range.match(/(\d+)/);
+  return match ? parseInt(match[1], 10) : 0;
+};
+
+const isInstalled = (pkg) =>
+  fs.existsSync(path.join(projectRoot, 'node_modules', pkg, 'package.json'));
+
+// Only warn about missing stylelint plugins if stylelint itself is installed —
+// consumers who don't use stylelint at all don't need any of these.
+const stylelintInUse = isInstalled('stylelint');
+
+const outdated = [];
+const missing = [];
+
+for (const [pkg, requiredRange] of stylelintPeers) {
+  const pkgJsonPath = path.join(projectRoot, 'node_modules', pkg, 'package.json');
+
+  if (!fs.existsSync(pkgJsonPath)) {
+    if (stylelintInUse && pkg !== 'stylelint') {
+      missing.push({ pkg, requiredRange });
+    }
+    continue;
+  }
+
+  const { version } = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+  const installedMajor = parseInt(version.split('.')[0], 10);
+
+  if (installedMajor < minMajor(requiredRange)) {
+    outdated.push({ pkg, version, requiredRange });
+  }
+}
+
+if (outdated.length === 0 && missing.length === 0) process.exit(0);
+
+const pkgName = ownPkg.name;
+
+if (missing.length > 0) {
+  console.warn(`\n⚠️  ${pkgName}: missing stylelint peer dependencies.\n`);
+  console.warn('   These packages are required for stylelint to work correctly:');
+  for (const { pkg, requiredRange } of missing) {
+    console.warn(`   • ${pkg}  (required: ${requiredRange})`);
+  }
+  const installCmd = missing.map(({ pkg, requiredRange }) => `${pkg}@"${requiredRange}"`).join(' ');
+  console.warn(`\n   Run: npm install --save-dev ${installCmd}`);
+  console.warn('   Linting will fail without these packages.\n');
+}
+
+if (outdated.length > 0) {
+  console.warn(`\n⚠️  ${pkgName}: outdated stylelint peer dependencies detected.\n`);
+  console.warn('   These packages are installed at versions that are no longer compatible:');
+  for (const { pkg, version, requiredRange } of outdated) {
+    console.warn(`   • ${pkg}@${version}  →  required: ${requiredRange}`);
+  }
+  const upgradeCmd = outdated.map(({ pkg, requiredRange }) => `${pkg}@"${requiredRange}"`).join(' ');
+  console.warn(`\n   Run: npm install ${upgradeCmd}`);
+  console.warn('   Failure to upgrade may cause unexpected lint errors.\n');
+}

package/browser.js

@@ -7,7 +7,7 @@ import jsxA11yPlugin from 'eslint-plugin-jsx-a11y';
 
 // Base rules adapted from the browser config
 const baseRules = {
-  'comma-dangle': 'warn',
+  'comma-dangle': ['warn', 'always-multiline'],
   'no-param-reassign': ['warn', { props: false }],
   'arrow-parens': 0,
   'no-plusplus': 0,
@@ -19,8 +19,8 @@ const baseRules = {
       allow: [
         '_hsg',
         '_hsq',
-      ]
-    }
+      ],
+    },
   ],
   'no-trailing-spaces': ['error', { skipBlankLines: true }],
   'no-unused-expressions': ['warn', { allowTernary: true }],
@@ -29,15 +29,15 @@ const baseRules = {
     {
       code: 120,
       ignoreStrings: true,
-      ignoreTemplateLiterals: true
-    }
+      ignoreTemplateLiterals: true,
+    },
   ],
   'operator-linebreak': 0,
   'implicit-arrow-linebreak': 0,
   indent: 0,
   'object-curly-newline': 0,
   'function-paren-newline': 0,
-  'nonblock-statement-body-position': 0
+  'nonblock-statement-body-position': 0,
 };
 
 // React-specific rules
@@ -50,10 +50,10 @@ const reactRules = {
     2,
     {
       component: true,
-      html: false
-    }
+      html: false,
+    },
   ],
-  'react/forbid-prop-types': 0
+  'react/forbid-prop-types': 0,
 };
 
 // Common ignore patterns
@@ -63,13 +63,13 @@ const commonIgnores = [
   '**/build/**',
   '**/.next/**',
   '**/coverage/**',
-  'eslint.config.js'
+  'eslint.config.js',
 ];
 
 export default [
   // Global ignores
   {
-    ignores: commonIgnores
+    ignores: commonIgnores,
   },
   // Base config for all JavaScript files
   js.configs.recommended,
@@ -85,17 +85,17 @@ export default [
         // Custom browser globals from original config
         $: true,
         jQuery: true,
-        Invoca: true
+        Invoca: true,
       },
       parserOptions: {
         ecmaFeatures: {
-          jsx: true
-        }
-      }
+          jsx: true,
+        },
+      },
     },
     rules: {
-      ...baseRules
-    }
+      ...baseRules,
+    },
   },
   // React configuration
   {
@@ -103,24 +103,24 @@ export default [
     plugins: {
       react: reactPlugin,
       'react-hooks': reactHooksPlugin,
-      'jsx-a11y': jsxA11yPlugin
+      'jsx-a11y': jsxA11yPlugin,
     },
     settings: {
       react: {
-        version: 'detect'
-      }
+        version: 'detect',
+      },
     },
     rules: {
       ...reactPlugin.configs.recommended.rules,
       ...reactHooksPlugin.configs.recommended.rules,
       ...jsxA11yPlugin.configs.recommended.rules,
-      ...reactRules
-    }
+      ...reactRules,
+    },
   },
   // TypeScript config
   ...tseslint.configs.recommended.map(config => ({
     ...config,
-    files: ['**/*.{ts,mts,cts,tsx}']
+    files: ['**/*.{ts,mts,cts,tsx}'],
   })),
   {
     files: ['**/*.{ts,mts,cts,tsx}'],
@@ -133,17 +133,17 @@ export default [
         ...globals.jest,
         $: true,
         jQuery: true,
-        Invoca: true
+        Invoca: true,
       },
       parserOptions: {
         ecmaFeatures: {
-          jsx: true
-        }
-      }
+          jsx: true,
+        },
+      },
     },
     rules: {
-      ...baseRules
-    }
+      ...baseRules,
+    },
   },
   // React configuration for TypeScript files
   {
@@ -151,18 +151,18 @@ export default [
     plugins: {
       react: reactPlugin,
       'react-hooks': reactHooksPlugin,
-      'jsx-a11y': jsxA11yPlugin
+      'jsx-a11y': jsxA11yPlugin,
     },
     settings: {
       react: {
-        version: 'detect'
-      }
+        version: 'detect',
+      },
     },
     rules: {
       ...reactPlugin.configs.recommended.rules,
       ...reactHooksPlugin.configs.recommended.rules,
       ...jsxA11yPlugin.configs.recommended.rules,
-      ...reactRules
-    }
-  }
+      ...reactRules,
+    },
+  },
 ];

package/index.js

@@ -20,8 +20,8 @@ const baseRules = {
       allow: [
         '__dirname',
         '__filename',
-      ]
-    }
+      ],
+    },
   ],
   'no-confusing-arrow': 0,
   'import/no-unresolved': 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hs-web-team/eslint-config-node",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "HubSpot Marketing WebTeam shared configurations for ESLint, Prettier, Stylelint, and Cypress",
   "main": "index.js",
   "type": "module",
@@ -29,8 +29,10 @@
     }
   },
   "scripts": {
+    "postinstall": "node bin/check-peer-deps.cjs",
     "lint": "npx eslint -c ./index.js *.js --fix",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepare": "git rev-parse --git-dir > /dev/null 2>&1 && git config core.hooksPath .githooks || true"
   },
   "engines": {
     "node": ">=24"

package/release-please-config.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "node",
+  "include-component-in-tag": false,
+  "packages": {
+    ".": {}
+  }
+}