cc-devflow 1.0.1

package/.claude/hooks/error-handling-reminder.ts

@@ -0,0 +1,459 @@
+#!/usr/bin/env node
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 错误处理最佳实践提醒 Hook (UserPromptSubmit)
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// 【核心功能】
+//   在用户提交新 prompt 前，分析本会话中已编辑的文件
+//   如果检测到可能存在错误处理风险的代码模式，提供定制化提醒
+//   帮助开发者在编码过程中遵循错误处理最佳实践
+//
+// 【工作原理】
+//   1. 读取会话级别的文件编辑跟踪日志 (edited-files.log)
+//   2. 根据文件路径，分类为 backend / frontend / database / other
+//   3. 对每个文件执行静态代码分析，检测关键模式：
+//      - async/await 使用
+//      - try/catch 存在性
+//      - Prisma 数据库操作
+//      - Controller 路由定义
+//      - API 调用（fetch/axios）
+//   4. 根据检测结果，生成分类提醒（Backend / Frontend / Database）
+//   5. 仅在检测到高风险模式时输出提醒，避免噪音
+//
+// 【设计哲学】
+//   - 主动教育优于被动修复：在错误产生前提醒，而不是事后补救
+//   - 上下文感知：根据文件类型和代码模式，提供针对性建议
+//   - 低噪音原则：仅在真正有风险时提醒，避免过度打扰
+//   - 可选退出：通过环境变量 SKIP_ERROR_REMINDER=1 可禁用
+//
+// 【适用场景】
+//   - Backend 开发：确保所有异常都被 Sentry 捕获
+//   - Frontend 开发：确保 API 错误有用户友好的提示
+//   - Database 操作：提醒验证字段名和迁移测试
+//
+// ═══════════════════════════════════════════════════════════════════════════════
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// ───────────────────────────────────────────────────────────────────────────────
+// 类型定义：Hook 输入与数据结构
+// ───────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Hook 输入数据结构（由 Claude Code 传递）
+ */
+interface HookInput {
+    session_id: string;         // 会话唯一标识符
+    transcript_path: string;    // 对话历史文件路径
+    cwd: string;                // 当前工作目录
+    permission_mode: string;    // 权限模式（sandbox/dangerous）
+    hook_event_name: string;    // Hook 事件名称
+}
+
+/**
+ * 文件编辑记录（从 edited-files.log 解析）
+ */
+interface EditedFile {
+    path: string;       // 文件绝对路径
+    tool: string;       // 使用的工具（Write/Edit/MultiEdit）
+    timestamp: string;  // 编辑时间戳
+}
+
+/**
+ * 会话级别的文件跟踪数据
+ */
+interface SessionTracking {
+    edited_files: EditedFile[];
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// 函数：根据文件路径判断文件分类
+// ───────────────────────────────────────────────────────────────────────────────
+//
+// 【功能说明】
+//   通过路径特征，将文件分类为 backend / frontend / database / other
+//   用于后续提供针对性的错误处理建议
+//
+// 【分类规则】
+//   - Frontend: 包含 /frontend/, /client/, /src/components/, /src/features/
+//   - Backend:  包含 /src/controllers/, /src/services/, /src/routes/, /src/api/, /server/
+//   - Database: 包含 /database/, /prisma/, /migrations/
+//   - Other:    以上都不匹配的文件
+//
+// 【为什么基于路径而不是扩展名】
+//   - 扩展名不足以区分前后端（都可能是 .ts/.tsx）
+//   - 路径结构反映了项目架构，更准确
+//   - 便于适配不同项目结构（可轻松扩展规则）
+//
+// ───────────────────────────────────────────────────────────────────────────────
+function getFileCategory(filePath: string): 'backend' | 'frontend' | 'database' | 'other' {
+    // ─── Frontend 检测 ───
+    if (filePath.includes('/frontend/') ||
+        filePath.includes('/client/') ||
+        filePath.includes('/src/components/') ||
+        filePath.includes('/src/features/')) return 'frontend';
+
+    // ─── Backend 检测（常见服务目录）───
+    if (filePath.includes('/src/controllers/') ||
+        filePath.includes('/src/services/') ||
+        filePath.includes('/src/routes/') ||
+        filePath.includes('/src/api/') ||
+        filePath.includes('/server/')) return 'backend';
+
+    // ─── Database 检测 ───
+    if (filePath.includes('/database/') ||
+        filePath.includes('/prisma/') ||
+        filePath.includes('/migrations/')) return 'database';
+
+    // ─── 兜底分类 ───
+    return 'other';
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// 函数：判断文件是否需要错误处理检查
+// ───────────────────────────────────────────────────────────────────────────────
+//
+// 【功能说明】
+//   过滤不需要错误处理检查的文件类型，减少误报
+//
+// 【排除规则】
+//   - 测试文件（.test.ts, .spec.tsx）：测试代码有自己的错误处理模式
+//   - 配置文件（.config.ts）：配置通常是静态的，不涉及运行时错误
+//   - 类型定义文件（.d.ts）：纯类型声明，无运行时代码
+//   - 类型目录（/types/）：同上
+//   - 样式文件（.styles.ts）：CSS-in-JS，通常不涉及异步操作
+//
+// 【包含规则】
+//   - 所有 .ts/.tsx/.js/.jsx 文件（排除上述情况）
+//
+// 【为什么这样设计】
+//   - 避免噪音：测试和配置文件不应触发业务代码的错误处理提醒
+//   - 提高信噪比：专注于真正需要关注的业务逻辑代码
+//
+// ───────────────────────────────────────────────────────────────────────────────
+function shouldCheckErrorHandling(filePath: string): boolean {
+    // ─── 排除测试文件 ───
+    if (filePath.match(/\.(test|spec)\.(ts|tsx)$/)) return false;
+
+    // ─── 排除配置文件和类型定义 ───
+    if (filePath.match(/\.(config|d)\.(ts|tsx)$/)) return false;
+
+    // ─── 排除类型目录 ───
+    if (filePath.includes('types/')) return false;
+
+    // ─── 排除样式文件 ───
+    if (filePath.includes('.styles.ts')) return false;
+
+    // ─── 仅检查代码文件 ───
+    return filePath.match(/\.(ts|tsx|js|jsx)$/) !== null;
+}
+
+// ───────────────────────────────────────────────────────────────────────────────
+// 函数：静态代码分析 - 检测错误处理相关模式
+// ───────────────────────────────────────────────────────────────────────────────
+//
+// 【功能说明】
+//   读取文件内容，通过正则表达式检测关键代码模式
+//   用于判断文件是否包含需要特别关注错误处理的代码
+//
+// 【检测模式】
+//   1. hasTryCatch   - 是否使用 try-catch 块
+//   2. hasAsync      - 是否使用 async 函数
+//   3. hasPrisma     - 是否包含 Prisma ORM 操作
+//   4. hasController - 是否定义 HTTP 路由/控制器
+//   5. hasApiCall    - 是否调用外部 API（fetch/axios）
+//
+// 【为什么使用正则而不是 AST】
+//   - 轻量级：无需解析完整语法树，性能更好
+//   - 足够准确：对于提醒场景，正则匹配足够识别风险
+//   - 低依赖：不需要引入 TypeScript 编译器或 Babel
+//   - 快速执行：Hook 需要尽可能快，避免阻塞用户
+//
+// 【设计权衡】
+//   - 可能存在误报（如注释中的代码），但对提醒场景可接受
+//   - 不支持复杂的代码混淆，但目标是源码分析
+//
+// ───────────────────────────────────────────────────────────────────────────────
+function analyzeFileContent(filePath: string): {
+    hasTryCatch: boolean;
+    hasAsync: boolean;
+    hasPrisma: boolean;
+    hasController: boolean;
+    hasApiCall: boolean;
+} {
+    // ─── 文件存在性检查 ───
+    if (!existsSync(filePath)) {
+        // 文件已被删除或路径错误，返回空结果
+        return { hasTryCatch: false, hasAsync: false, hasPrisma: false, hasController: false, hasApiCall: false };
+    }
+
+    // ─── 读取文件内容 ───
+    const content = readFileSync(filePath, 'utf-8');
+
+    // ─── 模式检测（正则匹配）───
+    return {
+        // Try-catch 块检测：匹配 "try {" 模式
+        hasTryCatch: /try\s*\{/.test(content),
+
+        // Async 函数检测：匹配 "async " 关键字
+        hasAsync: /async\s+/.test(content),
+
+        // Prisma 操作检测：匹配常见 Prisma API 调用
+        // 示例：prisma.user.findMany(), PrismaService, create(), update()
+        hasPrisma: /prisma\.|PrismaService|findMany|findUnique|create\(|update\(|delete\(/i.test(content),
+
+        // Controller 检测：匹配路由定义或控制器类
+        // 示例：export class UserController, router.get(), app.post()
+        hasController: /export class.*Controller|router\.|app\.(get|post|put|delete|patch)/.test(content),
+
+        // API 调用检测：匹配常见 HTTP 客户端
+        // 示例：fetch(), axios.get(), apiClient.post()
+        hasApiCall: /fetch\(|axios\.|apiClient\./i.test(content),
+    };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 主流程：分析会话文件并生成错误处理提醒
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function main() {
+    try {
+        // ─── Step 1: 读取 Hook 输入数据 ───
+        const input = readFileSync(0, 'utf-8'); // 从 stdin 读取
+        const data: HookInput = JSON.parse(input);
+
+        const { session_id } = data;
+        const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+        // ─── Step 2: 检查文件编辑跟踪日志 ───
+        //
+        // 【日志位置】
+        //   $CLAUDE_PROJECT_DIR/.claude/tsc-cache/{session_id}/edited-files.log
+        //
+        // 【为什么需要跟踪日志】
+        //   - 会话级别状态：Hook 是无状态的，需要外部存储来跟踪会话中的文件编辑
+        //   - 增量分析：仅分析本会话中编辑过的文件，避免全量扫描
+        //
+        // 【路径统一】
+        //   与 post-tool-use-tracker.sh 使用相同的项目级别缓存路径
+        //
+        const cacheDir = join(projectDir, '.claude', 'tsc-cache', session_id);
+        const trackingFile = join(cacheDir, 'edited-files.log');
+
+        // 如果没有编辑记录，直接退出（无需提醒）
+        if (!existsSync(trackingFile)) {
+            process.exit(0);
+        }
+
+        // ─── Step 3: 解析编辑记录 ───
+        //
+        // 【文件格式】
+        //   每行格式：{timestamp}\t{tool}\t{file_path}
+        //   示例：2025-01-15T10:30:00Z	Write	/path/to/file.ts
+        //
+        const trackingContent = readFileSync(trackingFile, 'utf-8');
+        const editedFiles = trackingContent
+            .trim()
+            .split('\n')
+            .filter(line => line.length > 0)
+            .map(line => {
+                const [timestamp, tool, path] = line.split('\t');
+                return { timestamp, tool, path };
+            });
+
+        // 如果解析结果为空，退出
+        if (editedFiles.length === 0) {
+            process.exit(0);
+        }
+
+        // ─── Step 4: 文件分类与代码分析 ───
+        //
+        // 【分类目的】
+        //   - 按照文件类型（backend/frontend/database）分组
+        //   - 为后续提供针对性的错误处理建议
+        //
+        const categories = {
+            backend: [] as string[],
+            frontend: [] as string[],
+            database: [] as string[],
+            other: [] as string[],
+        };
+
+        // 存储每个文件的分析结果
+        const analysisResults: Array<{
+            path: string;
+            category: string;
+            analysis: ReturnType<typeof analyzeFileContent>;
+        }> = [];
+
+        // ─── 遍历所有编辑过的文件 ───
+        for (const file of editedFiles) {
+            // 过滤不需要检查的文件（测试、配置等）
+            if (!shouldCheckErrorHandling(file.path)) continue;
+
+            // 分类文件
+            const category = getFileCategory(file.path);
+            categories[category].push(file.path);
+
+            // 分析文件内容
+            const analysis = analyzeFileContent(file.path);
+            analysisResults.push({ path: file.path, category, analysis });
+        }
+
+        // ─── Step 5: 风险评估 ───
+        //
+        // 【何时需要提醒】
+        //   如果任何文件包含以下模式之一，则需要提醒：
+        //   - try-catch 块 → 可能需要 Sentry 捕获
+        //   - async 函数 → 可能有未处理的 Promise rejection
+        //   - Prisma 操作 → 数据库错误需要妥善处理
+        //   - Controller 定义 → HTTP 错误需要统一处理
+        //   - API 调用 → 网络错误需要用户提示
+        //
+        const needsAttention = analysisResults.some(
+            ({ analysis }) =>
+                analysis.hasTryCatch ||
+                analysis.hasAsync ||
+                analysis.hasPrisma ||
+                analysis.hasController ||
+                analysis.hasApiCall
+        );
+
+        // 如果没有检测到风险模式，静默退出（避免噪音）
+        if (!needsAttention) {
+            process.exit(0);
+        }
+
+        // ═══════════════════════════════════════════════════════════════════
+        // Step 6: 生成分类提醒
+        // ═══════════════════════════════════════════════════════════════════
+
+        // ─── 提醒标题 ───
+        console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('📋 ERROR HANDLING SELF-CHECK');
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+        // ───────────────────────────────────────────────────────────────────
+        // Backend 提醒：Sentry 集成与错误处理最佳实践
+        // ───────────────────────────────────────────────────────────────────
+        //
+        // 【提醒触发条件】
+        //   - 编辑了 backend 分类的文件
+        //   - 检测到 try-catch / Prisma / Controller 等模式
+        //
+        // 【提醒内容】
+        //   - 询问是否添加 Sentry.captureException()
+        //   - 询问 Prisma 操作是否有错误处理
+        //   - 询问 Controller 是否使用 BaseController.handleError()
+        //   - 提供最佳实践建议
+        //
+        if (categories.backend.length > 0) {
+            const backendFiles = analysisResults.filter(f => f.category === 'backend');
+
+            // 聚合检测结果
+            const hasTryCatch = backendFiles.some(f => f.analysis.hasTryCatch);
+            const hasPrisma = backendFiles.some(f => f.analysis.hasPrisma);
+            const hasController = backendFiles.some(f => f.analysis.hasController);
+
+            console.log('⚠️  Backend Changes Detected');
+            console.log(`   ${categories.backend.length} file(s) edited\n`);
+
+            // ─── 条件化提醒：仅显示相关问题 ───
+            if (hasTryCatch) {
+                console.log('   ❓ Did you add Sentry.captureException() in catch blocks?');
+            }
+            if (hasPrisma) {
+                console.log('   ❓ Are Prisma operations wrapped in error handling?');
+            }
+            if (hasController) {
+                console.log('   ❓ Do controllers use BaseController.handleError()?');
+            }
+
+            // ─── 最佳实践建议 ───
+            console.log('\n   💡 Backend Best Practice:');
+            console.log('      - All errors should be captured to Sentry');
+            console.log('      - Use appropriate error helpers for context');
+            console.log('      - Controllers should extend BaseController\n');
+        }
+
+        // ───────────────────────────────────────────────────────────────────
+        // Frontend 提醒：用户体验与错误反馈
+        // ───────────────────────────────────────────────────────────────────
+        //
+        // 【提醒触发条件】
+        //   - 编辑了 frontend 分类的文件
+        //   - 检测到 API 调用或 try-catch 块
+        //
+        // 【提醒内容】
+        //   - 询问 API 错误是否有用户友好的提示
+        //   - 询问错误是否展示给用户
+        //   - 提供前端错误处理最佳实践
+        //
+        if (categories.frontend.length > 0) {
+            const frontendFiles = analysisResults.filter(f => f.category === 'frontend');
+
+            // 聚合检测结果
+            const hasApiCall = frontendFiles.some(f => f.analysis.hasApiCall);
+            const hasTryCatch = frontendFiles.some(f => f.analysis.hasTryCatch);
+
+            console.log('💡 Frontend Changes Detected');
+            console.log(`   ${categories.frontend.length} file(s) edited\n`);
+
+            // ─── 条件化提醒 ───
+            if (hasApiCall) {
+                console.log('   ❓ Do API calls show user-friendly error messages?');
+            }
+            if (hasTryCatch) {
+                console.log('   ❓ Are errors displayed to the user?');
+            }
+
+            // ─── 最佳实践建议 ───
+            console.log('\n   💡 Frontend Best Practice:');
+            console.log('      - Use your notification system for user feedback');
+            console.log('      - Error boundaries for component errors');
+            console.log('      - Display user-friendly error messages\n');
+        }
+
+        // ───────────────────────────────────────────────────────────────────
+        // Database 提醒：Schema 一致性与迁移测试
+        // ───────────────────────────────────────────────────────────────────
+        //
+        // 【提醒触发条件】
+        //   - 编辑了 database 分类的文件（如 Prisma schema, migrations）
+        //
+        // 【提醒内容】
+        //   - 询问列名是否与 schema 一致
+        //   - 询问迁移是否经过测试
+        //
+        if (categories.database.length > 0) {
+            console.log('🗄️  Database Changes Detected');
+            console.log(`   ${categories.database.length} file(s) edited\n`);
+            console.log('   ❓ Did you verify column names against schema?');
+            console.log('   ❓ Are migrations tested?\n');
+        }
+
+        // ─── 提醒尾部：禁用提示 ───
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('💡 TIP: Disable with SKIP_ERROR_REMINDER=1');
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+        // 正常退出（提醒不应阻塞用户）
+        process.exit(0);
+
+    } catch (err) {
+        // ─── 静默失败策略 ───
+        //
+        // 【为什么静默失败】
+        //   - 提醒是辅助功能，不应因 Hook 错误而中断用户工作流
+        //   - 避免给用户带来困扰（如解析错误、文件不存在等）
+        //   - 保证 Claude Code 的核心功能不受影响
+        //
+        process.exit(0);
+    }
+}
+
+// ─── 入口执行 ───
+// 捕获未处理的 Promise rejection，确保 Hook 不会崩溃
+main().catch(() => process.exit(0));