create-fullstack-scaffold 0.1.0

package/template/eslint-rules/__tests__/no-new-old-service-naming.test.ts

@@ -0,0 +1,76 @@
+import { RuleTester } from 'eslint'
+import { noNewOldServiceNaming } from '../no-new-old-service-naming.js'
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+  },
+})
+
+ruleTester.run('no-new-old-service-naming', noNewOldServiceNaming, {
+  valid: [
+    // 合法的版本号命名
+    {
+      code: 'const service = {}',
+      filename: 'permission-service-V1.ts',
+    },
+    {
+      code: 'const service = {}',
+      filename: 'user-service-V2.ts',
+    },
+    {
+      code: 'const service = {}',
+      filename: 'order-service-V10.ts',
+    },
+    // 正常的命名
+    {
+      code: 'const newUser = {}',
+      filename: 'user-service.ts',
+    },
+    {
+      code: 'const renewed = true',
+      filename: 'order-service.ts',
+    },
+  ],
+  invalid: [
+    // 文件名包含 -new
+    {
+      code: 'const service = {}',
+      filename: 'permission-service-new.ts',
+      errors: [{ messageId: 'noNewOldInFilename' }],
+    },
+    // 文件名包含 -old
+    {
+      code: 'const service = {}',
+      filename: 'permission-service-old.ts',
+      errors: [{ messageId: 'noNewOldInFilename' }],
+    },
+    // 文件名包含 .new.
+    {
+      code: 'const service = {}',
+      filename: 'permission.new.service.ts',
+      errors: [{ messageId: 'noNewOldInFilename' }],
+    },
+    // 代码中包含 干new
+    {
+      code: 'const pattern = "干new"',
+      filename: 'service.ts',
+      errors: [{ messageId: 'noNewOldInContent' }],
+    },
+    // 代码中包含 干old
+    {
+      code: 'const pattern = "干old"',
+      filename: 'service.ts',
+      errors: [{ messageId: 'noNewOldInContent' }],
+    },
+    // 标识符包含 _old
+    {
+      code: 'const service_old = {}',
+      filename: 'test.ts',
+      errors: [{ messageId: 'noNewOldSuffix' }],
+    },
+  ],
+})
+
+console.log('All tests passed!')

package/template/eslint-rules/e2e-test-location.js

