create-fullstack-scaffold 0.1.0

package/template/eslint-rules/layer-boundary.js

@@ -0,0 +1,164 @@
+/**
+ * @framework-baseline 1636ca089cc6b544
+ */
+
+/**
+ * ESLint 规则：框架层和业务层边界约束
+ *
+ * 规则：
+ * 1. 业务层代码不能直接修改框架层代码
+ * 2. 业务层代码导入框架层代码时需要添加注释说明原因
+ * 3. 框架层内部文件不能被业务层直接导入
+ */
+
+export const layerBoundary = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Enforce boundary between framework layer and business layer',
+      recommended: true,
+    },
+    messages: {
+      modifyFrameworkCode:
+        '禁止在业务层代码中修改框架层代码。框架层代码位于 shared/core/ 和 server/core/，是通用基础设施，不应被业务逻辑修改。\n' +
+        '如果需要扩展功能，请：\n' +
+        '1. 在业务层创建新的实现\n' +
+        '2. 或者在框架层添加扩展点（需要框架维护者审批）',
+      importFrameworkInternal:
+        '禁止直接导入框架层内部文件。请使用公开的导出入口：\n' +
+        '- @shared/core (框架层导出)\n' +
+        '- @shared/schemas (统一导出)',
+      missingFrameworkImportComment:
+        '业务层导入框架层代码时，请添加注释说明原因。\n' +
+        '示例：// @framework-import 用于 WebSocket 连接管理',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allowFrameworkModification: {
+            type: 'boolean',
+            default: false,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const options = context.options[0] || {}
+
+    const frameworkLayerPaths = ['/shared/core/', '/server/core/']
+
+    const businessLayerPaths = ['/shared/modules/', '/server/module-', '/client/']
+
+    const frameworkInternalFiles = [
+      '/shared/core/ws-client.ts',
+      '/shared/core/sse-client.ts',
+      '/shared/core/api-schemas.ts',
+      '/shared/core/protocol-types.ts',
+      '/server/core/runtime.ts',
+      '/server/core/runtime-node.ts',
+      '/server/core/runtime-cloudflare.ts',
+      '/server/core/realtime-core.ts',
+    ]
+
+    const isFrameworkFile = frameworkLayerPaths.some(p => filename.includes(p))
+    const isBusinessFile = businessLayerPaths.some(p => filename.includes(p))
+
+    function hasCommentAbove(node, commentTag) {
+      const comments = context.sourceCode.getAllComments()
+      const nodeLine = node.loc?.start.line
+      if (!nodeLine) return false
+
+      for (const comment of comments) {
+        if (comment.loc && comment.loc.end.line === nodeLine - 1) {
+          if (comment.value?.includes(commentTag)) {
+            return true
+          }
+        }
+      }
+      return false
+    }
+
+    return {
+      ImportDeclaration(node) {
+        if (!isBusinessFile) return
+
+        const source = node.source
+        if (!source || source.type !== 'Literal') return
+
+        const importPath = source.value
+        if (typeof importPath !== 'string') return
+
+        const normalizedImport = importPath
+          .replace('@shared', '/shared')
+          .replace('@server', '/server')
+
+        for (const internalPath of frameworkInternalFiles) {
+          if (normalizedImport.includes(internalPath.replace('.ts', ''))) {
+            context.report({
+              node,
+              messageId: 'importFrameworkInternal',
+            })
+            return
+          }
+        }
+
+        const isImportingFramework = frameworkLayerPaths.some(p => normalizedImport.includes(p))
+        if (isImportingFramework) {
+          if (!hasCommentAbove(node, '@framework-import')) {
+            context.report({
+              node,
+              messageId: 'missingFrameworkImportComment',
+            })
+          }
+        }
+      },
+
+      CallExpression(node) {
+        if (!isBusinessFile) return
+        if (options.allowFrameworkModification) return
+
+        if (node.callee.type === 'MemberExpression') {
+          const obj = node.callee.object
+          if (obj.type === 'Identifier' && obj.name === 'runtime') {
+            if (node.callee.property.type === 'Identifier') {
+              const method = node.callee.property.name
+              const dangerousMethods = ['registerRPC', 'registerEvent', 'broadcast']
+
+              if (dangerousMethods.includes(method)) {
+                if (!hasCommentAbove(node, '@framework-allow-modification')) {
+                  context.report({
+                    node,
+                    messageId: 'modifyFrameworkCode',
+                  })
+                }
+              }
+            }
+          }
+        }
+      },
+
+      AssignmentExpression(node) {
+        if (!isBusinessFile) return
+        if (options.allowFrameworkModification) return
+
+        if (node.left.type === 'MemberExpression') {
+          const obj = node.left.object
+          if (obj.type === 'Identifier' && obj.name === 'runtime') {
+            if (!hasCommentAbove(node, '@framework-allow-modification')) {
+              context.report({
+                node,
+                messageId: 'modifyFrameworkCode',
+              })
+            }
+          }
+        }
+      },
+    }
+  },
+}
+
+export default layerBoundary

