@spectrabrain/eds 0.1.0 → 0.2.0

package/consumer/align-rules.mjs

@@ -0,0 +1,473 @@
+// The EVA frontend conventions as data. FRONTEND_CONVENTIONS.md states the same rules in prose, and
+// scripts/check-consumer-guidance.mjs checks that every replacement category and layer listed here appears there.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const alignDirectory = ".eds/align";
+export const planFileName = "PLAN.md";
+export const stateFileName = "state.json";
+export const templatesDirectoryName = "templates";
+export const stateSchemaVersion = 1;
+export const conventionsFileName = "FRONTEND_CONVENTIONS.md";
+
+// FSD layers from top to bottom. A module imports only layers below its own, plus its own slice.
+export const layerOrder = ["app", "pages", "widgets", "features", "entities", "shared"];
+// Layers whose second path segment is a slice (pages/<domain>, widgets/<name>, features/<domain>, entities/<domain>).
+export const slicedLayers = new Set(["pages", "widgets", "features", "entities"]);
+// src/ entries allowed besides the layers: MSW handlers, global declaration files and the file eds sync generates.
+export const auxiliarySourceDirectories = ["mocks", "types", "styles"];
+export const allowedSourceRootFiles = ["vite-env.d.ts"];
+export const generatedStylesFileName = "eds-tokens.css";
+
+export const appEntries = ["main.tsx", "App.tsx", "providers", "router", "styles"];
+export const entitySegments = ["components", "hooks", "services", "stores", "types", "lib"];
+export const featureSegments = ["ui", "lib", "types"];
+export const sharedSegments = ["api", "assets", "hooks", "lib", "ui"];
+
+// Relative to the source directory (src/) and to the Vite root (the directory of index.html).
+export const requiredSourceFiles = [
+  "app/main.tsx",
+  "app/App.tsx",
+  "app/router/index.tsx",
+  "app/styles/index.css",
+  "shared/api/index.ts",
+  "shared/api/queryClient.ts",
+  "shared/lib/utils/index.ts",
+];
+export const entryModule = "app/main.tsx";
+
+// Scripts every aligned frontend declares; the value is what the template uses when the script is missing.
+export const requiredScripts = {
+  lint: "eslint .",
+  format: "prettier --write .",
+  "format:check": "prettier --check .",
+  typecheck: "tsc --noEmit",
+  build: "vite build",
+};
+
+// Packages an aligned frontend declares. axios is required unless the app talks to its backend only through a data SDK.
+export const requiredDependencies = [
+  "react",
+  "react-dom",
+  "react-router-dom",
+  "@tanstack/react-query",
+  "sonner",
+  "clsx",
+  "tailwind-merge",
+  "tailwindcss",
+  "@spectrabrain/eds",
+];
+export const requiredDevDependencies = [
+  "vite",
+  "@vitejs/plugin-react",
+  "@tailwindcss/vite",
+  "@types/react",
+  "@types/react-dom",
+  "babel-plugin-react-compiler",
+  "typescript",
+  "eslint",
+  "@eslint/js",
+  "typescript-eslint",
+  "eslint-plugin-react-hooks",
+  "eslint-plugin-react-refresh",
+  "globals",
+  "prettier",
+];
+// Vite 8 moved Babel out of @vitejs/plugin-react; the React Compiler then runs through this plugin.
+export const rolldownBabelPackage = "@rolldown/plugin-babel";
+export const minimumMajors = { react: 19, "@tanstack/react-query": 5, tailwindcss: 4 };
+
+// Install ranges the templates are written against. Packages without a range install at their latest version.
+export const installRanges = {
+  eslint: "^9.22",
+  "@eslint/js": "^9.22",
+  "typescript-eslint": "^8",
+  "eslint-plugin-react-hooks": "^7",
+  "eslint-plugin-react-refresh": "^0.4.20",
+  prettier: "^3",
+  "babel-plugin-react-compiler": "^1",
+  tailwindcss: "^4",
+  "@tailwindcss/vite": "^4",
+  "@types/react": "^19",
+  "@types/react-dom": "^19",
+  "@tanstack/react-query": "^5",
+  react: "^19",
+  "react-dom": "^19",
+};
+// The oldest versions the eslint.config template loads with (eslint/config defineConfig, react-hooks flat configs,
+// react-refresh configs.vite). An older declared or installed version fails the check and is reinstalled in step 3.
+export const templateToolMinimums = {
+  eslint: "9.22.0",
+  "@eslint/js": "9.22.0",
+  "typescript-eslint": "8.0.0",
+  "eslint-plugin-react-hooks": "7.0.0",
+  "eslint-plugin-react-refresh": "0.4.20",
+};
+// Installed with the tooling step although no check requires them: the templates reference them.
+export const templateDevDependencies = ["vite-plugin-svgr", "terser", "tw-animate-css", "msw"];
+// The lucide-react version EDS depends on: a consumer that imports lucide-react directly declares the same one, so the
+// icon code is bundled once.
+export const edsLucideVersion = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).dependencies?.["lucide-react"] ?? null;
+// Installed in step 6 only when the app calls a REST API that gets MSW handlers.
+export const mockDevDependencies = ["@faker-js/faker"];
+
+// Tests are outside the conventions: a prototype's test policy may change at any time. eds align neither requires,
+// replaces nor lists test tooling, and leaves test files, test directories and test setup files where they are.
+export const testDirectoryNames = ["test", "tests", "__tests__", "__mocks__"];
+export const testFilePattern = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+export const testSetupFilePattern = /^(?:setupTests|setup-tests|testSetup|test-setup|vitest\.setup|jest\.setup)\.[cm]?[jt]sx?$/;
+export const testToolingPattern =
+  /^(?:jest|jest-.+|@jest\/.+|ts-jest|babel-jest|vitest|@vitest\/.+|@testing-library\/.+|cypress|@cypress\/.+|playwright|@playwright\/.+|happy-dom|jsdom|enzyme|enzyme-.+|identity-obj-proxy|mocha|chai|sinon|nock|supertest)$/;
+
+// Libraries a prototype often brings and the EVA standard that replaces each category.
+export const replacementRules = [
+  { category: "routing", target: "react-router-dom", packages: ["wouter", "@tanstack/react-router", "@reach/router"] },
+  { category: "server-state", target: "@tanstack/react-query", packages: ["swr", "react-query"] },
+  {
+    category: "http",
+    target: "axios",
+    packages: ["ky", "ofetch", "redaxios", "wretch", "superagent", "cross-fetch", "isomorphic-fetch", "node-fetch"],
+  },
+  {
+    category: "client-state",
+    target: "zustand",
+    packages: [
+      "redux",
+      "@reduxjs/toolkit",
+      "react-redux",
+      "redux-thunk",
+      "redux-saga",
+      "redux-persist",
+      "jotai",
+      "recoil",
+      "mobx",
+      "mobx-react",
+      "mobx-react-lite",
+      "valtio",
+      "effector",
+      "effector-react",
+      "@preact/signals-react",
+      "@legendapp/state",
+    ],
+  },
+  {
+    category: "form",
+    target: "useState or Context + useReducer",
+    label: "useState 또는 Context + useReducer",
+    packages: ["react-hook-form", "@hookform/resolvers", "formik", "react-final-form", "final-form", "@tanstack/react-form"],
+  },
+  {
+    category: "validation",
+    target: "TypeScript types and validation functions",
+    label: "TypeScript 타입과 검증 함수",
+    packages: ["zod", "yup", "valibot", "joi", "superstruct"],
+  },
+  {
+    category: "styling",
+    target: "Tailwind CSS v4 + EDS tokens",
+    packages: [
+      "styled-components",
+      "@emotion/react",
+      "@emotion/styled",
+      "@emotion/css",
+      "sass",
+      "sass-embedded",
+      "less",
+      "stylus",
+      "@stitches/react",
+      "@vanilla-extract/css",
+      "goober",
+      "jss",
+      "react-jss",
+      "@pandacss/dev",
+      "twin.macro",
+      "unocss",
+      "windicss",
+    ],
+  },
+  {
+    category: "ui-kit",
+    target: "EDS Button + shadcn/ui (Radix)",
+    packages: [
+      "@mui/material",
+      "@mui/joy",
+      "@mui/lab",
+      "@mui/system",
+      "@material-ui/core",
+      "@chakra-ui/react",
+      "antd",
+      "@mantine/core",
+      "@mantine/hooks",
+      "react-bootstrap",
+      "bootstrap",
+      "reactstrap",
+      "@headlessui/react",
+      "@nextui-org/react",
+      "@heroui/react",
+      "daisyui",
+      "flowbite",
+      "flowbite-react",
+      "primereact",
+      "semantic-ui-react",
+      "@blueprintjs/core",
+      "rsuite",
+      "@fluentui/react",
+      "@radix-ui/themes",
+    ],
+  },
+  {
+    category: "icon",
+    target: "lucide-react",
+    packages: [
+      "react-icons",
+      "@heroicons/react",
+      "@fortawesome/react-fontawesome",
+      "@fortawesome/fontawesome-svg-core",
+      "@fortawesome/free-solid-svg-icons",
+      "@fortawesome/free-regular-svg-icons",
+      "@fortawesome/free-brands-svg-icons",
+      "@tabler/icons-react",
+      "@phosphor-icons/react",
+      "phosphor-react",
+      "@iconify/react",
+      "react-feather",
+      "@radix-ui/react-icons",
+      "@mui/icons-material",
+      "@ant-design/icons",
+    ],
+  },
+  { category: "toast", target: "sonner", packages: ["react-toastify", "react-hot-toast", "notistack"] },
+  { category: "date", target: "date-fns", packages: ["moment", "moment-timezone", "dayjs", "luxon"] },
+  { category: "virtual-list", target: "react-virtuoso", packages: ["react-window", "react-virtualized", "@tanstack/react-virtual"] },
+  { category: "api-mock", target: "msw", packages: ["miragejs"] },
+  {
+    category: "lint-format",
+    target: "ESLint flat config + Prettier",
+    packages: [
+      "@biomejs/biome",
+      "rome",
+      "oxlint",
+      "standard",
+      "xo",
+      "ts-standard",
+      "eslint-config-airbnb",
+      "eslint-config-airbnb-typescript",
+      "eslint-config-standard",
+      "eslint-config-react-app",
+    ],
+  },
+  { category: "build-plugin", target: "@vitejs/plugin-react", packages: ["@vitejs/plugin-react-swc", "@vitejs/plugin-react-oxc"] },
+];
+
+// Client SDKs that carry the backend data contract. They stay, and shared/api creates their client once. With one of
+// them and no fetch() call, axios is not required.
+export const backendDataClientPackages = [
+  "@supabase/supabase-js",
+  "@supabase/ssr",
+  "firebase",
+  "appwrite",
+  "pocketbase",
+  "convex",
+  "@trpc/client",
+  "@trpc/react-query",
+  "@trpc/tanstack-react-query",
+  "@apollo/client",
+  "urql",
+  "graphql-request",
+  "aws-amplify",
+];
+// Auth and payment SDKs: they stay, but REST calls next to them still go through axios.
+export const serviceClientPackages = [
+  "@clerk/clerk-react",
+  "@auth0/auth0-react",
+  "@stripe/stripe-js",
+  "@stripe/react-stripe-js",
+];
+export const backendClientPackages = [...backendDataClientPackages, ...serviceClientPackages];
+
+// Server-side packages: when the frontend package declares one, it also contains backend code.
+export const backendServerPackages = [
+  "express",
+  "fastify",
+  "koa",
+  "@koa/router",
+  "hono",
+  "@hono/node-server",
+  "@nestjs/core",
+  "drizzle-orm",
+  "drizzle-kit",
+  "prisma",
+  "@prisma/client",
+  "mongoose",
+  "pg",
+  "postgres",
+  "mysql2",
+  "better-sqlite3",
+  "sqlite3",
+  "knex",
+  "sequelize",
+  "typeorm",
+  "socket.io",
+  "ws",
+  "passport",
+  "express-session",
+  "connect-pg-simple",
+  "memorystore",
+  "@neondatabase/serverless",
+  "json-server",
+];
+
+// Stack changes that are framework migrations, not alignment: eds align stops with exit 2.
+export const unsupportedFrameworks = [
+  ["next", "Next.js"],
+  ["@remix-run/react", "Remix"],
+  ["@react-router/dev", "React Router framework mode"],
+  ["@tanstack/react-start", "TanStack Start"],
+  ["gatsby", "Gatsby"],
+  ["astro", "Astro"],
+  ["expo", "Expo"],
+  ["react-native", "React Native"],
+  ["react-scripts", "Create React App"],
+  ["@docusaurus/core", "Docusaurus"],
+  ["vike", "Vike"],
+  ["waku", "Waku"],
+];
+
+// Top-level directories (of the frontend package or the repository) that hold backend or deployment code.
+export const backendDirectoryNames = [
+  "server",
+  "backend",
+  "api",
+  "functions",
+  "supabase",
+  "prisma",
+  "drizzle",
+  "migrations",
+  "db",
+  "database",
+  "convex",
+  "amplify",
+  "netlify",
+  "lambda",
+  "workers",
+];
+// A top-level shared/ is protected when backend code sits next to it (the server imports it).
+export const sharedWithBackendDirectoryName = "shared";
+
+// Backend, deployment and run configuration files at the top of the frontend package or the repository.
+export const backendMarkerFiles = [
+  "requirements.txt",
+  "pyproject.toml",
+  "Pipfile",
+  "poetry.lock",
+  "go.mod",
+  "Cargo.toml",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "Gemfile",
+  "composer.json",
+  "manage.py",
+  "drizzle.config.ts",
+  "drizzle.config.js",
+  "wrangler.toml",
+  "wrangler.json",
+  "wrangler.jsonc",
+  "vercel.json",
+  "netlify.toml",
+  "firebase.json",
+  ".firebaserc",
+  "Dockerfile",
+  "docker-compose.yml",
+  "docker-compose.yaml",
+  "compose.yml",
+  "compose.yaml",
+  "Procfile",
+  "nixpacks.toml",
+  ".replit",
+  "replit.nix",
+  "fly.toml",
+  "render.yaml",
+  "app.yaml",
+  "serverless.yml",
+  "amplify.yml",
+];
+
+// A script runs backend code when it names a backend runtime or tool, or a bundled server entry.
+export const backendScriptPattern =
+  /\b(?:nodemon|ts-node|uvicorn|gunicorn|flask|django-admin|python3?|drizzle-kit|prisma|supabase|wrangler|firebase|netlify|json-server|nest)\b|\bnode\s+(?:dist|build)\//;
+
+// Lockfiles at the repository root change when a workspace package installs dependencies.
+export const rootLockfiles = ["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"];
+
+export const testSupportHint = "테스트 코드는 정렬 대상이 아니므로 그대로 둡니다";
+
+// Where the usual prototype directories go. Keys are src/ top-level names (lower case).
+export const structureHints = {
+  app: "app/ (main.tsx · App.tsx · router/ · providers/ · styles/)",
+  pages: "pages/<domain>/<action>/page.tsx · pages/<name>/page.tsx (resource 밖 화면)",
+  routes: "pages/<domain>/<action>/page.tsx · pages/<name>/page.tsx (resource 밖 화면)",
+  views: "pages/<domain>/<action>/page.tsx · pages/<name>/page.tsx (resource 밖 화면)",
+  screens: "pages/<domain>/<action>/page.tsx · pages/<name>/page.tsx (resource 밖 화면)",
+  widgets: "widgets/<name>/",
+  layouts: "widgets/layout/",
+  layout: "widgets/layout/",
+  features: "features/<domain>/<feature>/{ui,lib,types}",
+  entities: "entities/<domain>/{components,hooks,services,stores,types,lib}",
+  shared: "shared/{api,assets,hooks,lib,ui}",
+  components: "widgets/<name> (화면 구획) · features/<domain>/<feature>/ui (사용자 행동) · entities/<domain>/components (도메인 표시) · shared/ui (범용)",
+  ui: "shared/ui/",
+  hooks: "shared/hooks (범용) · entities/<domain>/hooks (서버 데이터)",
+  lib: "shared/lib/ (cn은 shared/lib/utils, queryClient는 shared/api/queryClient.ts)",
+  utils: "shared/lib/utils/",
+  helpers: "shared/lib/",
+  api: "shared/api (axios instance·queryClient) · entities/<domain>/services (endpoint 함수)",
+  services: "entities/<domain>/services/<domain>Service.ts · shared/api",
+  requests: "entities/<domain>/services/",
+  store: "entities/<domain>/stores/ (zustand)",
+  stores: "entities/<domain>/stores/ (zustand)",
+  state: "entities/<domain>/stores/ (zustand)",
+  redux: "entities/<domain>/stores/ (zustand로 교체)",
+  slices: "entities/<domain>/stores/ (zustand로 교체)",
+  atoms: "entities/<domain>/stores/ (zustand로 교체)",
+  context: "app/providers (앱 전역) · features/<domain>/<feature>/lib (폼 context)",
+  contexts: "app/providers (앱 전역) · features/<domain>/<feature>/lib (폼 context)",
+  providers: "app/providers/",
+  router: "app/router/index.tsx",
+  routing: "app/router/index.tsx",
+  types: "entities/<domain>/types/api.ts (API 타입) · types/ (전역 선언만)",
+  interfaces: "entities/<domain>/types/",
+  models: "entities/<domain>/types/",
+  assets: "shared/assets/",
+  images: "shared/assets/",
+  icons: "shared/assets/ 또는 lucide-react",
+  fonts: "삭제 (EDS가 Pretendard를 제공)",
+  styles: "app/styles/index.css (전역) · Tailwind className (컴포넌트). eds sync가 만든 eds-tokens.css는 그대로 둡니다",
+  css: "app/styles/index.css (전역) · Tailwind className (컴포넌트)",
+  config: "shared/lib/ · entities/<domain>/types/enums.ts",
+  constants: "shared/lib/ · entities/<domain>/types/enums.ts",
+  consts: "shared/lib/ · entities/<domain>/types/enums.ts",
+  i18n: "shared/lib/ (기존 i18n 설정은 지우지 않고 옮깁니다. 새 문구는 「UI 문구」를 따릅니다)",
+  locales: "shared/lib/ (기존 번역 파일은 지우지 않고 옮깁니다)",
+  lang: "shared/lib/ (기존 번역 파일은 지우지 않고 옮깁니다)",
+  translations: "shared/lib/ (기존 번역 파일은 지우지 않고 옮깁니다)",
+  mocks: "mocks/<domain>/index.ts",
+  integrations: "shared/api/ (backend client SDK)",
+  "app.tsx": "app/App.tsx",
+  "app.jsx": "app/App.tsx",
+  "main.tsx": "app/main.tsx",
+  "main.jsx": "app/main.tsx",
+  "i18n.ts": "shared/lib/i18n.ts (기존 i18n 설정은 지우지 않고 옮깁니다)",
+  "i18n.tsx": "shared/lib/i18n.ts (기존 i18n 설정은 지우지 않고 옮깁니다)",
+  "i18n.js": "shared/lib/i18n.ts (기존 i18n 설정은 지우지 않고 옮깁니다)",
+  "i18n.jsx": "shared/lib/i18n.ts (기존 i18n 설정은 지우지 않고 옮깁니다)",
+  "index.tsx": "app/main.tsx",
+  "index.jsx": "app/main.tsx",
+  "index.css": "app/styles/index.css",
+  "app.css": "app/styles/index.css (컴포넌트 규칙은 className으로)",
+  "globals.css": "app/styles/index.css",
+  "global.css": "app/styles/index.css",
+  "vite-env.d.ts": "그대로 둡니다",
+};