commit-sheriff 1.4.0 → 1.6.0

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,9 +76,18 @@ 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 **overwrites** `.eslintrc.js` and `.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 `.eslintrc.js` or `.prettierrc.js`, back them up first — those two get overwritten on every re-run.
+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.
@@ -257,37 +265,73 @@ other through a public barrel file, never through deep/internal paths:
 npx commit-sheriff add-eslint-react
 ```
 
-This copies two templates into your repo root, **always overwriting** whatever is already
-there at those exact filenames (same behavior as the `commit-msg`/`pre-commit` hooks — re-running
-it refreshes both files to the latest version of the template):
-
-- `.eslintrc.js` — legacy-format ESLint config (TypeScript + React + a11y + import + sonarjs +
-  testing-library/jest/vitest rules) with a module-boundary `no-restricted-imports` rule.
-- `.prettierrc.js` — matching Prettier config.
-
-If you've customized either file by hand, back it up under a different name before re-running
-`add-eslint-react` (or `init` on a react+typescript project, which calls it automatically) —
-your edits will be replaced.
+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.
 
 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
 for the `[MODULE]` tag), lowercased. For older installs still using `package.json`'s
 `commitGuard.modules`, that's used as a fallback. If neither is set, a small illustrative default
-(`auth`, `billing`, `reports`, `settings`) is used — open `.eslintrc.js` and replace it, or just
-fill in `modules` in `.commitsheriffrc.json` and it picks it up automatically.
+(`auth`, `billing`, `reports`, `settings`) is used — open the generated config and replace it, or
+just fill in `modules` in `.commitsheriffrc.json` and it picks it up automatically.
 
 This template assumes a `src/app/<module>/...` folder layout with `<module>.public.ts` barrel
-files; adjust the paths inside `.eslintrc.js` if your structure differs.
+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-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 eslint-plugin-vitest 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`
+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+, in both the standalone and merge-into-existing-config cases.
+
+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.
+
 ## Examples
 
 **Minimal project (no modules)** — `.commitsheriffrc.json`:

package/bin/commit-sheriff.js

@@ -91,6 +91,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 +154,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,9 +197,14 @@ 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",
+  "@eslint/js",
+  "@eslint/eslintrc",
   "eslint-plugin-sonarjs",
   "eslint-plugin-import",
   "eslint-plugin-prettier",
@@ -156,32 +213,78 @@ const ESLINT_REACT_DEV_DEPS = [
   "eslint-plugin-react-hooks",
   "eslint-plugin-jsx-a11y",
   "eslint-plugin-testing-library",
-  "eslint-plugin-vitest",
+  "@vitest/eslint-plugin",
   "eslint-plugin-jest",
   "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)));
+}
+
 function copyTemplateOverwrite(templateName, destName) {
   const src = path.join(__dirname, "..", "templates", templateName);
   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ı`);
+  return dest;
 }
 
 function addEslintReact() {
-  copyTemplateOverwrite("eslintrc.module-boundaries.js", ".eslintrc.js");
+  // 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",
+    );
+  }
   copyTemplateOverwrite("prettier.module-boundaries.js", ".prettierrc.js");
   console.log(
-    "\nBu şablon TypeScript/React + modul-sərhəd (module-boundary) qaydaları üçündür.\n" +
+    "Bu ş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 — .eslintrc.js içindəki şərhi oxuyun).\n\n" +
-      "Diqqət: .eslintrc.js və .prettierrc.js hər dəfə şablonun ən son versiyası ilə\n" +
-      "üzərinə yazılır (commit-msg/pre-commit hook-ları kimi) — özünüzə uyğun etdiyiniz\n" +
-      "dəyişiklikləri qorumaq istəsəniz, əvvəlcə fərqli adla 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`,
+      "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",
   );
+  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.4.0",
+  "version": "1.6.0",
   "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

