commit-sheriff 1.4.0 → 1.5.0

package/README.md

@@ -77,9 +77,9 @@ 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. 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.
 
-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).
 
 ## Commit message format
 
@@ -257,37 +257,64 @@ 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.:
 
 ```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
+  @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
 ```
 
+#### 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

@@ -148,6 +148,8 @@ const ESLINT_REACT_DEV_DEPS = [
   "typescript",
   "@typescript-eslint/parser",
   "@typescript-eslint/eslint-plugin",
+  "@eslint/js",
+  "@eslint/eslintrc",
   "eslint-plugin-sonarjs",
   "eslint-plugin-import",
   "eslint-plugin-prettier",
@@ -156,29 +158,67 @@ 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" +
+      "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\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`,
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commit-sheriff",
-  "version": "1.4.0",
+  "version": "1.5.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,272 @@
+/**
+ * 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",
+    ],
+  },
+  // 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: {