create-react-admin-template 0.0.0-stage → 0.1.0

package/template/eslint.config.js

@@ -0,0 +1,697 @@
+import globals from 'globals'
+import js from '@eslint/js'
+import pluginQuery from '@tanstack/eslint-plugin-query'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import { defineConfig } from 'eslint/config'
+import nodePath from 'node:path'
+import tseslint from 'typescript-eslint'
+
+const strComponentOrHookPattern = '^(?:[A-Z]|use[A-Z])'
+const strPreservedTypePropertyPattern =
+  '^(?:[A-Z]|account$|phone$|password$|email$|confirmPassword$|children$|className$|ref$|id$|aria-describedby$|aria-invalid$|app$|api$|auth$|brand$|navigation$|storage$|observability$|release$|context$|location$|href$|redirect$|router$|env$|instance$|tableKey$|instanceKey$|config$|runtime$|controller$|tableProps$|operator$|value$|label$|color$|description$|disabled$|enabled$|name$|revision$|items$|total$|sortOrder$|metadata$|locale$|version$|enums$|parameters$|type$|onopen$|onmessage$|onerror$|onclose$)'
+const objTypePrefixes = {
+  boolean: 'b',
+  string: 'str',
+  number: 'n',
+  array: 'arr',
+  function: 'fn',
+}
+const arrTypedNamingRules = Object.entries(objTypePrefixes).flatMap(
+  ([strType, strPrefix]) => [
+    {
+      selector: ['variable', 'parameter'],
+      filter: { regex: strComponentOrHookPattern, match: false },
+      types: [strType],
+      format: ['PascalCase'],
+      leadingUnderscore: 'allow',
+      prefix: [strPrefix],
+    },
+    {
+      selector: 'typeProperty',
+      filter: { regex: strPreservedTypePropertyPattern, match: false },
+      types: [strType],
+      format: ['PascalCase'],
+      leadingUnderscore: 'allow',
+      prefix: [strPrefix],
+    },
+  ]
+)
+const objProjectNamingPlugin = {
+  rules: {
+    'public-types-in-types-file': {
+      meta: {
+        type: 'suggestion',
+        schema: [],
+        messages: {
+          misplacedPublicType:
+            'Exported TypeScript types must be declared in a types.ts file.',
+        },
+      },
+      create(objContext) {
+        if (
+          nodePath.basename(objContext.filename) === 'types.ts' ||
+          objContext.filename.endsWith('.d.ts')
+        ) {
+          return {}
+        }
+
+        return {
+          ExportNamedDeclaration(objNode) {
+            if (
+              objNode.declaration?.type !== 'TSInterfaceDeclaration' &&
+              objNode.declaration?.type !== 'TSTypeAliasDeclaration'
+            ) {
+              return
+            }
+
+            objContext.report({
+              node: objNode.declaration,
+              messageId: 'misplacedPublicType',
+            })
+          },
+        }
+      },
+    },
+    'no-direct-api-request': {
+      meta: {
+        type: 'problem',
+        schema: [],
+        messages: {
+          directRequest:
+            'Backend requests must use an OpenAPI-generated client instead of {{strClient}}.',
+        },
+      },
+      create(objContext) {
+        if (
+          objContext.filename.endsWith(
+            nodePath.join('src', 'config', 'runtimeConfig.ts')
+          )
+        ) {
+          return {}
+        }
+
+        const objAxiosImports = new Set()
+        const objAxiosClients = new Set()
+        const objRequestMethods = new Set([
+          'delete',
+          'get',
+          'patch',
+          'post',
+          'put',
+          'request',
+        ])
+
+        return {
+          ImportDeclaration(objNode) {
+            if (objNode.source.value !== 'axios') return
+            objNode.specifiers.forEach((objSpecifier) => {
+              if (objSpecifier.type === 'ImportDefaultSpecifier') {
+                objAxiosImports.add(objSpecifier.local.name)
+              }
+            })
+          },
+          VariableDeclarator(objNode) {
+            if (
+              objNode.id.type !== 'Identifier' ||
+              objNode.init?.type !== 'CallExpression' ||
+              objNode.init.callee.type !== 'MemberExpression' ||
+              objNode.init.callee.object.type !== 'Identifier' ||
+              objNode.init.callee.property.type !== 'Identifier' ||
+              !objAxiosImports.has(objNode.init.callee.object.name) ||
+              objNode.init.callee.property.name !== 'create'
+            ) {
+              return
+            }
+            objAxiosClients.add(objNode.id.name)
+          },
+          CallExpression(objNode) {
+            if (
+              objNode.callee.type === 'Identifier' &&
+              objNode.callee.name === 'fetch'
+            ) {
+              objContext.report({
+                node: objNode,
+                messageId: 'directRequest',
+                data: { strClient: 'fetch' },
+              })
+              return
+            }
+            if (
+              objNode.callee.type !== 'MemberExpression' ||
+              objNode.callee.object.type !== 'Identifier' ||
+              objNode.callee.property.type !== 'Identifier' ||
+              !objRequestMethods.has(objNode.callee.property.name)
+            ) {
+              return
+            }
+
+            const strClient = objNode.callee.object.name
+            if (
+              objAxiosImports.has(strClient) ||
+              objAxiosClients.has(strClient)
+            ) {
+              objContext.report({
+                node: objNode,
+                messageId: 'directRequest',
+                data: { strClient },
+              })
+            }
+          },
+        }
+      },
+    },
+    'no-hyphenated-path': {
+      meta: {
+        type: 'problem',
+        schema: [],
+        messages: {
+          hyphenatedPath:
+            'Project path segment "{{strSegment}}" must not contain hyphens.',
+        },
+      },
+      create(objContext) {
+        return {
+          Program(objNode) {
+            const strRelativePath = nodePath.relative(
+              import.meta.dirname,
+              objContext.filename
+            )
+            const strUiPath = nodePath.join('src', 'components', 'ui')
+
+            if (
+              strRelativePath === nodePath.join('src', 'vite-env.d.ts') ||
+              strRelativePath.startsWith(`${strUiPath}${nodePath.sep}`)
+            ) {
+              return
+            }
+
+            const strInvalidSegment = strRelativePath
+              .split(nodePath.sep)
+              .find((strSegment) => strSegment.includes('-'))
+
+            if (strInvalidSegment) {
+              objContext.report({
+                node: objNode,
+                messageId: 'hyphenatedPath',
+                data: { strSegment: strInvalidSegment },
+              })
+            }
+          },
+        }
+      },
+    },
+    'feature-boundaries': {
+      meta: {
+        type: 'problem',
+        schema: [],
+        messages: {
+          privateFeatureImport:
+            'Feature "{{strFeature}}" internals are private. Import from "@/features/{{strFeature}}" instead.',
+          relativeCrossFeatureImport:
+            'Cross-Feature imports must use the target Feature public entry "@/features/{{strFeature}}".',
+          reverseApplicationDependency:
+            'Feature code must not depend on the application layer "{{strImportPath}}". Move shared policy below the Feature boundary or inject it from composition.',
+        },
+      },
+      create(objContext) {
+        const strSourceRoot = nodePath.join(import.meta.dirname, 'src')
+        const strFeaturesRoot = nodePath.join(strSourceRoot, 'features')
+        const strRelativeFeatureFile = nodePath.relative(
+          strFeaturesRoot,
+          objContext.filename
+        )
+        const bIsFeatureFile =
+          strRelativeFeatureFile !== '' &&
+          !strRelativeFeatureFile.startsWith(`..${nodePath.sep}`) &&
+          strRelativeFeatureFile !== '..' &&
+          !nodePath.isAbsolute(strRelativeFeatureFile)
+        const strCurrentFeature = bIsFeatureFile
+          ? strRelativeFeatureFile.split(nodePath.sep)[0]
+          : undefined
+        const arrApplicationPrefixes = [
+          '@/Application',
+          '@/layouts',
+          '@/main',
+          '@/router',
+        ]
+
+        function fnCheckImport(objNode, strImportPath) {
+          if (
+            strCurrentFeature &&
+            arrApplicationPrefixes.some(
+              (strPrefix) =>
+                strImportPath === strPrefix ||
+                strImportPath.startsWith(`${strPrefix}.`) ||
+                strImportPath.startsWith(`${strPrefix}/`)
+            )
+          ) {
+            objContext.report({
+              node: objNode,
+              messageId: 'reverseApplicationDependency',
+              data: { strImportPath },
+            })
+            return
+          }
+
+          if (strImportPath.startsWith('@/features/')) {
+            const arrFeaturePath = strImportPath
+              .slice('@/features/'.length)
+              .split('/')
+              .filter(Boolean)
+            const strTargetFeature = arrFeaturePath[0]
+
+            if (
+              strTargetFeature &&
+              strTargetFeature !== strCurrentFeature &&
+              arrFeaturePath.length > 1
+            ) {
+              objContext.report({
+                node: objNode,
+                messageId: 'privateFeatureImport',
+                data: { strFeature: strTargetFeature },
+              })
+            }
+            return
+          }
+
+          if (!strCurrentFeature || !strImportPath.startsWith('.')) return
+
+          const strTargetPath = nodePath.resolve(
+            nodePath.dirname(objContext.filename),
+            strImportPath
+          )
+          const strRelativeSourceTarget = nodePath.relative(
+            strSourceRoot,
+            strTargetPath
+          )
+          const strTargetSourceSegment = strRelativeSourceTarget.split(
+            nodePath.sep
+          )[0]
+
+          if (
+            strTargetSourceSegment === 'Application' ||
+            strTargetSourceSegment === 'layouts' ||
+            strTargetSourceSegment === 'main' ||
+            strTargetSourceSegment === 'router'
+          ) {
+            objContext.report({
+              node: objNode,
+              messageId: 'reverseApplicationDependency',
+              data: { strImportPath },
+            })
+            return
+          }
+
+          const strRelativeTarget = nodePath.relative(
+            strFeaturesRoot,
+            strTargetPath
+          )
+
+          if (
+            strRelativeTarget === '..' ||
+            strRelativeTarget.startsWith(`..${nodePath.sep}`) ||
+            nodePath.isAbsolute(strRelativeTarget)
+          ) {
+            return
+          }
+
+          const strTargetFeature = strRelativeTarget.split(nodePath.sep)[0]
+          if (strTargetFeature !== strCurrentFeature) {
+            objContext.report({
+              node: objNode,
+              messageId: 'relativeCrossFeatureImport',
+              data: { strFeature: strTargetFeature },
+            })
+          }
+        }
+
+        function fnCheckSource(objNode) {
+          if (typeof objNode.source?.value === 'string') {
+            fnCheckImport(objNode, objNode.source.value)
+          }
+        }
+
+        return {
+          ExportAllDeclaration: fnCheckSource,
+          ExportNamedDeclaration: fnCheckSource,
+          ImportDeclaration: fnCheckSource,
+          ImportExpression: fnCheckSource,
+        }
+      },
+    },
+    'component-boundaries': {
+      meta: {
+        type: 'problem',
+        schema: [],
+        messages: {
+          privateOwnedComponentImport:
+            'Owned component "{{strComponent}}" internals are private. Import from "@/components/{{strComponent}}" instead.',
+        },
+      },
+      create(objContext) {
+        const strSourceRoot = nodePath.join(import.meta.dirname, 'src')
+        const strRelativeSourceFile = nodePath.relative(
+          strSourceRoot,
+          objContext.filename
+        )
+        if (
+          strRelativeSourceFile === '..' ||
+          strRelativeSourceFile.startsWith(`..${nodePath.sep}`) ||
+          nodePath.isAbsolute(strRelativeSourceFile)
+        ) {
+          return {}
+        }
+
+        const strComponentsRoot = nodePath.join(strSourceRoot, 'components')
+        const arrOwnedComponents = ['AppPageForm', 'AppTable']
+
+        function fnReportPrivateImport(objNode, strComponent) {
+          objContext.report({
+            node: objNode,
+            messageId: 'privateOwnedComponentImport',
+            data: { strComponent },
+          })
+        }
+
+        function fnCheckImport(objNode, strImportPath) {
+          if (strImportPath.startsWith('@/components/')) {
+            const arrPathSegments = strImportPath
+              .slice('@/components/'.length)
+              .split('/')
+              .filter(Boolean)
+            const strComponent = arrPathSegments[0]
+            if (
+              strComponent &&
+              arrOwnedComponents.includes(strComponent) &&
+              arrPathSegments.length > 1 &&
+              !objContext.filename.startsWith(
+                `${nodePath.join(strComponentsRoot, strComponent)}${nodePath.sep}`
+              )
+            ) {
+              fnReportPrivateImport(objNode, strComponent)
+            }
+            return
+          }
+
+          if (!strImportPath.startsWith('.')) return
+          const strTargetPath = nodePath.resolve(
+            nodePath.dirname(objContext.filename),
+            strImportPath
+          )
+
+          for (const strComponent of arrOwnedComponents) {
+            const strComponentRoot = nodePath.join(
+              strComponentsRoot,
+              strComponent
+            )
+            const bIsOwnedFile = objContext.filename.startsWith(
+              `${strComponentRoot}${nodePath.sep}`
+            )
+            const bTargetsPrivatePath =
+              strTargetPath.startsWith(`${strComponentRoot}${nodePath.sep}`) &&
+              strTargetPath !== strComponentRoot
+            if (!bIsOwnedFile && bTargetsPrivatePath) {
+              fnReportPrivateImport(objNode, strComponent)
+              return
+            }
+          }
+        }
+
+        function fnCheckSource(objNode) {
+          if (typeof objNode.source?.value === 'string') {
+            fnCheckImport(objNode, objNode.source.value)
+          }
+        }
+
+        return {
+          ExportAllDeclaration: fnCheckSource,
+          ExportNamedDeclaration: fnCheckSource,
+          ImportDeclaration: fnCheckSource,
+          ImportExpression: fnCheckSource,
+        }
+      },
+    },
+  },
+}
+
+export default defineConfig(
+  {
+    ignores: [
+      '.artifacts',
+      'packages/create-react-admin-template/template',
+      'dist',
+      'src/api/generated',
+      'src/components/ui',
+      // 生成器模板由 TypeScript 校验；写出的 Feature 再接受完整应用 ESLint 规则。
+      'tools/scaffold/templates/feature',
+    ],
+  },
+  {
+    extends: [js.configs.recommended],
+    files: ['**/*.{js,mjs,cjs}'],
+    languageOptions: {
+      globals: globals.node,
+    },
+  },
+  {
+    extends: [
+      js.configs.recommended,
+      ...tseslint.configs.recommended,
+      ...pluginQuery.configs['flat/recommended'],
+    ],
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    plugins: {
+      'project-naming': objProjectNamingPlugin,
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+      'no-unused-vars': 'off',
+      'project-naming/no-direct-api-request': 'error',
+      'project-naming/component-boundaries': 'error',
+      'project-naming/feature-boundaries': 'error',
+      'project-naming/no-hyphenated-path': 'error',
+      'project-naming/public-types-in-types-file': 'error',
+      '@typescript-eslint/no-explicit-any': [
+        'error',
+        { fixToUnknown: false, ignoreRestArgs: false },
+      ],
+      '@typescript-eslint/no-restricted-types': [
+        'error',
+        {
+          types: {
+            unknown: {
+              message:
+                'Do not use unknown in application code. Define a concrete type, or keep unknown inside an explicitly allowed external-data boundary.',
+            },
+          },
+        },
+      ],
+      '@typescript-eslint/naming-convention': [
+        'error',
+        {
+          selector: 'interface',
+          filter: {
+            regex:
+              '^(?:AxiosRequestConfig|AxiosResponse|ImportMeta|ImportMetaEnv|Register|StaticDataRouteOption)$',
+            match: false,
+          },
+          format: ['PascalCase'],
+          prefix: ['I'],
+        },
+        {
+          selector: 'typeAlias',
+          format: ['PascalCase'],
+          prefix: ['T'],
+        },
+        {
+          selector: 'function',
+          filter: {
+            regex: '^(?:[A-Z]|use[A-Z]|cn$)',
+            match: false,
+          },
+          format: ['PascalCase'],
+          prefix: ['fn'],
+        },
+        ...arrTypedNamingRules,
+        {
+          selector: ['variable', 'parameter'],
+          filter: { regex: strComponentOrHookPattern, match: false },
+          format: ['PascalCase'],
+          leadingUnderscore: 'allow',
+          prefix: ['obj'],
+        },
+        {
+          selector: 'typeProperty',
+          filter: {
+            regex: strPreservedTypePropertyPattern,
+            match: false,
+          },
+          format: ['PascalCase'],
+          leadingUnderscore: 'allow',
+          prefix: ['obj'],
+        },
+      ],
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          args: 'all',
+          argsIgnorePattern: '^_',
+          caughtErrors: 'all',
+          caughtErrorsIgnorePattern: '^_',
+          destructuredArrayIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          ignoreRestSiblings: true,
+        },
+      ],
+      // Enforce type-only imports for TypeScript types
+      '@typescript-eslint/consistent-type-imports': [
+        'error',
+        {
+          prefer: 'type-imports',
+          fixStyle: 'inline-type-imports',
+          disallowTypeAnnotations: false,
+        },
+      ],
+      // Prevent duplicate imports from the same module
+      'no-duplicate-imports': 'error',
+    },
+  },
+  {
+    files: ['src/**/*.{ts,tsx}', 'tests/**/*.{ts,tsx}'],
+    ignores: [
+      'src/api/**',
+      'src/config/runtimeConfig.ts',
+      'src/components/layout/AppSidebar.tsx',
+      'src/pageFilters/**',
+    ],
+    rules: {
+      // 防止依赖声明中的 any 静默传播到普通业务代码。
+      '@typescript-eslint/no-unsafe-argument': 'error',
+      '@typescript-eslint/no-unsafe-assignment': 'error',
+      '@typescript-eslint/no-unsafe-call': 'error',
+      '@typescript-eslint/no-unsafe-member-access': 'error',
+      '@typescript-eslint/no-unsafe-return': 'error',
+      '@typescript-eslint/use-unknown-in-catch-callback-variable': 'error',
+    },
+  },
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    ignores: ['src/components/AppDialog/**', 'src/components/ui/**'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          paths: [
+            {
+              name: '@/components/ui/dialog',
+              message:
+                'Application dialogs must use the shared @/components/AppDialog wrapper.',
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    files: [
+      'src/components/AppPageForm/**/*.{ts,tsx}',
+      'src/components/AppTable/**/*.{ts,tsx}',
+    ],
+    rules: {
+      // 基础组件遵循上游领域命名；业务层匈牙利命名不应触发大规模无语义重命名。
+      '@typescript-eslint/naming-convention': 'off',
+      // 内部领域类型可与实现共置，组件根入口仍是唯一对外公共边界。
+      'project-naming/public-types-in-types-file': 'off',
+      // 表单值、表格单元格和第三方网格输入必须从 unknown 开始收窄。
+      '@typescript-eslint/no-restricted-types': 'off',
+      // 泛型表单值与 Handsontable 的声明会传播第三方 any；显式 any 仍单独禁止。
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
+    },
+  },
+  {
+    files: [
+      'src/components/AppPageForm/PageForm.tsx',
+      'src/components/AppTable/preference/useTablePreference.ts',
+      'src/components/AppTable/table/grid/useTableGrid.ts',
+    ],
+    rules: {
+      // 这些文件向渲染回调传递稳定命令或延迟读取 ref 的 getter，并未在渲染期读取 current。
+      'react-hooks/refs': 'off',
+    },
+  },
+  {
+    files: [
+      'src/components/AppTable/pagination/TablePaginationBar.tsx',
+      'src/components/AppTable/search/useTableQuery.ts',
+      'src/components/AppTable/table/layout/useResizablePanel.ts',
+      'src/components/AppTable/table/layout/useTablePanels.ts',
+      'src/components/AppTable/table/layout/useTableTheme.ts',
+    ],
+    rules: {
+      // 受控配置变化需要同步本地草稿或外部控制器，属于明确的状态协调边界。
+      'react-hooks/set-state-in-effect': 'off',
+    },
+  },
+  {
+    files: [
+      'src/components/AppTable/cell/frameworkCell/cellComponentSession.ts',
+      'src/components/AppTable/config/types.ts',
+    ],
+    rules: {
+      // 异构 React 组件注册表需要擦除值泛型；读取时仍通过具体 Props 恢复类型。
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
+  {
+    files: ['src/api/authClient.ts'],
+    rules: {
+      // 认证适配器是有意维护的窄 HTTP 边界，不属于业务请求调用点。
+      'project-naming/no-direct-api-request': 'off',
+    },
+  },
+  {
+    files: [
+      'src/api/authClient.ts',
+      'src/api/ApiError.ts',
+      'src/api/authSession.ts',
+      'src/api/hooks/**/*.ts',
+      'src/api/types.ts',
+      'src/config/runtimeConfig.ts',
+      'src/lib/navigationRedirect.ts',
+      'src/pageFilters/**/*.ts',
+      'src/router/config.ts',
+      'src/router/searchSchemas.ts',
+      'tests/**/*.{ts,tsx}',
+    ],
+    rules: {
+      // 外部响应、路由输入、通用表单/表格值与第三方测试桩必须先以 unknown 接收，再显式收窄。
+      '@typescript-eslint/no-restricted-types': 'off',
+    },
+  },
+  {
+    files: ['tests/**/*.{ts,tsx}'],
+    rules: {
+      // 白盒单元测试可直接覆盖 Feature 内部行为，不因此扩大生产公共 API。
+      'project-naming/feature-boundaries': 'off',
+    },
+  }
+)