create-fullstack-scaffold 0.1.0

package/template/eslint-rules/require-file-openapi-props.js

@@ -0,0 +1,114 @@
+/**
+ * @framework-baseline 0956d31f0680e2f0
+ */
+
+/**
+ * 要求 z.file() 必须指定 type 和 format
+ * 避免 Internal server error: Unknown zod object type 错误
+ */
+
+export const requireFileOpenapiProps = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'z.file() 必须指定 type 和 format，使用 .openapi({ type: "string", format: "binary" })',
+      recommended: true,
+    },
+    messages: {
+      requireFileOpenapiProps:
+        '🚫 z.file() 必须指定 type 和 format！\n\n' +
+        '缺少 openapi 配置会导致错误：\n' +
+        '"Internal server error: Unknown zod object type, please specify `type` and other OpenAPI props using `schema.openapi`"\n\n' +
+        '📖 正确示例：\n' +
+        '   file: z.file().openapi({ type: "string", format: "binary" })\n\n' +
+        '💡 修复建议：\n' +
+        '   1. 在 z.file() 后添加 .openapi({ type: "string", format: "binary" })\n' +
+        '   2. 如果用于文件上传，确保包含这两个属性',
+      missingTypeOrFormat:
+        '🚫 z.file().openapi() 必须包含 type 和 format 属性！\n\n' +
+        '📖 正确示例：\n' +
+        '   file: z.file().openapi({ type: "string", format: "binary" })\n\n' +
+        '💡 修复建议：\n' +
+        '   确保 openapi 配置对象中包含 type: "string" 和 format: "binary"',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename?.() || ''
+
+    // 只对 schema 文件生效
+    const isSchemaFile = filename.includes('/shared/modules/') && filename.includes('/schemas.ts')
+    if (!isSchemaFile) {
+      return {}
+    }
+
+    return {
+      CallExpression(node) {
+        // 检查是否是 z.file() 调用
+        if (
+          node.callee?.type !== 'MemberExpression' ||
+          node.callee.object?.type !== 'Identifier' ||
+          node.callee.object.name !== 'z' ||
+          node.callee.property?.type !== 'Identifier' ||
+          node.callee.property.name !== 'file'
+        ) {
+          return
+        }
+
+        // 检查是否有 .openapi() 链式调用
+        let currentNode = node.parent
+        let hasOpenapiCall = false
+        let openapiConfigNode = null
+
+        while (currentNode) {
+          if (
+            currentNode.type === 'CallExpression' &&
+            currentNode.callee?.type === 'MemberExpression' &&
+            currentNode.callee.property?.type === 'Identifier' &&
+            currentNode.callee.property.name === 'openapi'
+          ) {
+            hasOpenapiCall = true
+            openapiConfigNode = currentNode.arguments[0]
+            break
+          }
+          currentNode = currentNode.parent
+        }
+
+        // 如果没有 openapi 调用，报错
+        if (!hasOpenapiCall) {
+          context.report({
+            node,
+            messageId: 'requireFileOpenapiProps',
+          })
+          return
+        }
+
+        // 检查 openapi 配置中是否有 type 和 format
+        if (openapiConfigNode && openapiConfigNode.type === 'ObjectExpression') {
+          const hasType = openapiConfigNode.properties.some(
+            prop =>
+              prop.type === 'Property' &&
+              prop.key?.type === 'Identifier' &&
+              prop.key.name === 'type'
+          )
+          const hasFormat = openapiConfigNode.properties.some(
+            prop =>
+              prop.type === 'Property' &&
+              prop.key?.type === 'Identifier' &&
+              prop.key.name === 'format'
+          )
+
+          if (!hasType || !hasFormat) {
+            context.report({
+              node: openapiConfigNode,
+              messageId: 'missingTypeOrFormat',
+            })
+          }
+        }
+      },
+    }
+  },
+}
+
+export default requireFileOpenapiProps

package/template/eslint-rules/require-hono-chain-syntax.js

