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

package/examples/claude-code-usage.md

@@ -0,0 +1,73 @@
+# CLAUDE.md & SKILL.md linting
+
+The Node (`.`) and browser (`./browser`) configs include a rule that lints each
+repo's `CLAUDE.md` project-context files and the `SKILL.md` files under
+`.claude/skills/`. It is **on by default** for any project that extends either
+config — no extra setup.
+
+`CLAUDE.md` is what gives Claude Code project context (conventions, commands,
+gotchas), and each `SKILL.md` holds a skill's instructions. Oversized context
+files are harder for Claude Code to use effectively and tend to accumulate stale
+guidance, so this rule keeps them small enough to stay useful. Skills carry more
+detail than a `CLAUDE.md`, so they get a higher guideline.
+
+## What it checks
+
+| Rule | Target | Severity | Purpose |
+| --- | --- | --- | --- |
+| `claude-code/max-lines` | `**/CLAUDE.md` | `warn` | Flags a `CLAUDE.md` longer than the guideline (default **100** lines). |
+| `claude-code/max-lines` | `**/.claude/skills/**/SKILL.md` | `warn` | Flags a `SKILL.md` longer than the guideline (default **500** lines). |
+
+It is a **warning** — it never fails a lint run on its own. Bump it to `error`
+in your own config if you want CI to enforce it.
+
+## Important: your lint command must include these files
+
+ESLint only lints files you point it at. `eslint .` picks up `CLAUDE.md` and
+`SKILL.md` automatically; a narrowed command such as `eslint src/**/*.ts` will
+**not**. If you lint a subset of files, add `**/CLAUDE.md` and
+`**/.claude/skills/**/SKILL.md` to the set.
+
+## Overriding
+
+The rule is tunable per project in your `eslint.config.js`. Because it targets
+`**/CLAUDE.md`, scope overrides to that file so they don't touch other files:
+
+```js
+import wtConfig from '@hs-web-team/eslint-config-node';
+
+export default [
+  ...wtConfig,
+  {
+    files: ['**/CLAUDE.md'],
+    rules: {
+      // Raise the line limit for a large repo.
+      'claude-code/max-lines': ['warn', { max: 150 }],
+    },
+  },
+];
+```
+
+Turn it off entirely:
+
+```js
+{
+  files: ['**/CLAUDE.md'],
+  rules: { 'claude-code/max-lines': 'off' },
+}
+```
+
+## Rule options
+
+### `claude-code/max-lines`
+
+```js
+['warn', { max: 100, advice: 'Trim it or split sections into files Claude Code can import on demand.' }]
+```
+
+- `max` (integer, ≥ 1) — the maximum number of content lines. A trailing
+  newline does not count as an extra line. Defaults to **100** (the CLAUDE.md
+  block); the SKILL.md block sets it to **500**.
+- `advice` (string) — the guidance appended to the warning message, so you can
+  tailor it to the file type. The message also names the offending file (e.g.
+  `SKILL.md has 620 lines, over the 500-line guideline. …`).

package/examples/custom-rules.md

