create-fullstack-scaffold 0.1.0

package/template/eslint-rules/no-util-functions-in-service.js

@@ -0,0 +1,128 @@
+/**
+ * @framework-baseline 1c3ea2e294425001
+ */
+
+/**
+ * 自定义 ESLint 规则：禁止在业务文件中定义工具函数
+ *
+ * 工具函数应该放在 utils 目录中，而不是业务文件中
+ * 适用文件：
+ * - services/*-service.ts
+ * - routes/*-routes.ts
+ * - handlers/*.ts
+ * - stores/*.ts
+ */
+
+export const noUtilFunctionsInService = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow utility functions in business files. Move them to utils directory.',
+      recommended: true,
+    },
+    messages: {
+      utilFunctionInBusiness:
+        'Utility function "{{functionName}}" should be moved to utils directory.\n' +
+        'Business files should focus on domain logic, not utility functions.\n' +
+        'Create a new file in src/server/utils/ or add to an existing utility file.\n' +
+        'Example: src/server/utils/date.ts, src/server/utils/format.ts, src/server/utils/validate.ts',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+
+    const isBusinessFile =
+      (filename.includes('/services/') && filename.endsWith('-service.ts')) ||
+      (filename.includes('/routes/') && filename.endsWith('-routes.ts')) ||
+      (filename.includes('/handlers/') && filename.endsWith('.ts')) ||
+      (filename.includes('/stores/') && filename.endsWith('-store.ts'))
+
+    if (!isBusinessFile) {
+      return {}
+    }
+
+    const utilFunctionPatterns = [
+      /^to[A-Z]/,
+      /^format[A-Z]/,
+      /^parse[A-Z]/,
+      /^convert[A-Z]/,
+      /^generate[A-Z]/,
+      /^validate[A-Z]/,
+      /^sanitize[A-Z]/,
+      /^transform[A-Z]/,
+      /^normalize[A-Z]/,
+      /^encode[A-Z]/,
+      /^decode[A-Z]/,
+      /^serialize[A-Z]/,
+      /^deserialize[A-Z]/,
+      /^camelCase$/,
+      /^snakeCase$/,
+      /^kebabCase$/,
+      /^capitalize$/,
+      /^truncate$/,
+      /^debounce$/,
+      /^throttle$/,
+      /^deepClone$/,
+      /^deepEqual$/,
+      /^isObject$/,
+      /^isArray$/,
+      /^isString$/,
+      /^isNumber$/,
+      /^isBoolean$/,
+      /^isNull$/,
+      /^isUndefined$/,
+      /^isEmpty$/,
+      /^toISOString$/,
+      /^fromISOString$/,
+      /^formatDate$/,
+      /^parseDate$/,
+      /^getTimestamp$/,
+      /^slugify$/,
+      /^escapeHtml$/,
+      /^unescapeHtml$/,
+      /^trim$/,
+      /^clamp$/,
+      /^range$/,
+      /^unique$/,
+      /^flatten$/,
+      /^groupBy$/,
+      /^sortBy$/,
+      /^filterBy$/,
+      /^findBy$/,
+      /^pick$/,
+      /^omit$/,
+      /^merge$/,
+      /^clone$/,
+      /^isEqual$/,
+      /^hashPassword$/,
+      /^verifyPassword$/,
+      /^generateToken$/,
+      /^verifyToken$/,
+      /^encrypt$/,
+      /^decrypt$/,
+    ]
+
+    return {
+      FunctionDeclaration(node) {
+        if (!node.id || !node.id.name) return
+
+        const functionName = node.id.name
+
+        const isUtilFunction = utilFunctionPatterns.some(pattern => pattern.test(functionName))
+
+        if (isUtilFunction) {
+          context.report({
+            node,
+            messageId: 'utilFunctionInBusiness',
+            data: {
+              functionName,
+            },
+          })
+        }
+      },
+    }
+  },
+}
+
+export default noUtilFunctionsInService