@@ -0,0 +1,278 @@
+/**
+ * Advanced ESLint config (flat config format) — enforces module boundaries in a modular
+ * TypeScript/React app. This is the flat-config (ESLint 9+, `eslint.config.*`) counterpart of
+ * the rules previously shipped only as a legacy `.eslintrc.js`.
+ *
+ * Why this exists: ESLint 9+ looks for `eslint.config.*` (flat config) first and, if one is
+ * found, ignores `.eslintrc.js` entirely — it does NOT fall back to it. Frameworks like Next.js
+ * (`create-next-app`) already scaffold their own `eslint.config.mjs`, so a legacy `.eslintrc.js`
+ * sitting next to it is silently dead: none of its rules (including the module-boundary ones)
+ * ever run. This file avoids that trap by speaking flat config natively.
+ *
+ * Assumptions this template makes (edit as needed):
+ *   - Feature modules live under `src/app/<module>/` (e.g. `src/app/auth/`).
+ *   - Each module exposes its public surface via a `<module>.public.ts` barrel file; anything
+ *     else under `src/app/<module>/modules/**` or `src/app/<module>/shared/**` is internal and
+ *     must not be imported directly from another module.
+ *   - Shared/base code lives under `src/app/_shared/**` and `src/packages/**` and must never
+ *     import from a feature module (that would invert the dependency direction).
+ *   - `src/packages/routing/AppRoutes.tsx` and `src/packages/routing/config/modules.registry.ts`
+ *     are the one place allowed to import every module directly (that's the whole point of a
+ *     router/registry), so the boundary rule is turned off just for those two files.
+ *
+ * Module list: instead of hardcoding module names, this reads `modules` from the repo's
+ * `.commitsheriffrc.json` (the same list used by the commit-sheriff commit-msg/branch-name
+ * hooks — see README), so the two conventions (module tags in commits/branches, and module
+ * boundaries in imports) stay in sync automatically. For older installs that still keep their
+ * config under `package.json`'s `commitGuard` block, that location is used as a fallback. If
+ * neither is found, a small illustrative default is used instead — replace it with your real
+ * module names.
+ *
+ * How to use this file:
+ *   - If your project has NO `eslint.config.*` yet, `commit-sheriff add-eslint-react` writes
+ *     this content directly as your `eslint.config.mjs` — nothing else to do.
+ *   - If your project ALREADY has an `eslint.config.*` (e.g. Next.js's own), this content is
+ *     instead written to `eslint.config.commit-sheriff.mjs` alongside it, and you import + spread
+ *     it into your existing config so nothing gets silently overwritten:
+ *
+ *       import moduleBoundaries from "./eslint.config.commit-sheriff.mjs";
+ *       export default [
+ *         ...compat.extends("next/core-web-vitals", "next/typescript"),
+ *         ...moduleBoundaries,
+ *       ];
+ */
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+import js from "@eslint/js";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// `recommendedConfig`/`allConfig` are required so FlatCompat can resolve the bare
+// "eslint:recommended" / "eslint:all" strings used in `extends` below — without them it throws
+// "Missing parameter 'recommendedConfig' in FlatCompat constructor" as soon as `.config()` runs.
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+});
+
+function loadAppModules() {
+  try {
+    const rcPath = path.join(__dirname, ".commitsheriffrc.json");
+    const rc = JSON.parse(fs.readFileSync(rcPath, "utf8"));
+    if (Array.isArray(rc.modules) && rc.modules.length) {
+      return rc.modules.map((m) => String(m).toLowerCase());
+    }
+  } catch {
+    // fall through to the legacy package.json lookup below
+  }
+  try {
+    const pkgPath = path.join(__dirname, "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    const modules = pkg.commitGuard && pkg.commitGuard.modules;
+    if (Array.isArray(modules) && modules.length) {
+      return modules.map((m) => String(m).toLowerCase());
+    }
+  } catch {
+    // fall through to the illustrative default below
+  }
+  return ["auth", "billing", "reports", "settings"]; // example only — replace with your modules
+}
+
+const APP_MODULES = loadAppModules();
+const MODULE_INTERNALS = ["modules", "shared"];
+
+const restrictImports = (group, message) => ({
+  "no-restricted-imports": ["error", { patterns: [{ group, message }] }],
+});
+
+const moduleBoundaryConfigs = [
+  // A module reaches another module's internals only through `<module>.public.ts`, so the
+  // surface between modules stays explicit. `routing/` stays open on purpose: route enums are
+  // dependency-free leaves, while the barrel pulls in services that instantiate on import.
+  ...APP_MODULES.map((appModule) => ({
+    files: [`src/app/${appModule}/**`],
+    rules: restrictImports(
+      APP_MODULES.filter((other) => other !== appModule).flatMap((other) =>
+        MODULE_INTERNALS.map((internal) => `~/app/${other}/${internal}/**`),
+      ),
+      "Cross-module import: use the other module's '<module>.public.ts' barrel instead of a deep path.",
+    ),
+  })),
+  {
+    files: ["src/app/_shared/**", "src/packages/**"],
+    rules: restrictImports(
+      APP_MODULES.map((appModule) => `~/app/${appModule}/**`),
+      "Base layers must not depend on a feature module: move the shared piece down into _shared or packages instead.",
+    ),
+  },
+  {
+    files: [
+      "src/packages/routing/AppRoutes.tsx",
+      "src/packages/routing/config/modules.registry.ts",
+    ],
+    rules: { "no-restricted-imports": "off" },
+  },
+];
+
+const moduleBoundaryConfig = [
+  {
+    ignores: [
+      "coverage/**",
+      "dist/**",
+      "build/**",
+      "node_modules/**",
+      "**/*.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`
+  // block ESLint's own docs recommend for migrating a single rich config to flat format — this
+  // keeps every rule identical to the previous .eslintrc.js version, just in flat shape.
+  ...compat.config({
+    parser: "@typescript-eslint/parser",
+    parserOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      ecmaFeatures: { jsx: true },
+      project: true,
+    },
+    env: { browser: true, es2021: true, node: true },
+    settings: {
+      react: { version: "detect" },
+      linkComponents: [
+        { name: "RouterLink", linkAttribute: ["href", "to"] },
+        { name: "Link", linkAttribute: ["href", "to"] },
+      ],
+      jest: { version: "29.0" },
+    },
+    extends: [
+      "eslint:recommended",
+      "plugin:@typescript-eslint/recommended",
+      "plugin:sonarjs/recommended-legacy",
+      "plugin:import/recommended",
+      "plugin:import/typescript",
+      "plugin:prettier/recommended",
+      "plugin:react/recommended",
+      "plugin:react-hooks/recommended",
+      "plugin:jsx-a11y/recommended",
+      "plugin:testing-library/react",
+      "plugin:@vitest/legacy-recommended",
+      "plugin:jest/recommended",
+    ],
+    plugins: [
+      "@typescript-eslint",
+      "sonarjs",
+      "import",
+      "prettier",
+      "react",
+      "react-hooks",
+      "jsx-a11y",
+      "testing-library",
+      "@vitest",
+      "jest",
+    ],
+    rules: {
+      "prettier/prettier": ["error", { endOfLine: "auto" }],
+      /** React-specific rules */
+      "react/hook-use-state": ["warn", { allowDestructuredState: true }],
+      "react/react-in-jsx-scope": ["off"],
+      "react/no-array-index-key": ["error"],
+      "react/display-name": ["off"],
+      "react/prop-types": ["off"],
+      /** Accessibility rules */
+      "jsx-a11y/anchor-is-valid": [
+        "error",
+        {
+          components: ["Link", "RouterLink"],
+          specialLink: ["to"],
+          aspects: ["noHref", "invalidHref", "preferButton"],
+        },
+      ],
+      /** Best practices and coding style */
+      "no-console": process.env.NODE_ENV === "production" ? "error" : "warn",
+      "no-debugger": process.env.NODE_ENV === "production" ? "error" : "warn",
+      "prefer-const": ["error"],
+      "no-use-before-define": ["error", { functions: false, classes: true, variables: true }],
+      "no-nested-ternary": ["error"],
+      /** SonarJS rules */
+      "sonarjs/cognitive-complexity": ["error"],
+      "sonarjs/no-inverted-boolean-check": ["off"],
+      "sonarjs/no-duplicate-string": ["off"],
+      /** Import rules */
+      "import/no-anonymous-default-export": "off",
+      "import/no-cycle": ["off"],
+      "import/namespace": ["off"],
+      "import/no-named-as-default": ["off"],
+      "import/no-unresolved": ["off", { ignore: ["^src/"] }],
+      /** TypeScript-specific rules */
+      "@typescript-eslint/explicit-module-boundary-types": ["off"],
+      "@typescript-eslint/no-explicit-any": ["error"],
+      "@typescript-eslint/no-unsafe-return": ["warn"],
+      "@typescript-eslint/no-unsafe-call": ["warn"],
+      "@typescript-eslint/no-unsafe-member-access": ["warn"],
+      "@typescript-eslint/no-unsafe-assignment": ["warn"],
+      "@typescript-eslint/prefer-optional-chain": ["error"],
+      "@typescript-eslint/prefer-nullish-coalescing": ["warn"],
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^_",
+        },
+      ],
+      "@typescript-eslint/no-restricted-types": [
+        "error",
+        {
+          types: {
+            Array: {
+              message: "Use yourType[] instead. So for Array<string> you need to use string[]",
+            },
+          },
+        },
+      ],
+      "@typescript-eslint/consistent-type-definitions": ["warn", "interface"],
+      "@typescript-eslint/naming-convention": [
+        "error",
+        {
+          selector: "variable",
+          types: ["boolean"],
+          format: ["PascalCase"],
+          prefix: ["is", "should", "has", "can", "did", "will", "are"],
+        },
+      ],
+      /** File size constraints */
+      "max-lines": ["warn", { max: 250, skipComments: true, skipBlankLines: true }],
+    },
+  }),
+  {
+    files: ["*.js", "**/*.styles.ts"],
+    rules: {
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-var-requires": "off",
+    },
+  },
+  {
+    files: ["**/*.styles.ts"],
+    rules: {
+      "@typescript-eslint/no-unsafe-return": "off",
+    },
+  },
+  ...moduleBoundaryConfigs,
+];
+
+export default moduleBoundaryConfig;

package/templates/eslintrc.module-boundaries.js

@@ -222,7 +222,7 @@ module.exports = {
         caughtErrorsIgnorePattern: "^_",
       },
     ],
-    "@typescript-eslint/ban-types": [
+    "@typescript-eslint/no-restricted-types": [
       "error",
       {
         types: {

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) ─────────────────────────────