@@ -0,0 +1,98 @@
+# Custom Rules (`hs-web-team` plugin)
+
+This package bundles a small set of custom ESLint rules under the `hs-web-team` plugin. They are active automatically when you spread `wtConfig` or `wtBrowserConfig` — no extra configuration required.
+
+---
+
+## `hs-web-team/no-reduce-accumulator-copy` ❌ error
+
+**Disallows O(n²) accumulator copies inside `reduce`/`reduceRight` callbacks.**
+
+Each iteration of `reduce` creates an entirely new object or array, making the total work proportional to n². This is rarely intentional and degrades quickly as the input grows.
+
+### What triggers it
+
+```js
+// ❌ Object spread — copies every key on every iteration
+const byId = items.reduce((acc, item) => ({ ...acc, [item.id]: item }), {});
+
+// ❌ Array spread — copies every element on every iteration
+const doubled = items.reduce((acc, n) => [...acc, n * 2], []);
+
+// ❌ acc.concat() — same problem, different syntax
+const flat = items.reduce((acc, arr) => acc.concat(arr), []);
+```
+
+### What to do instead
+
+```js
+// ✅ Object.groupBy / Object.fromEntries for grouping/indexing
+const byId = Object.fromEntries(items.map(item => [item.id, item]));
+
+// ✅ for...of with in-place mutation for accumulation
+const byId = {};
+for (const item of items) {
+  byId[item.id] = item;
+}
+
+// ✅ flatMap for flat-map patterns
+const doubled = items.flatMap(n => [n * 2]);
+
+// ✅ flat() for flattening
+const flat = items.flat();
+```
+
+### When `reduce` is fine
+
+The rule only fires when the **accumulator itself** is copied. Reads from the accumulator, or spreading non-accumulator values into it, are allowed:
+
+```js
+// ✅ Spreading a non-accumulator value into the result
+const merged = items.reduce((acc, item) => ({ ...acc, ...item.overrides }), base);
+//                                                         ^^^^^^^^^^^^^^ not the accumulator — fine
+
+// ✅ Accumulator mutation with no copy
+const counts = items.reduce((acc, item) => {
+  acc[item.type] = (acc[item.type] ?? 0) + 1;
+  return acc;
+}, {});
+```
+
+---
+
+## `hs-web-team/no-non-literal-constant-case` ⚠️ warn
+
+**Disallows `CONSTANT_CASE` names whose value isn't actually static.**
+
+A `CONSTANT_CASE` name signals to readers that the value is fixed and safe to assume unchanged for the lifetime of the program. When the value is actually computed at runtime — a function call, a conditional, a reference to a mutable binding — the name is misleading and can cost real debugging time (this rule was added after a `CONSTANT_CASE`-named variable turned out to be a debug-only runtime computation, defaulting to `0` for normal visitors).
+
+### What triggers it
+
+```js
+// ❌ Conditional — depends on runtime state
+const REDIRECT_DELAY_MS = isDebugMode() ? 1000 : 0;
+
+// ❌ Function call result
+const TOKEN = generateToken();
+
+// ❌ Declared with let/var — can be reassigned regardless of its current value
+let API_HOST = 'www.api-host.com';
+```
+
+### What to do instead
+
+```js
+// ✅ Rename to camelCase if the value genuinely isn't a constant
+const redirectDelayMs = isDebugMode() ? 1000 : 0;
+
+// ✅ Keep CONSTANT_CASE only when the value is a literal (or built purely from literals)
+const API_HOST = 'www.api-host.com';
+const RETRY_LIMITS = Object.freeze({ max: 3, backoffMs: 500 });
+const SORT_METHODS = new Set(['sort', 'toSorted']);
+```
+
+### What's allowed
+
+Literals, template literals with no interpolation, unary-wrapped literals (`-1`), arrays/objects composed entirely of the above (optionally wrapped in `Object.freeze(...)`), `new Set`/`new Map`/`new RegExp` (and their `Weak` variants) built from literal arguments, `process.env.X` references, and references to other `CONSTANT_CASE`-named identifiers are all treated as static and won't be flagged.
+
+**Not covered:** this rule only checks whether the *value* is static — it does not enforce that `CONSTANT_CASE` be reserved for exported bindings (a separate naming convention with much broader rollout impact, intentionally left out of this rule for now).

package/examples/gherkin-usage.md

