create-fullstack-scaffold 0.1.0

package/template/lint-scripts/validators/index.ts

@@ -0,0 +1,271 @@
+/**
+ * 通用验证器的类型定义
+ */
+
+// ============================================
+// TODO/FIXME 验证配置
+// ============================================
+export interface TodosConfig {
+  keywords: string[]
+  allowedPattern: RegExp
+  ignoreDirs: string[]
+  checkDirs: string[]
+}
+
+export interface TodoError {
+  file: string
+  line: number
+  keyword: string
+  content: string
+}
+
+// ============================================
+// 敏感信息检测配置
+// ============================================
+export interface PatternRule {
+  pattern: RegExp
+  message: string
+  excludePattern?: RegExp
+}
+
+export interface SensitiveConfig {
+  patterns: PatternRule[]
+  ignorePatterns?: RegExp[]
+  fileExtensions: string[]
+  checkDirs: string[]
+}
+
+export interface SensitiveError {
+  file: string
+  line: number
+  message: string
+  content: string
+}
+
+// ============================================
+// 导入路径验证配置
+// ============================================
+export type ModuleName = string
+
+export interface ImportsConfig {
+  modules: readonly ModuleName[]
+  srcDir: string
+  aliases: Record<string, string>
+  minCrossModuleDepth: number
+  ignoreDirs: string[]
+  checkDirs: string[]
+}
+
+export interface ImportError {
+  file: string
+  importPath: string
+  suggestion: string
+}
+
+// ============================================
+// 服务端 RPC 验证配置
+// ============================================
+export interface ServerRPCConfig {
+  checkDirs: string[]
+  ignoreDirs: string[]
+  requireChainSyntax: boolean
+  requireTypeExport: boolean
+}
+
+export interface ServerRPCError {
+  file: string
+  line: number
+  message: string
+  suggestion: string
+}
+
+// ============================================
+// 客户端 RPC 验证配置
+// ============================================
+export interface ClientRPCConfig {
+  checkDirs: string[]
+  ignoreDirs: string[]
+  requireAPIClient: boolean
+  forbidDirectFetch: boolean
+  forbidDirectWebSocket?: boolean
+  forbidDirectEventSource?: boolean
+}
+
+export interface ClientRPCError {
+  file: string
+  line: number
+  message: string
+  suggestion: string
+}
+
+// ============================================
+// 目录结构验证配置
+// ============================================
+export interface DirectoryRule {
+  pattern: string
+  requiredDir: string
+  description?: string
+}
+
+export interface ForbiddenLocation {
+  pattern: string
+  forbiddenDirs: string[]
+  message: string
+  suggestion: string
+}
+
+export interface DirectoryStructureConfig {
+  rules: DirectoryRule[]
+  forbiddenLocations?: ForbiddenLocation[]
+  ignoreDirs: string[]
+  allowedRootFiles?: string[]
+}
+
+export interface DirectoryError {
+  file: string
+  expectedDir: string
+  actualDir: string
+}
+
+export interface ForbiddenError {
+  file: string
+  message: string
+  suggestion: string
+}
+
+// ============================================
+// 模块测试文件验证配置
+// ============================================
+export interface RequiredTestFile {
+  pattern: string
+  description: string
+  minAssertions?: number
+}
+
+export interface ModuleTestsConfig {
+  modulePattern: string
+  testsDir: string
+  requiredTestFiles: RequiredTestFile[]
+  ignoreDirs: string[]
+  checkDirs: string[]
+}
+
+export interface ModuleTestError {
+  module: string
+  missingTests: string[]
+  suggestion: string
+}
+
+// ============================================
+// 测试质量验证配置
+// ============================================
+export interface AssertionRule {
+  type: 'min_per_test' | 'error_coverage' | 'edge_case_coverage'
+  minCount?: number
+  description: string
+}
+
+export interface TestQualityConfig {
+  minAssertionsPerTest: number
+  requireErrorAssertions: boolean
+  requireEdgeCaseAssertions: boolean
+  errorAssertionPatterns: string[]
+  edgeCasePatterns: string[]
+  ignoreDirs: string[]
+  checkDirs: string[]
+}
+
+export interface TestQualityError {
+  file: string
+  testSuite: string
+  testName: string
+  issue: string
+  suggestion: string
+}
+
+export interface TestQualityWarning {
+  file: string
+  testSuite: string
+  testName: string
+  assertionCount: number
+  suggestion: string
+}
+
+// ============================================
+// Client 测试覆盖验证配置
+// ============================================
+export interface ClientTestRule {
+  dir: string
+  filePattern: string
+  testPattern: string
+  description: string
+}
+
+export interface ClientTestsConfig {
+  rules: ClientTestRule[]
+  ignoreFiles: string[]
+  ignoreDirs: string[]
+  checkDirs: string[]
+}
+
+export interface ClientTestError {
+  file: string
+  expectedTest: string
+  suggestion: string
+}
+
+// ============================================
+// Vite 路由配置验证配置
+// ============================================
+export interface ViteRoutesConfig {
+  viteConfigPath: string
+  checkDirs: string[]
+  ignoreDirs: string[]
+}
+
+export interface ViteRouteError {
+  file: string
+  line: number
+  routePath: string
+  basename: string | null
+  suggestion: string
+}
+
+export interface ParsedPattern {
+  pattern: string
+  isExact: boolean
+}
+
+// ============================================
+// Markdown 引用路径验证配置
+// ============================================
+export interface MdRefsConfig {
+  ignoreDirs: string[]
+  checkDirs: string[]
+}
+
+export interface MdRefError {
+  file: string
+  line: number
+  ref: string
+  resolvedPath: string
+  isGlob: boolean
+}
+
+// ============================================
+// Console.log 检测配置
+// ============================================
+export interface ConsoleLogConfig {
+  pattern: RegExp
+  excludePattern?: RegExp
+  ignorePatterns?: RegExp[]
+  fileExtensions: string[]
+  checkDirs: string[]
+}
+
+export interface ConsoleLogError {
+  file: string
+  line: number
+  message: string
+  content: string
+}