package/template/eslint-rules/limit-type-complexity.js

@@ -0,0 +1,130 @@
+/**
+ * @framework-baseline a96111023f2c1552
+ */
+
+/**
+ * @fileoverview 限制会导致 TypeScript 类型推导复杂化的写法
+ *
+ * 此规则检测以下可能导致类型推导问题的模式：
+ * 1. 单个变量声明中的链式调用 .route() 超过限制次数
+ * 2. ReturnType<typeof hc<AppType>> 等复杂类型推导
+ *
+ * @author biomimic-app
+ */
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ */
+function create(context) {
+  const maxRouteChainLength = context.options[0]?.maxRouteChainLength ?? 5
+
+  /**
+   * 检查单个变量声明中的链式调用 .route() 数量
+   * @param {import('eslint').Rule.Node} node
+   */
+  function checkRouteChain(node) {
+    if (node.type !== 'CallExpression') return
+
+    let routeCount = 0
+    let currentNode = node
+
+    while (currentNode && currentNode.type === 'CallExpression') {
+      const callee = currentNode.callee
+
+      if (
+        callee.type === 'MemberExpression' &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'route'
+      ) {
+        routeCount++
+      }
+
+      if (callee.type === 'MemberExpression') {
+        currentNode = callee.object
+      } else {
+        break
+      }
+    }
+
+    if (routeCount > maxRouteChainLength) {
+      context.report({
+        node,
+        messageId: 'tooManyRouteChains',
+        data: {
+          count: routeCount,
+          max: maxRouteChainLength,
+        },
+      })
+    }
+  }
+
+  /**
+   * 检查 ReturnType 的使用
+   * @param {import('eslint').Rule.Node} node
+   */
+  function checkReturnType(node) {
+    if (node.type !== 'TSTypeReference') return
+
+    const typeName = node.typeName
+
+    if (typeName.type === 'Identifier' && typeName.name === 'ReturnType') {
+      if (node.typeArguments?.typeArguments?.length > 0) {
+        const typeArg = node.typeArguments.typeArguments[0]
+
+        if (typeArg.type === 'TSTypeQuery' && typeArg.exprName.type === 'Identifier') {
+          const funcName = typeArg.exprName.name
+
+          if (['createApp', 'hc'].includes(funcName)) {
+            context.report({
+              node,
+              messageId: 'complexReturnType',
+              data: {
+                funcName,
+              },
+            })
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    VariableDeclarator(node) {
+      if (node.init?.type === 'CallExpression') {
+        checkRouteChain(node.init)
+      }
+    },
+    TSTypeReference: checkReturnType,
+  }
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export const limitTypeComplexity = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: '限制会导致 TypeScript 类型推导复杂化的写法',
+      recommended: true,
+    },
+    messages: {
+      tooManyRouteChains:
+        '链式调用 .route() {{count}} 次超过了建议的最大值 {{max}} 次。这会导致 TypeScript 类型推导复杂化，建议拆分为多个变量。',
+      complexReturnType:
+        'ReturnType<typeof {{funcName}}> 可能导致类型推导复杂化。如果遇到 "类型实例化过深" 错误，请考虑使用更简单的类型定义。',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          maxRouteChainLength: {
+            type: 'integer',
+            minimum: 1,
+            default: 5,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create,
+}

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

@@ -0,0 +1,162 @@
+/**
+ * @framework-baseline 78198aa6d5603535
+ */
+
+/**
+ * 约束中间件的位置和写法
+ * 1. 中间件必须放在 src/server/middleware/ 目录下
+ * 2. 中间件文件必须导出命名函数，函数名以 Middleware 结尾
+ * 3. 辅助函数（如 getAuthUser）不以 Middleware 结尾是允许的
+ * 4. 私有方法（以 _ 开头）不以 Middleware 结尾是允许的
+ */
+
+const HELPER_FUNCTIONS = ['getAuthUser', 'requireAuth', 'hasPermission']
+
+function isPrivateMethod(name) {
+  return name.startsWith('_')
+}
+
+export const middlewareLocation = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '约束中间件的位置和写法',
+      recommended: true,
+    },
+    messages: {
+      wrongLocation: '中间件必须放在 src/server/middleware/ 目录下，当前文件: {{filename}}',
+      missingExport: '中间件文件必须导出以 Middleware 结尾的命名函数',
+      invalidName: '中间件函数名必须以 Middleware 结尾，当前名称: {{name}}',
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const isMiddlewareFile = filename.includes('/middleware/') && filename.endsWith('.ts')
+    const isTestFile = filename.includes('/__tests__/')
+
+    return {
+      ExportNamedDeclaration(node) {
+        if (!isMiddlewareFile || isTestFile) return
+
+        if (node.declaration?.type === 'FunctionDeclaration') {
+          const name = node.declaration.id?.name
+          if (
+            name &&
+            !name.endsWith('Middleware') &&
+            !HELPER_FUNCTIONS.includes(name) &&
+            !isPrivateMethod(name)
+          ) {
+            context.report({
+              node: node.declaration,
+              messageId: 'invalidName',
+              data: { name },
+            })
+          }
+        }
+
+        if (node.declaration?.type === 'VariableDeclaration') {
+          for (const decl of node.declaration.declarations) {
+            if (decl.id.type === 'Identifier') {
+              const name = decl.id.name
+              if (
+                !name.endsWith('Middleware') &&
+                !HELPER_FUNCTIONS.includes(name) &&
+                !isPrivateMethod(name)
+              ) {
+                context.report({
+                  node: decl,
+                  messageId: 'invalidName',
+                  data: { name },
+                })
+              }
+            }
+          }
+        }
+      },
+
+      Program(node) {
+        if (!isMiddlewareFile || isTestFile) return
+
+        const hasMiddlewareExport = node.body.some(statement => {
+          if (statement.type === 'ExportNamedDeclaration') {
+            if (statement.declaration?.type === 'FunctionDeclaration') {
+              const name = statement.declaration.id?.name
+              return (
+                name?.endsWith('Middleware') ||
+                HELPER_FUNCTIONS.includes(name) ||
+                isPrivateMethod(name)
+              )
+            }
+            if (statement.declaration?.type === 'VariableDeclaration') {
+              return statement.declaration.declarations.some(decl => {
+                if (decl.id.type === 'Identifier') {
+                  const name = decl.id.name
+                  return (
+                    name.endsWith('Middleware') ||
+                    HELPER_FUNCTIONS.includes(name) ||
+                    isPrivateMethod(name)
+                  )
+                }
+                return false
+              })
+            }
+          }
+          return false
+        })
+
+        if (!hasMiddlewareExport) {
+          context.report({
+            node,
+            messageId: 'missingExport',
+          })
+        }
+      },
+    }
+  },
+}
+
+/**
+ * 禁止在非 middleware 目录下定义中间件
+ */
+export const noMiddlewareOutsideDir = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: '禁止在非 middleware 目录下定义中间件',
+      recommended: true,
+    },
+    messages: {
+      noMiddlewareOutsideDir: '中间件定义必须放在 src/server/middleware/ 目录下',
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const isMiddlewareFile = filename.includes('/middleware/')
+    const isTestFile = filename.includes('/__tests__/')
+
+    return {
+      VariableDeclaration(node) {
+        if (isMiddlewareFile || isTestFile) return
+
+        for (const decl of node.declarations) {
+          if (decl.id.type === 'Identifier' && decl.id.name.endsWith('Middleware')) {
+            context.report({
+              node,
+              messageId: 'noMiddlewareOutsideDir',
+            })
+          }
+        }
+      },
+      FunctionDeclaration(node) {
+        if (isMiddlewareFile || isTestFile) return
+
+        if (node.id?.name?.endsWith('Middleware')) {
+          context.report({
+            node,
+            messageId: 'noMiddlewareOutsideDir',
+          })
+        }
+      },
+    }
+  },
+}

package/template/eslint-rules/module-boundary.js

@@ -0,0 +1,125 @@
+/**
+ * @framework-baseline 87b36ab59f454a78
+ */
+
+/**
+ * ESLint 规则：模块边界约束
+ *
+ * 规则：
+ * 1. client、cli、admin 三个模块之间不能存在直接引用关系
+ * 2. 模块间共享代码必须通过 shared 目录
+ * 3. 违规引用将报错并提示使用 shared 中转
+ */
+
+export const moduleBoundary = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Enforce boundary between client, cli and admin modules',
+      recommended: true,
+    },
+    messages: {
+      directCrossModuleImport:
+        '禁止直接在 {{fromModule}} 中引用 {{toModule}}。\n' +
+        '模块间共享代码必须通过 @shared 中转。\n' +
+        '解决方案：\n' +
+        '1. 将共享的类型/代码放入 @shared 目录\n' +
+        '2. 在 {{fromModule}} 和 {{toModule}} 中都从 @shared 导入',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+
+    const modulePaths = {
+      client: '/client/',
+      cli: '/cli/',
+      admin: '/admin/',
+    }
+
+    const moduleNames = {
+      client: 'client',
+      cli: 'cli',
+      admin: 'admin',
+    }
+
+    function getCurrentModule(filePath) {
+      for (const [moduleName, path] of Object.entries(modulePaths)) {
+        if (filePath.includes(path)) {
+          return moduleName
+        }
+      }
+      return null
+    }
+
+    function getTargetModule(importPath) {
+      let bestMatch = null
+      let bestIndex = -1
+      for (const [moduleName, path] of Object.entries(modulePaths)) {
+        const idx = importPath.indexOf(path)
+        if (idx !== -1 && idx > bestIndex) {
+          bestIndex = idx
+          bestMatch = moduleName
+        }
+      }
+      return bestMatch
+    }
+
+    function resolveRelativePath(basePath, relativePath) {
+      const normalizedBase = basePath.replace(/[^/]+$/, '')
+      const parts = normalizedBase.split('/')
+      const relativeParts = relativePath.split('/')
+
+      for (const part of relativeParts) {
+        if (part === '..') {
+          parts.pop()
+        } else if (part !== '.') {
+          parts.push(part)
+        }
+      }
+      return parts.join('/')
+    }
+
+    const currentModule = getCurrentModule(filename)
+    if (!currentModule) return {}
+
+    const otherModules = Object.keys(modulePaths).filter(m => m !== currentModule)
+
+    return {
+      ImportDeclaration(node) {
+        const source = node.source
+        if (!source || source.type !== 'Literal') return
+
+        const importPath = source.value
+        if (typeof importPath !== 'string') return
+
+        if (importPath.startsWith('@shared')) {
+          return
+        }
+
+        if (importPath.endsWith('.css')) {
+          return
+        }
+
+        let resolvedPath = importPath
+        if (importPath.startsWith('.')) {
+          resolvedPath = resolveRelativePath(filename, importPath)
+        }
+
+        const targetModule = getTargetModule(resolvedPath)
+        if (targetModule && otherModules.includes(targetModule)) {
+          context.report({
+            node,
+            messageId: 'directCrossModuleImport',
+            data: {
+              fromModule: moduleNames[currentModule],
+              toModule: moduleNames[targetModule],
+            },
+          })
+        }
+      },
+    }
+  },
+}
+
+export default moduleBoundary

