@yasainet/eslint 0.1.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@yasainet/eslint",
+  "version": "0.1.0",
+  "description": "Shared ESLint configuration for Next.js projects with feature-based architecture",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "eslint",
+    "eslintconfig",
+    "nextjs",
+    "typescript"
+  ],
+  "author": "yasainet",
+  "license": "MIT",
+  "dependencies": {
+    "@stylistic/eslint-plugin": "^5.9.0",
+    "eslint-plugin-check-file": "^3.3.1",
+    "eslint-plugin-react-you-might-not-need-an-effect": "^0.5.6",
+    "eslint-plugin-simple-import-sort": "^12.1.1"
+  },
+  "peerDependencies": {
+    "eslint": "^9",
+    "eslint-config-next": "^15 || ^16"
+  }
+}

package/src/base.mjs

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Base ESLint configurations including Next.js presets and shared rules.
+ */
+
+import { globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+import {
+  reactYouMightNotNeedAnEffect,
+  simpleImportSortPlugin,
+  stylistic,
+} from "./plugins.mjs";
+
+/**
+ * Next.js base configurations (core-web-vitals + typescript).
+ * @type {import("eslint").Linter.Config[]}
+ */
+export const baseConfigs = [...nextVitals, ...nextTs];
+
+/**
+ * Global ignore patterns for build outputs and generated files.
+ * @type {import("eslint").Linter.Config}
+ */
+export const ignoresConfig = globalIgnores([
+  ".backup/**", // NOTE: Not a default.
+  ".next/**",
+  "out/**",
+  "build/**",
+  "next-env.d.ts",
+]);
+
+/**
+ * Shared rules applied to all files.
+ * Includes stylistic rules, import sorting, and TypeScript best practices.
+ * @type {import("eslint").Linter.Config}
+ */
+export const sharedRulesConfig = {
+  name: "shared-rules",
+  plugins: {
+    "@stylistic": stylistic,
+    "react-you-might-not-need-an-effect": reactYouMightNotNeedAnEffect,
+    "simple-import-sort": simpleImportSortPlugin,
+  },
+  rules: {
+    ...reactYouMightNotNeedAnEffect.configs.recommended.rules,
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        argsIgnorePattern: "^_",
+        varsIgnorePattern: "^_",
+        caughtErrorsIgnorePattern: "^_",
+      },
+    ],
+    "@typescript-eslint/consistent-type-imports": [
+      "error",
+      { prefer: "type-imports" },
+    ],
+    "@typescript-eslint/no-explicit-any": "warn",
+    "no-console": "warn",
+    "no-irregular-whitespace": [
+      "warn",
+      {
+        skipStrings: false,
+        skipComments: false,
+        skipRegExps: false,
+        skipTemplates: false,
+      },
+    ],
+    "simple-import-sort/imports": "warn",
+    "simple-import-sort/exports": "warn",
+    "@stylistic/quotes": ["warn", "double", { avoidEscape: true }],
+  },
+};

package/src/cardinality.mjs

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Cardinality constraints for action-domain relationships.
+ *
+ * Each action file can only import its matching domain:
+ * - server.action.ts → server.domain.ts only
+ * - client.action.ts → client.domain.ts only
+ * - admin.action.ts → admin.domain.ts only
+ *
+ * This prevents mixing server-side and client-side logic.
+ */
+
+/**
+ * Cardinality constraint configurations.
+ * @type {import("eslint").Linter.Config[]}
+ */
+export const cardinalityConfigs = [
+  {
+    name: "cardinality/server-action",
+    files: ["**/actions/server.action.ts"],
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["**/domains/client.domain*", "**/domains/admin.domain*"],
+              message:
+                "server.action can only import server.domain (cardinality violation)",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    name: "cardinality/client-action",
+    files: ["**/actions/client.action.ts"],
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["**/domains/server.domain*", "**/domains/admin.domain*"],
+              message:
+                "client.action can only import client.domain (cardinality violation)",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    name: "cardinality/admin-action",
+    files: ["**/actions/admin.action.ts"],
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["**/domains/server.domain*", "**/domains/client.domain*"],
+              message:
+                "admin.action can only import admin.domain (cardinality violation)",
+            },
+          ],
+        },
+      ],
+    },
+  },
+];

