@hs-web-team/eslint-config-node 4.2.2 → 5.1.0

package/.stylelintrc.json

@@ -21,9 +21,9 @@
     ],
     "scss/dollar-variable-pattern": null,
     "selector-class-pattern": [
-      "^-?[a-z0-9]([a-z0-9]|-(?!-))*$",
+      "^(?:-?[a-z0-9](?:[a-z0-9]|-(?!-))*|[a-z0-9]+(?:-[a-z0-9]+)*(?:__[a-z0-9]+(?:-[a-z0-9]+)*)?(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?)$",
       {
-        "message": "Class names should only contain lowercase alphanumeric characters and hyphens, with no consecutive hyphens",
+        "message": "Class names must be kebab-case (e.g. block-element), or strict BEM (block__element--modifier) with at most one __element and one --modifier, in that order",
         "severity": "warning"
       }
     ],
@@ -50,7 +50,10 @@
       }
     ],
     "selector-disallowed-list": [
-      ["/(?:^|[\\s>+~])\\s*\\.-[a-z]/i"],
+      [
+        "/(?<!:(?:is|not|where|matches)\\([^)]*)(?:^|[\\s>+~])\\s*\\.-[a-z]/i",
+        "/(?:^|[\\s>+~])\\s*:(?:is|not|where|matches)\\(\\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

@@ -10,7 +10,9 @@ This package provides ESLint rules and configurations for **Hubspot Marketing We
 - [Browser/React Setup](#browserreact-setup)
 - [Stylelint Setup](#stylelint-setup)
 - [Cypress Setup](#cypress-setup)
+- [Gherkin Tag Linting Setup](#gherkin-tag-linting-setup)
 - [Accessibility Testing](#accessibility-testing-optional)
+- [Custom Rules](#custom-rules)
 - [Where to use it](#where-to-use-it)
 - [Using the Prettier Scripts](#using-the-prettier-scripts)
 - [Contributing](#contributing)
@@ -125,6 +127,26 @@ This package provides shared Cypress configuration for E2E testing.
 
 For detailed Cypress configuration and migration documentation, see [examples/cypress-usage.md](./examples/cypress-usage.md).
 
+## Gherkin Tag Linting Setup
+
+Cucumber selects tests by tag, so an untagged scenario is silently skipped and a green suite can hide tests that never ran. This package ships two checks that make that a build failure.
+
+This applies only to repositories whose Cypress suite is written in Gherkin `.feature` files. A Cypress suite written in Mocha has no tags to check. Neither check is part of `wtConfig`, `wtBrowserConfig`, or the Cypress config, so existing consumers are unaffected until they opt in with the script below.
+
+1. Add one script to `package.json`
+
+    ```json
+    {
+      "scripts": {
+        "lint:gherkin": "gplint cypress/e2e --config=node_modules/@hs-web-team/eslint-config-node/gherkin/.gplintrc && gherkin-tag-coverage"
+      }
+    }
+    ```
+
+`gplint` is bundled, so there is nothing extra to install. Repositories with no production environment opt out of the prod requirement with a `gherkin-coverage.json` file.
+
+For the full rule list, QA-only setup and troubleshooting, see [examples/gherkin-usage.md](./examples/gherkin-usage.md).
+
 ## Accessibility Testing (optional)
 
 This package includes a shared accessibility testing setup using [cypress-axe](https://github.com/component-driven/cypress-axe). Projects can opt in with a single import — no need to install `cypress-axe` or `axe-core` directly.
@@ -158,6 +180,17 @@ This package includes a shared accessibility testing setup using [cypress-axe](h
 
 `cy.checkAccessibility()` adds the `high-contrast` class to `body`, runs WCAG 2.2 Level AA rules only, and logs each violation with its id, help text, impact, element targets, and help URL. TypeScript types are included — no `tsconfig.json` changes required.
 
+## Custom Rules
+
+This package ships a `hs-web-team` ESLint plugin with custom rules that are active automatically when you use `wtConfig` or `wtBrowserConfig` — no extra setup needed.
+
+| Rule | Severity | Summary |
+|------|----------|---------|
+| `hs-web-team/no-reduce-accumulator-copy` | error | Disallows O(n²) accumulator copies (spread, concat) inside `reduce`/`reduceRight` |
+| `hs-web-team/no-non-literal-constant-case` | warn | Disallows CONSTANT_CASE names whose value isn't a literal/static constant, or that are declared with `let`/`var` |
+
+For examples and remediation guidance, see [examples/custom-rules.md](./examples/custom-rules.md).
+
 ## Where to use it
 
 This package provides multiple configurations:

package/base-rules.js

@@ -0,0 +1,61 @@
+import globals from 'globals';
+
+// Underscore-prefixed HubSpot platform globals (e.g. window._hsq, window._hsg.__ip_lookup).
+// Exported so consuming projects can extend this list with their own no-underscore-dangle
+// allowances without duplicating the shared entries, e.g.:
+//   allow: [...underscoreDangleAllowlist, 'myProjectGlobal']
+export const underscoreDangleAllowlist = ['_hsg', '_hsp', '_hsq', '__ip_lookup'];
+
+export const nodeGlobals = { ...globals.node, ...globals.es2022, ...globals.jest };
+
+export const browserGlobals = {
+  ...globals.browser,
+  ...globals.es2021,
+  ...globals.jest,
+  $: true,
+  jQuery: true,
+  Invoca: true,
+};
+
+export const nodeBaseRules = {
+  'no-console': ['error', { allow: ['info', 'warn', 'error'] }],
+  camelcase: 'off',
+  'comma-dangle': ['warn', 'always-multiline'],
+  'arrow-parens': 0,
+  'no-plusplus': 0,
+  'no-underscore-dangle': ['error', { allow: ['__dirname', '__filename'] }],
+  'no-confusing-arrow': 0,
+  'import/no-unresolved': 0,
+  'import/prefer-default-export': 0,
+  'no-trailing-spaces': ['error', { skipBlankLines: true }],
+  'no-unused-expressions': ['warn', { allowTernary: true }],
+  'max-len': [2, { code: 120, ignoreStrings: true, ignoreTemplateLiterals: true }],
+  'operator-linebreak': 0,
+  'implicit-arrow-linebreaks': 0,
+  'implicit-arrow-linebreak': 0,
+  'object-curly-newline': 0,
+  'newline-per-chained-call': 0,
+  indent: 0,
+  'function-paren-newline': 0,
+  'max-params': ['warn', { max: 3 }],
+};
+
+export const browserBaseRules = {
+  'comma-dangle': ['warn', 'always-multiline'],
+  'no-param-reassign': ['warn', { props: false }],
+  'arrow-parens': 0,
+  'no-plusplus': 0,
+  'no-console': ['error', { allow: ['warn', 'error'] }],
+  'no-confusing-arrow': 0,
+  'no-underscore-dangle': ['error', { allow: underscoreDangleAllowlist }],
+  'no-trailing-spaces': ['error', { skipBlankLines: true }],
+  'no-unused-expressions': ['warn', { allowTernary: true }],
+  'max-len': [2, { code: 120, ignoreStrings: 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,
+  'max-params': ['warn', { max: 3 }],
+};

package/bin/check-peer-deps.cjs

@@ -14,7 +14,7 @@ if (!projectRoot || projectRoot === path.resolve(__dirname, '..')) {
 const ownPkg = require('../package.json');
 
 const stylelintPeers = Object.entries(ownPkg.peerDependencies || {}).filter(([name]) =>
-  name.startsWith('stylelint')
+  name.startsWith('stylelint'),
 );
 
 // Extracts the minimum required major version from a semver range like ^17.0.0 or >=17.1.1.

package/bin/gherkin-tag-coverage.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Fails when the suite as a whole is missing a required tag combination, e.g. no scenario
+ * anywhere is tagged @smoke @prod @en, which would make that CI job select zero specs and
+ * exit green.
+ *
+ * Silent on success, like gplint and eslint.
+ * Exit codes: 0 covered, 1 uncovered, 2 bad input.
+ *
+ * Usage: gherkin-tag-coverage [path]     (path defaults to cypress/e2e)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { loadCoverageConfig } from '../gherkin/load-config.js';
+import { findFeatureFiles, collectScenarios, findUncovered, formatProblems } from '../gherkin/suite-coverage.js';
+
+const target = process.argv[2] ?? path.join('cypress', 'e2e');
+
+if (!fs.existsSync(target)) {
+  console.error(`gherkin-tag-coverage: path not found: ${target}`);
+  process.exit(2);
+}
+
+let combinations;
+try {
+  ({ combinations } = await loadCoverageConfig());
+} catch (err) {
+  console.error(`gherkin-tag-coverage: ${err.message}`);
+  process.exit(2);
+}
+
+const files = findFeatureFiles(target);
+if (files.length === 0) {
+  console.error(`gherkin-tag-coverage: no .feature files found under ${target}`);
+  process.exit(1);
+}
+
+let scenarios;
+try {
+  scenarios = collectScenarios(files);
+} catch (err) {
+  console.error(`gherkin-tag-coverage: could not parse feature files. ${err.message}`);
+  process.exit(2);
+}
+
+if (scenarios.length === 0) {
+  console.error(
+    `gherkin-tag-coverage: found ${files.length} feature file(s) under ${target} but no scenarios in any of them.`,
+  );
+  process.exit(1);
+}
+
+const problems = findUncovered(scenarios, combinations);
+
+if (problems.length === 0) {
+  process.exit(0);
+}
+
+console.info(formatProblems(problems));
+process.exit(1);

package/browser.js

@@ -1,44 +1,13 @@
 import js from '@eslint/js';
-import globals from 'globals';
 import tseslint from 'typescript-eslint';
 import reactPlugin from 'eslint-plugin-react';
 import reactHooksPlugin from 'eslint-plugin-react-hooks';
 import jsxA11yPlugin from 'eslint-plugin-jsx-a11y';
+import { claudeCodePlugin } from './plugins/claude-code/index.js';
+import { hsWebTeamPlugin } from './plugins/hs-web-team/index.js';
+import { underscoreDangleAllowlist, browserBaseRules as baseRules, browserGlobals } from './base-rules.js';
 
-// Base rules adapted from the browser config
-const baseRules = {
-  'comma-dangle': ['warn', 'always-multiline'],
-  'no-param-reassign': ['warn', { props: false }],
-  'arrow-parens': 0,
-  'no-plusplus': 0,
-  'no-console': ['error', { allow: ['warn', 'error'] }],
-  'no-confusing-arrow': 0,
-  'no-underscore-dangle': [
-    'error',
-    {
-      allow: [
-        '_hsg',
-        '_hsq',
-      ],
-    },
-  ],
-  'no-trailing-spaces': ['error', { skipBlankLines: true }],
-  'no-unused-expressions': ['warn', { allowTernary: true }],
-  'max-len': [
-    2,
-    {
-      code: 120,
-      ignoreStrings: 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,
-};
+export { underscoreDangleAllowlist };
 
 // React-specific rules
 const reactRules = {
@@ -57,36 +26,22 @@ const reactRules = {
 };
 
 // Common ignore patterns
-const commonIgnores = [
-  '**/node_modules/**',
-  '**/dist/**',
-  '**/build/**',
-  '**/.next/**',
-  '**/coverage/**',
-  'eslint.config.js',
-];
+const commonIgnores = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.next/**', '**/coverage/**'];
 
 export default [
   // Global ignores
   {
     ignores: commonIgnores,
   },
-  // Base config for all JavaScript files
-  js.configs.recommended,
+  // Base recommended rules — scoped to JS/TS so they never run against
+  // non-JS languages (e.g. the markdown used for CLAUDE.md below).
+  { ...js.configs.recommended, files: ['**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}'] },
   {
     files: ['**/*.{js,mjs,cjs,jsx}'],
     languageOptions: {
       ecmaVersion: 2021,
       sourceType: 'module',
-      globals: {
-        ...globals.browser,
-        ...globals.es2021,
-        ...globals.jest,
-        // Custom browser globals from original config
-        $: true,
-        jQuery: true,
-        Invoca: true,
-      },
+      globals: browserGlobals,
       parserOptions: {
         ecmaFeatures: {
           jsx: true,
@@ -117,6 +72,7 @@ export default [
       ...reactRules,
     },
   },
+  hsWebTeamPlugin.configs.recommended,
   // TypeScript config
   ...tseslint.configs.recommended.map(config => ({
     ...config,
@@ -127,14 +83,7 @@ export default [
     languageOptions: {
       ecmaVersion: 2021,
       sourceType: 'module',
-      globals: {
-        ...globals.browser,
-        ...globals.es2021,
-        ...globals.jest,
-        $: true,
-        jQuery: true,
-        Invoca: true,
-      },
+      globals: browserGlobals,
       parserOptions: {
         ecmaFeatures: {
           jsx: true,
@@ -165,4 +114,6 @@ export default [
       ...reactRules,
     },
   },
+  // CLAUDE.md and SKILL.md context-file checks (see plugins/claude-code)
+  ...claudeCodePlugin.configs.recommended,
 ];

package/cypress.config.cjs

@@ -22,13 +22,13 @@ const envs = {
  * the directory where the hubspot.config.yml file is located.
  *
  * @param {string} currDir - the current working directory path to search from
- * @returns {string} The absolute path of the project's root directory
+ * @returns {string|null} The absolute path of the project's root directory, or null if not found
  */
 const getRootDir = currDir => {
   if (fs.existsSync(path.join(currDir, 'hubspot.config.yml'))) return currDir;
   const parentDir = path.dirname(currDir);
   if (parentDir === currDir) {
-    throw new Error('Error: Could not find the hubspot.config.yml file within the projects directories.');
+    return null;
   }
   return getRootDir(parentDir);
 };
@@ -39,19 +39,21 @@ const getRootDir = currDir => {
  */
 const getDevBaseUrl = () => {
   try {
-    global.console.log(
-      'To test a dev URL, add the `baseUrl` property to your `DEV` portal configuration in `hubspot.config.yml`',
-    );
-
     const root = getRootDir(__dirname);
+    if (!root) return null;
     const configPath = path.resolve(root, 'hubspot.config.yml');
     const config = fs.readFileSync(configPath, 'utf8');
     const { portals } = yaml.load(config);
     const devPortal = portals.find(portal => portal.name === 'DEV');
     const devBaseUrl = devPortal.baseUrl;
+    if (!devBaseUrl) {
+      global.console.log(
+        'To test a dev URL, add the `baseUrl` property to your `DEV` portal configuration in `hubspot.config.yml`',
+      );
+    }
     return devBaseUrl || null;
   } catch (error) {
-    global.console.error(error);
+    global.console.log('Could not read DEV baseUrl from hubspot.config.yml:', error.message);
     return null;
   }
 };
@@ -90,10 +92,7 @@ async function setupNodeEvents(on, config) {
   await addCucumberPreprocessorPlugin(on, config);
 
   // Use esbuild for fast TypeScript and feature file processing
-  on(
-    'file:preprocessor',
-    createBundler({ plugins: [createEsbuildPlugin(config)] }),
-  );
+  on('file:preprocessor', createBundler({ plugins: [createEsbuildPlugin(config)] }));
 
   return config;
 }

package/docs/adr/0001-lint-claude-md-with-eslint.md

@@ -0,0 +1,123 @@
+# 1. Lint CLAUDE.md with an ESLint rule
+
+- Status: Accepted
+- Date: 2026-08-19
+- Deciders: HubSpot Web Team
+
+## Context
+
+`CLAUDE.md` gives Claude Code the project context it needs to be useful in a
+repo: conventions, common commands, and gotchas. One failure mode quietly
+degrades that context: the file **grows too large**. Oversized context files
+are harder for Claude Code to use effectively and tend to accumulate stale or
+redundant guidance. We treat **100 lines** as the practical guideline.
+
+An earlier prototype enforced this as a warn-only check in a shared **git
+pre-push hook** (HubSpotMarketingWebTeam/shared-githooks PR #35, recorded in
+that repo's ADR 0001). During review the point was raised that a check on a
+file's content — line count, banned boilerplate, deprecated constructs — is
+conceptually a **linting** concern: deterministic, per-file, and something each
+project should be able to tune or disable. This package
+(`@hs-web-team/eslint-config-node`) is the shared home for exactly those rules,
+already installed as a dev dependency across the team's projects, so it is the
+natural place for the check to live.
+
+This ADR supersedes the pre-push-hook approach. The `shared-githooks` ADR 0001
+should be marked superseded and its `CLAUDE.md` check removed.
+
+## Decision
+
+Add a first-party ESLint plugin, `claude-code`, to this package and wire it
+**always-on** into both shared configs (`index.js` for Node, `browser.js` for
+browser/React). The plugin ships one rule:
+
+- **`claude-code/max-lines`** — warns when `CLAUDE.md` exceeds a maximum number
+  of lines. Default `max` is **100**; a trailing newline does not count as a
+  content line. It reports at the first line past the limit.
+
+Wiring (see `claude-code.config.js`):
+
+```js
+{
+  files: ['**/CLAUDE.md'],
+  language: 'markdown/gfm',
+  plugins: { markdown, 'claude-code': claudeCode },
+  rules: { 'claude-code/max-lines': ['warn', { max: 100 }] },
+}
+```
+
+Properties:
+
+- **Warn-only.** Severity is `warn`, so the rule never fails a lint run on its
+  own — consistent with the nudge-not-block philosophy of the original hook.
+- **Always on, fully overridable.** Every project that extends either config
+  gets the check with no setup, and can retune (`{ max: 150 }`), promote
+  (`error`), or disable (`off`) it per project by scoping an override to
+  `files: ['**/CLAUDE.md']`.
+- **Markdown language dependency.** ESLint cannot parse `.md` on its own — it
+  would feed `CLAUDE.md` to the JavaScript parser and error. We add
+  `@eslint/markdown`, which registers the `markdown/gfm` language used to parse
+  the file into an AST the rule can inspect.
+- **Scoped base rules.** `js.configs.recommended` was previously registered
+  with no `files` key, so it applied to *every* linted file. Once `CLAUDE.md`
+  became lintable, its recommended JS rules (e.g. `no-irregular-whitespace`)
+  ran against the markdown AST and crashed. We scoped that config to
+  `**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx}`. This is a no-op for existing
+  consumers — non-JS files were never lintable before — but it is a subtle
+  change worth recording.
+
+## Considered options
+
+**Enforcement mechanism — ESLint rule vs. git pre-push hook.** We chose the
+**ESLint rule**. A file-content check is a linting concern, and expressing it as
+a rule makes it per-project overridable — the property the hook lacked. The
+hook's advantages were real (it fires for every push regardless of a repo's
+lint setup, and can surface a desktop notification to GUI git clients), but they
+did not outweigh living in the tool built for opinionated, tunable file rules.
+
+**Missing-`CLAUDE.md` check — keep vs. drop.** We **dropped** it. ESLint only
+runs rules against files that exist and match, so "this repo has no `CLAUDE.md`"
+cannot be expressed as a rule. The prototype hook warned on a missing file; that
+capability does not survive the move and we accepted the loss rather than keep a
+hook alongside the rule.
+
+**Rule set — which checks to ship.** Review suggested three deterministic
+checks: max lines, banned boilerplate/placeholder text, and flagging deprecated
+"commands" in favour of skills. We shipped **`max-lines` only**. It is the
+objective, high-signal check that maps directly to the context-bloat concern. A
+`no-placeholder-text` rule was prototyped and dropped (YAGNI): matching a single
+canonical phrase is a weak proxy for quality — false positives for files that
+keep a generated opener but are well-customised, false negatives for genuinely
+empty files that reword it — with no evidence yet of a recurring problem. The
+rule structure makes adding more checks later cheap.
+
+**Delivery — always-on in the default config vs. opt-in export.** We chose
+**always-on**. Because the rule is warn-only and overridable, the cost to a
+project that does not want it is one line in `eslint.config.js`; that does not
+justify an opt-in export that most projects would have to remember to add.
+
+## Consequences
+
+- Projects extending either config will see a warning when their `CLAUDE.md`
+  exceeds 100 lines. Lint runs still pass (warnings only).
+- **The rule only fires if the project's lint command actually includes
+  `CLAUDE.md` in its file set.** `eslint .` picks it up automatically; a
+  narrowed command such as `eslint src/**/*.ts` does not. Projects that lint a
+  subset must add `CLAUDE.md` (or `**/CLAUDE.md`) to the set. This is weaker,
+  less guaranteed coverage than the always-on hook, and it depends on projects
+  being on ESLint 9 flat config.
+- There is no longer any warning for a **missing** `CLAUDE.md`.
+- Adds `@eslint/markdown` as a runtime dependency of this package (it installs
+  into consumers' dev dependency tree via the config).
+- Establishes `docs/adr/` and the ADR format for this repository.
+- This package's own `CLAUDE.md` (currently ~145 lines) now warns against the
+  rule; trimming it is tracked separately.
+
+## Future work (not yet implemented)
+
+- **More `CLAUDE.md` rules.** The plugin can grow additional checks as concrete
+  needs appear (e.g. flagging deprecated constructs). Each should stay warn-only
+  and overridable.
+- **Shared, reusable config export.** If more `CLAUDE.md` rules land, consider
+  exposing them as a named `claude-code` config object so projects can opt into or
+  out of the whole group in one place.

package/docs/adr/0002-extend-max-lines-to-skill-md.md

@@ -0,0 +1,105 @@
+# 2. Extend max-lines to SKILL.md and consolidate the claude-code plugin
+
+- Status: Accepted
+- Date: 2026-08-25
+- Deciders: HubSpot Web Team
+
+## Context
+
+[ADR 0001](0001-lint-claude-md-with-eslint.md) added the first-party
+`claude-code` ESLint plugin with a single `max-lines` rule targeting
+`CLAUDE.md`, and named two follow-ons in its *Future work* section: more
+`claude-code` rules/targets, and exposing the wiring as a reusable named config
+object. This ADR records both landing together.
+
+Claude Code skills live under `.claude/skills/`, each described by a `SKILL.md`
+instruction file. The same context-bloat failure mode that motivated the
+`CLAUDE.md` check applies to skills: an oversized `SKILL.md` is harder for
+Claude Code to use and tends to accumulate stale guidance. Skills legitimately
+carry more detail than a `CLAUDE.md`, so they warrant a **higher** guideline
+rather than the same 100-line limit.
+
+Separately, ADR 0001 wired the plugin through a root-level `claude-code.config.js`
+that exported the flat-config blocks, while the sibling `hs-web-team` plugin was
+already self-contained under `plugins/hs-web-team/` and exposed its config via
+`configs.recommended` (the pattern typescript-eslint and eslint-plugin-react
+use). Two plugins, two wiring styles, and a config file in the repo root.
+
+## Decision
+
+**1. Extend `max-lines` to `SKILL.md`.** The rule itself is file-agnostic — it
+counts content lines of whatever the flat-config glob feeds it — so no counting
+logic changed. A second flat-config block targets
+`**/.claude/skills/**/SKILL.md` with `max: 500`. The `CLAUDE.md` block keeps its
+100-line guideline. Per-type thresholds live in the config blocks, not baked
+into the rule (its internal `DEFAULT_MAX` stays 100 as a fallback).
+
+**2. Add an `advice` rule option for per-type messaging.** The rule message is
+now `{{file}} has {{count}} lines, over the {{max}}-line guideline. {{advice}}`,
+where `{{file}}` is the offending file's basename (from `context.filename`) and
+`{{advice}}` is a configurable string. Each block supplies tailored guidance:
+
+- `CLAUDE.md` — "Trim it or split sections into files Claude Code can import on
+  demand."
+- `SKILL.md` — "Trim it or move detail into reference files the skill loads on
+  demand."
+
+`advice` defaults to the original `CLAUDE.md` wording, so the change is
+backward-compatible for any consumer overriding the rule without it.
+
+**3. Consolidate the plugin to match `hs-web-team`.** The root
+`claude-code.config.js` is removed. The plugin (`plugins/claude-code/index.js`)
+now exports a named `claudeCodePlugin` carrying both `rules` and
+`configs.recommended` — an array of the two flat-config blocks. `index.js` and
+`browser.js` consume it with `...claudeCodePlugin.configs.recommended`. This is
+the reusable-config-object follow-on named in ADR 0001, and it makes both
+first-party plugins self-contained under `plugins/<name>/` with one wiring style.
+
+Both blocks remain **warn-only** and **always-on**, fully overridable per
+project by scoping to the relevant glob — unchanged from ADR 0001.
+
+## Considered options
+
+**New rule vs. reuse `max-lines`.** We **reused** the rule. Line-counting is
+identical for both file types; only the threshold and advice differ, which
+flat-config blocks and the `advice` option express cleanly. A separate rule
+would only be justified by checks of a different *kind* (e.g. validating
+`SKILL.md` frontmatter), which we did not need.
+
+**Generic message vs. per-type advice.** We chose **per-type advice** via a rule
+option. A single generic message would have been simpler but would give
+misleading guidance (the `CLAUDE.md` "import on demand" wording does not fit a
+skill). Naming the file via `context.filename` and letting each block supply its
+own advice keeps one rule while producing accurate messages for both targets.
+
+**SKILL.md glob scope.** We scoped to `**/.claude/skills/**/SKILL.md` only — the
+standard skills location — rather than also matching a bare top-level
+`skills/**/SKILL.md`. Narrower is safer; it can widen later if a need appears.
+
+**Keep root config file vs. fold into the plugin.** We **folded** it in to match
+`hs-web-team`. One wiring convention across first-party plugins is easier to
+reason about, and it removes a root-level file whose only consumers were
+`index.js`/`browser.js`.
+
+## Consequences
+
+- Projects extending either config now also get a warning when a
+  `.claude/skills/**/SKILL.md` exceeds 500 lines, in addition to the existing
+  `CLAUDE.md` 100-line check. Still warnings only.
+- As with `CLAUDE.md`, the `SKILL.md` check fires only if the project's lint
+  command includes those files in its set (`eslint .` does; a narrowed command
+  may not).
+- The `advice` option is now part of the rule's public schema.
+- `claude-code.config.js` no longer exists; anything importing
+  `claudeCodeConfig`/`claudeSkillsConfig` from it must instead import
+  `claudeCodePlugin` from `plugins/claude-code/index.js` and use
+  `configs.recommended`. Only this package's own `index.js`/`browser.js` did so.
+- No change to the counting logic, the `markdown/gfm` dependency, or the
+  warn-only/always-on/overridable properties established in ADR 0001.
+
+## Future work (not yet implemented)
+
+- **`SKILL.md` structural checks.** If needed, a distinct rule could validate
+  skill frontmatter (`name`/`description`) or required sections — a different
+  kind of check than line-counting, so a new rule rather than another
+  `max-lines` block.

package/examples/browser-usage.md

@@ -57,6 +57,26 @@ If you're migrating from `@hs-web-team/eslint-config-browser` (ESLint 8):
 3. Ensure you're using Node.js >= 22
 4. Review and adapt any custom rules in your project
 
+## Extending the underscore-dangle allowlist
+
+`no-underscore-dangle` allows a fixed set of HubSpot platform globals (`_hsg`, `_hsp`, `_hsq`, `__ip_lookup`). If your project reads an additional underscore-prefixed global, extend the shared list instead of overriding the rule entirely:
+
+```javascript
+import wtBrowserConfig, { underscoreDangleAllowlist } from '@hs-web-team/eslint-config-node/browser';
+
+export default [
+  ...wtBrowserConfig,
+  {
+    rules: {
+      'no-underscore-dangle': [
+        'error',
+        { allow: [...underscoreDangleAllowlist, 'myProjectGlobal'] },
+      ],
+    },
+  },
+];
+```
+
 ## File Patterns
 
 The configuration applies to: