@yasainet/eslint 0.0.1

package/README.md

@@ -0,0 +1,50 @@
+# @yasainet/eslint
+
+Shared ESLint configuration for feature-based architecture.
+
+## Install
+
+```sh
+npm install -D @yasainet/eslint eslint
+```
+
+## Usage
+
+### Next.js
+
+```js
+// eslint.config.mjs
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+import { eslintConfig } from "@yasainet/eslint/next";
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([".next/**", "out/**", "build/**", "next-env.d.ts"]),
+  ...eslintConfig,
+]);
+```
+
+### Node.js
+
+```js
+// eslint.config.mjs
+import { eslintConfig } from "@yasainet/eslint/node";
+
+export default eslintConfig;
+```
+
+## Release
+
+1. Update `version` in `package.json`
+2. Commit and push to `main`
+3. Create and push a tag:
+
+```sh
+git tag v1.0.0
+git push --tags
+```
+
+4. GitHub Actions will automatically publish to npm

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@yasainet/eslint",
+  "version": "0.0.1",
+  "description": "ESLint",
+  "type": "module",
+  "exports": {
+    "./next": "./src/next/index.mjs",
+    "./node": "./src/node/index.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "eslint",
+    "eslintconfig",
+    "nextjs",
+    "nodejs",
+    "typescript"
+  ],
+  "author": "yasainet",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@stylistic/eslint-plugin": "^5.9.0",
+    "eslint-plugin-check-file": "^3.3.1",
+    "eslint-plugin-jsdoc": "^62.7.1",
+    "eslint-plugin-simple-import-sort": "^12.1.1"
+  },
+  "peerDependencies": {
+    "eslint": "^9"
+  }
+}

package/src/common/constants.mjs

@@ -0,0 +1,72 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function findProjectRoot() {
+  let dir = __dirname;
+  while (dir !== path.dirname(dir)) {
+    if (
+      fs.existsSync(path.join(dir, "package.json")) &&
+      !dir.includes("/node_modules/")
+    ) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+const PROJECT_ROOT = findProjectRoot();
+
+export const FEATURE_ROOTS = [
+  "src/features",
+  "scripts/features",
+  "supabase/functions/features",
+];
+
+const EXCLUDE_LIST = ["proxy.ts", "types"];
+
+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()) {
+      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;
+}
+
+export const PREFIX_LIB_MAPPING = generatePrefixLibMapping();
+
+export const featuresGlob = (subpath) =>
+  FEATURE_ROOTS.map((root) => `${root}/${subpath}`);

package/src/common/imports.mjs

@@ -0,0 +1,186 @@
+import { PREFIX_LIB_MAPPING } from "./constants.mjs";
+
+const LAYER_PATTERNS = {
+  repositories: [
+    {
+      group: ["*/services/*", "*/services"],
+      message: "repositories cannot import services (layer violation)",
+    },
+    {
+      group: ["*/actions/*", "*/actions"],
+      message: "repositories cannot import actions (layer violation)",
+    },
+    {
+      group: ["*/hooks/*", "*/hooks"],
+      message: "repositories cannot import hooks (layer violation)",
+    },
+  ],
+  services: [
+    {
+      group: ["*/actions/*", "*/actions"],
+      message: "services cannot import actions (layer violation)",
+    },
+    {
+      group: ["*/hooks/*", "*/hooks"],
+      message: "services cannot import hooks (layer violation)",
+    },
+  ],
+  actions: [
+    {
+      group: ["*/hooks/*", "*/hooks"],
+      message: "actions cannot import hooks (layer violation)",
+    },
+  ],
+};
+
+const LATERAL_PATTERNS = {
+  repositories: [
+    {
+      group: ["@/features/*/repositories/*", "@/features/*/repositories"],
+      message:
+        "repositories cannot import other feature's repositories (lateral violation)",
+    },
+  ],
+  services: [
+    {
+      group: ["@/features/*/services/*", "@/features/*/services"],
+      message:
+        "services cannot import other feature's services (lateral violation)",
+    },
+  ],
+  actions: [
+    {
+      group: ["@/features/*/actions/*", "@/features/*/actions"],
+      message:
+        "actions cannot import other feature's actions (lateral violation)",
+    },
+  ],
+};
+
+const CARDINALITY_PATTERNS = {
+  server: [
+    {
+      group: ["**/services/client.service*", "**/services/admin.service*"],
+      message:
+        "server.action can only import server.service (cardinality violation)",
+    },
+  ],
+  client: [
+    {
+      group: ["**/services/server.service*", "**/services/admin.service*"],
+      message:
+        "client.action can only import client.service (cardinality violation)",
+    },
+  ],
+  admin: [
+    {
+      group: ["**/services/server.service*", "**/services/client.service*"],
+      message:
+        "admin.action can only import admin.service (cardinality violation)",
+    },
+  ],
+};
+
+function prefixLibPatterns(prefix) {
+  const prefixes = Object.keys(PREFIX_LIB_MAPPING);
+  const allowedLib = PREFIX_LIB_MAPPING[prefix];
+  return prefixes
+    .filter((p) => p !== prefix)
+    .map((p) => ({
+      group: [PREFIX_LIB_MAPPING[p], `${PREFIX_LIB_MAPPING[p]}/*`],
+      message: `${prefix}.repo.ts can only import from ${allowedLib}. Use the correct repository file for this lib.`,
+    }));
+}
+
+const LIB_BOUNDARY_PATTERNS = [
+  {
+    group: ["@/lib/*", "@/lib/**"],
+    message:
+      "@/lib/* can only be imported from repositories (lib-boundary violation)",
+  },
+];
+
+function makeConfig(name, files, ...patternArrays) {
+  const patterns = patternArrays.flat();
+  if (patterns.length === 0) return null;
+  return {
+    name: `imports/${name}`,
+    files,
+    rules: {
+      "no-restricted-imports": ["error", { patterns }],
+    },
+  };
+}
+
+function generateImportConfigs() {
+  const configs = [];
+
+  configs.push({
+    name: "imports/lib-boundary",
+    files: ["src/**/*.{ts,tsx}"],
+    ignores: ["src/lib/**", "src/proxy.ts", "src/app/sitemap.ts"],
+    rules: {
+      "no-restricted-imports": ["error", { patterns: LIB_BOUNDARY_PATTERNS }],
+    },
+  });
+
+  configs.push(
+    makeConfig(
+      "repositories",
+      ["**/repositories/*.ts"],
+      LAYER_PATTERNS.repositories,
+      LATERAL_PATTERNS.repositories,
+    ),
+  );
+
+  for (const prefix of Object.keys(PREFIX_LIB_MAPPING)) {
+    const patterns = prefixLibPatterns(prefix);
+    if (patterns.length === 0) continue;
+    configs.push(
+      makeConfig(
+        `repositories/${prefix}`,
+        [`**/repositories/${prefix}.repo.ts`],
+        LAYER_PATTERNS.repositories,
+        LATERAL_PATTERNS.repositories,
+        patterns,
+      ),
+    );
+  }
+
+  configs.push(
+    makeConfig(
+      "services",
+      ["**/services/*.ts"],
+      LAYER_PATTERNS.services,
+      LATERAL_PATTERNS.services,
+      LIB_BOUNDARY_PATTERNS,
+    ),
+  );
+
+  configs.push(
+    makeConfig(
+      "actions",
+      ["**/actions/*.ts"],
+      LAYER_PATTERNS.actions,
+      LATERAL_PATTERNS.actions,
+      LIB_BOUNDARY_PATTERNS,
+    ),
+  );
+
+  for (const prefix of ["server", "client", "admin"]) {
+    configs.push(
+      makeConfig(
+        `actions/${prefix}`,
+        [`**/actions/${prefix}.action.ts`],
+        LAYER_PATTERNS.actions,
+        LATERAL_PATTERNS.actions,
+        CARDINALITY_PATTERNS[prefix],
+        LIB_BOUNDARY_PATTERNS,
+      ),
+    );
+  }
+
+  return configs.filter(Boolean);
+}
+
+export const importsConfigs = generateImportConfigs();

package/src/common/index.mjs

@@ -0,0 +1,13 @@
+import { importsConfigs } from "./imports.mjs";
+import { jsdocConfigs } from "./jsdoc.mjs";
+import { layersConfigs } from "./layers.mjs";
+import { namingConfigs } from "./naming.mjs";
+import { rulesConfigs } from "./rules.mjs";
+
+export const commonConfigs = [
+  ...rulesConfigs,
+  ...namingConfigs,
+  ...layersConfigs,
+  ...importsConfigs,
+  ...jsdocConfigs,
+];

package/src/common/jsdoc.mjs

@@ -0,0 +1,39 @@
+import jsdocPlugin from "eslint-plugin-jsdoc";
+
+import { featuresGlob } from "./constants.mjs";
+
+export const jsdocConfigs = [
+  {
+    name: "jsdoc",
+    files: [
+      ...featuresGlob("**/repositories/*.ts"),
+      ...featuresGlob("**/services*/*.ts"),
+      ...featuresGlob("**/utils*/*.ts"),
+    ],
+    plugins: {
+      jsdoc: jsdocPlugin,
+    },
+    rules: {
+      "jsdoc/require-jsdoc": [
+        "warn",
+        {
+          publicOnly: true,
+          require: {
+            FunctionDeclaration: true,
+            ArrowFunctionExpression: true,
+            FunctionExpression: true,
+          },
+          checkGetters: false,
+          checkSetters: false,
+          checkConstructors: false,
+        },
+      ],
+      "jsdoc/require-description": [
+        "warn",
+        {
+          contexts: ["any"],
+        },
+      ],
+    },
+  },
+];

package/src/common/layers.mjs

@@ -0,0 +1,35 @@
+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 services.",
+        },
+      ],
+    },
+  },
+  {
+    name: "layers/services",
+    files: ["**/services/*.ts"],
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "TryStatement",
+          message:
+            "try-catch is not allowed in services. Error handling belongs in actions.",
+        },
+      ],
+    },
+  },
+];

package/src/common/local-plugins/action-handle-service.mjs

@@ -0,0 +1,60 @@
+/**
+ * @description In *.action.ts, `handleXxx` must call the service method `*.xxx()`.
+ */
+export const actionHandleServiceRule = {
+  meta: {
+    type: "problem",
+    messages: {
+      missingCall:
+        "handleXxx must call the corresponding service method '*.{{ expected }}()'.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      "ExportNamedDeclaration > FunctionDeclaration[id.name=/^handle[A-Z]/]"(
+        node,
+      ) {
+        const name = node.id.name;
+        const suffix = name.slice("handle".length);
+        const expected = suffix[0].toLowerCase() + suffix.slice(1);
+
+        let found = false;
+
+        function walk(n) {
+          if (found || !n || typeof n !== "object") return;
+
+          if (
+            n.type === "CallExpression" &&
+            n.callee.type === "MemberExpression" &&
+            !n.callee.computed &&
+            n.callee.property.name === expected
+          ) {
+            found = true;
+            return;
+          }
+
+          for (const key of Object.keys(n)) {
+            if (key === "parent") continue;
+            const child = n[key];
+            if (Array.isArray(child)) {
+              for (const item of child) walk(item);
+            } else if (child && typeof child.type === "string") {
+              walk(child);
+            }
+          }
+        }
+
+        walk(node.body);
+
+        if (!found) {
+          context.report({
+            node: node.id,
+            messageId: "missingCall",
+            data: { expected },
+          });
+        }
+      },
+    };
+  },
+};

package/src/common/naming.mjs

@@ -0,0 +1,150 @@
+import { featuresGlob, PREFIX_LIB_MAPPING } from "./constants.mjs";
+import { checkFile } from "./plugins.mjs";
+import { actionHandleServiceRule } from "./local-plugins/action-handle-service.mjs";
+
+const prefixPattern = `@(${Object.keys(PREFIX_LIB_MAPPING).join("|")})`;
+
+export const namingConfigs = [
+  {
+    name: "naming/services",
+    files: featuresGlob("**/services/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": `${prefixPattern}.service` },
+      ],
+    },
+  },
+  {
+    name: "naming/repositories",
+    files: featuresGlob("**/repositories/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": `${prefixPattern}.repo` },
+      ],
+    },
+  },
+  {
+    name: "naming/types",
+    files: featuresGlob("*/types/*.type.ts"),
+    ignores: featuresGlob("shared/types/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*/types/*.ts": "<1>" },
+        { ignoreMiddleExtensions: true },
+      ],
+    },
+  },
+  {
+    name: "naming/types-shared",
+    files: featuresGlob("shared/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("*/utils/*.utils.ts"),
+    ignores: featuresGlob("shared/utils/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*/utils/*.ts": "<1>" },
+        { ignoreMiddleExtensions: true },
+      ],
+    },
+  },
+  {
+    name: "naming/utils-shared",
+    files: featuresGlob("shared/utils/*.ts"),
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.ts": "+([a-z0-9_-]).utils" },
+      ],
+    },
+  },
+  {
+    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/actions-export",
+    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: "naming/actions-handle-service",
+    files: featuresGlob("**/actions/*.ts"),
+    plugins: {
+      local: { rules: { "action-handle-service": actionHandleServiceRule } },
+    },
+    rules: {
+      "local/action-handle-service": "error",
+    },
+  },
+  {
+    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/.",
+        },
+      ],
+    },
+  },
+];

package/src/common/plugins.mjs

@@ -0,0 +1,13 @@
+import stylistic from "@stylistic/eslint-plugin";
+import checkFile from "eslint-plugin-check-file";
+import jsdocPlugin from "eslint-plugin-jsdoc";
+import simpleImportSortPlugin from "eslint-plugin-simple-import-sort";
+
+export const plugins = {
+  "@stylistic": stylistic,
+  "check-file": checkFile,
+  jsdoc: jsdocPlugin,
+  "simple-import-sort": simpleImportSortPlugin,
+};
+
+export { checkFile, jsdocPlugin, simpleImportSortPlugin, stylistic };

package/src/common/rules.mjs

@@ -0,0 +1,39 @@
+import { simpleImportSortPlugin, stylistic } from "./plugins.mjs";
+
+export const rulesConfigs = [
+  {
+    name: "rules/shared",
+    plugins: {
+      "@stylistic": stylistic,
+      "simple-import-sort": simpleImportSortPlugin,
+    },
+    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/next/directives.mjs

@@ -0,0 +1,58 @@
+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/next/index.mjs

@@ -0,0 +1,10 @@
+import { commonConfigs } from "../common/index.mjs";
+
+import { directivesConfigs } from "./directives.mjs";
+import { namingConfigs } from "./naming.mjs";
+
+export const eslintConfig = [
+  ...commonConfigs,
+  ...namingConfigs,
+  ...directivesConfigs,
+];

package/src/next/naming.mjs

@@ -0,0 +1,58 @@
+import { featuresGlob } from "../common/constants.mjs";
+import { checkFile } from "../common/plugins.mjs";
+
+export const namingConfigs = [
+  {
+    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/hooks-export",
+    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).",
+        },
+      ],
+    },
+  },
+  {
+    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/.",
+        },
+      ],
+    },
+  },
+  {
+    name: "naming/components-pascal-case",
+    files: ["src/components/**/*.tsx"],
+    ignores: ["src/components/shared/ui/**"],
+    plugins: { "check-file": checkFile },
+    rules: {
+      "check-file/filename-naming-convention": [
+        "error",
+        { "**/*.tsx": "PASCAL_CASE" },
+      ],
+    },
+  },
+];

package/src/node/index.mjs

@@ -0,0 +1,3 @@
+import { commonConfigs } from "../common/index.mjs";
+
+export const eslintConfig = [...commonConfigs];