package/template/eslint-rules/no-ambiguous-file-paths.js

@@ -0,0 +1,64 @@
+/**
+ * @framework-baseline e5b8bf14244c53b9
+ */
+
+/**
+ * 自定义 ESLint 规则：禁止有歧义的文件路径命名
+ *
+ * 禁止以下模式：
+ * - core/core.ts
+ * - index/index.ts
+ * - service/service.ts
+ * - xxx/xxx.ts (目录名与文件名相同)
+ * - xxx/xxx/index.ts (嵌套重复)
+ */
+
+export const noAmbiguousFilePaths = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow ambiguous file path naming like core/core.ts or index/index.ts',
+      recommended: true,
+    },
+    messages: {
+      ambiguousFileName:
+        'Ambiguous file path: "{{path}}". File name "{{fileName}}" is the same as parent directory "{{dirName}}".\n' +
+        'This creates confusion when importing. Consider renaming to something more descriptive.\n' +
+        'Examples:\n' +
+        '  ❌ core/core.ts → ✅ core/realtime-core.ts or core/ws-core.ts\n' +
+        '  ❌ service/service.ts → ✅ service/user-service.ts\n' +
+        '  ❌ index/index.ts → ✅ index/main.ts or just index.ts in parent',
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+
+    const pathParts = filename.split(/[/\\]/)
+    if (pathParts.length < 2) return {}
+
+    const fileName = pathParts[pathParts.length - 1]
+    const fileNameWithoutExt = fileName
+      .replace(/\.ts$/, '')
+      .replace(/\.tsx$/, '')
+      .replace(/\.js$/, '')
+
+    const parentDir = pathParts[pathParts.length - 2]
+
+    if (fileNameWithoutExt === parentDir) {
+      context.report({
+        loc: { line: 1, column: 0 },
+        messageId: 'ambiguousFileName',
+        data: {
+          path: filename,
+          fileName: fileNameWithoutExt,
+          dirName: parentDir,
+        },
+      })
+    }
+
+    return {}
+  },
+}
+
+export default noAmbiguousFilePaths