@@ -0,0 +1,129 @@
+/**
+ * @framework-baseline b8577e20b7faff0e
+ */
+
+/**
+ * 自定义 ESLint 规则：
+ * 1. 禁止使用普通 Hono，必须使用 OpenAPIHono
+ * 2. 强制 OpenAPIHono 使用链式语法
+ * 3. 禁止 createRoute 在 new OpenAPIHono 之后出现
+ *
+ * 原因：
+ * - OpenAPIHono 支持 RPC 类型推断
+ * - 非链式写法会导致 Hono RPC 类型推断丢失
+ * - createRoute 必须在 OpenAPIHono 实例化之前定义，保证代码结构清晰
+ */
+
+export const requireHonoChainSyntax = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require OpenAPIHono chain syntax and forbid createRoute after OpenAPIHono instantiation',
+      recommended: true,
+    },
+    messages: {
+      useOpenAPIHono: 'Use OpenAPIHono instead of Hono for RPC type inference',
+      nonChainSyntax:
+        'OpenAPIHono must use chain syntax. Non-chain syntax breaks RPC type inference. ' +
+        'Example: new OpenAPIHono().openapi(route1, handler1).openapi(route2, handler2)',
+      standaloneOpenapiCall:
+        'Standalone .openapi() calls are forbidden. Use chain syntax instead. ' +
+        'Example: new OpenAPIHono().openapi(route1, handler1).openapi(route2, handler2)',
+      createRouteAfterOpenAPIHono:
+        'createRoute must be defined BEFORE new OpenAPIHono(). ' +
+        'All route definitions should come before the OpenAPIHono instantiation. ' +
+        'This ensures better code organization and type inference.',
+    },
+    schema: [],
+  },
+  create(context) {
+    const openAPIHonoVariables = new Set()
+    const createRouteCallNodes = []
+    let openAPIHonoNode = null
+
+    return {
+      NewExpression(node) {
+        if (
+          node.callee &&
+          node.callee.type === 'Identifier' &&
+          node.callee.name === 'OpenAPIHono'
+        ) {
+          openAPIHonoNode = node
+
+          const hasNextCall =
+            node.parent &&
+            node.parent.type === 'MemberExpression' &&
+            node.parent.property &&
+            node.parent.property.type === 'Identifier' &&
+            (node.parent.property.name === 'openapi' ||
+              node.parent.property.name === 'use' ||
+              node.parent.property.name === 'route' ||
+              node.parent.property.name === 'get' ||
+              node.parent.property.name === 'post' ||
+              node.parent.property.name === 'put' ||
+              node.parent.property.name === 'delete')
+
+          if (!hasNextCall) {
+            openAPIHonoVariables.add(node.id?.name || 'unknown')
+            context.report({
+              node,
+              messageId: 'nonChainSyntax',
+            })
+          }
+        }
+
+        if (node.callee && node.callee.type === 'Identifier' && node.callee.name === 'Hono') {
+          context.report({
+            node,
+            messageId: 'useOpenAPIHono',
+          })
+        }
+      },
+      CallExpression(node) {
+        if (
+          node.callee &&
+          node.callee.type === 'Identifier' &&
+          node.callee.name === 'createRoute'
+        ) {
+          createRouteCallNodes.push(node)
+        }
+
+        if (
+          node.callee &&
+          node.callee.type === 'MemberExpression' &&
+          node.callee.object &&
+          node.callee.object.type === 'Identifier' &&
+          openAPIHonoVariables.has(node.callee.object.name) &&
+          node.callee.property &&
+          node.callee.property.name === 'openapi'
+        ) {
+          context.report({
+            node,
+            messageId: 'standaloneOpenapiCall',
+          })
+        }
+      },
+      'Program:exit'() {
+        if (openAPIHonoNode) {
+          for (const createRouteNode of createRouteCallNodes) {
+            if (createRouteNode.loc && openAPIHonoNode.loc) {
+              if (
+                createRouteNode.loc.start.line > openAPIHonoNode.loc.start.line ||
+                (createRouteNode.loc.start.line === openAPIHonoNode.loc.start.line &&
+                  createRouteNode.loc.start.column > openAPIHonoNode.loc.start.column)
+              ) {
+                context.report({
+                  node: createRouteNode,
+                  messageId: 'createRouteAfterOpenAPIHono',
+                })
+              }
+            }
+          }
+        }
+      },
+    }
+  },
+}
+
+export default requireHonoChainSyntax

package/template/eslint-rules/require-nullable-for-optional.js

@@ -0,0 +1,99 @@
+/**
+ * @framework-baseline 8a9c7790b3e83f1a
+ */
+
+/**
+ * 要求 optional 字段必须同时 nullable
+ *
+ * 原因：
+ * 1. 前端经常传 null 表示空值（如 description: null）
+ * 2. Zod 的 .optional() 只接受 undefined，不接受 null
+ * 3. 导致前后端数据不一致，产生 ZodError
+ *
+ * 解决方案：
+ * - 使用 .optional().nullable() 同时接受 undefined 和 null
+ * - 或者使用 .nullish() 简写（等价于 .optional().nullable()）
+ */
+
+export const requireNullableForOptional = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'optional 字段必须同时 nullable，避免前端传 null 时产生 ZodError。使用 .optional().nullable() 或 .nullish()',
+      recommended: true,
+    },
+    messages: {
+      requireNullable:
+        '🚫 .optional() 字段必须同时加 .nullable()！\n\n' +
+        '❌ 问题原因：\n' +
+        '   前端经常传 { description: null } 表示空值\n' +
+        '   但 z.string().optional() 只接受 undefined，不接受 null\n' +
+        '   导致 ZodError: expected string, received null\n\n' +
+        '✅ 正确写法：\n' +
+        '   description: z.string().optional().nullable()\n' +
+        '   // 或使用简写\n' +
+        '   description: z.string().nullish()\n\n' +
+        '💡 修复建议：\n' +
+        '   在 .optional() 后添加 .nullable()，或改用 .nullish()',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename?.() || ''
+
+    const isSchemaFile = filename.includes('/shared/modules/') && filename.includes('/schemas.ts')
+    if (!isSchemaFile) {
+      return {}
+    }
+
+    return {
+      CallExpression(node) {
+        if (
+          node.callee?.type !== 'MemberExpression' ||
+          node.callee.property?.type !== 'Identifier' ||
+          node.callee.property.name !== 'optional'
+        ) {
+          return
+        }
+
+        let currentNode = node.parent
+        let hasNullable = false
+
+        while (currentNode) {
+          if (
+            currentNode.type === 'CallExpression' &&
+            currentNode.callee?.type === 'MemberExpression' &&
+            currentNode.callee.property?.type === 'Identifier'
+          ) {
+            const methodName = currentNode.callee.property.name
+
+            if (methodName === 'nullable' || methodName === 'nullish') {
+              hasNullable = true
+              break
+            }
+
+            if (
+              methodName !== 'optional' &&
+              methodName !== 'describe' &&
+              methodName !== 'openapi' &&
+              methodName !== 'default'
+            ) {
+              break
+            }
+          }
+          currentNode = currentNode.parent
+        }
+
+        if (!hasNullable) {
+          context.report({
+            node,
+            messageId: 'requireNullable',
+          })
+        }
+      },
+    }
+  },
+}
+
+export default requireNullableForOptional

package/template/eslint-rules/require-response-helpers.js