@@ -0,0 +1,153 @@
+/**
+ * @framework-baseline 57f760912fa6ecd4
+ */
+
+/**
+ * 约束E2E测试文件的位置和命名
+ * 1. E2E测试文件必须放在 tests/e2e/ 目录下
+ * 2. E2E测试文件必须以 .spec.ts 结尾
+ * 3. E2E测试文件必须使用 Playwright 的测试API
+ */
+
+export const e2eTestLocation = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '约束E2E测试文件的位置和命名',
+      recommended: true,
+    },
+    messages: {
+      wrongLocation: 'E2E测试文件必须放在 tests/e2e/ 目录下，当前文件: {{filename}}',
+      wrongExtension: 'E2E测试文件必须以 .spec.ts 结尾，当前文件: {{filename}}',
+      missingTestApi: 'E2E测试文件必须使用 Playwright 的测试API (test/describe)',
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const isE2ETestFile = filename.includes('/tests/e2e/') || filename.includes('tests/e2e')
+    const hasSpecExtension = filename.endsWith('.spec.ts')
+    const isSpecialFile =
+      filename.endsWith('playwright.config.ts') ||
+      filename.endsWith('global-setup.ts') ||
+      filename.endsWith('global-teardown.ts')
+
+    return {
+      Program(node) {
+        if (isSpecialFile) return
+
+        // 检查文件是否在正确的目录下
+        if (!isE2ETestFile && hasSpecExtension) {
+          context.report({
+            node,
+            messageId: 'wrongLocation',
+            data: { filename },
+          })
+        }
+
+        // 检查文件扩展名
+        if (isE2ETestFile && !hasSpecExtension) {
+          context.report({
+            node,
+            messageId: 'wrongExtension',
+            data: { filename },
+          })
+        }
+
+        // 检查是否使用了Playwright的测试API
+        if (isE2ETestFile && !hasSpecExtension) {
+          const hasTestApi = node.body.some(statement => {
+            if (statement.type === 'ImportDeclaration') {
+              return statement.source.value === '@playwright/test'
+            }
+            if (
+              statement.type === 'ExpressionStatement' &&
+              statement.expression.type === 'CallExpression'
+            ) {
+              const callee = statement.expression.callee
+              return (
+                callee.type === 'Identifier' &&
+                (callee.name === 'test' || callee.name === 'describe')
+              )
+            }
+            return false
+          })
+
+          if (!hasTestApi) {
+            context.report({
+              node,
+              messageId: 'missingTestApi',
+            })
+          }
+        }
+      },
+    }
+  },
+}
+
+/**
+ * 禁止在非 e2e 目录下使用 Playwright 测试API进行E2E测试
+ */
+export const noE2ETestOutsideDir = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '禁止在非 e2e 目录下使用 Playwright 测试API进行E2E测试',
+      recommended: true,
+    },
+    messages: {
+      noE2ETestOutsideDir: 'E2E测试必须放在 tests/e2e/ 目录下',
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const isE2ETestFile = filename.includes('/tests/e2e/') || filename.includes('tests/e2e')
+    const isSpecialFile =
+      filename.endsWith('playwright.config.ts') ||
+      filename.endsWith('global-setup.ts') ||
+      filename.endsWith('global-teardown.ts')
+
+    return {
+      ImportDeclaration(node) {
+        if (isE2ETestFile || isSpecialFile) return
+
+        if (node.source.value === '@playwright/test') {
+          context.report({
+            node,
+            messageId: 'noE2ETestOutsideDir',
+          })
+        }
+      },
+      CallExpression(node) {
+        if (isE2ETestFile || isSpecialFile) return
+
+        if (
+          node.callee.type === 'Identifier' &&
+          (node.callee.name === 'test' || node.callee.name === 'describe')
+        ) {
+          // 检查是否在测试文件中
+          if (
+            filename.endsWith('.test.ts') ||
+            filename.endsWith('.test.tsx') ||
+            filename.endsWith('.spec.ts')
+          ) {
+            // 检查是否导入了 Playwright
+            let currentNode = node.parent
+            while (currentNode.type !== 'Program') {
+              if (
+                currentNode.type === 'ImportDeclaration' &&
+                currentNode.source.value === '@playwright/test'
+              ) {
+                context.report({
+                  node,
+                  messageId: 'noE2ETestOutsideDir',
+                })
+                break
+              }
+              currentNode = currentNode.parent
+            }
+          }
+        }
+      },
+    }
+  },
+}

package/template/eslint-rules/enforce-valid-method.js