package/template/eslint-rules/prefer-shared-types.js

@@ -0,0 +1,352 @@
+/**
+ * @framework-baseline 3d7fff2afc62da61
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs'
+import { resolve, join } from 'path'
+
+const SHARED_TYPES_CACHE = new Map()
+let cacheTimestamp = 0
+const CACHE_TTL = 5000
+
+function parseSchemaFile(content) {
+  const schemaMap = new Map()
+
+  const schemaVarMatch = content.matchAll(
+    /export\s+const\s+(\w+Schema)\s*=\s*z\.object\s*\(\s*\{([^}]+)\}/gs
+  )
+
+  for (const match of schemaVarMatch) {
+    const schemaName = match[1]
+    const fieldsBlock = match[2]
+
+    const fields = new Set()
+    const fieldMatches = fieldsBlock.matchAll(/(\w+)\s*:/g)
+    for (const fm of fieldMatches) {
+      fields.add(fm[1])
+    }
+
+    if (fields.size > 0) {
+      schemaMap.set(schemaName, fields)
+    }
+  }
+
+  const typeExportMatch = content.matchAll(
+    /export\s+type\s+(\w+)\s*=\s*z\.infer<typeof\s+(\w+Schema)>/g
+  )
+
+  const typeToSchema = new Map()
+  for (const match of typeExportMatch) {
+    const typeName = match[1]
+    const schemaName = match[2]
+    typeToSchema.set(typeName, schemaName)
+  }
+
+  return { schemaMap, typeToSchema }
+}
+
+function discoverSchemaFiles(cwd) {
+  const schemaFiles = []
+  const modulesDir = resolve(cwd, 'src/shared/modules')
+
+  if (!existsSync(modulesDir)) {
+    return schemaFiles
+  }
+
+  try {
+    const modules = readdirSync(modulesDir)
+    for (const moduleName of modules) {
+      const modulePath = join(modulesDir, moduleName)
+      if (!statSync(modulePath).isDirectory()) continue
+
+      const schemaPath = join(modulePath, 'schemas.ts')
+      if (existsSync(schemaPath)) {
+        schemaFiles.push(schemaPath)
+      }
+
+      const indexPath = join(modulePath, 'index.ts')
+      if (existsSync(indexPath)) {
+        schemaFiles.push(indexPath)
+      }
+    }
+  } catch {
+    // ignore read errors
+  }
+
+  return schemaFiles
+}
+
+function getSharedTypes(context) {
+  const now = Date.now()
+  if (SHARED_TYPES_CACHE.size > 0 && now - cacheTimestamp < CACHE_TTL) {
+    return SHARED_TYPES_CACHE
+  }
+
+  SHARED_TYPES_CACHE.clear()
+
+  const cwd = context.cwd || process.cwd()
+
+  const schemaFiles = discoverSchemaFiles(cwd)
+
+  const allTypeToSchema = new Map()
+  const allSchemaFields = new Map()
+
+  for (const filePath of schemaFiles) {
+    if (!existsSync(filePath)) continue
+
+    try {
+      const content = readFileSync(filePath, 'utf-8')
+      const { schemaMap, typeToSchema } = parseSchemaFile(content)
+
+      for (const [typeName, schemaName] of typeToSchema) {
+        allTypeToSchema.set(typeName, schemaName)
+      }
+
+      for (const [schemaName, fields] of schemaMap) {
+        allSchemaFields.set(schemaName, fields)
+      }
+    } catch {
+      // ignore read errors
+    }
+  }
+
+  for (const [typeName, schemaName] of allTypeToSchema) {
+    const fields = allSchemaFields.get(schemaName)
+    if (fields) {
+      SHARED_TYPES_CACHE.set(typeName, {
+        schemaName,
+        fields: [...fields],
+      })
+    }
+  }
+
+  cacheTimestamp = now
+  return SHARED_TYPES_CACHE
+}
+
+function calculateSimilarity(fields1, fields2) {
+  if (fields1.size === 0 || fields2.size === 0) return 0
+
+  const set1 = new Set(fields1)
+  const set2 = new Set(fields2)
+
+  const intersection = new Set([...set1].filter(x => set2.has(x)))
+  const union = new Set([...set1, ...set2])
+
+  return intersection.size / union.size
+}
+
+function generatePickOmitSuggestion(typeName, localFields, sharedTypeName, sharedFields) {
+  const localSet = new Set(localFields)
+  const sharedSet = new Set(sharedFields)
+
+  const intersection = [...localSet].filter(f => sharedSet.has(f))
+  const onlyInLocal = [...localSet].filter(f => !sharedSet.has(f))
+  const onlyInShared = [...sharedSet].filter(f => !localSet.has(f))
+
+  const suggestions = []
+
+  if (intersection.length === localSet.size && onlyInLocal.length === 0) {
+    suggestions.push(`import type { ${sharedTypeName} } from '@shared/schemas'`)
+  } else if (intersection.length > 0) {
+    if (onlyInShared.length <= 2 && onlyInLocal.length <= 2) {
+      const pickFields = intersection.map(f => `'${f}'`).join(', ')
+      const extraFields = onlyInLocal.map(f => `${f}: <type>`).join('; ')
+      suggestions.push(
+        `type ${typeName} = Pick<${sharedTypeName}, ${pickFields}>` +
+          (onlyInLocal.length > 0 ? ` & { ${extraFields} }` : '')
+      )
+    } else if (onlyInShared.length < intersection.length) {
+      const omitFields = onlyInShared.map(f => `'${f}'`).join(' | ')
+      const extraFields = onlyInLocal.map(f => `${f}: <type>`).join('; ')
+      suggestions.push(
+        `type ${typeName} = Omit<${sharedTypeName}, ${omitFields}>` +
+          (onlyInLocal.length > 0 ? ` & { ${extraFields} }` : '')
+      )
+    }
+  }
+
+  return suggestions
+}
+
+function extractFieldsFromTSInterface(node) {
+  const fields = new Set()
+
+  if (node.type !== 'TSInterfaceDeclaration') return null
+
+  for (const member of node.body.body) {
+    if (member.type === 'TSPropertySignature' && member.key?.type === 'Identifier') {
+      fields.add(member.key.name)
+    }
+  }
+
+  return fields
+}
+
+function extractFieldsFromTSTypeAlias(node, context) {
+  const fields = new Set()
+
+  if (node.type !== 'TSTypeAliasDeclaration') return null
+
+  const typeAnnotation = node.typeAnnotation
+
+  if (typeAnnotation?.type === 'TSTypeLiteral') {
+    for (const member of typeAnnotation.members) {
+      if (member.type === 'TSPropertySignature' && member.key?.type === 'Identifier') {
+        fields.add(member.key.name)
+      }
+    }
+  }
+
+  return fields.size > 0 ? fields : null
+}
+
+export const preferSharedTypes = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: '检测与 @shared/schemas 中结构相似的类型定义，建议直接导入或使用 Pick/Omit 派生',
+      recommended: true,
+    },
+    messages: {
+      similarTypeDetected:
+        '类型 "{{typeName}}" 的结构 (字段: {{fields}}) 与 @shared/schemas 中的 "{{sharedTypeName}}" (字段: {{sharedFields}}) 相似度 {{similarity}}%。\n' +
+        '建议使用 Pick/Omit 派生类型:\n' +
+        '{{suggestions}}',
+      duplicateTypeDetected:
+        '类型 "{{typeName}}" 已存在于 @shared/schemas 中。\n' +
+        '请直接导入: `import type { {{typeName}} } from "@shared/schemas"`',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          similarityThreshold: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1,
+            default: 0.6,
+          },
+          checkClientOnly: {
+            type: 'boolean',
+            default: true,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const options = context.options[0] || {}
+    const similarityThreshold = options.similarityThreshold ?? 0.6
+    const checkClientOnly = options.checkClientOnly ?? true
+
+    const filename = context.filename || context.getFilename?.() || ''
+
+    const isClientFile = filename.includes('/src/client/')
+    const isAdminFile = filename.includes('/src/admin/')
+    const isCliFile = filename.includes('/src/cli/')
+    const isSharedFile = filename.includes('/src/shared/')
+
+    if (checkClientOnly && !isClientFile && !isAdminFile && !isCliFile) return {}
+    if (isSharedFile) return {}
+
+    const sharedTypes = getSharedTypes(context)
+
+    return {
+      TSInterfaceDeclaration(node) {
+        const typeName = node.id?.name
+        if (!typeName) return
+
+        const fields = extractFieldsFromTSInterface(node)
+        if (!fields || fields.size === 0) return
+
+        if (sharedTypes.has(typeName)) {
+          context.report({
+            node,
+            messageId: 'duplicateTypeDetected',
+            data: { typeName },
+          })
+          return
+        }
+
+        for (const [sharedTypeName, info] of sharedTypes) {
+          const sharedFields = new Set(info.fields)
+          const similarity = calculateSimilarity(fields, sharedFields)
+
+          if (similarity >= similarityThreshold) {
+            const suggestions = generatePickOmitSuggestion(
+              typeName,
+              fields,
+              sharedTypeName,
+              sharedFields
+            )
+
+            context.report({
+              node,
+              messageId: 'similarTypeDetected',
+              data: {
+                typeName,
+                fields: [...fields].slice(0, 5).join(', ') + (fields.size > 5 ? '...' : ''),
+                sharedTypeName,
+                sharedFields:
+                  [...sharedFields].slice(0, 5).join(', ') + (sharedFields.size > 5 ? '...' : ''),
+                similarity: Math.round(similarity * 100),
+                suggestions: suggestions.length > 0 ? suggestions.join('\n') : '直接导入共享类型',
+              },
+            })
+            break
+          }
+        }
+      },
+
+      TSTypeAliasDeclaration(node) {
+        const typeName = node.id?.name
+        if (!typeName) return
+
+        const fields = extractFieldsFromTSTypeAlias(node, context)
+        if (!fields || fields.size === 0) return
+
+        if (sharedTypes.has(typeName)) {
+          context.report({
+            node,
+            messageId: 'duplicateTypeDetected',
+            data: { typeName },
+          })
+          return
+        }
+
+        for (const [sharedTypeName, info] of sharedTypes) {
+          const sharedFields = new Set(info.fields)
+          const similarity = calculateSimilarity(fields, sharedFields)
+
+          if (similarity >= similarityThreshold) {
+            const suggestions = generatePickOmitSuggestion(
+              typeName,
+              fields,
+              sharedTypeName,
+              sharedFields
+            )
+
+            context.report({
+              node,
+              messageId: 'similarTypeDetected',
+              data: {
+                typeName,
+                fields: [...fields].slice(0, 5).join(', ') + (fields.size > 5 ? '...' : ''),
+                sharedTypeName,
+                sharedFields:
+                  [...sharedFields].slice(0, 5).join(', ') + (sharedFields.size > 5 ? '...' : ''),
+                similarity: Math.round(similarity * 100),
+                suggestions: suggestions.length > 0 ? suggestions.join('\n') : '直接导入共享类型',
+              },
+            })
+            break
+          }
+        }
+      },
+    }
+  },
+}
+
+export default preferSharedTypes

package/template/eslint-rules/protect-ws-sse-interface.js

@@ -0,0 +1,66 @@
+/**
+ * @framework-baseline dbb0b78091cd9d47
+ */
+
+/**
+ * 自定义 ESLint 规则：保护 WS/SSE 客户端的核心接口
+ * 禁止随意添加新的公共方法
+ */
+
+export const protectWsSseInterface = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Protect WS/SSE client public interface from unauthorized modifications',
+      recommended: true,
+    },
+    messages: {
+      forbiddenMethodAddition:
+        'Adding new public methods to WSClientImpl/SSEClientImpl is not allowed.\n' +
+        'The interface is defined in src/types/global.d.ts and should not be extended.\n' +
+        'If you need new functionality, consider:\n' +
+        '  1. Adding a private method (prefix with # or private)\n' +
+        '  2. Creating a separate utility function\n' +
+        '  3. Updating the global.d.ts interface first',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+
+    const protectedMethods = {
+      WSClientImpl: ['status', 'call', 'emit', 'on', 'onStatusChange', 'close', 'getSocket'],
+      SSEClientImpl: ['status', 'on', 'onStatusChange', 'onError', 'abort'],
+    }
+
+    if (!filename.endsWith('wsClient.ts') && !filename.endsWith('sseClient.ts')) {
+      return {}
+    }
+
+    return {
+      MethodDefinition(node) {
+        const classBody = node.parent
+        const classDecl = classBody?.parent
+        const className = classDecl?.id?.name
+
+        if (!className || !protectedMethods[className]) return
+
+        if (
+          node.kind === 'method' &&
+          node.accessibility !== 'private' &&
+          !node.key.name.startsWith('#')
+        ) {
+          const methodName = node.key.name
+          if (!protectedMethods[className].includes(methodName)) {
+            context.report({
+              node,
+              messageId: 'forbiddenMethodAddition',
+            })
+          }
+        }
+      },
+    }
+  },
+}
+
+export default protectWsSseInterface

