commit-sheriff 1.6.2 → 1.7.1

package/README.md

@@ -5,11 +5,15 @@ Shared [Husky](https://typicode.github.io/husky/) git hooks for any project —
 ## Quick start
 
 ```bash
-npm i commit-sheriff
+npm install --save-dev commit-sheriff husky
 npx commit-sheriff init
-npx commit-sheriff add-eslint-react   # optional — TypeScript/React + module-boundary ESLint config
+npx commit-sheriff add-eslint-react   # optional — only needed if init didn't auto-detect react+typescript
 ```
 
+This is the full flow end to end. The `Install`, `Usage`, and `What init does` sections below repeat
+these same commands with more context/explanation — you don't need to run anything extra from
+there, they're not additional steps.
+
 ## Table of contents
 
 - [Quick start](#quick-start)
@@ -77,9 +81,9 @@ Run this once per repo, from the repo root (where `package.json` lives). This wo
 4. Adds a default `lint-staged` block to `package.json` **only if one doesn't already exist**.
 5. Adds a `"prepare": "husky"` npm script if missing, so hooks are (re)installed automatically after `npm install`.
 6. Installs `lint-staged`, `eslint`, and `prettier` as devDependencies (via `npm install --save-dev`) if any of them are missing, so the pre-commit lint/format step actually runs instead of silently no-oping.
-7. If `react` and `typescript` are both present in your `dependencies`/`devDependencies`, also runs [`add-eslint-react`](#advanced-eslint-module-boundary-template-typescriptreact) automatically, which writes the ESLint flat-config module-boundary template (as `eslint.config.mjs` if you have none yet, or as a separate `eslint.config.commit-sheriff.mjs` if you already have one), **overwrites** `.prettierrc.js` with the latest template, and installs the extra plugins it needs. Otherwise it's skipped and you can add it manually later.
+7. If `react` and `typescript` are both present in your `dependencies`/`devDependencies`, also runs [`add-eslint-react`](#advanced-eslint-module-boundary-template-typescriptreact) automatically, which **overwrites** `eslint.config.mjs` and `.prettierrc.js` with the latest templates (folding in `next/core-web-vitals`/`next/typescript` automatically if `next` is detected) and installs the extra plugins it needs — no manual merge step. Otherwise it's skipped and you can add it manually later.
 
-Re-running `npx commit-sheriff init` later (e.g. after updating the package) is safe for your project-specific settings: it refreshes the hook scripts and (on react+typescript projects) the ESLint/Prettier templates to the latest version, but leaves your `.commitsheriffrc.json` / `lint-staged` config alone. If you've hand-edited `.prettierrc.js`, or `eslint.config.mjs` in the no-existing-config case, back them up first — those get overwritten on every re-run (the side-file case, `eslint.config.commit-sheriff.mjs`, is also overwritten each time, but your own `eslint.config.mjs` is never touched there).
+Re-running `npx commit-sheriff init` later (e.g. after updating the package) is safe for your project-specific settings: it refreshes the hook scripts and (on react+typescript projects) the ESLint/Prettier templates to the latest version, but leaves your `.commitsheriffrc.json` / `lint-staged` config alone. `eslint.config.mjs`, `eslint.config.commit-sheriff.mjs`, and `.prettierrc.js` are **always overwritten** on every re-run — back them up under a different name first if you've hand-edited them.
 
 **Why the auto-install matters**: the pre-commit hook only runs `lint-staged` if it can actually
 find the package — if it's missing, older versions of this hook **silently skipped linting
@@ -272,29 +276,40 @@ npx commit-sheriff add-eslint-react
 ```
 
 This ships as a **flat config** (`eslint.config.*`, ESLint 9+ format), not the legacy
-`.eslintrc.js` format — see [why](#why-flat-config) below. Where it lands depends on what your
-project already has:
-
-- **No `eslint.config.*` yet** → written directly as `eslint.config.mjs` (your main config).
-- **You already have one** (e.g. Next.js's own `create-next-app`-generated `eslint.config.mjs`)
-  → left untouched; the module-boundary rules go into a separate
-  `eslint.config.commit-sheriff.mjs` instead, printed with a snippet to import + spread it into
-  your existing config:
-
-  ```js
-  import moduleBoundaries from "./eslint.config.commit-sheriff.mjs";
-  export default [
-    ...compat.extends("next/core-web-vitals", "next/typescript"),
-    ...moduleBoundaries,
-  ];
-  ```
-
-Either way, `.prettierrc.js` is also written/refreshed, **always overwriting** whatever is
-already there at that filename (same behavior as the `commit-msg`/`pre-commit` hooks — re-running
-`add-eslint-react` refreshes it to the latest version of the template). If you've customized it
-by hand, back it up under a different name first — your edits will be replaced. The same applies
-to `eslint.config.mjs` when it's the one written directly (the no-existing-config case above); the
-side-file case never touches your own config.
+`.eslintrc.js` format — see [why](#why-flat-config) below. It always writes two files, no manual
+merge step required, ever:
+
+- `eslint.config.commit-sheriff.mjs` — the actual ruleset (module-boundary rules + all the
+  recommended plugins: TypeScript, React, hooks, a11y, sonarjs, import, testing-library, vitest,
+  jest, prettier).
+- `eslint.config.mjs` — the entry point ESLint actually reads, generated fresh every run to import
+  the file above. **If you already had an `eslint.config.mjs` (e.g. Next.js's own
+  `create-next-app`-generated one), it is fully overwritten** — not merged, not left alone. If
+  `next` is detected in your `dependencies`, the generated entry point folds in Next's own ESLint
+  rules automatically so you don't lose Next-specific linting; `eslint-config-next` is
+  auto-installed too if it's missing. Any other hand-written customizations in your previous
+  `eslint.config.mjs` are not preserved — back it up under a different name first if you need them.
+
+  `eslint-config-next` changed shape between major versions, so the generated entry point checks
+  the actually-installed version and picks the matching pattern automatically:
+  - **v16+** (current): ships a native flat-config array
+    (`import nextCoreWebVitals from "eslint-config-next/core-web-vitals"`, spread directly). Mixing
+    this with our own module-boundary plugins (which resolve the same plugin _names_ — `react`,
+    `jsx-a11y`, `import`, etc. — through a separate loader) would otherwise throw `Cannot redefine
+plugin ...`; the generated config strips those redundant re-registrations automatically so both
+    rule sets apply cleanly.
+  - **v15 and earlier**: still ships the legacy eslintrc-style object, so the generated config uses
+    `FlatCompat.extends("next/core-web-vitals", "next/typescript")` instead — the same bridge
+    `create-next-app@15` itself generates.
+
+  (An earlier version of this tool hardcoded the v15-style pattern unconditionally, which crashed
+  with `TypeError: Converting circular structure to JSON` on projects using `eslint-config-next@16+`
+  — fixed by detecting the installed version instead of assuming one.)
+
+`.prettierrc.js` is written/refreshed the same way — **always overwritten** with the latest
+template (same behavior as the `commit-msg`/`pre-commit` hooks). This trade-off is intentional:
+zero manual steps for the common case, at the cost of not preserving bespoke prior ESLint/Prettier
+setups.
 
 The module list for the boundary rule isn't hardcoded — it's read straight from the `modules`
 array in your root `.commitsheriffrc.json` (the same list the commit-msg/branch-name hooks use
@@ -338,7 +353,7 @@ entirely** — there's no fallback. Since frameworks like Next.js already scaffo
 actually run (this was a real bug: an unused `useState` import went completely unflagged because
 the module-boundary config was silently dead). The flat config here uses `FlatCompat` (the same
 official migration helper Next.js's own generated config uses internally) so the exact same rule
-set works natively under ESLint 9+, in both the standalone and merge-into-existing-config cases.
+set works natively under ESLint 9+, whether or not the project already had its own flat config.
 
 A legacy `.eslintrc.js` version of this template (`eslintrc.module-boundaries.js`) still ships
 inside the package for reference/manual use on pure ESLint 8 projects with no flat config support

package/bin/commit-sheriff.js

@@ -229,17 +229,12 @@ const ESLINT_REACT_DEV_DEPS = [
   "prettier",
 ];
 
-const FLAT_CONFIG_CANDIDATES = [
-  "eslint.config.js",
-  "eslint.config.mjs",
-  "eslint.config.cjs",
-  "eslint.config.ts",
-];
-const FLAT_CONFIG_SIDE_FILE = "eslint.config.commit-sheriff.mjs";
-
-function hasFlatEslintConfig() {
-  return FLAT_CONFIG_CANDIDATES.some((name) => fs.existsSync(path.join(cwd, name)));
-}
+// The module-boundary + all-recommended-plugins ruleset lives in this file, copied verbatim from
+// the template every run. `eslint.config.mjs` itself (the file ESLint actually reads) is then
+// generated fresh below to import it — no manual merge step for the user, ever. This intentionally
+// means a fully hand-written `eslint.config.mjs` gets replaced: simplicity/zero-manual-steps was
+// chosen over preserving bespoke prior setups, matching how `.prettierrc.js` already worked.
+const RULES_FILE = "eslint.config.commit-sheriff.mjs";
 
 function copyTemplateOverwrite(templateName, destName) {
   const src = path.join(__dirname, "..", "templates", templateName);
@@ -250,50 +245,129 @@ function copyTemplateOverwrite(templateName, destName) {
   return dest;
 }
 
-function addEslintReact() {
-  // ESLint 9+ prioritizes flat config (`eslint.config.*`) and completely ignores a legacy
-  // `.eslintrc.js` when one is present — no fallback. Frameworks like Next.js already scaffold
-  // their own `eslint.config.mjs`, so if we wrote only `.eslintrc.js` here it would silently
-  // never run for the majority of modern projects. We therefore ship the flat-config template
-  // as the primary artifact, and decide where it lands based on what the project already has.
-  const flatConfigAlreadyExists = hasFlatEslintConfig();
-
-  if (flatConfigAlreadyExists) {
-    copyTemplateOverwrite("eslint.config.module-boundaries.mjs", FLAT_CONFIG_SIDE_FILE);
-    console.log(
-      `\n• Layihədə artıq öz eslint.config.* faylınız var — ona toxunulmadı.\n` +
-        `  Modul-sərhəd qaydaları ayrıca ${FLAT_CONFIG_SIDE_FILE} faylına yazıldı.\n` +
-        `  Özünüzün eslint.config.* faylınıza əlavə edin, məsələn:\n\n` +
-        `    import moduleBoundaries from "./${FLAT_CONFIG_SIDE_FILE}";\n` +
-        `    export default [\n` +
-        `      ...compat.extends("next/core-web-vitals", "next/typescript"),\n` +
-        `      ...moduleBoundaries,\n` +
-        `    ];\n`,
+function writeFileOverwrite(destName, content) {
+  const dest = path.join(cwd, destName);
+  const existed = fs.existsSync(dest);
+  fs.writeFileSync(dest, content);
+  console.log(existed ? `✔ ${destName} yeniləndi (üzərinə yazıldı)` : `✔ ${destName} yazıldı`);
+  return dest;
+}
+
+// eslint-config-next changed shape across majors: up through v15 it ships an eslintrc-style
+// object (`module.exports = { extends: [...] }`) meant to be pulled in via FlatCompat's legacy
+// `compat.extends("next/core-web-vitals", "next/typescript")` bridge (exactly what
+// `create-next-app` itself generates for v15 projects). From v16 on it ships a native flat-config
+// array as the default export of `eslint-config-next/core-web-vitals` / `/typescript` instead —
+// running the *old* FlatCompat-string pattern against a v16 install crashes with
+// "TypeError: Converting circular structure to JSON" deep inside `@eslint/eslintrc`'s config
+// validator (confirmed by reproducing it in a scratch project — the crash reproduces with only
+// Next's own extends, no module-boundary rules involved at all). `create-next-app@latest` itself
+// already generates the new native-import form for v16, so we mirror that here rather than the
+// older FlatCompat form once eslint-config-next resolves to 16+.
+function installedVersion(pkgName) {
+  try {
+    return require(path.join(cwd, "node_modules", pkgName, "package.json")).version;
+  } catch {
+    return null;
+  }
+}
+
+function buildEslintEntryConfig(hasNext) {
+  if (!hasNext) {
+    return (
+      `import moduleBoundaries from "./${RULES_FILE}";\n\n` +
+      `export default [...moduleBoundaries];\n`
     );
-  } else {
-    copyTemplateOverwrite("eslint.config.module-boundaries.mjs", "eslint.config.mjs");
-    console.log(
-      "\n• Layihədə eslint.config.* yox idi — eslint.config.mjs olaraq birbaşa yazıldı.\n",
+  }
+
+  const version = installedVersion("eslint-config-next");
+  const major = version ? parseInt(version.split(".")[0], 10) : null;
+  // Default to the modern (16+) form when the version can't be determined (e.g. install failed
+  // offline) — that's what any newly-scaffolded Next project will have going forward.
+  const useNativeFlatExport = major === null || major >= 16;
+
+  if (useNativeFlatExport) {
+    // eslint-config-next's native flat array already registers plugins like "react",
+    // "react-hooks", "import", "jsx-a11y" and "@typescript-eslint". Our own module-boundary
+    // template is built through @eslint/eslintrc's FlatCompat, which independently resolves
+    // those same plugin *names* into separate object instances — even though they load the same
+    // underlying package, ESLint's flat config throws "Cannot redefine plugin ..." when a plugin
+    // name is registered twice with two different object references (confirmed by reproducing it
+    // in a scratch Next 16 project). Only one registration per plugin name is actually needed, so
+    // any config entry from our own template that re-declares a plugin Next.js already registered
+    // has that redundant "plugins" key stripped below — its "rules" keep working against the
+    // plugin instance Next.js already loaded.
+    return (
+      `import nextCoreWebVitals from "eslint-config-next/core-web-vitals";\n` +
+      `import nextTypescript from "eslint-config-next/typescript";\n` +
+      `import moduleBoundaries from "./${RULES_FILE}";\n\n` +
+      `const nextConfigs = [...nextCoreWebVitals, ...nextTypescript];\n` +
+      `const pluginsNextAlreadyRegisters = new Set(\n` +
+      `  nextConfigs.flatMap((entry) => (entry.plugins ? Object.keys(entry.plugins) : [])),\n` +
+      `);\n` +
+      `const dedupedModuleBoundaries = moduleBoundaries.map((entry) => {\n` +
+      `  if (!entry.plugins) return entry;\n` +
+      `  const ownPlugins = Object.fromEntries(\n` +
+      `    Object.entries(entry.plugins).filter(([name]) => !pluginsNextAlreadyRegisters.has(name)),\n` +
+      `  );\n` +
+      `  const { plugins, ...rest } = entry;\n` +
+      `  return Object.keys(ownPlugins).length ? { ...rest, plugins: ownPlugins } : rest;\n` +
+      `});\n\n` +
+      `export default [...nextConfigs, ...dedupedModuleBoundaries];\n`
     );
   }
+
+  return (
+    `import { fileURLToPath } from "node:url";\n` +
+    `import path from "node:path";\n` +
+    `import { FlatCompat } from "@eslint/eslintrc";\n` +
+    `import moduleBoundaries from "./${RULES_FILE}";\n\n` +
+    `const compat = new FlatCompat({\n` +
+    `  baseDirectory: path.dirname(fileURLToPath(import.meta.url)),\n` +
+    `});\n\n` +
+    `export default [\n` +
+    `  ...compat.extends("next/core-web-vitals", "next/typescript"),\n` +
+    `  ...moduleBoundaries,\n` +
+    `];\n`
+  );
+}
+
+function addEslintReact() {
+  const { pkg } = readPackageJson();
+  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+  const hasNext = Boolean(deps.next);
+
+  copyTemplateOverwrite("eslint.config.module-boundaries.mjs", RULES_FILE);
+
+  // eslint-config-next must actually be installed (and its version readable) *before* generating
+  // the entry config below, so the version check above sees real, resolved data instead of "not
+  // installed yet".
+  const extraDeps = hasNext && !deps["eslint-config-next"] ? ["eslint-config-next"] : [];
+  ensureDevDeps(ESLINT_REACT_DEV_DEPS.concat(extraDeps));
+
+  writeFileOverwrite("eslint.config.mjs", buildEslintEntryConfig(hasNext));
   copyTemplateOverwrite("prettier.module-boundaries.js", ".prettierrc.js");
+
   console.log(
-    "Bu şablon TypeScript/React + modul-sərhəd (module-boundary) qaydaları üçündür.\n" +
+    "\nBu şablon TypeScript/React + modul-sərhəd (module-boundary) qaydaları üçündür.\n" +
       `Modul siyahısı ${CONFIG_FILE_NAME}.modules-dən avtomatik oxunur (boşdursa nümunə\n` +
       "siyahı istifadə olunur — şablon faylı içindəki şərhi oxuyun).\n\n" +
-      "Diqqət: eslint.config.* (və ya yuxarıdakı side-file) və .prettierrc.js hər dəfə\n" +
-      "şablonun ən son versiyası ilə üzərinə yazılır (commit-msg/pre-commit hook-ları kimi)\n" +
-      "— özünüzə uyğun etdiyiniz dəyişiklikləri qorumaq istəsəniz, əvvəlcə fərqli adla\n" +
-      "backup götürün.\n",
+      "Diqqət: eslint.config.mjs, " +
+      RULES_FILE +
+      " və .prettierrc.js hər dəfə\n" +
+      "şablonun ən son versiyası ilə üzərinə yazılır (commit-msg/pre-commit hook-ları kimi) —\n" +
+      "manual dəyişiklik lazım deyil, amma özünüzə uyğun etdiyiniz dəyişiklikləri qorumaq\n" +
+      "istəsəniz, əvvəlcə fərqli adla backup götürün.\n" +
+      (hasNext
+        ? "\nNext.js aşkarlandı → next/core-web-vitals və next/typescript qaydaları da\n" +
+          "avtomatik daxil edildi.\n"
+        : ""),
   );
-  ensureDevDeps(ESLINT_REACT_DEV_DEPS);
-  if (flatConfigAlreadyExists) {
+
+  if (fs.existsSync(path.join(cwd, ".eslintrc.js"))) {
     console.log(
-      `\nUnutmayın: ${FLAT_CONFIG_SIDE_FILE} avtomatik import olunmur — onu öz\n` +
-        "eslint.config.* faylınıza əlavə etməsəniz, bu qaydalar heç vaxt işə düşməyəcək\n" +
-        "(yuxarıdakı nümunəyə baxın). Həmçinin, əgər layihənizdə hələ də köhnə .eslintrc.js\n" +
-        "varsa, onu silin — flat config varkən ESLint onu oxumur, üstəlik özü də indi\n" +
-        "adi .js fayl kimi lint xətaları törədə bilər.\n",
+      "\nDiqqət: layihənizdə hələ də köhnə .eslintrc.js var — silin. Flat config varkən\n" +
+        "ESLint onu oxumur, üstəlik özü də indi adi .js fayl kimi lint xətaları törədə bilər.\n",
     );
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commit-sheriff",
-  "version": "1.6.2",
+  "version": "1.7.1",
   "description": "Shared husky commit-msg / pre-commit hooks enforcing ticket-based commit messages and branch naming",
   "main": "index.js",
   "bin": {