create-fullstack-scaffold 0.1.0

package/template/lint-scripts/validators/console-log.validator.ts

@@ -0,0 +1,122 @@
+/**
+ * Console.log 检测验证器
+ *
+ * 检测代码中遗留的 console.log/console.debug 语句
+ * 这些语句不应该出现在生产代码中
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import type { ConsoleLogConfig, ConsoleLogError } from './index.js'
+
+function checkFileConsoleLog(
+  filePath: string,
+  rootPath: string,
+  config: ConsoleLogConfig
+): ConsoleLogError[] {
+  const content = readFileSync(filePath, 'utf-8')
+  const errors: ConsoleLogError[] = []
+  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
+    }
+
+    if (config.pattern.test(trimmedLine)) {
+      if (config.excludePattern && config.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: 'console.log detected (remove before committing)',
+        content: trimmedLine.substring(0, 100) + (trimmedLine.length > 100 ? '...' : ''),
+      })
+    }
+  }
+
+  return errors
+}
+
+function scanDirectory(
+  rootPath: string,
+  targetDir: string,
+  config: ConsoleLogConfig
+): ConsoleLogError[] {
+  const errors: ConsoleLogError[] = []
+  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 = checkFileConsoleLog(fullPath, rootPath, config)
+          errors.push(...fileErrors)
+        }
+      }
+    }
+  }
+
+  scanDir(targetPath)
+  return errors
+}
+
+export function validateConsoleLog(config: ConsoleLogConfig, rootPath: string): ConsoleLogError[] {
+  const allErrors: ConsoleLogError[] = []
+
+  for (const dir of config.checkDirs) {
+    const errors = scanDirectory(rootPath, dir, config)
+    allErrors.push(...errors)
+  }
+
+  return allErrors
+}
+
+export function formatConsoleLogErrors(errors: ConsoleLogError[]): string {
+  if (errors.length === 0) return ''
+
+  let output = `❌ Found ${errors.length} console.log statement(s):\n\n`
+
+  for (const err of errors) {
+    output += `  ${err.file}:${err.line}:\n`
+    output += `    ${err.content}\n`
+    output += `    → ${err.message}\n\n`
+  }
+
+  output += '📋 Code Quality Guidelines:\n'
+  output += '  - Remove console.log before committing\n'
+  output += '  - Use logger utility for production logging\n'
+  output += '  - Test files can use console.log for debugging\n'
+
+  return output
+}

package/template/lint-scripts/validators/directory-structure.validator.ts

@@ -0,0 +1,181 @@
+/**
+ * 目录结构验证器（增强版）
+ *
+ * 检查文件是否放在正确的目录中：
+ * 1. 路由文件必须在 routes/ 目录
+ * 2. 服务文件必须在 services/ 目录
+ * 3. 测试文件必须在 __tests__/ 或 e2e/ 或 integration/ 目录
+ * 4. 禁止在根目录随意放置文件
+ * 5. 禁止在特定位置放置特定类型的文件
+ */
+
+import { readdirSync, existsSync } from 'node:fs'
+import { join, relative, dirname, basename } from 'node:path'
+import type { DirectoryStructureConfig, DirectoryError, ForbiddenError } from './index.js'
+import { minimatch } from 'minimatch'
+
+function validateFileLocation(
+  filePath: string,
+  rootPath: string,
+  config: DirectoryStructureConfig
+): { directoryErrors: DirectoryError[]; forbiddenErrors: ForbiddenError[] } {
+  const directoryErrors: DirectoryError[] = []
+  const forbiddenErrors: ForbiddenError[] = []
+  const relativePath = relative(rootPath, filePath)
+  const fileName = basename(filePath)
+  const fileDir = dirname(relativePath)
+
+  // 跳过测试目录
+  if (
+    relativePath.includes('e2e/') ||
+    relativePath.includes('integration/') ||
+    relativePath.includes('__tests__/') ||
+    relativePath.includes('lint-scripts/')
+  ) {
+    return { directoryErrors, forbiddenErrors }
+  }
+
+  // 检查必需的目录规则
+  for (const rule of config.rules) {
+    if (minimatch(fileName, rule.pattern)) {
+      const expectedDir = rule.requiredDir
+      const isInCorrectDir = fileDir.includes(expectedDir) || fileDir.endsWith(expectedDir)
+
+      if (!isInCorrectDir) {
+        const actualDir = fileDir === '.' ? 'root' : fileDir.split('/').pop() || 'root'
+        directoryErrors.push({
+          file: relativePath,
+          expectedDir: expectedDir,
+          actualDir: actualDir,
+        })
+      }
+    }
+  }
+
+  // 检查禁止的位置规则
+  if (config.forbiddenLocations) {
+    for (const forbidden of config.forbiddenLocations) {
+      if (minimatch(fileName, forbidden.pattern)) {
+        const isInForbiddenDir = forbidden.forbiddenDirs.some(
+          forbiddenDir => fileDir === forbiddenDir || fileDir.startsWith(forbiddenDir + '/')
+        )
+
+        if (isInForbiddenDir) {
+          forbiddenErrors.push({
+            file: relativePath,
+            message: forbidden.message,
+            suggestion: forbidden.suggestion,
+          })
+        }
+      }
+    }
+  }
+
+  // 检查根目录文件
+  if (config.allowedRootFiles && fileDir === '.') {
+    const isAllowed = config.allowedRootFiles.some(allowedPattern =>
+      minimatch(fileName, allowedPattern)
+    )
+
+    if (!isAllowed && (fileName.endsWith('.ts') || fileName.endsWith('.tsx'))) {
+      // 允许配置文件
+      const configFiles = ['*.config.ts', '*.config.js', '*.setup.ts', 'vite-env.d.ts']
+      const isConfigFile = configFiles.some(pattern => minimatch(fileName, pattern))
+
+      if (!isConfigFile) {
+        forbiddenErrors.push({
+          file: relativePath,
+          message: `Source file '${fileName}' should not be in root directory`,
+          suggestion: `Move to appropriate directory under src/ or scripts/`,
+        })
+      }
+    }
+  }
+
+  return { directoryErrors, forbiddenErrors }
+}
+
+function scanDirectory(
+  rootPath: string,
+  config: DirectoryStructureConfig
+): { directoryErrors: DirectoryError[]; forbiddenErrors: ForbiddenError[] } {
+  const directoryErrors: DirectoryError[] = []
+  const forbiddenErrors: ForbiddenError[] = []
+
+  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('.ts') || entry.name.endsWith('.tsx'))) {
+        const errors = validateFileLocation(fullPath, rootPath, config)
+        directoryErrors.push(...errors.directoryErrors)
+        forbiddenErrors.push(...errors.forbiddenErrors)
+      }
+    }
+  }
+
+  scanDir(rootPath)
+  return { directoryErrors, forbiddenErrors }
+}
+
+export function validateDirectoryStructure(
+  config: DirectoryStructureConfig,
+  rootPath: string
+): { directoryErrors: DirectoryError[]; forbiddenErrors: ForbiddenError[] } {
+  return scanDirectory(rootPath, config)
+}
+
+export function formatDirectoryErrors(
+  directoryErrors: DirectoryError[],
+  forbiddenErrors: ForbiddenError[]
+): string {
+  const totalErrors = directoryErrors.length + forbiddenErrors.length
+  if (totalErrors === 0) return ''
+
+  let output = `❌ Found ${totalErrors} directory structure error(s):\n\n`
+
+  // 格式化目录错误
+  if (directoryErrors.length > 0) {
+    output += `📁 Wrong Directory Location (${directoryErrors.length}):\n\n`
+    for (const err of directoryErrors) {
+      output += `  ${err.file}\n`
+      output += `    Expected: ${err.expectedDir}/\n`
+      output += `    Actual: ${err.actualDir}/\n\n`
+    }
+  }
+
+  // 格式化禁止位置错误
+  if (forbiddenErrors.length > 0) {
+    output += `🚫 Forbidden Location (${forbiddenErrors.length}):\n\n`
+    for (const err of forbiddenErrors) {
+      output += `  ${err.file}\n`
+      output += `    ${err.message}\n`
+      output += `    Suggestion: ${err.suggestion}\n\n`
+    }
+  }
+
+  output += '📋 Directory Structure Guidelines:\n\n'
+  output += '  src/server/module-{feature}/\n'
+  output += '    ├── routes/          # Route files (*routes*.ts)\n'
+  output += '    ├── services/        # Service files (*service*.ts)\n'
+  output += '    └── __tests__/       # Test files (*.test.ts)\n\n'
+  output += '  src/client/\n'
+  output += '    ├── services/        # Client services\n'
+  output += '    ├── stores/          # State management\n'
+  output += '    ├── hooks/           # React hooks\n'
+  output += '    └── components/      # UI components\n\n'
+  output += '  scripts/              # Build and utility scripts\n'
+  output += '  e2e/                  # E2E tests\n'
+  output += '  docs/                 # Documentation\n\n'
+  output += '  📖 See: .claude/rules/project-rules.md\n'
+
+  return output
+}

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

