commit-sheriff 1.5.0 → 1.6.1

package/README.md

@@ -56,11 +56,10 @@ Different repos tend to drift into different commit-message and branch-naming co
 npm install --save-dev commit-sheriff husky
 ```
 
-`lint-staged`, `eslint`, and `prettier` are optional — install them too if you want the pre-commit hook to lint/format staged files:
-
-```bash
-npm install --save-dev lint-staged eslint prettier
-```
+`npx commit-sheriff init` installs `lint-staged`, `eslint`, and `prettier` for you automatically
+(via `npm install --save-dev`) if they're missing, so the pre-commit lint/format step is actually
+functional right away — you don't need to install them yourself first. This only happens as part
+of `init` (see below), not from installing `commit-sheriff` itself.
 
 ## Usage
 
@@ -77,10 +76,19 @@ Run this once per repo, from the repo root (where `package.json` lives). This wo
 3. Creates a default `.commitsheriffrc.json` file at the repo root **only if one doesn't already exist** (and only if there's no legacy `package.json` → `commitGuard` block either — see [Configuration](#configuration-commitsheriffrcjson)) — re-running `init` never overwrites your customized config.
 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. 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) and **overwrites** `.prettierrc.js` with the latest template. Otherwise it's skipped and you can add it manually later.
+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.
 
 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).
 
+**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
+entirely**, so a broken/incomplete setup looked identical to a working one until someone noticed
+bad code slipping through. The hook itself is now hardened too: if `package.json` has a
+`lint-staged` config block but the package isn't actually installed (e.g. `node_modules` got
+wiped, or someone added the config by hand), the commit now **fails loudly** with instructions,
+instead of passing silently.
+
 ## Commit message format
 
 ```