package/template/lint-scripts/validators/md-refs.validator.ts

@@ -0,0 +1,165 @@
+/**
+ * Markdown 引用路径验证器
+ *
+ * 检查项目中所有 md 文件的引用路径是否正确
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { glob } from 'glob'
+import type { MdRefsConfig, MdRefError } from './index.js'
+
+const MD_FILE_PATTERN = /\.md$/
+const MD_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/g
+
+const GLOB_CHARS = ['*', '?', '[', '{']
+const PLACEHOLDER_PATTERN = /\{[a-zA-Z_]+\}/
+const EXCLUDED_PROTOCOLS = ['http://', 'https://', 'mailto:']
+
+function isGlobPattern(p: string): boolean {
+  return GLOB_CHARS.some(char => p.includes(char))
+}
+
+function isPlaceholder(p: string): boolean {
+  return PLACEHOLDER_PATTERN.test(p)
+}
+
+function shouldExclude(refPath: string): boolean {
+  if (refPath.startsWith('#')) return true
+  if (EXCLUDED_PROTOCOLS.some(proto => refPath.startsWith(proto))) return true
+  return false
+}
+
+function findAllMdFiles(rootPath: string, config: MdRefsConfig): string[] {
+  const results: string[] = []
+
+  function scanDir(dir: string) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (!config.ignoreDirs.includes(entry.name)) {
+          scanDir(fullPath)
+        }
+      } else if (entry.isFile() && MD_FILE_PATTERN.test(entry.name)) {
+        results.push(fullPath)
+      }
+    }
+  }
+
+  for (const checkDir of config.checkDirs) {
+    const targetPath = path.join(rootPath, checkDir)
+    if (fs.existsSync(targetPath)) {
+      scanDir(targetPath)
+    }
+  }
+
+  return results
+}
+
+function checkGlobPattern(baseDir: string, pattern: string): boolean {
+  try {
+    const fullPattern = path.isAbsolute(pattern) ? pattern : path.join(baseDir, pattern)
+    const matchedFiles = glob.sync(fullPattern, {
+      cwd: baseDir,
+      nodir: true,
+    })
+    return matchedFiles.length > 0
+  } catch {
+    return false
+  }
+}
+
+function checkFileExists(baseDir: string, refPath: string): boolean {
+  const fullPath = path.isAbsolute(refPath) ? refPath : path.join(baseDir, refPath)
+  return fs.existsSync(fullPath)
+}
+
+export function validateMdRefs(config: MdRefsConfig, rootPath: string): MdRefError[] {
+  const errors: MdRefError[] = []
+  const mdFiles = findAllMdFiles(rootPath, config)
+
+  for (const filePath of mdFiles) {
+    const content = fs.readFileSync(filePath, 'utf-8')
+    const lines = content.split('\n')
+    const fileDir = path.dirname(filePath)
+    const relativePath = path.relative(rootPath, filePath)
+
+    lines.forEach((line, index) => {
+      const lineNum = index + 1
+
+      MD_LINK_PATTERN.lastIndex = 0
+      let match
+      while ((match = MD_LINK_PATTERN.exec(line)) !== null) {
+        const refPath = match[2]
+
+        if (shouldExclude(refPath)) continue
+        if (isPlaceholder(refPath)) continue
+
+        const resolvedPath = refPath.startsWith('/')
+          ? path.join(rootPath, refPath.slice(1))
+          : path.resolve(fileDir, refPath)
+
+        const resolvedRelative = path.relative(rootPath, resolvedPath)
+
+        if (isGlobPattern(refPath)) {
+          const exists = checkGlobPattern(refPath.startsWith('/') ? rootPath : fileDir, refPath)
+          if (!exists) {
+            errors.push({
+              file: relativePath,
+              line: lineNum,
+              ref: refPath,
+              resolvedPath: resolvedRelative,
+              isGlob: true,
+            })
+          }
+        } else {
+          const exists = checkFileExists(fileDir, refPath)
+          if (!exists) {
+            errors.push({
+              file: relativePath,
+              line: lineNum,
+              ref: refPath,
+              resolvedPath: resolvedRelative,
+              isGlob: false,
+            })
+          }
+        }
+      }
+    })
+  }
+
+  return errors
+}
+
+export function formatMdRefErrors(errors: MdRefError[]): string {
+  if (errors.length === 0) return ''
+
+  let output = `❌ Found ${errors.length} broken reference(s):\n\n`
+
+  const grouped = new Map<string, MdRefError[]>()
+  for (const err of errors) {
+    const key = err.file
+    if (!grouped.has(key)) grouped.set(key, [])
+    grouped.get(key)!.push(err)
+  }
+
+  for (const [file, refs] of Array.from(grouped.entries())) {
+    output += `  📄 ${file}\n`
+    for (const r of refs) {
+      if (r.isGlob) {
+        output += `     L${r.line}: ${r.ref} (NO MATCHES)\n`
+      } else {
+        output += `     L${r.line}: ${r.ref} -> ${r.resolvedPath} (NOT FOUND)\n`
+      }
+    }
+  }
+
+  output += '\n📋 Guidelines:\n'
+  output += '  - Ensure all file references exist\n'
+  output += '  - Use relative paths from the markdown file location\n'
+  output += '  - For absolute paths, start with / (project root)\n'
+
+  return output
+}

package/template/lint-scripts/validators/module-tests.validator.ts

@@ -0,0 +1,112 @@
+/**
+ * 模块测试文件验证器
+ *
+ * 检查每个模块是否有必需的测试文件：
+ * 1. 检查 __tests__/ 目录是否存在
+ * 2. 检查是否有 service 测试文件
+ * 3. 检查是否有 route 测试文件
+ */
+
+import { readdirSync, existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import type { ModuleTestsConfig, ModuleTestError, RequiredTestFile } from './index.js'
+import { minimatch } from 'minimatch'
+
+function findModules(rootPath: string, config: ModuleTestsConfig): string[] {
+  const modules: 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 (minimatch(entry.name, config.modulePattern)) {
+          modules.push(fullPath)
+        } else if (!config.ignoreDirs.includes(entry.name)) {
+          scanDir(fullPath)
+        }
+      }
+    }
+  }
+
+  for (const checkDir of config.checkDirs) {
+    scanDir(join(rootPath, checkDir))
+  }
+
+  return modules
+}
+
+function checkRequiredTestFiles(
+  modulePath: string,
+  config: ModuleTestsConfig
+): { missing: string[]; found: string[] } {
+  const testsDir = join(modulePath, config.testsDir)
+  const missing: string[] = []
+  const found: string[] = []
+
+  if (!existsSync(testsDir)) {
+    missing.push(`${config.testsDir}/ directory`)
+    return { missing, found }
+  }
+
+  const testFiles = readdirSync(testsDir).filter(f => f.endsWith('.test.ts') || f.endsWith('.spec.ts'))
+
+  for (const required of config.requiredTestFiles) {
+    const hasMatch = testFiles.some(file => minimatch(file, required.pattern))
+    if (hasMatch) {
+      found.push(required.description)
+    } else {
+      missing.push(required.description)
+    }
+  }
+
+  return { missing, found }
+}
+
+export function validateModuleTests(
+  config: ModuleTestsConfig,
+  rootPath: string
+): ModuleTestError[] {
+  const errors: ModuleTestError[] = []
+  const modules = findModules(rootPath, config)
+
+  for (const modulePath of modules) {
+    const moduleName = relative(rootPath, modulePath)
+    const { missing } = checkRequiredTestFiles(modulePath, config)
+
+    if (missing.length > 0) {
+      errors.push({
+        module: moduleName,
+        missingTests: missing,
+        suggestion: `在 ${moduleName}/${config.testsDir}/ 目录下添加缺失的测试文件`,
+      })
+    }
+  }
+
+  return errors
+}
+
+export function formatModuleTestErrors(errors: ModuleTestError[]): string {
+  if (errors.length === 0) return ''
+
+  let output = `❌ Found ${errors.length} module(s) with missing test files:\n\n`
+
+  for (const err of errors) {
+    output += `  📁 ${err.module}\n`
+    output += `     Missing: ${err.missingTests.join(', ')}\n`
+    output += `     Suggestion: ${err.suggestion}\n\n`
+  }
+
+  output += '📋 Required Test Files per Module:\n\n'
+  output += '  src/server/module-{feature}/\n'
+  output += '    └── __tests__/\n'
+  output += '        ├── *-service.test.ts    # Service layer tests\n'
+  output += '        └── *-route*.test.ts     # Route/API tests\n\n'
+  output += '  📖 Each module must have both service and route tests.\n'
+
+  return output
+}