@@ -0,0 +1,140 @@
+/**
+ * @framework-baseline 411aa894e66ae6d5
+ */
+
+export const requireResponseHelpers = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'HTTP 路由必须使用 successResponse/errorResponse 辅助函数定义响应',
+      recommended: true,
+    },
+    messages: {
+      requireSuccessResponse:
+        'HTTP JSON 成功响应必须使用 successResponse() 辅助函数。\n' +
+        '正确写法: 200: successResponse(schema, "description")\n' +
+        '参考: src/server/utils/route-helpers.ts',
+      requireErrorResponse:
+        'HTTP JSON 错误响应必须使用 errorResponse() 辅助函数。\n' +
+        '正确写法: 404: errorResponse("Not found")\n' +
+        '参考: src/server/utils/route-helpers.ts',
+      noDirectJsonContent:
+        '禁止直接定义 application/json 响应内容。\n' +
+        '使用 successResponse() 或 errorResponse() 辅助函数。\n' +
+        '参考: src/server/utils/route-helpers.ts',
+    },
+    schema: [],
+  },
+  create(context) {
+    const ALLOWED_CONTENT_TYPES = ['text/event-stream', 'application/octet-stream', 'websocket']
+    const SUCCESS_CODES = [200, 201, 202, 204]
+    const HELPER_FUNCTIONS = [
+      'successResponse',
+      'errorResponse',
+      'listResponse',
+      'deleteResponse',
+      'standardResponses',
+      'withNotFoundResponses',
+      'createResponses',
+    ]
+
+    function isHelperCall(node) {
+      if (node.type !== 'CallExpression') return false
+      if (node.callee.type === 'Identifier') {
+        return HELPER_FUNCTIONS.includes(node.callee.name)
+      }
+      if (node.callee.type === 'MemberExpression' && node.callee.property.type === 'Identifier') {
+        return HELPER_FUNCTIONS.includes(node.callee.property.name)
+      }
+      return false
+    }
+
+    function isAllowedContentType(node) {
+      if (node.type !== 'ObjectExpression') return false
+
+      const contentProp = node.properties.find(p => p.key?.name === 'content')
+      if (!contentProp?.value || contentProp.value.type !== 'ObjectExpression') return false
+
+      const contentTypes = contentProp.value.properties
+        .filter(p => p.key?.type === 'Literal' && typeof p.key.value === 'string')
+        .map(p => p.key.value)
+
+      return contentTypes.some(type => ALLOWED_CONTENT_TYPES.includes(type))
+    }
+
+    function hasApplicationJson(node) {
+      if (node.type !== 'ObjectExpression') return false
+
+      const contentProp = node.properties.find(p => p.key?.name === 'content')
+      if (!contentProp?.value || contentProp.value.type !== 'ObjectExpression') return false
+
+      return contentProp.value.properties.some(
+        p => p.key?.type === 'Literal' && p.key.value === 'application/json'
+      )
+    }
+
+    function getStatusCode(node) {
+      if (node.type === 'Literal' && typeof node.value === 'number') {
+        return node.value
+      }
+      if (node.type === 'Literal' && typeof node.value === 'string') {
+        return parseInt(node.value, 10)
+      }
+      return null
+    }
+
+    function isSuccessCode(code) {
+      return SUCCESS_CODES.includes(code)
+    }
+
+    function checkResponseProperty(prop) {
+      const statusCode = getStatusCode(prop.key)
+      const value = prop.value
+
+      if (isHelperCall(value)) return
+
+      if (isAllowedContentType(value)) return
+
+      if (hasApplicationJson(value)) {
+        context.report({
+          node: value,
+          messageId: 'noDirectJsonContent',
+        })
+        return
+      }
+
+      if (value.type === 'ObjectExpression') {
+        const hasContent = value.properties.some(p => p.key?.name === 'content')
+        if (!hasContent) {
+          context.report({
+            node: value,
+            messageId:
+              statusCode && isSuccessCode(statusCode)
+                ? 'requireSuccessResponse'
+                : 'requireErrorResponse',
+          })
+        }
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== 'Identifier' || node.callee.name !== 'createRoute') return
+
+        const arg = node.arguments[0]
+        if (arg?.type !== 'ObjectExpression') return
+
+        const responsesProp = arg.properties.find(p => p.key?.name === 'responses')
+        if (!responsesProp || responsesProp.value?.type !== 'ObjectExpression') return
+
+        responsesProp.value.properties.forEach(prop => {
+          if (prop.type === 'Property') {
+            checkResponseProperty(prop)
+          }
+        })
+      },
+    }
+  },
+}
+
+export default requireResponseHelpers

package/template/eslint-rules/require-type-safe-test-client.js