@@ -227,7 +235,7 @@ Allowed `type` words in **commit messages**, following [Conventional Commits](ht
 In addition to the branch name check, `pre-commit` conditionally runs (skipped when the project doesn't have the relevant tool):
 
 - `npm run type-check` — if a `type-check` script exists in `package.json`
-- `npx lint-staged` — if `lint-staged` is listed as a dependency
+- `npx lint-staged` — if `package.json` has a `lint-staged` config block. If the block exists but the `lint-staged` package itself isn't actually installed, the commit **fails with instructions** rather than silently skipping the check (this used to silently no-op — see [What `init` does](#what-init-does)).
 - `npx vitest related --run --passWithNoTests <staged .ts/.tsx files>` — if `vitest` is listed as a dependency and staged `.ts`/`.tsx` files exist (bounded to 60s via `timeout`/`gtimeout` when available)
 
 Any failure here aborts the commit.
@@ -239,13 +247,19 @@ The default config added by `init` (only if you don't already have one):
 ```json
 {
   "lint-staged": {
-    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
+    "*.{js,jsx,ts,tsx}": ["eslint --fix --max-warnings=0", "prettier --write"],
     "*.{json,md,css,scss,html}": ["prettier --write"]
   }
 }
 ```
 
-Adjust freely — `commit-sheriff` doesn't overwrite it once present.
+`--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.
+
+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.
 
 ## Advanced: ESLint module-boundary template (TypeScript/React)
 
@@ -292,15 +306,24 @@ just fill in `modules` in `.commitsheriffrc.json` and it picks it up automatical
 This template assumes a `src/app/<module>/...` folder layout with `<module>.public.ts` barrel
 files; adjust the paths inside the generated config if your structure differs.
 
-It doesn't install any dependencies for you — install what your project needs, e.g.:
+It installs whatever it needs automatically (via `npm install --save-dev`, same as `init` does for
+`lint-staged`/`eslint`/`prettier`), skipping anything already present:
 
 ```bash
-npm install --save-dev typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin \
-  @eslint/js @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
+npm install --save-dev eslint@^9 typescript @typescript-eslint/parser \
+  @typescript-eslint/eslint-plugin @eslint/js @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.
+
+If the install fails (offline, registry issue, etc.), it prints this exact command so you can run
+it yourself.
+
 #### Why flat config?
 
 ESLint 9+ looks for `eslint.config.*` first and, if one is found, **ignores `.eslintrc.js`

package/bin/commit-sheriff.js

@@ -38,7 +38,10 @@ const DEFAULT_COMMIT_GUARD = {
 };
 
 const DEFAULT_LINT_STAGED = {
-  "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
+  // --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"],
   "*.{json,md,css,scss,html}": ["prettier --write"],
 };
 
@@ -91,6 +94,46 @@ function ensureConfigFile() {
   console.log(`✔ ${CONFIG_FILE_NAME} yazıldı`);
 }
 
+// Installs whatever in `packages` isn't already a listed dependency/devDependency, so the hooks
+// this tool wires up are actually functional right after `init`/`add-eslint-react` — not just
+// documented as a copy-paste command the user has to remember to run separately. Falls back to
+// printing the manual command if the install itself fails (offline, registry auth issue, etc.),
+// so the user isn't left silently thinking it worked.
+// Strips a trailing "@version" from an install spec to get the plain package name for looking it
+// up in package.json — careful with scoped packages ("@eslint/js" has no version, but
+// "@vitest/eslint-plugin@^1" does; only the *last* "@" is ever the version separator).
+function packageNameOf(spec) {
+  const atIndex = spec.lastIndexOf("@");
+  return atIndex > 0 ? spec.slice(0, atIndex) : spec;
+}
+
+function ensureDevDeps(packages) {
+  const { pkg } = readPackageJson();
+  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ı");
+    return;
+  }
+  console.log(`→ Quraşdırılır: ${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
+    // resolves plain "eslint" to 10.x), which makes npm's default strict peer resolution abort
+    // the whole install with ERESOLVE even though the versions work fine together in practice.
+    execSync(`npm install --save-dev --legacy-peer-deps ${missing.join(" ")}`, {
+      cwd,
+      stdio: "inherit",
+    });
+    console.log("✔ devDependencies quraşdırıldı");
+  } 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" +
+        `    npm install --save-dev ${missing.join(" ")}\n`,
+    );
+  }
+}
+
 function mergeConfig() {
   const { pkgPath, pkg } = readPackageJson();
   let changed = false;
@@ -114,6 +157,18 @@ function mergeConfig() {
   if (changed) {
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
   }
+
+  // Without this, the pre-commit hook's `lint-staged` step silently no-ops when the package
+  // itself isn't installed (it only checks whether *some* config/listing exists), so lint/format
+  // checks would never actually run on commit even though everything *looks* set up. `eslint`
+  // and `prettier` are included too since the default lint-staged config above already assumes
+  // both are runnable — otherwise the very first commit would fail on "command not found" instead
+  // of an actual lint/format problem. `eslint` is pinned to ^9 (not left to resolve to whatever
+  // "latest" is) because the plugin ecosystem this tool depends on (eslint-plugin-react, etc.)
+  // regularly lags behind ESLint's newest major for months — installing an unpinned "latest" has
+  // broken real installs (e.g. eslint-plugin-react crashing under ESLint 10's changed rule-context
+  // API) within days of a new major landing on npm.
+  ensureDevDeps(["lint-staged", "eslint@^9", "prettier"]);
 }
 
 function isReactTypescriptProject() {
@@ -145,6 +200,9 @@ 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@^9",
   "typescript",
   "@typescript-eslint/parser",
   "@typescript-eslint/eslint-plugin",
@@ -218,10 +276,18 @@ function addEslintReact() {
       "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\n" +
-      "Lazımi devDependencies (özünüz quraşdırın, layihənizin real versiyalarına uyğun):\n" +
-      `  npm install --save-dev ${ESLINT_REACT_DEV_DEPS.join(" ")}\n`,
+      "backup götürün.\n",
   );
+  ensureDevDeps(ESLINT_REACT_DEV_DEPS);
+  if (flatConfigAlreadyExists) {
+    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",
+    );
+  }
 }
 
 if (command === "init") {

package/package.json

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

package/templates/eslint.config.module-boundaries.mjs

@@ -129,6 +129,12 @@ const moduleBoundaryConfig = [
       "**/*.d.ts",
       "**/*.config.js",
       "**/*.config.mjs",
+      // Root-level CommonJS config dotfiles (this template's own .prettierrc.js among them) aren't
+      // part of the TS project's `include`, so `parserOptions.project: true` below fails to parse
+      // them with a "TSConfig does not include this file" error unless they're excluded here.
+      ".eslintrc.js",
+      ".prettierrc.js",
+      ".prettierrc.cjs",
     ],
   },
   // FlatCompat translates the same legacy-style `extends`/`env`/`parserOptions`/`plugins`/`rules`

package/templates/pre-commit

@@ -66,13 +66,28 @@ if [ "$HAS_TYPE_CHECK" = "1" ]; then
     npm run type-check || exit 1
 fi
 
-HAS_LINT_STAGED=$(node -e "
-  const p = require('./package.json');
-  const deps = Object.assign({}, p.dependencies, p.devDependencies);
-  process.stdout.write(deps['lint-staged'] ? '1' : '0');
+# Two separate signals on purpose: whether the project *wants* lint-staged (has a config block
+# in package.json — commit-sheriff's own `init` writes one by default) vs. whether the package is
+# *actually installed* right now. If a config exists but the package isn't resolvable, that's not
+# "this project doesn't use lint-staged" — it's a broken setup (e.g. someone ran `npm prune`,
+# skipped `npm install`, or deleted node_modules) and used to fail silently, letting broken commits
+# through with zero lint/format enforcement. Now it fails loudly instead.
+HAS_LINT_CONFIG=$(node -e "
+  process.stdout.write(require('./package.json')['lint-staged'] ? '1' : '0');
 " 2>/dev/null)
-if [ "$HAS_LINT_STAGED" = "1" ]; then
-    npx lint-staged || exit 1
+if [ "$HAS_LINT_CONFIG" = "1" ]; then
+    if node -e "require.resolve('lint-staged')" 2>/dev/null; then
+        npx lint-staged || 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 ""
+        echo "  Düzəltmək üçün:"
+        echo "    npm install --save-dev lint-staged"
+        echo ""
+        exit 1
+    fi
 fi
 
 # ── Related tests (only if vitest is installed) ─────────────────────────────