@@ -0,0 +1,217 @@
+/**
+ * @framework-baseline a46dbed45beaa561
+ */
+
+/**
+ * ESLint 规则：强制在 OpenAPI 路由中使用正确的 c.req.valid() 方法
+ *
+ * 根据 route definition 中的 request schema 自动推导应该使用的 valid 方法：
+ * - request.body (application/json) -> c.req.valid('json') 或 c.req.valid('body')
+ * - request.body (multipart/form-data) -> c.req.parseBody() 或 c.req.valid('form')
+ * - request.query -> c.req.valid('query')
+ * - request.params -> c.req.valid('param')
+ * - request.headers -> c.req.valid('header')
+ * - request.cookies -> c.req.valid('cookie')
+ *
+ * 同时禁止使用原始方法：c.req.json(), c.req.query(), c.req.param(), c.req.header()
+ */
+
+export const enforceValidMethod = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        '强制在 OpenAPI 路由 handler 中使用 c.req.valid() 获取校验后的参数，禁止使用原始方法',
+      recommended: true,
+    },
+    messages: {
+      useValidMethod:
+        "路由定义了 {{schemaType}}，请使用 c.req.valid('{{validMethod}}') 获取校验后的参数。\n" +
+        '原始方法 c.req.{{originalMethod}}() 不会进行 Zod 校验，也无法获得类型推断。',
+      missingValidCall:
+        "路由定义了 {{schemaType}}，但 handler 中未调用 c.req.valid('{{validMethod}}')。",
+      forbiddenRawMethod:
+        '在 OpenAPI 路由中禁止使用 c.req.{{method}}()。\n' +
+        '请根据路由定义使用对应的 c.req.valid() 方法：\n' +
+        "  - body (json) -> c.req.valid('json') 或 c.req.valid('body')\n" +
+        "  - body (form) -> c.req.parseBody() 或 c.req.valid('form')\n" +
+        "  - query -> c.req.valid('query')\n" +
+        "  - params -> c.req.valid('param')\n" +
+        "  - headers -> c.req.valid('header')\n" +
+        "  - cookies -> c.req.valid('cookie')",
+      unusedSchema:
+        "路由定义了 {{schemaType}}，但 handler 中未使用 c.req.valid('{{validMethod}}') 获取数据。",
+      useParseBodyForMultipart:
+        "路由定义了 multipart/form-data body，请使用 c.req.valid('form') 或 c.req.parseBody() 获取表单数据。",
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename?.() || ''
+    const isRouteFile =
+      /module-.*\/routes\/.*\.ts$/.test(filename) && !filename.includes('__tests__')
+    if (!isRouteFile) return {}
+
+    const routeDefinitions = new Map()
+    const VALID_METHOD_MAP = {
+      body: ['json', 'body'],
+      query: ['query'],
+      params: ['param'],
+      headers: ['header'],
+      cookies: ['cookie'],
+      form: ['form'],
+    }
+
+    const SCHEMA_TYPE_NAMES = {
+      body: 'request.body',
+      query: 'request.query',
+      params: 'request.params',
+      headers: 'request.headers',
+      cookies: 'request.cookies',
+    }
+
+    function extractRequestSchemas(routeNode) {
+      const schemas = new Set()
+      const bodyContentTypes = new Set()
+
+      if (!routeNode || routeNode.type !== 'ObjectExpression') return { schemas, bodyContentTypes }
+
+      const requestProp = routeNode.properties.find(
+        p => p.key?.type === 'Identifier' && p.key.name === 'request'
+      )
+
+      if (!requestProp || requestProp.value?.type !== 'ObjectExpression')
+        return { schemas, bodyContentTypes }
+
+      for (const prop of requestProp.value.properties) {
+        if (prop.key?.type === 'Identifier') {
+          const key = prop.key.name
+          if (['body', 'query', 'params', 'headers', 'cookies'].includes(key)) {
+            schemas.add(key)
+          }
+          if (key === 'body' && prop.value?.type === 'ObjectExpression') {
+            const contentProp = prop.value.properties.find(
+              p => p.key?.type === 'Identifier' && p.key.name === 'content'
+            )
+            if (contentProp?.value?.type === 'ObjectExpression') {
+              for (const contentKey of contentProp.value.properties) {
+                if (
+                  contentKey.key?.type === 'Literal' &&
+                  typeof contentKey.key.value === 'string'
+                ) {
+                  bodyContentTypes.add(contentKey.key.value)
+                }
+              }
+            }
+          }
+        }
+      }
+
+      return { schemas, bodyContentTypes }
+    }
+
+    function checkOpenapiHandler(node, routeArg, handlerArg) {
+      let schemas = new Set()
+      let bodyContentTypes = new Set()
+
+      if (routeArg.type === 'Identifier') {
+        const routeInfo = routeDefinitions.get(routeArg.name)
+        if (routeInfo) {
+          schemas = routeInfo.schemas
+          bodyContentTypes = routeInfo.bodyContentTypes
+        }
+      } else if (routeArg.type === 'ObjectExpression') {
+        const extracted = extractRequestSchemas(routeArg)
+        schemas = extracted.schemas
+        bodyContentTypes = extracted.bodyContentTypes
+      }
+
+      if (schemas.size === 0) return
+
+      const handlerText = context.sourceCode.getText(handlerArg)
+      const usedValidMethods = new Set()
+      const validMethodRegex = /c\.req\.valid\s*\(\s*['"](\w+)['"]\s*\)/g
+      let match
+      while ((match = validMethodRegex.exec(handlerText)) !== null) {
+        usedValidMethods.add(match[1])
+      }
+
+      const hasParseBody = /c\.req\.parseBody\s*\(/.test(handlerText)
+
+      const rawMethodRegex = /c\.req\.(json|query|param|header|cookie)\s*\(/g
+      const rawMethodsUsed = new Set()
+      while ((match = rawMethodRegex.exec(handlerText)) !== null) {
+        rawMethodsUsed.add(match[1])
+      }
+
+      if (rawMethodsUsed.size > 0) {
+        for (const method of rawMethodsUsed) {
+          context.report({
+            node: handlerArg,
+            messageId: 'forbiddenRawMethod',
+            data: { method },
+          })
+        }
+        return
+      }
+
+      const isMultipartFormData = Array.from(bodyContentTypes).some(type =>
+        type.startsWith('multipart/form-data')
+      )
+
+      for (const schema of schemas) {
+        if (schema === 'body' && isMultipartFormData) {
+          if (!hasParseBody && !usedValidMethods.has('form')) {
+            context.report({
+              node: handlerArg,
+              messageId: 'useParseBodyForMultipart',
+            })
+          }
+        } else {
+          const validMethods = VALID_METHOD_MAP[schema] || []
+          const isUsed = validMethods.some(m => usedValidMethods.has(m))
+
+          if (!isUsed) {
+            context.report({
+              node: handlerArg,
+              messageId: 'unusedSchema',
+              data: {
+                schemaType: SCHEMA_TYPE_NAMES[schema],
+                validMethod: validMethods[0],
+              },
+            })
+          }
+        }
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        if (
+          node.callee?.type === 'Identifier' &&
+          node.callee.name === 'createRoute' &&
+          node.arguments.length > 0 &&
+          node.parent?.type === 'VariableDeclarator'
+        ) {
+          const routeName = node.parent.id?.name
+          if (routeName) {
+            const extracted = extractRequestSchemas(node.arguments[0])
+            if (extracted.schemas.size > 0) {
+              routeDefinitions.set(routeName, extracted)
+            }
+          }
+        }
+
+        if (
+          node.callee?.type === 'MemberExpression' &&
+          node.callee.property?.name === 'openapi' &&
+          node.arguments.length >= 2
+        ) {
+          checkOpenapiHandler(node, node.arguments[0], node.arguments[1])
+        }
+      },
+    }
+  },
+}
+
+export default enforceValidMethod

package/template/eslint-rules/flat-routes-services.js

@@ -0,0 +1,69 @@
+/**
+ * @framework-baseline de2fed6c6a7ff346
+ */
+
+/**
+ * 禁止在 routes/ 和 services/ 目录下创建文件
+ *
+ * 规则：
+ * 1. src/server/routes/ 和 src/server/services/ 目录不允许放置任何文件
+ * 2. 所有路由和服务必须在 module-* 目录下
+ *
+ * 原因：
+ * - 强制模块化组织，便于维护
+ * - 每个功能模块独立管理路由、服务和测试
+ * - 避免代码分散难以追踪
+ *
+ * 参考: .claude/rules/20-server-api.md
+ */
+
+export const flatRoutesServices = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '禁止在 routes/services 目录下创建文件，必须在 module-* 目录下',
+      recommended: true,
+    },
+    messages: {
+      noFilesInRoutesServices: `禁止在 routes/services 目录下创建文件。
+
+当前路径：{{filepath}}
+
+routes/ 和 services/ 目录不允许放置任何文件。
+所有路由和服务必须在 module-* 目录下。
+
+📋 规则文档: .claude/rules/20-server-api.md
+
+🚀 快速创建模块:
+  npm run create:module <name>
+
+示例：
+❌ src/server/routes/user-routes.ts
+❌ src/server/services/user-service.ts
+✅ src/server/module-user/routes/user-routes.ts
+✅ src/server/module-user/services/user-service.ts
+`,
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename?.() || ''
+
+    const isInRoutesDir = filename.includes('/server/routes/')
+    const isInServicesDir = filename.includes('/server/services/')
+
+    if (!isInRoutesDir && !isInServicesDir) return {}
+
+    return {
+      Program(node) {
+        context.report({
+          node,
+          messageId: 'noFilesInRoutesServices',
+          data: { filepath: filename },
+        })
+      },
+    }
+  },
+}
+
+export default flatRoutesServices

package/template/eslint-rules/framework-protect.js

@@ -0,0 +1,186 @@
+/**
+ * @framework-baseline 46287a1935b462a6
+ */
+
+import * as crypto from 'crypto'
+import * as fs from 'fs'
+
+const hashCache = new Map()
+
+const FRAMEWORK_PATTERNS = [
+  '/shared/core/',
+  '/server/core/',
+  '/server/entries/',
+  '/server/test-utils/',
+  '/client/services/',
+]
+
+function isFrameworkFile(filePath) {
+  return FRAMEWORK_PATTERNS.some(p => filePath.includes(p))
+}
+
+function computeContentHash(content) {
+  return crypto.createHash('md5').update(content).digest('hex').slice(0, 16)
+}
+
+function extractCodeContent(fullContent) {
+  const lines = fullContent.split('\n')
+  const codeLines = []
+  let inHeaderComment = false
+  let headerEnded = false
+  let foundFirstCode = false
+
+  for (const line of lines) {
+    if (!headerEnded) {
+      if (line.trim().startsWith('/**')) {
+        inHeaderComment = true
+        continue
+      }
+      if (inHeaderComment) {
+        if (line.trim() === '*/') {
+          inHeaderComment = false
+          headerEnded = true
+        }
+        continue
+      }
+      if (line.trim() === '' || line.trim().startsWith('//')) {
+        continue
+      }
+      headerEnded = true
+      foundFirstCode = true
+    }
+    if (!foundFirstCode && (line.trim() === '' || line.trim().startsWith('//'))) {
+      continue
+    }
+    foundFirstCode = true
+    codeLines.push(line)
+  }
+
+  return codeLines.join('\n')
+}
+
+function computeFileHash(filePath) {
+  try {
+    const stat = fs.statSync(filePath)
+    const cached = hashCache.get(filePath)
+
+    if (cached && cached.mtime === stat.mtimeMs && cached.size === stat.size) {
+      return cached.hash
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8')
+    const codeContent = extractCodeContent(content)
+    const hash = computeContentHash(codeContent)
+
+    hashCache.set(filePath, {
+      mtime: stat.mtimeMs,
+      size: stat.size,
+      hash,
+    })
+
+    return hash
+  } catch {
+    return null
+  }
+}
+
+function extractBaselineInfo(content) {
+  const firstCommentEnd = content.indexOf('*/')
+  const headerComment = firstCommentEnd > 0 ? content.slice(0, firstCommentEnd) : ''
+
+  const baselineMatch = headerComment.match(/@framework-baseline\s+([a-f0-9]+)/i)
+  const reasonMatch = headerComment.match(/@reason\s+(.+)/i)
+  const impactMatch = headerComment.match(/@impact\s+(.+)/i)
+
+  return {
+    baseline: baselineMatch ? baselineMatch[1] : null,
+    hasModify: /@framework-modify/i.test(headerComment),
+    reason: reasonMatch ? reasonMatch[1].trim() : null,
+    impact: impactMatch ? impactMatch[1].trim() : null,
+  }
+}
+
+export const frameworkProtect = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Protect framework files from unauthorized modifications',
+      recommended: true,
+    },
+    messages: {
+      missingBaseline:
+        '框架文件缺少 @framework-baseline 声明。\n\n' +
+        '请运行 npm run framework:init 初始化框架文件基准。',
+      fileModified:
+        '框架文件已被修改！\n\n' +
+        '基准 Hash: {{baseline}}\n' +
+        '当前 Hash: {{current}}\n\n' +
+        '此文件属于框架层代码，修改需要添加说明。请在文件顶部注释中添加：\n\n' +
+        '@framework-modify\n' +
+        '@reason [必填] 修改原因\n' +
+        '@impact [必填] 影响范围',
+      missingReason:
+        '框架文件修改缺少 @reason 说明。\n\n' + '请在注释中添加：\n' + '@reason [修改原因]',
+      missingImpact:
+        '框架文件修改缺少 @impact 说明。\n\n' + '请在注释中添加：\n' + '@impact [影响范围]',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const filename = context.filename || context.getFilename()
+
+    if (!isFrameworkFile(filename)) {
+      return {}
+    }
+
+    return {
+      Program(node) {
+        const sourceCode = context.sourceCode || context.getSourceCode()
+        const content = sourceCode.text
+        const info = extractBaselineInfo(content)
+
+        if (!info.baseline) {
+          context.report({
+            node,
+            messageId: 'missingBaseline',
+          })
+          return
+        }
+
+        const currentHash = computeFileHash(filename)
+        if (!currentHash) return
+
+        if (currentHash !== info.baseline) {
+          if (!info.hasModify) {
+            context.report({
+              node,
+              messageId: 'fileModified',
+              data: {
+                baseline: info.baseline,
+                current: currentHash,
+              },
+            })
+            return
+          }
+
+          if (!info.reason) {
+            context.report({
+              node,
+              messageId: 'missingReason',
+            })
+          }
+
+          if (!info.impact) {
+            context.report({
+              node,
+              messageId: 'missingImpact',
+            })
+          }
+        }
+      },
+    }
+  },
+}
+
+export default frameworkProtect