create-fullstack-scaffold 0.1.0

package/template/lint-scripts/validators/sensitive.validator.ts

@@ -0,0 +1,185 @@
+/**
+ * 敏感信息检测验证器（通用版本）
+ *
+ * 防止将敏感信息提交到代码仓库
+ * 可配置检测模式、忽略规则、文件类型等
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import type { SensitiveConfig, SensitiveError } from './index.js';
+
+/**
+ * 检查单个文件中的敏感信息
+ */
+function checkFileSensitiveData(
+  filePath: string,
+  rootPath: string,
+  config: SensitiveConfig
+): SensitiveError[] {
+  const content = readFileSync(filePath, 'utf-8');
+  const errors: SensitiveError[] = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmedLine = line.trim();
+
+    if (
+      trimmedLine.startsWith('//') ||
+      trimmedLine.startsWith('#') ||
+      trimmedLine.startsWith('/*') ||
+      trimmedLine.startsWith('*')
+    ) {
+      continue;
+    }
+
+    for (const rule of config.patterns) {
+      if (rule.pattern.test(trimmedLine)) {
+        if (rule.excludePattern && rule.excludePattern.test(trimmedLine)) {
+          continue;
+        }
+
+        const relativePath = relative(rootPath, filePath);
+        if (config.ignorePatterns?.some((pattern) => pattern.test(relativePath))) {
+          continue;
+        }
+
+        errors.push({
+          file: relativePath,
+          line: i + 1,
+          message: rule.message,
+          content: trimmedLine.substring(0, 100) + (trimmedLine.length > 100 ? '...' : ''),
+        });
+        break;
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * 扫描目录中的所有文件
+ */
+function scanDirectory(
+  rootPath: string,
+  targetDir: string,
+  config: SensitiveConfig
+): SensitiveError[] {
+  const errors: SensitiveError[] = [];
+  const targetPath = join(rootPath, targetDir);
+
+  if (!existsSync(targetPath)) {
+    return errors;
+  }
+
+  function scanDir(dir: string) {
+    const entries = readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        // 跳过忽略的目录
+        if (!config.ignorePatterns?.some((pattern) => pattern.test(entry.name))) {
+          scanDir(fullPath);
+        }
+      } else if (entry.isFile()) {
+        // 检查文件扩展名
+        const hasMatchingExtension = config.fileExtensions.some((ext) =>
+          entry.name.endsWith(ext)
+        );
+
+        if (hasMatchingExtension) {
+          const fileErrors = checkFileSensitiveData(fullPath, rootPath, config);
+          errors.push(...fileErrors);
+        }
+      }
+    }
+  }
+
+  scanDir(targetPath);
+  return errors;
+}
+
+/**
+ * 检查 .env 文件是否被 Git 追踪
+ */
+async function checkEnvFiles(rootPath: string): Promise<SensitiveError[]> {
+  const { execSync } = await import('node:child_process');
+  const errors: SensitiveError[] = [];
+
+  try {
+    const trackedFiles = execSync('git ls-files', {
+      cwd: rootPath,
+      encoding: 'utf-8',
+    });
+
+    const envFiles = trackedFiles
+      .split('\n')
+      .filter((line: string) => line.trim() && /^\.env$/i.test(line.trim()));
+
+    for (const envFile of envFiles) {
+      errors.push({
+        file: envFile,
+        line: 0,
+        message: '.env file should not be committed to Git',
+        content: 'Add to .gitignore or use .env.example instead',
+      });
+    }
+  } catch {
+    // Git 命令失败（可能不是 Git 仓库），忽略
+  }
+
+  return errors;
+}
+
+/**
+ * 主验证函数
+ */
+export async function validateSensitive(
+  config: SensitiveConfig,
+  rootPath: string
+): Promise<SensitiveError[]> {
+  const allErrors: SensitiveError[] = [];
+
+  // 检查 .env 文件
+  const envErrors = await checkEnvFiles(rootPath);
+  allErrors.push(...envErrors);
+
+  // 扫描目录
+  for (const dir of config.checkDirs) {
+    const errors = scanDirectory(rootPath, dir, config);
+    allErrors.push(...errors);
+  }
+
+  return allErrors;
+}
+
+/**
+ * 格式化错误输出
+ */
+export function formatSensitiveErrors(errors: SensitiveError[]): string {
+  if (errors.length === 0) return '';
+
+  let output = `❌ Found ${errors.length} sensitive data issue(s):\n\n`;
+
+  for (const err of errors) {
+    if (err.line > 0) {
+      output += `  ${err.file}:${err.line}:\n`;
+    } else {
+      output += `  ${err.file}:\n`;
+    }
+    output += `    ${err.content}\n`;
+    output += `    → ${err.message}\n\n`;
+  }
+
+  output += '📋 Security Guidelines:\n';
+  output += '  - Use environment variables for sensitive data\n';
+  output += '  - Add .env files to .gitignore\n';
+  output += '  - Use .env.example as a template\n';
+  output += '  - Remove console.log statements before committing\n';
+
+  return output;
+}

package/template/lint-scripts/validators/server-rpc.validator.ts

@@ -0,0 +1,141 @@
+/**
+ * 服务端 RPC 规范验证器
+ *
+ * 检查服务端路由文件是否符合 Hono RPC 规范：
+ * 1. 必须使用 OpenAPIHono 链式语法
+ * 2. 禁止非链式调用
+ * 3. 必须导出路由类型
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import type { ServerRPCConfig, ServerRPCError } from './index.js'
+
+export function validateServerRPCInFile(
+  filePath: string,
+  rootPath: string,
+  config: ServerRPCConfig,
+  fileContent?: string
+): ServerRPCError[] {
+  const content = fileContent || readFileSync(filePath, 'utf-8')
+  const lines = content.split('\n')
+  const errors: ServerRPCError[] = []
+
+  const hasOpenAPIHono = content.includes('OpenAPIHono')
+  if (!hasOpenAPIHono) return errors
+
+  const chainSyntaxPattern = /new\s+OpenAPIHono\s*\(\s*\)\s*\n?\s*\./
+  const nonChainPattern = /(?:const|let|var)\s+(\w+)\s*=\s*new\s+OpenAPIHono\s*\(\s*\)/
+
+  const chainMatch = content.match(chainSyntaxPattern)
+  const nonChainMatch = content.match(nonChainPattern)
+
+  if (nonChainMatch && !chainMatch) {
+    const variableName = nonChainMatch[1]
+    const lineNumber = content.substring(0, nonChainMatch.index!).split('\n').length
+
+    errors.push({
+      file: relative(rootPath, filePath),
+      line: lineNumber,
+      message: `Non-chain syntax detected: variable '${variableName}' is assigned but not using chain syntax`,
+      suggestion: `Use chain syntax: export const routes = new OpenAPIHono()\n  .openapi(route1, handler1)\n  .openapi(route2, handler2)`,
+    })
+
+    const standaloneOpenapiPattern = new RegExp(`${variableName}\\s*\\.\\s*openapi\\s*\\(`, 'g')
+    let match
+    while ((match = standaloneOpenapiPattern.exec(content)) !== null) {
+      const lineNum = content.substring(0, match.index).split('\n').length
+      errors.push({
+        file: relative(rootPath, filePath),
+        line: lineNum,
+        message: `Standalone .openapi() call on variable '${variableName}'`,
+        suggestion: `Chain the .openapi() calls directly after new OpenAPIHono()`,
+      })
+    }
+  }
+
+  if (config.requireTypeExport) {
+    const hasTypeExport = /export\s+(?:type|const)\s+\w+/.test(content)
+    const hasExportDefault = /export\s+(?:const|default)\s+\w+/.test(content)
+
+    if (!hasTypeExport && !hasExportDefault && chainMatch) {
+      const lineNumber = lines.length
+      errors.push({
+        file: relative(rootPath, filePath),
+        line: lineNumber,
+        message: 'Route file does not export route type or instance',
+        suggestion: `Export the route: export const apiRoutes = new OpenAPIHono()... or export type { RoutesType }`,
+      })
+    }
+  }
+
+  return errors
+}
+
+function scanDirectory(
+  rootPath: string,
+  targetDir: string,
+  config: ServerRPCConfig
+): ServerRPCError[] {
+  const errors: ServerRPCError[] = []
+  const targetPath = join(rootPath, targetDir)
+
+  if (!existsSync(targetPath)) {
+    return errors
+  }
+
+  function scanDir(dir: string) {
+    const entries = readdirSync(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        if (!config.ignoreDirs.includes(entry.name)) {
+          scanDir(fullPath)
+        }
+      } else if (entry.isFile() && entry.name.includes('routes') && entry.name.endsWith('.ts')) {
+        const fileErrors = validateServerRPCInFile(fullPath, rootPath, config)
+        errors.push(...fileErrors)
+      }
+    }
+  }
+
+  scanDir(targetPath)
+  return errors
+}
+
+export function validateServerRPC(config: ServerRPCConfig, rootPath: string): ServerRPCError[] {
+  const allErrors: ServerRPCError[] = []
+
+  for (const dir of config.checkDirs) {
+    const errors = scanDirectory(rootPath, dir, config)
+    allErrors.push(...errors)
+  }
+
+  return allErrors
+}
+
+export function formatServerRPCErrors(errors: ServerRPCError[]): string {
+  if (errors.length === 0) return ''
+
+  let output = `❌ Found ${errors.length} server RPC pattern error(s):\n\n`
+
+  for (const err of errors) {
+    output += `  ${err.file}:${err.line}\n`
+    output += `    Error: ${err.message}\n`
+    output += `    Suggestion: ${err.suggestion}\n\n`
+  }
+
+  output += '📋 Server RPC Guidelines:\n'
+  output += '  ✅ DO: Use chain syntax with OpenAPIHono\n'
+  output += '    export const apiRoutes = new OpenAPIHono()\n'
+  output += '      .openapi(route1, handler1)\n'
+  output += '      .openapi(route2, handler2)\n\n'
+  output += "  ❌ DON'T: Use standalone variable assignment\n"
+  output += '    const app = new OpenAPIHono()\n'
+  output += '    app.openapi(route1, handler1)\n\n'
+  output += '  📖 See: .claude/rules/api-type-inference-rules.md\n'
+
+  return output
+}

package/template/lint-scripts/validators/test-quality.validator.ts

@@ -0,0 +1,257 @@
+/**
+ * 测试质量验证器
+ *
+ * 检查测试文件的质量：
+ * 1. 每个测试用例的断言数量（避免断言太少）
+ * 2. 错误场景覆盖（必须有错误断言）
+ * 3. 边界情况覆盖
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import type { TestQualityConfig, TestQualityError, TestQualityWarning } from './index.js'
+import { minimatch } from 'minimatch'
+
+interface TestCase {
+  name: string
+  suite: string
+  startLine: number
+  endLine: number
+  assertions: string[]
+  hasErrorAssertion: boolean
+  hasEdgeCaseAssertion: boolean
+}
+
+interface ParsedTestFile {
+  file: string
+  testCases: TestCase[]
+  totalAssertions: number
+  errorAssertions: number
+  edgeCaseAssertions: number
+}
+
+function parseTestFile(filePath: string, config: TestQualityConfig): ParsedTestFile {
+  const content = readFileSync(filePath, 'utf-8')
+  const lines = content.split('\n')
+  const testCases: TestCase[] = []
+  let currentSuite = ''
+  let currentTest: TestCase | null = null
+  let braceDepth = 0
+  let testStartLine = 0
+
+  const errorPatterns = config.errorAssertionPatterns.map(p => new RegExp(p, 'i'))
+  const edgeCasePatterns = config.edgeCasePatterns.map(p => new RegExp(p, 'i'))
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNum = i + 1
+
+    const suiteMatch = line.match(/describe\s*\(\s*['"`]([^'"`]+)['"`]/)
+    if (suiteMatch) {
+      currentSuite = suiteMatch[1]
+    }
+
+    // Support both single-line and multi-line test definitions
+    // Single-line: it('name', () => { })
+    // Multi-line: it(\n  'name',\n  () => { }
+    let testMatch = line.match(/(?:it|test)\s*\(\s*['"`]([^'"`]+)['"`]/)
+
+    // If no match and line ends with '(', check next line for test name
+    if (!testMatch && /(?:it|test)\s*\(\s*$/.test(line)) {
+      for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
+        const nextLine = lines[j].trim()
+        const multiLineMatch = nextLine.match(/^['"`]([^'"`]+)['"`]/)
+        if (multiLineMatch) {
+          testMatch = multiLineMatch
+          break
+        }
+      }
+    }
+
+    if (testMatch) {
+      if (currentTest) {
+        testCases.push(currentTest)
+      }
+      currentTest = {
+        name: testMatch[1],
+        suite: currentSuite,
+        startLine: lineNum,
+        endLine: lineNum,
+        assertions: [],
+        hasErrorAssertion: false,
+        hasEdgeCaseAssertion: false,
+      }
+      testStartLine = lineNum
+      braceDepth = 0
+    }
+
+    if (currentTest) {
+      const expectMatches = line.match(/expect\s*\(/g)
+      if (expectMatches) {
+        for (const match of expectMatches) {
+          currentTest.assertions.push(line.trim())
+
+          const lineLower = line.toLowerCase()
+          if (errorPatterns.some(p => p.test(line))) {
+            currentTest.hasErrorAssertion = true
+          }
+          if (edgeCasePatterns.some(p => p.test(line))) {
+            currentTest.hasEdgeCaseAssertion = true
+          }
+        }
+      }
+
+      braceDepth += (line.match(/{/g) || []).length
+      braceDepth -= (line.match(/}/g) || []).length
+
+      if (braceDepth <= 0 && line.includes('})') && lineNum > testStartLine) {
+        currentTest.endLine = lineNum
+        testCases.push(currentTest)
+        currentTest = null
+      }
+    }
+  }
+
+  if (currentTest) {
+    testCases.push(currentTest)
+  }
+
+  const totalAssertions = testCases.reduce((sum, t) => sum + t.assertions.length, 0)
+  const errorAssertions = testCases.filter(t => t.hasErrorAssertion).length
+  const edgeCaseAssertions = testCases.filter(t => t.hasEdgeCaseAssertion).length
+
+  return {
+    file: filePath,
+    testCases,
+    totalAssertions,
+    errorAssertions,
+    edgeCaseAssertions,
+  }
+}
+
+function findTestFiles(rootPath: string, config: TestQualityConfig): string[] {
+  const testFiles: string[] = []
+
+  function scanDir(dir: string) {
+    if (!existsSync(dir)) return
+
+    const entries = readdirSync(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        if (!config.ignoreDirs.includes(entry.name)) {
+          scanDir(fullPath)
+        }
+      } else if (
+        entry.isFile() &&
+        (entry.name.endsWith('.test.ts') || entry.name.endsWith('.spec.ts'))
+      ) {
+        testFiles.push(fullPath)
+      }
+    }
+  }
+
+  for (const checkDir of config.checkDirs) {
+    scanDir(join(rootPath, checkDir))
+  }
+
+  return testFiles
+}
+
+export function validateTestQuality(
+  config: TestQualityConfig,
+  rootPath: string
+): { errors: TestQualityError[]; warnings: TestQualityWarning[] } {
+  const errors: TestQualityError[] = []
+  const warnings: TestQualityWarning[] = []
+  const testFiles = findTestFiles(rootPath, config)
+
+  for (const filePath of testFiles) {
+    const parsed = parseTestFile(filePath, config)
+    const relativePath = relative(rootPath, filePath)
+
+    for (const testCase of parsed.testCases) {
+      if (testCase.assertions.length < config.minAssertionsPerTest) {
+        warnings.push({
+          file: relativePath,
+          testSuite: testCase.suite,
+          testName: testCase.name,
+          assertionCount: testCase.assertions.length,
+          suggestion: `增加断言数量，当前只有 ${testCase.assertions.length} 个，建议至少 ${config.minAssertionsPerTest} 个`,
+        })
+      }
+    }
+
+    if (config.requireErrorAssertions && parsed.errorAssertions === 0) {
+      errors.push({
+        file: relativePath,
+        testSuite: '',
+        testName: '',
+        issue: '缺少错误场景测试',
+        suggestion: '添加错误场景测试，如：无效参数、边界值、异常情况等',
+      })
+    }
+
+    if (config.requireEdgeCaseAssertions && parsed.edgeCaseAssertions === 0) {
+      warnings.push({
+        file: relativePath,
+        testSuite: '',
+        testName: '',
+        assertionCount: 0,
+        suggestion: '考虑添加边界情况测试，如：空值、最大值、最小值等',
+      })
+    }
+  }
+
+  return { errors, warnings }
+}
+
+export function formatTestQualityErrors(
+  errors: TestQualityError[],
+  warnings: TestQualityWarning[]
+): string {
+  const totalIssues = errors.length + warnings.length
+  if (totalIssues === 0) return ''
+
+  let output = `❌ Found ${totalIssues} test quality issue(s):\n\n`
+
+  if (errors.length > 0) {
+    output += `🚨 Errors (${errors.length}):\n\n`
+    for (const err of errors) {
+      output += `  📄 ${err.file}\n`
+      if (err.testSuite || err.testName) {
+        output += `     Test: ${err.testSuite}${err.testName ? ' > ' + err.testName : ''}\n`
+      }
+      output += `     Issue: ${err.issue}\n`
+      output += `     Suggestion: ${err.suggestion}\n\n`
+    }
+  }
+
+  if (warnings.length > 0) {
+    output += `⚠️  Warnings (${warnings.length}):\n\n`
+    for (const warn of warnings) {
+      output += `  📄 ${warn.file}\n`
+      if (warn.testSuite || warn.testName) {
+        output += `     Test: ${warn.testSuite}${warn.testName ? ' > ' + warn.testName : ''}\n`
+      }
+      if (warn.assertionCount > 0) {
+        output += `     Assertions: ${warn.assertionCount}\n`
+      }
+      output += `     Suggestion: ${warn.suggestion}\n\n`
+    }
+  }
+
+  output += '📋 Test Quality Guidelines:\n\n'
+  output += '  1. 每个测试用例至少要有 2-3 个断言\n'
+  output += '  2. 必须包含错误场景测试（无效参数、异常情况）\n'
+  output += '  3. 建议包含边界情况测试（空值、极值）\n\n'
+  output += '  错误断言示例:\n'
+  output += '    expect(res.status).toBe(400)   // 无效参数\n'
+  output += '    expect(res.status).toBe(404)   // 资源不存在\n'
+  output += '    expect(res.status).toBe(500)   // 服务器错误\n'
+  output += '    expect(result).toBeNull()      // 空值处理\n\n'
+
+  return output
+}

package/template/lint-scripts/validators/todos.validator.ts

@@ -0,0 +1,126 @@
+/**
+ * TODO/FIXME 验证器（通用版本）
+ *
+ * 检查代码中是否有未归属的 TODO/FIXME/HACK 注释
+ * 可配置关键词、允许模式、忽略目录等
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import type { TodosConfig, TodoError } from './index.js';
+
+/**
+ * 检查单个文件中的 TODO/FIXME
+ */
+export function validateTodosInFile(
+  filePath: string,
+  rootPath: string,
+  config: TodosConfig
+): TodoError[] {
+  const content = readFileSync(filePath, 'utf-8');
+  const errors: TodoError[] = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmedLine = line.trim();
+
+    // 检查是否包含关键词
+    for (const keyword of config.keywords) {
+      // 匹配注释中的 TODO/FIXME 等
+      const regex = new RegExp(`//.*${keyword}:|/\\*.*${keyword}:|<!--.*${keyword}:`, 'i');
+
+      if (regex.test(trimmedLine)) {
+        // 检查是否有允许模式（如 @author）
+        if (!config.allowedPattern.test(trimmedLine)) {
+          errors.push({
+            file: relative(rootPath, filePath),
+            line: i + 1,
+            keyword,
+            content: trimmedLine,
+          });
+        }
+        break;
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * 扫描目录中的所有文件
+ */
+function scanDirectory(rootPath: string, targetDir: string, config: TodosConfig): TodoError[] {
+  const errors: TodoError[] = [];
+  const targetPath = join(rootPath, targetDir);
+
+  if (!existsSync(targetPath)) {
+    return errors;
+  }
+
+  function scanDir(dir: string) {
+    const entries = readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        // 跳过忽略的目录
+        if (!config.ignoreDirs.includes(entry.name)) {
+          scanDir(fullPath);
+        }
+      } else if (
+        entry.isFile() &&
+        (entry.name.endsWith('.ts') ||
+          entry.name.endsWith('.tsx') ||
+          entry.name.endsWith('.js') ||
+          entry.name.endsWith('.jsx'))
+      ) {
+        const fileErrors = validateTodosInFile(fullPath, rootPath, config);
+        errors.push(...fileErrors);
+      }
+    }
+  }
+
+  scanDir(targetPath);
+  return errors;
+}
+
+/**
+ * 主验证函数
+ */
+export function validateTodos(config: TodosConfig, rootPath: string): TodoError[] {
+  const allErrors: TodoError[] = [];
+
+  for (const dir of config.checkDirs) {
+    const errors = scanDirectory(rootPath, dir, config);
+    allErrors.push(...errors);
+  }
+
+  return allErrors;
+}
+
+/**
+ * 格式化错误输出
+ */
+export function formatTodoErrors(errors: TodoError[]): string {
+  if (errors.length === 0) return '';
+
+  let output = `❌ Found ${errors.length} unassigned TODO(s):\n\n`;
+
+  for (const err of errors) {
+    output += `  ${err.file}:${err.line}:\n`;
+    output += `    ${err.content}\n`;
+    output += `    → Found unassigned "${err.keyword}"\n`;
+    output += `    → Fix: Remove "${err.keyword}" or add @author\n\n`;
+  }
+
+  output += '📋 Guidelines:\n';
+  output += '  Bad:  TODO or FIXME without @author\n';
+  output += '  Good: TODO @john: implement feature X\n';
+  output += '  Good: FIXME @sarah: refactor this function\n';
+  output += '\n  Note: Add @author to your TODOs to mark them as assigned.\n';
+
+  return output;
+}