@@ -0,0 +1,133 @@
+# Gherkin Tag Linting Usage
+
+This package provides shared tag linting for Cypress/Cucumber feature files.
+
+Cucumber selects which tests to run by tag, so a scenario with no tags is silently skipped. A
+suite can be fully green while some of its tests never execute. These two checks turn that into
+a build failure.
+
+## Applies to
+
+Only repositories whose Cypress suite is written in Gherkin, using
+`@badeball/cypress-cucumber-preprocessor` and `.feature` files.
+
+Both checks read `.feature` files and nothing else, so:
+
+- A Cypress suite written in Mocha (`.cy.js` / `.cy.ts` with `describe`/`it`) has nothing to
+  check. There are no tags to require, because Mocha does not select tests by tag.
+- Existing consumers of `@hs-web-team/eslint-config-node` are unaffected by upgrading. Neither
+  check is wired into `wtConfig`, `wtBrowserConfig`, or any Cypress config. Nothing runs until a
+  repository adds the `lint:gherkin` script below.
+
+## What is checked
+
+**Per scenario**, every scenario must carry:
+
+- at least one environment tag: `@qa` or `@prod`. Both together is valid.
+- at least one locale tag: `@en`, `@es`, `@fr`, `@de`, `@jp`, `@br`. Any number together is valid.
+
+Any other tag is allowed and ignored, including TestRail ids like `@a72w9o`. There is no tag
+allowlist.
+
+A tag counts wherever it is declared: the `Feature` line, a `Rule:`, the `Scenario:`, or an
+`Examples:` block. Inheritance works the same way as Cucumber's own `--tags` filtering.
+
+**Per suite**, the suite must contain at least one scenario tagged `@smoke @qa @en` and at least
+one tagged `@smoke @prod @en`. The same scenario may satisfy both, for example one tagged
+`@qa @prod @en @smoke`.
+
+This second check cannot be a lint rule, because a lint rule only ever sees one file at a time
+and never the whole suite.
+
+## Installation
+
+```bash
+npm i -D @hs-web-team/eslint-config-node@latest
+```
+
+`gplint` and the Gherkin parser are bundled, so there is nothing else to install.
+
+## Usage
+
+Add one script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint:gherkin": "gplint cypress/e2e --config=node_modules/@hs-web-team/eslint-config-node/gherkin/.gplintrc && gherkin-tag-coverage"
+  }
+}
+```
+
+Then run it:
+
+```bash
+npm run lint:gherkin
+```
+
+Both checks print nothing when they pass. A failure looks like this:
+
+```
+/path/to/cypress/e2e/login.feature
+   3:3  error  The tag(s) [@qa,@prod] should be present for Scenario.                required-tags
+   3:3  error  The tag(s) [@en,@es,@fr,@de,@jp,@br] should be present for Scenario.  required-tags
+
+✖ 2 problems (2 errors, 0 warnings)
+```
+
+Use `&&` rather than `;` to join the two commands. With `;` the exit code comes from the last
+command only, so a tag violation would pass CI.
+
+## QA-only repositories
+
+If a repository has no production environment, the `@smoke @prod @en` requirement can never be
+satisfied. Opt out by adding a `gherkin-coverage.json` next to `package.json`:
+
+```json
+{ "requiredCombinations": [["@smoke", "@qa", "@en"]] }
+```
+
+Do not satisfy the requirement by tagging a scenario `@prod` instead. Tags are what CI selects
+on, so that scenario would become eligible for the production run.
+
+A bare array works too:
+
+```json
+[["@smoke", "@qa", "@en"]]
+```
+
+## Passing a different path
+
+Both commands default to `cypress/e2e`. To point elsewhere:
+
+```bash
+gplint tests/features --config=node_modules/@hs-web-team/eslint-config-node/gherkin/.gplintrc
+gherkin-tag-coverage tests/features
+```
+
+Pass a **directory**, not a glob. `gplint` rewrites patterns containing `/**`, so
+`cypress/e2e/**/*.feature` matches nothing. Directories recurse to any depth.
+
+## Notes
+
+- `gplint` exits 0 when it matches no feature files, so a wrong path looks the same as a pass.
+  Check that the reported file count is non-zero when first setting this up, using
+  `--format=json` to list the files it found.
+- Tags are case sensitive. `@EN` does not satisfy `@en`, which is correct, because Cucumber
+  would not select it either.
+- A scenario written after a `Rule:` belongs to that Rule even if it is dedented back to feature
+  level, and inherits the Rule's tags. This is Gherkin behaviour, not a linter quirk.
+- An `Examples` table row cannot be tagged individually. Tags attach to the `Examples:` block and
+  every row inherits them.
+- Whitespace and formatting rules are deliberately not included, because Prettier owns those via
+  the bundled `prettier-plugin-gherkin`.
+- `gplint` prints an `ExperimentalWarning: Importing JSON modules` line to stderr on every run.
+  It is harmless.
+
+## Exit codes
+
+| Code | Meaning                                                                                   |
+| ---- | ----------------------------------------------------------------------------------------- |
+| 0    | Passed                                                                                    |
+| 1    | A real violation, or a missing suite-wide combination                                     |
+| 2    | Bad input, for example an unparseable feature file or a malformed `gherkin-coverage.json` |

package/gherkin/.gplintrc

@@ -0,0 +1,32 @@
+{
+  // Every scenario needs one tag from each list. Inherited tags count (Feature, Rule,
+  // Examples). Other tags are ignored. ignoreUntagged must stay false or fully untagged
+  // scenarios are skipped.
+  "required-tags": ["error", {
+    "ignoreUntagged": false,
+    "global": [
+      ["@qa", "@prod"],
+      ["@en", "@es", "@fr", "@de", "@jp", "@br"]
+    ]
+  }],
+
+  "no-duplicate-tags": "error",
+  // allowSeparated:false so "@qa @en #@smoke" fails. The default true allows it.
+  "no-partially-commented-tag-lines": ["error", { "allowSeparated": false }],
+
+  "no-empty-file": "error",
+  "no-files-without-scenarios": "error",
+  "no-unnamed-features": "error",
+  "no-unnamed-scenarios": "error",
+  "no-scenario-outlines-without-examples": "error",
+  "no-empty-background": "error",
+  "no-background-only-scenario": "error",
+  "no-dupe-feature-names": "error",
+  // in-feature, not the default "anywhere", which flags the same name in unrelated features.
+  "no-dupe-scenario-names": ["error", "in-feature"],
+  "use-and": "error",
+  "name-length": ["error", { "Feature": 60, "Scenario": 120, "Step": 475 }]
+
+  // Whitespace rules (indentation, no-trailing-spaces, new-line-at-eof,
+  // no-multiple-empty-lines) left off: prettier owns those.
+}

package/gherkin/coverage-config.js

@@ -0,0 +1,10 @@
+// Tag combinations the suite as a whole must contain at least one scenario for.
+// One scenario may satisfy several entries, e.g. a scenario tagged @qa @prod @en @smoke
+// covers both of these.
+//
+// Override per repo with a `gherkin-coverage.json` file next to package.json, either as a
+// bare array of combinations or as `{ "requiredCombinations": [...] }`.
+export default [
+  ['@smoke', '@qa', '@en'],
+  ['@smoke', '@prod', '@en'],
+];

package/gherkin/load-config.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import stripJsonComments from 'strip-json-comments';
+
+import defaultCombinations from './coverage-config.js';
+
+const OVERRIDE_FILE = 'gherkin-coverage.json';
+
+export async function loadCoverageConfig(cwd = process.cwd()) {
+  const overridePath = path.join(cwd, OVERRIDE_FILE);
+  if (!fs.existsSync(overridePath)) {
+    return { combinations: defaultCombinations, overridePath: null };
+  }
+
+  const override = JSON.parse(stripJsonComments(fs.readFileSync(overridePath, 'utf8')));
+  const combinations = Array.isArray(override) ? override : override?.requiredCombinations;
+
+  if (!Array.isArray(combinations) || combinations.some(combo => !Array.isArray(combo))) {
+    throw new Error(`${overridePath} must be an array of tag arrays, or { "requiredCombinations": [[...]] }.`);
+  }
+
+  return { combinations, overridePath };
+}

package/gherkin/suite-coverage.js

@@ -0,0 +1,126 @@
+/**
+ * Checks that the suite contains at least one scenario for each required tag combination.
+ *
+ * A gplint rule cannot do this: it is handed one file at a time and never sees the suite.
+ *
+ * Tags count no matter where they come from: the Feature line, a Rule, the Scenario, or an
+ * Examples block. This works because each file is compiled into "pickles" the same way
+ * Cucumber does, and a pickle's tag list is already the merged set Cucumber matches against
+ * when you run --tags.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import * as gherkin from '@cucumber/gherkin';
+import * as messages from '@cucumber/messages';
+
+export const RULE = 'suite-tag-coverage';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
+
+export function findFeatureFiles(target) {
+  if (fs.statSync(target).isFile()) {
+    return target.endsWith('.feature') ? [target] : [];
+  }
+
+  const found = [];
+  for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+    const full = path.join(target, entry.name);
+    if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+      found.push(...findFeatureFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.feature')) {
+      found.push(full);
+    }
+  }
+  return found;
+}
+
+function parse(filePath) {
+  const parser = new gherkin.Parser(
+    new gherkin.AstBuilder(messages.IdGenerator.uuid()),
+    new gherkin.GherkinClassicTokenMatcher(),
+  );
+  const doc = parser.parse(fs.readFileSync(filePath, 'utf8'));
+  return { pickles: gherkin.compile(doc, filePath, messages.IdGenerator.uuid()), doc };
+}
+
+// A pickle knows which AST nodes it came from but not its line number, so build id -> line.
+function lineIndex(doc) {
+  const lines = new Map();
+  const visit = children => {
+    for (const child of children ?? []) {
+      if (child.rule) visit(child.rule.children);
+      if (!child.scenario) continue;
+      lines.set(child.scenario.id, child.scenario.location.line);
+      for (const examples of child.scenario.examples ?? []) {
+        for (const row of examples.tableBody ?? []) {
+          lines.set(row.id, row.location.line);
+        }
+      }
+    }
+  };
+  visit(doc.feature?.children);
+  return lines;
+}
+
+export function collectScenarios(files) {
+  const scenarios = [];
+  for (const file of files) {
+    const parsed = parse(file);
+    const lines = lineIndex(parsed.doc);
+    for (const pickle of parsed.pickles) {
+      scenarios.push({
+        file,
+        name: pickle.name,
+        line: lines.get(pickle.astNodeIds.at(-1)) ?? '?',
+        tags: new Set(pickle.tags.map(tag => tag.name)),
+      });
+    }
+  }
+  return scenarios;
+}
+
+/** Returns one problem per uncovered combination, anchored at the closest scenario. */
+export function findUncovered(scenarios, combinations) {
+  return combinations
+    .filter(combo => !scenarios.some(scenario => combo.every(tag => scenario.tags.has(tag))))
+    .map(combo => {
+      // Rank by how many tags are missing so the suggestion is the smallest possible fix.
+      const closest = scenarios
+        .map(scenario => ({ scenario, missing: combo.filter(tag => !scenario.tags.has(tag)) }))
+        .sort((a, b) => a.missing.length - b.missing.length)[0];
+
+      return {
+        file: closest.scenario.file,
+        line: closest.scenario.line,
+        column: 3,
+        message: `No scenario in the suite is tagged [${combo.join(' ')}]. Add ${closest.missing.join(' ')} here, or tag another scenario.`,
+      };
+    });
+}
+
+/** gplint's stylish format, so the lint and coverage checks read as one tool. */
+export function formatProblems(problems) {
+  const byFile = new Map();
+  for (const problem of problems) {
+    if (!byFile.has(problem.file)) byFile.set(problem.file, []);
+    byFile.get(problem.file).push(problem);
+  }
+
+  const width = Math.max(...problems.map(problem => `${problem.line}:${problem.column}`.length));
+  const lines = [];
+
+  for (const [file, fileProblems] of [...byFile.entries()].sort()) {
+    lines.push('', path.resolve(file));
+    for (const problem of fileProblems.sort((a, b) => a.line - b.line)) {
+      const at = `${problem.line}:${problem.column}`.padStart(width);
+      lines.push(`  ${at}  error  ${problem.message}  ${RULE}`);
+    }
+  }
+
+  const count = problems.length;
+  const plural = count === 1 ? '' : 's';
+  lines.push('', `✖ ${count} problem${plural} (${count} error${plural}, 0 warnings)`, '');
+
+  return lines.join('\n');
+}

package/index.js

@@ -1,73 +1,28 @@
 import js from '@eslint/js';
-import globals from 'globals';
 import tseslint from 'typescript-eslint';
-
-// Base rules for all JavaScript files
-const baseRules = {
-  '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,
-};
+import { claudeCodePlugin } from './plugins/claude-code/index.js';
+import { hsWebTeamPlugin } from './plugins/hs-web-team/index.js';
+import { nodeBaseRules as baseRules, nodeGlobals } from './base-rules.js';
 
 // Common ignore patterns
-const commonIgnores = [
-  '**/node_modules/**',
-  '**/.serverless/**',
-  '**/.webpack/**',
-  '**/dist/**',
-  'eslint.config.js',
-];
+const commonIgnores = ['**/node_modules/**', '**/.serverless/**', '**/.webpack/**', '**/dist/**'];
 
 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}'],
     languageOptions: {
-      globals: {...globals.node, ...globals.es2022, ...globals.jest},
+      globals: nodeGlobals,
     },
     rules: baseRules,
   },
+  hsWebTeamPlugin.configs.recommended,
   // TypeScript config - restrict to TypeScript files only
   ...tseslint.configs.recommended.map(config => ({
     ...config,
@@ -76,8 +31,10 @@ export default [
   {
     files: ['**/*.{ts,mts,cts,tsx}'],
     languageOptions: {
-      globals: {...globals.node, ...globals.es2022, ...globals.jest},
+      globals: nodeGlobals,
     },
     rules: baseRules,
   },
+  // CLAUDE.md and SKILL.md context-file checks (see plugins/claude-code)
+  ...claudeCodePlugin.configs.recommended,
 ];