package/src/constants.mjs

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview Shared constants and helpers for ESLint configuration.
+ */
+
+import fs from "fs";
+import path from "path";
+
+/** Project root directory (resolved from the consuming project's CWD) */
+const PROJECT_ROOT = process.cwd();
+
+/**
+ * Root directories containing feature modules.
+ * @type {string[]}
+ */
+export const FEATURE_ROOTS = [
+  "src/features",
+  "scripts/features",
+  "supabase/functions/features",
+];
+
+/**
+ * Files and directories to exclude from prefix mapping.
+ * @type {string[]}
+ */
+const EXCLUDE_LIST = ["proxy.ts", "types"];
+
+/**
+ * Generate PREFIX_LIB_MAPPING by scanning src/lib/ directory.
+ *
+ * @returns {Record<string, string>} Mapping of prefix to lib import path.
+ * @example
+ * - src/lib/supabase/server.ts → { server: "@/lib/supabase/server" }
+ * - src/lib/supabase/client.ts → { server: "@/lib/supabase/client" }
+ */
+function generatePrefixLibMapping() {
+  const libDir = path.join(PROJECT_ROOT, "src/lib");
+  const mapping = {};
+
+  if (!fs.existsSync(libDir)) {
+    return mapping;
+  }
+
+  const entries = fs.readdirSync(libDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (EXCLUDE_LIST.includes(entry.name)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      // Scan subdirectory (e.g., src/lib/supabase/)
+      const subDir = path.join(libDir, entry.name);
+      const subEntries = fs.readdirSync(subDir, { withFileTypes: true });
+
+      for (const subEntry of subEntries) {
+        if (
+          subEntry.isFile() &&
+          subEntry.name.endsWith(".ts") &&
+          !EXCLUDE_LIST.includes(subEntry.name)
+        ) {
+          const prefix = subEntry.name.replace(".ts", "");
+          mapping[prefix] = `@/lib/${entry.name}/${prefix}`;
+        }
+      }
+    } else if (entry.isFile() && entry.name.endsWith(".ts")) {
+      const prefix = entry.name.replace(".ts", "");
+      mapping[prefix] = `@/lib/${prefix}`;
+    }
+  }
+
+  return mapping;
+}
+
+/**
+ * Mapping of file prefixes to their corresponding lib imports.
+ *
+ * Dynamically generated by scanning src/lib/ directory.
+ * Used by:
+ * - naming.mjs: Validates file naming (e.g., server.repo.ts, client.repo.ts)
+ * - imports.mjs: Enforces import restrictions
+ *
+ * @example
+ * server.repo.ts → can only import @/lib/supabase/server
+ * client.repo.ts → can only import @/lib/supabase/client
+ *
+ * @type {Record<string, string>}
+ */
+export const PREFIX_LIB_MAPPING = generatePrefixLibMapping();
+
+/**
+ * Creates glob patterns for all feature roots.
+ * @param {string} subpath - The subpath to append to each feature root.
+ * @returns {string[]} Array of glob patterns.
+ * @example
+ * featuresGlob("**\/actions/*.ts")
+ * // => ["src/features/**\/actions/*.ts", "scripts/features/**\/actions/*.ts", ...]
+ */
+export const featuresGlob = (subpath) =>
+  FEATURE_ROOTS.map((root) => `${root}/${subpath}`);

package/src/directives.mjs

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Directive requirements for React Server Components.
+ *
+ * Ensures correct usage of "use server" and "use client" directives:
+ * - server.action.ts: Must start with "use server"
+ * - admin.action.ts: Must start with "use server"
+ * - client.action.ts: Must NOT have "use server"
+ * - hooks/*.ts: Must start with "use client"
+ */
+
+/**
+ * Directive requirement configurations.
+ * @type {import("eslint").Linter.Config[]}
+ */
+export const directivesConfigs = [
+  {
+    name: "directives/server-action",
+    files: ["src/features/**/actions/server.action.ts"],
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "Program > :first-child:not(ExpressionStatement[expression.value='use server'])",
+          message: 'server.action.ts must start with "use server" directive.',
+        },
+      ],
+    },
+  },
+  {
+    name: "directives/admin-action",
+    files: ["src/features/**/actions/admin.action.ts"],
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "Program > :first-child:not(ExpressionStatement[expression.value='use server'])",
+          message: 'admin.action.ts must start with "use server" directive.',
+        },
+      ],
+    },
+  },
+  {
+    name: "directives/client-action",
+    files: ["src/features/**/actions/client.action.ts"],
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "ExpressionStatement[expression.value='use server']",
+          message:
+            'client.action.ts must NOT have "use server" directive. It uses @/lib/supabase/client.',
+        },
+      ],
+    },
+  },
+  {
+    name: "directives/hooks",
+    files: ["src/features/**/hooks/*.ts"],
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "Program > :first-child:not(ExpressionStatement[expression.value='use client'])",
+          message: 'Hooks must start with "use client" directive.',
+        },
+      ],
+    },
+  },
+];

package/src/imports.mjs

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Import restrictions for repository files.
+ *
+ * Enforces that each {prefix}.repo.ts can only import its corresponding lib:
+ * - server.repo.ts → @/lib/supabase/server only
+ * - client.repo.ts → @/lib/supabase/client only
+ *
+ * This prevents mixing different data sources in a single repository file.
+ */
+
+import { PREFIX_LIB_MAPPING } from "./constants.mjs";
+
+/**
+ * Generate import restriction configs for each prefix.
+ *
+ * For each prefix (e.g., "server"), creates a rule that forbids importing
+ * any other lib from PREFIX_LIB_MAPPING.
+ *
+ * @returns {import("eslint").Linter.Config[]}
+ */
+function generateImportConfigs() {
+  const prefixes = Object.keys(PREFIX_LIB_MAPPING);
+  const configs = [];
+
+  for (const prefix of prefixes) {
+    const allowedLib = PREFIX_LIB_MAPPING[prefix];
+    const forbiddenLibs = prefixes
+      .filter((p) => p !== prefix)
+      .map((p) => PREFIX_LIB_MAPPING[p]);
+
+    // Skip if no forbidden libs (shouldn't happen, but safety check)
+    if (forbiddenLibs.length === 0) continue;
+
+    configs.push({
+      name: `imports/${prefix}-repo`,
+      files: [`**/repositories/${prefix}.repo.ts`],
+      rules: {
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: forbiddenLibs.map((lib) => ({
+              group: [`${lib}`, `${lib}/*`],
+              message: `${prefix}.repo.ts can only import from ${allowedLib}. Use the correct repository file for this lib.`,
+            })),
+          },
+        ],
+      },
+    });
+  }
+
+  return configs;
+}
+
+/**
+ * Import restriction configurations for repository files.
+ * @type {import("eslint").Linter.Config[]}
+ */
+export const importsConfigs = generateImportConfigs();

package/src/index.mjs

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Main ESLint configuration aggregator.
+ *
+ * Combines all configuration modules:
+ * - base: Next.js presets and shared rules
+ * - naming: File naming conventions
+ * - layers: Layer architecture constraints
+ * - cardinality: Action-domain relationships
+ * - directives: "use server" / "use client" requirements
+ * - imports: Repository import restrictions (prefix → lib mapping)
+ */
+
+import { baseConfigs, ignoresConfig, sharedRulesConfig } from "./base.mjs";
+import { cardinalityConfigs } from "./cardinality.mjs";
+import { directivesConfigs } from "./directives.mjs";
+import { importsConfigs } from "./imports.mjs";
+import { layersConfigs } from "./layers.mjs";
+import { namingConfigs } from "./naming.mjs";
+
+/**
+ * Complete ESLint configuration array.
+ * @type {import("eslint").Linter.Config[]}
+ */
+export const eslintConfig = [
+  ...baseConfigs,
+  ignoresConfig,
+  sharedRulesConfig,
+  ...namingConfigs,
+  ...layersConfigs,
+  ...cardinalityConfigs,
+  ...directivesConfigs,
+  ...importsConfigs,
+];

package/src/layers.mjs

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Layer architecture constraints.
+ *
+ * Enforces the following dependency rules:
+ *
+ * Layer hierarchy (top to bottom):
+ *   hooks → actions → domains → repositories
+ *
+ * Rules:
+ * - Repositories: Cannot import domains, actions, or hooks.
+ *                 Cannot use try-catch or if statements.
+ * - Domains: Cannot import actions or hooks.
+ *            Cannot use try-catch.
+ * - Actions: Cannot import hooks.
+ *            Exported functions must start with "handle".
+ * - Hooks: Exported functions must start with "use".
+ *
+ * Cross-feature imports are also prohibited within the same layer.
+ */
+
+import { featuresGlob } from "./constants.mjs";
+
+/**
+ * Layer constraint configurations.
+ * @type {import("eslint").Linter.Config[]}
+ */
+export const layersConfigs = [
+  {
+    name: "layers/repositories",
+    files: ["**/repositories/*.ts"],
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "TryStatement",
+          message:
+            "try-catch is not allowed in repositories. Error handling belongs in actions.",
+        },
+        {
+          selector: "IfStatement",
+          message:
+            "if statements are not allowed in repositories. Conditional logic belongs in domain.",
+        },
+      ],
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["*/domains/*", "*/domains"],
+              message: "repositories cannot import domains (layer violation)",
+            },
+            {
+              group: ["*/actions/*", "*/actions"],
+              message: "repositories cannot import actions (layer violation)",
+            },
+            {
+              group: ["*/hooks/*", "*/hooks"],
+              message: "repositories cannot import hooks (layer violation)",
+            },
+            {
+              group: [
+                "@/features/*/repositories/*",
+                "@/features/*/repositories",
+              ],
+              message:
+                "repositories cannot import other feature's repositories (cross-feature violation)",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    name: "layers/domains",
+    files: ["**/domains/*.ts"],
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "TryStatement",
+          message:
+            "try-catch is not allowed in domain. Error handling belongs in actions.",
+        },
+      ],
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["*/actions/*", "*/actions"],
+              message: "domains cannot import actions (layer violation)",
+            },
+            {
+              group: ["*/hooks/*", "*/hooks"],
+              message: "domains cannot import hooks (layer violation)",
+            },
+            {
+              group: ["@/features/*/domains/*", "@/features/*/domains"],
+              message:
+                "domains cannot import other feature's domains (cross-feature violation)",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    name: "layers/actions-naming",
+    files: featuresGlob("**/actions/*.ts"),
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "ExportNamedDeclaration > FunctionDeclaration[id.name!=/^handle[A-Z]/]",
+          message:
+            "Exported functions in actions must start with 'handle' (e.g., handleGetComics).",
+        },
+      ],
+    },
+  },
+  {
+    name: "layers/actions-imports",
+    files: ["**/actions/*.ts"],
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["*/hooks/*", "*/hooks"],
+              message: "actions cannot import hooks (layer violation)",
+            },
+            {
+              group: ["@/features/*/actions/*", "@/features/*/actions"],
+              message:
+                "actions cannot import other feature's actions (cross-feature violation)",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    name: "layers/hooks-naming",
+    files: featuresGlob("**/hooks/*.ts"),
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "ExportNamedDeclaration > FunctionDeclaration[id.name!=/^use[A-Z]/]",
+          message:
+            "Exported functions in hooks must start with 'use' (e.g., useAuth).",
+        },
+      ],
+    },
+  },
+];

package/src/naming.mjs

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview File naming conventions for feature modules.
+ *
+ * Enforces consistent naming patterns:
+ * - domains: {prefix}.domain.ts (e.g., server.domain.ts, stripe.domain.ts)
+ * - repositories: {prefix}.repo.ts (e.g., server.repo.ts, stripe.repo.ts)
+ * - actions: {prefix}.action.ts (e.g., server.action.ts, stripe.action.ts)
+ * - hooks: useXxx.ts (e.g., useAuth.ts)
+ * - types: xxx.type.ts (e.g., comic.type.ts)
+ * - schemas: xxx.schema.ts (e.g., comic.schema.ts)
+ * - utils: xxx.util.ts (e.g., format.util.ts)
+ * - constants: xxx.constant.ts (e.g., api.constant.ts)
+ *
+ * Extension constraints:
+ * - features/**: .ts only (no .tsx — components belong in src/components/)
+ * - components/**:  .tsx only (no .ts — logic belongs in src/features/)
+ *
+ * Valid prefixes are defined in PREFIX_LIB_MAPPING (constants.mjs).
+ */
+
+import { featuresGlob, PREFIX_LIB_MAPPING } from "./constants.mjs";
+import { checkFile } from "./plugins.mjs";
+
+/**
+ * Generate glob pattern from PREFIX_LIB_MAPPING keys.
+ * @example "@(server|client|admin)"
+ */
+const prefixPattern = `@(${Object.keys(PREFIX_LIB_MAPPING).join("|")})`;
+
+/**
+ * File naming convention configurations.
+ * @type {import("eslint").Linter.Config[]}
+ */
+export const namingConfigs = [
+  {
+    name: "naming/domains",
+    files: featuresGlob("**/domains/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": `${prefixPattern}.domain` },
+      ],
+    },
+  },
+  {
+    name: "naming/repositories",
+    files: featuresGlob("**/repositories/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": `${prefixPattern}.repo` },
+      ],
+    },
+  },
+  {
+    name: "naming/hooks",
+    files: featuresGlob("**/hooks/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": "use[A-Z]*([a-zA-Z0-9])" },
+        { ignoreMiddleExtensions: true },
+      ],
+    },
+  },
+  {
+    name: "naming/types",
+    files: featuresGlob("**/types/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": "+([a-z0-9-]).type" },
+      ],
+    },
+  },
+  {
+    name: "naming/schemas",
+    files: featuresGlob("**/schemas/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": "+([a-z0-9-]).schema" },
+      ],
+    },
+  },
+  {
+    name: "naming/utils",
+    files: featuresGlob("**/util/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": "+([a-z0-9-]).util" },
+      ],
+    },
+  },
+  {
+    name: "naming/constants",
+    files: featuresGlob("**/constants/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": "+([a-z0-9-]).constant" },
+      ],
+    },
+  },
+  {
+    name: "naming/actions",
+    files: featuresGlob("**/actions/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": `${prefixPattern}.action` },
+      ],
+    },
+  },
+  {
+    name: "naming/features-ts-only",
+    files: featuresGlob("**/*.tsx"),
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "Program",
+          message:
+            "features/ must only contain .ts files. Components belong in src/components/.",
+        },
+      ],
+    },
+  },
+  {
+    name: "naming/components-tsx-only",
+    files: ["src/components/**/*.ts"],
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "Program",
+          message:
+            "components/ must only contain .tsx files. Logic belongs in src/features/.",
+        },
+      ],
+    },
+  },
+];

package/src/plugins.mjs

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview ESLint plugin imports and exports.
+ */
+
+import stylistic from "@stylistic/eslint-plugin";
+import checkFile from "eslint-plugin-check-file";
+import reactYouMightNotNeedAnEffect from "eslint-plugin-react-you-might-not-need-an-effect";
+import simpleImportSortPlugin from "eslint-plugin-simple-import-sort";
+
+/**
+ * Plugin namespace mapping for ESLint configuration.
+ * @type {Record<string, import("eslint").ESLint.Plugin>}
+ */
+export const plugins = {
+  "@stylistic": stylistic,
+  "check-file": checkFile,
+  "react-you-might-not-need-an-effect": reactYouMightNotNeedAnEffect,
+  "simple-import-sort": simpleImportSortPlugin,
+};
+
+export {
+  checkFile,
+  reactYouMightNotNeedAnEffect,
+  simpleImportSortPlugin,
+  stylistic,
+};