package/template/eslint-rules/require-antd-generic-types.js

@@ -0,0 +1,73 @@
+/**
+ * @framework-baseline 116dec37dbe7f2ca
+ */
+
+/**
+ * 自定义 ESLint 规则：强制 Antd 泛型组件必须传入类型参数
+ *
+ * Form.useForm<T>() 必须传入泛型类型
+ * Table<RecordType> 必须传入泛型类型
+ */
+
+export const requireAntdGenericTypes = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require generic type parameters for Antd Form.useForm() and Table components',
+      recommended: true,
+    },
+    messages: {
+      useFormMissingGeneric:
+        'Form.useForm() must have a generic type parameter.\n' +
+        'Example: const [form] = Form.useForm<MyFormValues>()\n' +
+        'This ensures type safety for form field values.',
+      tableMissingGeneric:
+        'Table component must have a generic type parameter for dataSource.\n' +
+        'Example: Table<UserData> or Table<RecordType>\n' +
+        'This ensures type safety for table data.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type === 'MemberExpression' &&
+          node.callee.object.type === 'Identifier' &&
+          node.callee.object.name === 'Form' &&
+          node.callee.property.type === 'Identifier' &&
+          node.callee.property.name === 'useForm'
+        ) {
+          const typeArgs = node.typeArguments || node.typeParameters
+          if (!typeArgs || typeArgs.params.length === 0) {
+            context.report({
+              node,
+              messageId: 'useFormMissingGeneric',
+            })
+          }
+        }
+      },
+      JSXElement(node) {
+        if (
+          node.openingElement.name.type === 'Identifier' &&
+          node.openingElement.name.name === 'Table'
+        ) {
+          const typeArgs = node.openingElement.typeArguments || node.openingElement.typeParameters
+          if (!typeArgs || typeArgs.params.length === 0) {
+            const hasDataSource = node.openingElement.attributes.some(
+              attr => attr.type === 'JSXAttribute' && attr.name.name === 'dataSource'
+            )
+            if (hasDataSource) {
+              context.report({
+                node: node.openingElement,
+                messageId: 'tableMissingGeneric',
+              })
+            }
+          }
+        }
+      },
+    }
+  },
+}
+
+export default requireAntdGenericTypes