@@ -0,0 +1,180 @@
+/**
+ * 导入路径验证器（通用版本）
+ *
+ * 检测跨模块的相对路径导入
+ * 可配置模块名称、路径别名、最小深度等
+ *
+ * 核心规则：
+ * - 允许: ../ (同模块内相对导入)
+ * - 禁止: ../../ 或更多 (跨模块，必须用别名)
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative, dirname, resolve } from 'node:path';
+import type { ImportsConfig, ImportError, ModuleName } from './index.js';
+
+/**
+ * 从文件路径提取模块名称
+ */
+function getModule(
+  filePath: string,
+  srcDir: string,
+  modules: readonly ModuleName[]
+): ModuleName | null {
+  const normalized = filePath.replace(/\\/g, '/');
+  const parts = normalized.split('/');
+  const srcIndex = parts.indexOf(srcDir);
+
+  if (srcIndex === -1 || srcIndex + 1 >= parts.length) return null;
+
+  const moduleName = parts[srcIndex + 1];
+  return modules.includes(moduleName) ? moduleName : null;
+}
+
+/**
+ * 提取文件中的所有 import 语句
+ */
+function extractImports(content: string): string[] {
+  const regex = /import\s+.*?from\s+['"]([^'"]+)['"]/g;
+  const imports: string[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+
+  return imports;
+}
+
+/**
+ * 检查是否为相对路径
+ */
+function isRelativePath(path: string): boolean {
+  return path.startsWith('./') || path.startsWith('../');
+}
+
+/**
+ * 计算相对路径深度
+ */
+function getRelativeDepth(path: string): number {
+  const matches = path.match(/\.\.\//g);
+  return matches ? matches.length : 0;
+}
+
+/**
+ * 检查单个文件的导入
+ */
+export function validateImportsInFile(
+  filePath: string,
+  rootPath: string,
+  config: ImportsConfig
+): ImportError[] {
+  const content = readFileSync(filePath, 'utf-8');
+  const imports = extractImports(content);
+  const fileModule = getModule(filePath, config.srcDir, config.modules);
+
+  if (!fileModule) return [];
+
+  const errors: ImportError[] = [];
+
+  for (const imp of imports) {
+    if (!isRelativePath(imp)) continue;
+
+    const depth = getRelativeDepth(imp);
+
+    // ⭐ 核心规则：../ 允许，../../ 或更多禁止
+    // 跨模块检测：达到最小深度且目标模块不同
+    if (depth >= config.minCrossModuleDepth) {
+      const fullPath = resolve(dirname(filePath), imp);
+      const targetModule = getModule(fullPath, config.srcDir, config.modules);
+
+      if (targetModule && targetModule !== fileModule) {
+        // 计算建议的别名路径
+        const targetSrcDir = join(rootPath, config.srcDir, targetModule);
+        const relativePath = relative(targetSrcDir, fullPath).replace(/\\/g, '/');
+
+        errors.push({
+          file: relative(rootPath, filePath),
+          importPath: imp,
+          suggestion: `@${targetModule}/${relativePath}`,
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * 扫描目录中的所有文件
+ */
+function scanDirectory(rootPath: string, targetDir: string, config: ImportsConfig): ImportError[] {
+  const errors: ImportError[] = [];
+  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'))) {
+        const fileErrors = validateImportsInFile(fullPath, rootPath, config);
+        errors.push(...fileErrors);
+      }
+    }
+  }
+
+  scanDir(targetPath);
+  return errors;
+}
+
+/**
+ * 主验证函数
+ */
+export function validateImports(config: ImportsConfig, rootPath: string): ImportError[] {
+  const allErrors: ImportError[] = [];
+
+  for (const dir of config.checkDirs) {
+    const errors = scanDirectory(rootPath, dir, config);
+    allErrors.push(...errors);
+  }
+
+  return allErrors;
+}
+
+/**
+ * 格式化错误输出
+ */
+export function formatImportErrors(errors: ImportError[]): string {
+  if (errors.length === 0) return '';
+
+  let output = `❌ Found ${errors.length} cross-module import(s):\n\n`;
+
+  for (const err of errors) {
+    output += `  ${err.file}:\n`;
+    output += `    Import: '${err.importPath}'\n`;
+    output += `    Suggestion: Change to '${err.suggestion}'\n\n`;
+  }
+
+  output += '📋 Import Path Guidelines:\n';
+  output += '  ✅ OK:  import { X } from "./sibling-file"         (same directory)\n';
+  output += '  ✅ OK:  import { X } from "../parent-file"          (parent directory)\n';
+  output += '  ❌ BAD: import { X } from "../../shared/types"     (cross-module, 2+ levels)\n';
+  output += '  ❌ BAD: import { X } from "../../../client/store"   (cross-module, 3+ levels)\n\n';
+  output += '  Use path aliases for cross-module imports:\n';
+  output += '  - @shared/* for shared types\n';
+  output += '  - @client/* for client code\n';
+  output += '  - @server/* for server code\n';
+
+  return output;
+}