commit-sheriff 1.7.1 → 1.7.3

package/README.md

@@ -251,19 +251,19 @@ The default config added by `init` (only if you don't already have one):
 ```json
 {
   "lint-staged": {
-    "*.{js,jsx,ts,tsx}": ["eslint --fix --max-warnings=0", "prettier --write"],
+    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
     "*.{json,md,css,scss,html}": ["prettier --write"]
   }
 }
 ```
 
-`--max-warnings=0` is there on purpose: ESLint only fails (non-zero exit) on errors by default, so
-a rule set to `"warn"` (e.g. many "recommended" configs' default severity for unused imports) would
-otherwise print in the terminal but still let the commit through looking clean.
+Warnings are printed but never block the commit — only actual errors (ESLint's non-zero exit) do.
+That's the default ESLint behavior (`--fix` alone exits 0 on warning-only results), so a rule set to
+`"warn"` (e.g. an unused import under some "recommended" configs) shows up in the terminal as a
+heads-up but doesn't stop you from committing.
 
-Adjust freely — `commit-sheriff` doesn't overwrite it once present. That also means this default
-only lands on **new** setups; if your project already has a `lint-staged` block from before this
-change, add `--max-warnings=0` to it by hand to get the same behavior.
+Adjust freely — `commit-sheriff` doesn't overwrite it once present. If you want warnings to block
+the commit too, add `--max-warnings=0` to the `eslint --fix` command by hand.
 
 ## Advanced: ESLint module-boundary template (TypeScript/React)
 
@@ -276,40 +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. 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.
+`.eslintrc.js` format — see [why](#why-flat-config) below.
+
+It writes/refreshes three files every run, **always overwriting** whatever was there before (same
+as the `commit-msg`/`pre-commit` hooks) — no manual merge step, ever. If you've hand-edited any of
+these, back them up under a different name first:
+
+| File                               | What it is                                                                                                                                                                                                                                                 |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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. Just imports the file above — or, if `next` is detected in your dependencies, also folds in Next.js's own ESLint rules so you don't lose Next-specific linting (`eslint-config-next` is auto-installed if missing). |
+| `.prettierrc.js`                   | Matching Prettier config for the same ruleset.                                                                                                                                                                                                             |
+
+If your project already had its own `eslint.config.mjs` (e.g. Next.js's own
+`create-next-app`-generated one), it gets replaced by the one above, not merged with it.
+
+Next.js support is version-aware: `eslint-config-next` changed its internal shape between major
+versions (a native flat-config array from v16 on, the older eslintrc-style object before that), and
+the generated `eslint.config.mjs` detects which one is actually installed and uses the matching
+pattern automatically — you don't need to think about this at all, it's handled for you.
 
 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
@@ -348,16 +333,14 @@ it yourself.
 #### Why flat config?
 
 ESLint 9+ looks for `eslint.config.*` first and, if one is found, **ignores `.eslintrc.js`
-entirely** — there's no fallback. Since frameworks like Next.js already scaffold their own
-`eslint.config.mjs`, a legacy-only `.eslintrc.js` template would sit right next to it and never
-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+, whether or not the project already had its own flat config.
+entirely** — there's no fallback. A legacy-only `.eslintrc.js` template sitting next to a
+framework-generated `eslint.config.mjs` (Next.js scaffolds one by default) would simply never run —
+this used to be a real bug here, where an unused import went completely unflagged because the
+module-boundary rules were silently dead. Flat config avoids that trap entirely.
 
 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
-at all, but the CLI no longer writes it by default.
+inside the package for reference/manual use on pure ESLint 8 projects with no flat config support,
+but the CLI no longer writes it by default.
 
 ## Examples
 

package/bin/commit-sheriff.js

@@ -38,10 +38,9 @@ const DEFAULT_COMMIT_GUARD = {
 };
 
 const DEFAULT_LINT_STAGED = {
-  // --max-warnings=0: without this, ESLint only fails (non-zero exit) on errors — a warning
-  // (e.g. many "recommended" configs' default severity for unused imports) prints in the
-  // terminal but still lets `eslint --fix` exit 0, so the commit goes through looking clean.
-  "*.{js,jsx,ts,tsx}": ["eslint --fix --max-warnings=0", "prettier --write"],
+  // No --max-warnings=0 here on purpose: warnings should be visible (ESLint prints them to the
+  // terminal either way) but must NOT block the commit — only actual errors (non-zero exit) do.
+  "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
   "*.{json,md,css,scss,html}": ["prettier --write"],
 };
 
@@ -50,7 +49,7 @@ const CONFIG_FILE_NAME = ".commitsheriffrc.json";
 function readPackageJson() {
   const pkgPath = path.join(cwd, "package.json");
   if (!fs.existsSync(pkgPath)) {
-    console.error("  package.json tapılmadı. Əvvəlcə `npm init` işlədin.");
+    console.error("  package.json not found. Run `npm init` first.");
     process.exit(1);
   }
   return { pkgPath, pkg: JSON.parse(fs.readFileSync(pkgPath, "utf8")) };
@@ -60,7 +59,7 @@ function ensureHusky() {
   const huskyDir = path.join(cwd, ".husky");
   const shimPath = path.join(huskyDir, "_", "husky.sh");
   if (!fs.existsSync(shimPath)) {
-    console.log("→ husky quraşdırılır (npx husky init)...");
+    console.log("→ setting up husky (npx husky init)...");
     execSync("npx husky init", { cwd, stdio: "inherit" });
   }
 }
@@ -71,7 +70,7 @@ function copyHook(name) {
   fs.mkdirSync(path.dirname(dest), { recursive: true });
   fs.copyFileSync(src, dest);
   fs.chmodSync(dest, 0o755);
-  console.log(`✔ .husky/${name} yazıldı`);
+  console.log(`✔ .husky/${name} written`);
 }
 
 function ensureConfigFile() {
@@ -79,19 +78,19 @@ function ensureConfigFile() {
   const { pkg } = readPackageJson();
 
   if (fs.existsSync(configPath)) {
-    console.log(`• ${CONFIG_FILE_NAME} artıq var, toxunulmadı`);
+    console.log(`• ${CONFIG_FILE_NAME} already exists, left untouched`);
     return;
   }
 
   if (pkg.commitGuard) {
     console.log(
-      `• package.json-da köhnə tərzli 'commitGuard' bloku tapıldı — ${CONFIG_FILE_NAME} yaradılmadı, köhnə konfiqurasiya işləməyə davam edir.`,
+      `• Found a legacy-style 'commitGuard' block in package.json — ${CONFIG_FILE_NAME} not created, the old configuration keeps working.`,
     );
     return;
   }
 
   fs.writeFileSync(configPath, JSON.stringify(DEFAULT_COMMIT_GUARD, null, 2) + "\n");
-  console.log(`✔ ${CONFIG_FILE_NAME} yazıldı`);
+  console.log(`✔ ${CONFIG_FILE_NAME} written`);
 }
 
 // Installs whatever in `packages` isn't already a listed dependency/devDependency, so the hooks
@@ -112,10 +111,10 @@ function ensureDevDeps(packages) {
   const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
   const missing = packages.filter((spec) => !deps[packageNameOf(spec)]);
   if (!missing.length) {
-    console.log("• Lazımi devDependencies artıq quraşdırılıb, toxunulmadı");
+    console.log("• Required devDependencies are already installed, nothing to do");
     return;
   }
-  console.log(`→ Quraşdırılır: ${missing.join(" ")}`);
+  console.log(`→ Installing: ${missing.join(" ")}`);
   try {
     // --legacy-peer-deps: some ESLint plugins lag behind the newest ESLint major in their
     // declared peerDependencies (e.g. eslint-plugin-import still capping at ^9 while npm already
@@ -125,10 +124,10 @@ function ensureDevDeps(packages) {
       cwd,
       stdio: "inherit",
     });
-    console.log("✔ devDependencies quraşdırıldı");
+    console.log("✔ devDependencies installed");
   } catch {
     console.log(
-      "\n  Avtomatik quraşdırma alınmadı (şəbəkə/npm xətası ola bilər) — özünüz işlədin:\n" +
+      "\n  Automatic install failed (could be a network/npm error) — run it yourself:\n" +
         `    npm install --save-dev ${missing.join(" ")}\n`,
     );
   }
@@ -143,9 +142,9 @@ function mergeConfig() {
   if (!pkg["lint-staged"]) {
     pkg["lint-staged"] = DEFAULT_LINT_STAGED;
     changed = true;
-    console.log("✔ package.json → lint-staged konfiqurasiyası əlavə olundu");
+    console.log("✔ package.json → lint-staged configuration added");
   } else {
-    console.log("• package.json-da lint-staged artıq var, toxunulmadı");
+    console.log("• package.json already has a lint-staged block, left untouched");
   }
 
   if (!pkg.scripts) pkg.scripts = {};
@@ -185,18 +184,16 @@ function init() {
 
   if (isReactTypescriptProject()) {
     console.log(
-      "\n• react + typescript aşkarlandı → TS/React modul-sərhəd ESLint şablonu da əlavə olunur:",
+      "\n• react + typescript detected → also adding the TS/React module-boundary ESLint template:",
     );
     addEslintReact();
   } else {
     console.log(
-      "\n(Layihə TS/React kimi aşkarlanmadı — istəsəniz `npx commit-sheriff add-eslint-react` ilə əlavə edə bilərsiniz.)",
+      "\n(Project not detected as TS/React — you can add it manually with `npx commit-sheriff add-eslint-react` if needed.)",
     );
   }
 
-  console.log(
-    `\nHazırdır. ${CONFIG_FILE_NAME} faylında 'project' və lazım olsa 'modules' dəyərlərini tənzimləyin.\n`,
-  );
+  console.log(`\nDone. Adjust 'project' and, if needed, 'modules' in ${CONFIG_FILE_NAME}.\n`);
 }
 
 const ESLINT_REACT_DEV_DEPS = [
@@ -241,7 +238,7 @@ function copyTemplateOverwrite(templateName, destName) {
   const dest = path.join(cwd, destName);
   const existed = fs.existsSync(dest);
   fs.copyFileSync(src, dest);
-  console.log(existed ? `✔ ${destName} yeniləndi (üzərinə yazıldı)` : `✔ ${destName} yazıldı`);
+  console.log(existed ? `✔ ${destName} updated (overwritten)` : `✔ ${destName} written`);
   return dest;
 }
 
@@ -249,7 +246,7 @@ 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ı`);
+  console.log(existed ? `✔ ${destName} updated (overwritten)` : `✔ ${destName} written`);
   return dest;
 }
 
@@ -349,25 +346,26 @@ function addEslintReact() {
   copyTemplateOverwrite("prettier.module-boundaries.js", ".prettierrc.js");
 
   console.log(
-    "\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.mjs, " +
+    "\nThis template is for TypeScript/React + module-boundary rules.\n" +
+      `The module list is read automatically from ${CONFIG_FILE_NAME}'s "modules" (falls back\n` +
+      "to an illustrative default if empty — read the comment inside the template file).\n\n" +
+      "Note: 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" +
+      ", and .prettierrc.js are overwritten\n" +
+      "with the latest template every run (same as the commit-msg/pre-commit hooks) — no manual\n" +
+      "merge step needed, but if you want to keep your own customizations, back them up under a\n" +
+      "different name first.\n" +
       (hasNext
-        ? "\nNext.js aşkarlandı → next/core-web-vitals və next/typescript qaydaları da\n" +
-          "avtomatik daxil edildi.\n"
+        ? "\nNext.js detected → next/core-web-vitals and next/typescript rules are folded in\n" +
+          "automatically too.\n"
         : ""),
   );
 
   if (fs.existsSync(path.join(cwd, ".eslintrc.js"))) {
     console.log(
-      "\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",
+      "\nNote: your project still has a legacy .eslintrc.js — delete it. With a flat config\n" +
+        "present, ESLint never reads it, and it can itself start producing lint errors as a\n" +
+        "plain .js file.\n",
     );
   }
 }
@@ -377,9 +375,9 @@ if (command === "init") {
 } else if (command === "add-eslint-react") {
   addEslintReact();
 } else {
-  console.log("İstifadə: npx commit-sheriff init");
+  console.log("Usage: npx commit-sheriff init");
   console.log(
-    "        : npx commit-sheriff add-eslint-react   (opsional, TS/React modul-sərhəd ESLint şablonu)",
+    "     : npx commit-sheriff add-eslint-react   (optional, TS/React module-boundary ESLint template)",
   );
   process.exit(command ? 1 : 0);
 }

package/package.json

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

package/templates/pre-commit

@@ -77,13 +77,17 @@ HAS_LINT_CONFIG=$(node -e "
 " 2>/dev/null)
 if [ "$HAS_LINT_CONFIG" = "1" ]; then
     if node -e "require.resolve('lint-staged')" 2>/dev/null; then
-        npx lint-staged || exit 1
+        # --verbose: lint-staged only prints a task's output when it *fails* by default, so a
+        # warning-only ESLint result (exit 0, commit still allowed through) would otherwise show
+        # nothing at all. --verbose keeps it printing on success too, so warnings stay visible as
+        # a heads-up without blocking the commit.
+        npx lint-staged --verbose || exit 1
     else
         echo ""
-        echo "  package.json-da 'lint-staged' konfiqurasiyası var, amma paketin özü"
-        echo "  node_modules-də tapılmadı — lint/format yoxlanışı keçirilə bilmədi."
+        echo "  package.json has a 'lint-staged' configuration, but the package itself"
+        echo "  was not found in node_modules — the lint/format check could not run."
         echo ""
-        echo "  Düzəltmək üçün:"
+        echo "  To fix:"
         echo "    npm install --save-dev lint-staged"
         echo ""
         exit 1