cc-devflow 4.3.0 → 4.5.0

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

@@ -1,459 +0,0 @@
-#!/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));

package/.claude/hooks/hooks.json

@@ -1,15 +0,0 @@
-{
-    "description": "CC-DevFlow Ralph loop stop hook integration",
-    "hooks": {
-        "Stop": [
-            {
-                "hooks": [
-                    {
-                        "type": "command",
-                        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/ralph-stop-hook.sh"
-                    }
-                ]
-            }
-        ]
-    }
-}