@chongyan/autospec 1.0.1

package/plugins/hooks/layer1-validator.js

@@ -0,0 +1,423 @@
+#!/usr/bin/env node
+
+/**
+ * AutoSpec Hook: Layer 1 Validator
+ *
+ * 统一的 Layer 1 验证管理 Hook，合并了三个相关功能：
+ * - PreToolUse: Layer 1 强制检查（原 layer1-mandatory.js）
+ * - PostToolUse: Layer 1 结果捕获（原 layer1-post-check.js）
+ * - PostToolUse: 质量指标追踪（原 pipeline-quality-tracker.js）
+ *
+ * 职责：
+ * 1. 阻止未执行 Layer 1 验证就标记阶段完成
+ * 2. 捕获 Layer 1 验证命令的执行结果
+ * 3. 追踪质量指标到 metrics.json
+ *
+ * Security Level: CRITICAL - fail-closed
+ */
+
+import { createHookLogger, safeJsonParse, handleHookError, readStdin, findProjectRootAsync, fileExists } from './lib/hook-logger.js';
+import { recordHookExecution } from './lib/hook-error-recorder.js';
+import {
+  detectValidationType,
+  isLayer1Validation,
+  extractTestMetrics,
+} from './lib/validation-patterns.js';
+import {
+  getState,
+  readStateField,
+  hasLayer1Execution,
+  getMetrics,
+  updateMetrics,
+  updateStageMetrics,
+  incrementTotalMetric,
+  incrementStageMetric,
+  addErrorEntry,
+} from './lib/hook-state-manager.js';
+import { getTraceId, recordEvent } from './lib/trace-context.js';
+import { analyzeFailures, requiresHumanConfirmation } from './lib/test-failure-analyzer.js';
+
+const logger = createHookLogger('layer1-validator');
+
+/**
+ * 分析测试失败
+ */
+async function analyzeTestFailure(testOutput, command) {
+  try {
+    // 构建测试结果对象
+    const testResult = {
+      success: false,
+      output: testOutput || '',
+      command: command
+    };
+
+    // 调用本地 analyzer 分析失败原因
+    const analysis = analyzeFailures(testResult);
+    return analysis;
+  } catch (e) {
+    logger.debug('Test analysis failed', { error: e.message });
+    return null;
+  }
+}
+
+/**
+ * PreToolUse 处理：Layer 1 强制检查
+ * 阻止未执行 Layer 1 验证就标记阶段完成
+ */
+async function handlePreToolUse(input, projectRoot) {
+  const toolName = input.tool_name;
+  if (toolName !== 'Write' && toolName !== 'Edit') {
+    logger.debug('Not a write/edit operation, skipping', { toolName });
+    return;
+  }
+
+  // Check if this is an attempt to update state.json
+  const filePath = (input.tool_input?.file_path || '').replace(/\\/g, '/');
+  if (!filePath.includes('state.json') && !filePath.includes('.autospec/state')) {
+    logger.debug('Not a state.json operation, skipping', { filePath });
+    return;
+  }
+
+  logger.debug('Intercepting state.json modification');
+
+  // Check if state exists
+  const currentState = getState(projectRoot, true);
+  if (!currentState) {
+    logger.debug('state.json does not exist yet, allowing');
+    return;
+  }
+
+  // Get new content (if Edit, get replacement text; if Write, get content)
+  let newContent = '';
+  if (toolName === 'Write') {
+    newContent = input.tool_input?.content || '';
+  } else if (toolName === 'Edit') {
+    newContent = input.tool_input?.new_string || '';
+  }
+
+  // Check if we're marking a stage as complete
+  const isMarkingComplete = newContent.includes('completed') ||
+                            newContent.includes('"status": "completed"');
+
+  if (!isMarkingComplete) {
+    logger.debug('Not a completion update, allowing');
+    return;
+  }
+
+  logger.info('Detected stage completion attempt');
+
+  // Check what stage is being marked complete
+  const stageMatch = newContent.match(/stage0?(\d)/i) ||
+                    newContent.match(/"stage": "?(\d+)"?/);
+  const stageNum = stageMatch ? stageMatch[1] : null;
+
+  logger.debug('Checking stage', { stageNum });
+
+  // Stage 1 (requirement) doesn't always need Layer 1 (it's analysis, not code)
+  // But stages 3+ (implementation, review, testing) definitely need Layer 1
+  if (stageNum && parseInt(stageNum) >= 3) {
+    const currentStageKey = 'stage' + (parseInt(stageNum) < 10 ? '0' : '') + stageNum;
+
+    // 使用 state-utils 检查 Layer 1 执行记录
+    const hasLayer1 = hasLayer1Execution(projectRoot, currentStageKey);
+
+    logger.debug('Layer 1 check', { stage: currentStageKey, hasLayer1 });
+
+    if (!hasLayer1) {
+      logger.info('BLOCKED: No Layer 1 execution for stage completion', { stage: stageNum });
+
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason:
+            `[AutoSpec Layer 1 Validator] ❌ BLOCKED - DP6 Violation\n` +
+            `Attempting to mark Stage ${stageNum} as completed without Layer 1 validation.\n\n` +
+            `Constitution DP6 requires: "Layer 1 must be real execution"\n` +
+            `Required steps before completion:\n` +
+            `  - /autospec:validate (runs build, test, lint)\n` +
+            `  - Or: Bash commands for build/test with real execution\n\n` +
+            `Layer 1 results not found in state.json for this stage.\n` +
+            `Run validation first, then mark complete.`
+        }
+      };
+      process.stdout.write(JSON.stringify(output));
+    }
+  }
+
+  logger.debug('Allowing state update');
+}
+
+/**
+ * PostToolUse 处理：Layer 1 结果捕获 + 质量指标追踪
+ * 使用 state-utils.js 进行状态管理
+ */
+async function handlePostToolUse(input, projectRoot) {
+  const toolName = input.tool_name;
+  const toolInput = input.tool_input || {};
+  const response = input.tool_response || {};
+
+  logger.debug('Tracking Layer 1 metrics');
+
+  // Only track when a pipeline is active
+  const currentState = getState(projectRoot, true);
+  if (!currentState) {
+    logger.debug('No active pipeline (state.json not found), skipping');
+    return;
+  }
+
+  // Load current stage
+  const currentStage = String(currentState.currentStage || '');
+
+  let updated = false;
+  let contextMessage = '';
+
+  // ========== Layer 1 验证命令检测（Bash 命令）==========
+  if (toolName === 'Bash') {
+    const command = toolInput.command || '';
+    const validationType = detectValidationType(command);
+
+    if (validationType) {
+      const exitCode = response.exitCode ?? (response.error ? 1 : 0);
+      const passed = exitCode === 0;
+
+      // 检查是否为该阶段的首次 Layer 1 尝试
+      const metrics = getMetrics(projectRoot, true);
+      const stageMetrics = metrics?.stages?.[currentStage] || {};
+      const isFirstAttempt = !stageMetrics.layer1FirstAttempts || stageMetrics.layer1FirstAttempts === 0;
+
+      // 记录首次尝试
+      if (isFirstAttempt) {
+        incrementStageMetric(projectRoot, currentStage, 'layer1FirstAttempts');
+        incrementTotalMetric(projectRoot, 'layer1FirstAttempts');
+        logger.debug('First Layer 1 attempt for stage', { stage: currentStage });
+
+        // 如果首次通过，记录
+        if (passed) {
+          incrementStageMetric(projectRoot, currentStage, 'layer1FirstPass');
+          incrementTotalMetric(projectRoot, 'layer1FirstPass');
+          logger.info('First attempt Layer 1 PASS', { stage: currentStage });
+        }
+      }
+
+      // 更新指标 - 使用 state-utils
+      if (passed) {
+        incrementTotalMetric(projectRoot, 'layer1Pass');
+        if (currentStage) incrementStageMetric(projectRoot, currentStage, 'layer1Pass');
+        logger.debug('Layer 1 validation passed', { stage: currentStage });
+      } else {
+        incrementTotalMetric(projectRoot, 'layer1Fail');
+        if (currentStage) incrementStageMetric(projectRoot, currentStage, 'layer1Fail');
+
+        // 添加错误记录
+        addErrorEntry(projectRoot, {
+          type: 'layer1_fail',
+          command: command.substring(0, 100),
+          stage: currentStage
+        }, currentStage);
+
+        logger.info('Layer 1 validation failed', { stage: currentStage, exitCode });
+
+        // 使用 test 模块分析测试失败原因
+        if (validationType === 'test') {
+          const testOutput = response.stdout || response.stderr || '';
+          const analysis = await analyzeTestFailure(testOutput, command);
+
+          if (analysis && analysis.errors && analysis.errors.length > 0) {
+            // 构建详细的错误分析消息
+            let analysisDetails = `\n\n[Test Module Analysis]\n`;
+            analysisDetails += `Error Type: ${analysis.errorType || 'unknown'}\n`;
+            analysisDetails += `Severity: ${analysis.severity || 'medium'}\n`;
+
+            if (analysis.errors && analysis.errors.length > 0) {
+              analysisDetails += `\nDetected Errors:\n`;
+              for (const err of analysis.errors.slice(0, 5)) {
+                analysisDetails += `  - [${err.type}] ${err.message}\n`;
+                if (err.file) analysisDetails += `    File: ${err.file}\n`;
+                if (err.line) analysisDetails += `    Line: ${err.line}\n`;
+              }
+            }
+
+            if (analysis.suggestions && analysis.suggestions.length > 0) {
+              analysisDetails += `\nSuggested Fixes:\n`;
+              for (const suggestion of analysis.suggestions.slice(0, 3)) {
+                analysisDetails += `  - ${suggestion}\n`;
+              }
+            }
+
+            // 检查是否需要人工确认
+            const needsHuman = analysis.requiresHumanConfirmation || false;
+            if (needsHuman) {
+              analysisDetails += `\n⚠️ Human confirmation recommended for this failure.`;
+            }
+
+            // 提示 AI 可以调用深度分析 skill
+            analysisDetails += `\n\n[AI Analysis Available]
+For comprehensive test diagnostics and quality assessment:
+- Read framework/skills/support/ai-test-diagnostics.md
+- Then use Agent tool with the test output for detailed diagnosis and improvement suggestions`;
+
+            contextMessage = analysisDetails;
+          }
+        }
+
+        // Alert on consecutive failures
+        const metrics = getMetrics(projectRoot, true);
+        const recentErrors = metrics?.totals?.errors?.filter(e => e.type === 'layer1_fail') || [];
+        if (recentErrors.length >= 3) {
+          contextMessage = (contextMessage ? contextMessage + '\n\n' : '') +
+            `[AutoSpec Quality Alert] Layer 1 has failed ${recentErrors.length} times in this pipeline.\n` +
+            `Consider: Is this a systemic issue? Check design assumptions or environment setup.`;
+          logger.info('Consecutive failures alert triggered', { count: recentErrors.length });
+        }
+      }
+
+      // 生成上下文消息（原 layer1-post-check 功能）
+      const status = passed ? 'PASS' : 'FAIL';
+      let validationMessage =
+        `[AutoSpec Layer 1] Validation command detected: ${command.substring(0, 80)}\n` +
+        `Type: ${validationType} | Result: ${status}\n`;
+
+      if (passed) {
+        validationMessage += `Layer 1 PASS — proceed to Layer 2 review if applicable.`;
+      } else {
+        validationMessage +=
+          `Layer 1 FAIL — DO NOT proceed to Layer 2 review.\n` +
+          `[CP6 Error Analysis Required] Before retrying, analyze the root cause:\n` +
+          `  1. Is this a code bug? → Fix the specific issue\n` +
+          `  2. Is this a design gap? → Flag for design-stage rollback\n` +
+          `  3. Is this an environment issue? → Mark as BLOCKED\n` +
+          `Record this failure in the stage results for practice-log (error pattern tracking).`;
+      }
+
+      contextMessage = contextMessage ? contextMessage + '\n\n' + validationMessage : validationMessage;
+      updated = true;
+
+      // 记录事件到 trace 日志
+      const traceId = getTraceId(projectRoot);
+      if (traceId) {
+        recordEvent(projectRoot, passed ? 'layer1_pass' : 'layer1_fail', {
+          source: 'layer1-validator',
+          stage: currentStage,
+          tool: 'Bash',
+          action: 'validation',
+           data: {
+            command: command.substring(0, 100),
+            validationType,
+            exitCode,
+            isFirstAttempt,
+            firstPass: isFirstAttempt && passed
+          }
+        });
+      }
+    }
+  }
+
+  // ========== Agent 调用追踪 ==========
+  if (toolName === 'Agent') {
+    incrementTotalMetric(projectRoot, 'agentCalls');
+    if (currentStage) incrementStageMetric(projectRoot, currentStage, 'agentCalls');
+
+    const agentResult = response.error ? 'fail' : 'success';
+    if (agentResult === 'success') {
+      incrementTotalMetric(projectRoot, 'agentSuccess');
+      if (currentStage) incrementStageMetric(projectRoot, currentStage, 'agentSuccess');
+    } else {
+      incrementTotalMetric(projectRoot, 'agentFail');
+      if (currentStage) incrementStageMetric(projectRoot, currentStage, 'agentFail');
+    }
+    logger.debug('Agent call tracked', { result: agentResult, stage: currentStage });
+    updated = true;
+  }
+
+  // ========== 用户干预追踪 ==========
+  if (toolName === 'AskUserQuestion') {
+    incrementTotalMetric(projectRoot, 'humanInterventions');
+    logger.debug('Human intervention tracked');
+    updated = true;
+  }
+
+  // Metrics are automatically saved by state-utils functions
+  if (updated) {
+    logger.debug('Metrics updated via state-utils');
+  }
+
+  // Output context message if any alert was triggered
+  if (contextMessage) {
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: contextMessage
+      }
+    };
+    process.stdout.write(JSON.stringify(output));
+  }
+}
+
+/**
+ * 主函数
+ */
+async function main() {
+  const startTime = Date.now();
+  let input;
+  let projectRoot = null;
+
+  try {
+    const rawInput = await readStdin(1000);
+    input = safeJsonParse(rawInput, null, 'hook input');
+
+    if (!input) {
+      logger.debug('Empty or invalid input, skipping');
+      process.exit(0);
+    }
+
+    // Find project root
+    const cwd = input.cwd || process.cwd();
+    projectRoot = await findProjectRootAsync(cwd);
+
+    if (!projectRoot) {
+      logger.debug('No .autospec directory found, skipping');
+      process.exit(0);
+    }
+
+    // 根据事件类型分发到不同处理函数
+    const eventName = input.event_name;
+
+    if (eventName === 'PreToolUse') {
+      await handlePreToolUse(input, projectRoot);
+    } else if (eventName === 'PostToolUse') {
+      await handlePostToolUse(input, projectRoot);
+    } else {
+      logger.debug('Unknown event type, skipping', { eventName });
+    }
+
+    // 记录成功执行
+    recordHookExecution(projectRoot, 'layer1-validator', input, null, Date.now() - startTime, true);
+    process.exit(0);
+
+  } catch (err) {
+    // 使用增强的错误处理
+    const result = handleHookError('layer1-validator', err, {
+      eventName: input?.event_name || 'Unknown',
+      projectRoot,
+      input
+    });
+
+    // 记录失败的执行
+    if (projectRoot) {
+      recordHookExecution(projectRoot, 'layer1-validator', input, result, Date.now() - startTime, false);
+    }
+
+    process.stdout.write(JSON.stringify(result.hookSpecificOutput));
+
+    // 关键 hook：根据错误类型决定退出码
+    // fail-closed: 如果 shouldBlock 为 true，使用 exit(2) 阻止操作
+    if (result.shouldBlock) {
+      process.exit(2);
+    } else {
+      process.exit(0);
+    }
+  }
+}
+
+main();