@@ -0,0 +1,106 @@
+/**
+ * @framework-baseline 28658b9194686a10
+ */
+
+/**
+ * 自定义 ESLint 规则：强制路由/RPC 测试使用类型安全的测试客户端
+ *
+ * 必须使用 createTestClient() 返回的客户端进行 API 测试
+ * 禁止使用 fetch、app.fetch、app.request 等非类型安全方式
+ */
+
+export const requireTypeSafeTestClient = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require type-safe test client for route/RPC tests to preserve type inference',
+      recommended: true,
+    },
+    messages: {
+      forbiddenFetch:
+        'Direct fetch() is not allowed in route tests. Use createTestClient() for type-safe API testing.\n' +
+        'Example: const client = createTestClient()\n' +
+        '         const res = await client.api.todos.$get()',
+      forbiddenAppFetch:
+        'Direct app.fetch() is not allowed in route tests. Use createTestClient() for type-safe API testing.\n' +
+        'Example: const client = createTestClient()\n' +
+        '         const res = await client.api.todos.$get()',
+      forbiddenAppRequest:
+        'Direct app.request() is not allowed in route tests. Use createTestClient() for type-safe API testing.\n' +
+        'Example: const client = createTestClient()\n' +
+        '         const res = await client.api.todos.$get()',
+      forbiddenHonoClient:
+        'Direct hono/client hc() is not allowed in route tests. Use createTestClient() from test-utils.\n' +
+        'Example: const client = createTestClient()\n' +
+        '         const res = await client.api.todos.$get()',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+
+    const isMiddlewareTest =
+      filename.includes('/middleware/__tests__') || filename.includes('/middleware/')
+
+    const isRouteTestFile =
+      !isMiddlewareTest &&
+      (filename.includes('-rpc.test.') ||
+        filename.includes('-route.test.') ||
+        (filename.includes('__tests__') && filename.includes('.test.')))
+
+    if (!isRouteTestFile) {
+      return {}
+    }
+
+    return {
+      CallExpression(node) {
+        if (!node.callee) return
+
+        if (node.callee.type === 'Identifier' && node.callee.name === 'fetch') {
+          context.report({
+            node,
+            messageId: 'forbiddenFetch',
+          })
+          return
+        }
+
+        if (node.callee.type === 'MemberExpression') {
+          const property = node.callee.property
+          const object = node.callee.object
+
+          if (property && property.name === 'fetch' && object && object.name === 'app') {
+            context.report({
+              node,
+              messageId: 'forbiddenAppFetch',
+            })
+            return
+          }
+
+          if (property && property.name === 'request' && object && object.name === 'app') {
+            context.report({
+              node,
+              messageId: 'forbiddenAppRequest',
+            })
+            return
+          }
+        }
+
+        if (node.callee.type === 'CallExpression') {
+          if (
+            node.callee.callee &&
+            node.callee.callee.type === 'Identifier' &&
+            node.callee.callee.name === 'hc'
+          ) {
+            context.report({
+              node,
+              messageId: 'forbiddenHonoClient',
+            })
+            return
+          }
+        }
+      },
+    }
+  },
+}
+
+export default requireTypeSafeTestClient

package/template/eslint-rules/route-location.js

@@ -0,0 +1,72 @@
+/**
+ * @framework-baseline 1d4a27aa61187954
+ */
+
+/**
+ * 路由文件位置规则
+ *
+ * 约束路由文件的位置：
+ * 1. 路由文件必须放在 src/server/module-{module}/routes/ 目录下
+ * 2. 禁止在 src/routes/ 或其他非模块目录下创建路由文件
+ */
+
+export const routeLocation = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '路由文件必须放在模块目录下',
+      recommended: true,
+    },
+    messages: {
+      routeOutsideModule: `路由文件必须放在模块目录下。
+
+当前文件位置：{{filename}}
+建议位置：src/server/module-{module}/routes/{name}-routes.ts
+
+示例目录结构：
+src/
+  server/
+    module-todos/
+      routes/
+        todos-routes.ts    <- Todo 路由
+      services/
+        todo-service.ts
+    module-notifications/
+      routes/
+        notification-routes.ts    <- Notification 路由
+      services/
+        notification-service.ts
+
+好处：
+1. 模块化组织，便于维护
+2. 路由与服务层就近放置
+3. 统一的代码结构
+`,
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename?.() || ''
+
+    const isRouteFile = filename.endsWith('-routes.ts') || filename.endsWith('-route.ts')
+
+    if (!isRouteFile) return {}
+
+    const isInModuleRoutes =
+      /module-.*\/routes\/.*\.ts$/.test(filename) && !filename.includes('__tests__')
+
+    if (isInModuleRoutes) return {}
+
+    return {
+      Program(node) {
+        context.report({
+          node,
+          messageId: 'routeOutsideModule',
+          data: { filename },
+        })
+      },
+    }
+  },
+}
+
+export default routeLocation