commit-sheriff 1.6.1 → 1.7.0

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,25 @@ 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/core-web-vitals`/`next/typescript` automatically (via the same `FlatCompat` pattern Next's
+  own generated config uses) 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.
+
+`.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
@@ -310,16 +310,22 @@ It installs whatever it needs automatically (via `npm install --save-dev`, same
 `lint-staged`/`eslint`/`prettier`), skipping anything already present:
 
 ```bash
-npm install --save-dev eslint@^9 typescript @typescript-eslint/parser \
-  @typescript-eslint/eslint-plugin @eslint/js @eslint/eslintrc eslint-plugin-sonarjs \
+npm install --save-dev eslint@^9 typescript@^5 @typescript-eslint/parser \
+  @typescript-eslint/eslint-plugin @eslint/js@^9 @eslint/eslintrc eslint-plugin-sonarjs \
   eslint-plugin-import eslint-plugin-prettier eslint-config-prettier eslint-plugin-react \
   eslint-plugin-react-hooks eslint-plugin-jsx-a11y eslint-plugin-testing-library \
   @vitest/eslint-plugin eslint-plugin-jest prettier
 ```
 
-`eslint` is pinned to `^9` on purpose rather than left to resolve to whatever `latest` is — plugins
-like `eslint-plugin-react` have historically taken a while to support each new ESLint major, so an
-unpinned install can grab a version the rest of the toolchain doesn't work with yet.
+`eslint`, `@eslint/js`, and `typescript` are pinned on purpose rather than left to resolve to
+whatever `latest` is — the plugin ecosystem here regularly lags behind both. Two concrete
+conflicts this has already caused: `@eslint/js`'s own `latest` declares a hard peer on
+`eslint@^10`, so leaving it unpinned next to `eslint@^9` is an instant `ERESOLVE`; and
+`@typescript-eslint/eslint-plugin` currently only supports `typescript` up to `<6.1.0`, so an
+unpinned `typescript` install (which resolves to its own `latest`, e.g. `7.x`) crashes plugin
+loading with "typescript-eslint does not support TS 7.0". Pinning `eslint`/`@eslint/js` together
+to `^9` and `typescript` to `^5` keeps the whole toolchain on versions that are actually
+compatible with each other today.
 
 If the install fails (offline, registry issue, etc.), it prints this exact command so you can run
 it yourself.
@@ -332,7 +338,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

@@ -202,11 +202,19 @@ function init() {
 const ESLINT_REACT_DEV_DEPS = [
   // Pinned (not left to resolve to "latest") — see the comment on the eslint@^9 install in
   // mergeConfig() for why: the plugin ecosystem here regularly lags behind ESLint's newest major.
+  // @eslint/js in particular is versioned in lockstep with ESLint core and its `latest` (10.x)
+  // declares a hard peerDependency on eslint@^10 — installing it unpinned alongside eslint@^9
+  // produces an immediate ERESOLVE conflict, which is exactly what this pin prevents.
   "eslint@^9",
-  "typescript",
+  // Same lag problem, different package: @typescript-eslint/eslint-plugin@8.65.0 declares
+  // `typescript: ">=4.8.4 <6.1.0"` as a peer, but unpinned "typescript" resolves to npm's
+  // "latest" (7.x once TypeScript ships a 7.0) — that's outside the supported range and
+  // crashes plugin loading with "typescript-eslint does not support TS 7.0". Pinning to the
+  // latest 5.x line keeps us inside the range the plugin actually supports today.
+  "typescript@^5",
   "@typescript-eslint/parser",
   "@typescript-eslint/eslint-plugin",
-  "@eslint/js",
+  "@eslint/js@^9",
   "@eslint/eslintrc",
   "eslint-plugin-sonarjs",
   "eslint-plugin-import",
@@ -221,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);
@@ -242,50 +245,71 @@ 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`,
-    );
-  } 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",
+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;
+}
+
+function buildEslintEntryConfig(hasNext) {
+  if (!hasNext) {
+    return (
+      `import moduleBoundaries from "./${RULES_FILE}";\n\n` +
+      `export default [...moduleBoundaries];\n`
     );
   }
+  // Next.js scaffolds its own eslint.config.mjs with `next/core-web-vitals`/`next/typescript` —
+  // those are folded in here (via the same FlatCompat pattern Next's own generated config uses)
+  // so overwriting the file doesn't silently drop Next-specific linting.
+  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);
+  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) {
+
+  const extraDeps = hasNext && !deps["eslint-config-next"] ? ["eslint-config-next"] : [];
+  ensureDevDeps(ESLINT_REACT_DEV_DEPS.concat(extraDeps));
+
+  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.1",
+  "version": "1.7.0",
   "description": "Shared husky commit-msg / pre-commit hooks enforcing ticket-based commit messages and branch naming",
   "main": "index.js",
   "bin": {