@dommaker/harness 0.16.6 → 0.16.8

package/src/types/failure.ts

@@ -0,0 +1,165 @@
+/**
+ * 失败处理类型定义
+ *
+ * 提供通用的错误分类和失败记录类型
+ * 不包含业务逻辑，只定义数据结构
+ */
+
+/**
+ * 错误类型枚举
+ */
+export enum ErrorType {
+  TEST_FAILED = 'TEST_FAILED',
+  GATE_FAILED = 'GATE_FAILED',
+  DEPENDENCY_BLOCKED = 'DEPENDENCY_BLOCKED',
+  CONTEXT_OVERFLOW = 'CONTEXT_OVERFLOW',
+  TIMEOUT = 'TIMEOUT',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  AGENT_ERROR = 'AGENT_ERROR',
+  TOOL_ERROR = 'TOOL_ERROR',
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  UNKNOWN = 'UNKNOWN',
+}
+
+/**
+ * 失败等级
+ *
+ * L1: 自动处理（重试、降级）
+ * L2: 需要干预（人工审核）
+ * L3: 严重问题（开会讨论）
+ * L4: 致命错误（回滚）
+ */
+export enum FailureLevel {
+  L1 = 'L1',
+  L2 = 'L2',
+  L3 = 'L3',
+  L4 = 'L4',
+}
+
+/**
+ * 错误分类规则
+ */
+export interface ErrorClassificationRule {
+  /** 匹配的错误类型 */
+  type: ErrorType;
+  /** 正则匹配模式 */
+  patterns?: RegExp[];
+  /** 关键词匹配（不区分大小写） */
+  keywords?: string[];
+  /** 失败等级 */
+  level?: FailureLevel;
+  /** 规则描述 */
+  description?: string;
+}
+
+/**
+ * 失败记录
+ */
+export interface FailureRecord {
+  /** 错误类型 */
+  type: ErrorType;
+  /** 失败等级 */
+  level: FailureLevel;
+  /** 错误消息 */
+  message: string;
+  /** 时间戳 */
+  timestamp: number;
+  /** 元数据 */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * 分类结果
+ */
+export interface ClassificationResult {
+  /** 错误类型 */
+  type: ErrorType;
+  /** 失败等级 */
+  level: FailureLevel;
+  /** 匹配的规则（如果有） */
+  matchedRule?: ErrorClassificationRule;
+  /** 原始错误 */
+  originalError: Error;
+}
+
+/**
+ * 默认错误分类规则
+ *
+ * 注意：规则按顺序匹配，更具体的规则应该放在前面
+ */
+export const DEFAULT_CLASSIFICATION_RULES: ErrorClassificationRule[] = [
+  // 更具体的规则优先
+  {
+    type: ErrorType.GATE_FAILED,
+    keywords: ['gate', 'checkpoint', 'constraint'],
+    level: FailureLevel.L2,
+    description: '门禁检查失败',
+  },
+  {
+    type: ErrorType.DEPENDENCY_BLOCKED,
+    keywords: ['dependency', 'blocked', 'dependency_fail'],
+    level: FailureLevel.L3,
+    description: '依赖阻塞',
+  },
+  {
+    type: ErrorType.CONTEXT_OVERFLOW,
+    keywords: ['context overflow', 'token limit', 'context exceed'],
+    level: FailureLevel.L2,
+    description: '上下文溢出',
+  },
+  {
+    type: ErrorType.TIMEOUT,
+    keywords: ['timeout', 'timed out', 'deadline'],
+    patterns: [/timeout/i, /timed?\s*out/i],
+    level: FailureLevel.L1,
+    description: '超时',
+  },
+  {
+    type: ErrorType.NETWORK_ERROR,
+    keywords: ['network', 'connection', 'econnrefused', 'enotfound', 'socket'],
+    level: FailureLevel.L1,
+    description: '网络错误',
+  },
+  {
+    type: ErrorType.AGENT_ERROR,
+    keywords: ['agent error', 'model error', 'rate limit', 'quota exceeded'],
+    level: FailureLevel.L2,
+    description: 'Agent 错误',
+  },
+  {
+    type: ErrorType.TOOL_ERROR,
+    keywords: ['tool error', 'skill error', 'executor error'],
+    level: FailureLevel.L1,
+    description: '工具错误',
+  },
+  {
+    type: ErrorType.VALIDATION_ERROR,
+    keywords: ['validation error', 'invalid', 'schema error'],
+    level: FailureLevel.L2,
+    description: '验证错误',
+  },
+  // 通用规则放在后面
+  {
+    type: ErrorType.TEST_FAILED,
+    keywords: ['test', 'assertion', 'expect'],
+    patterns: [/test.*fail/i, /assertion/i, /expect.*fail/i],
+    level: FailureLevel.L1,
+    description: '测试失败',
+  },
+];
+
+/**
+ * 错误类型到失败等级的默认映射
+ */
+export const DEFAULT_LEVEL_MAPPING: Record<ErrorType, FailureLevel> = {
+  [ErrorType.TEST_FAILED]: FailureLevel.L1,
+  [ErrorType.GATE_FAILED]: FailureLevel.L2,
+  [ErrorType.DEPENDENCY_BLOCKED]: FailureLevel.L3,
+  [ErrorType.CONTEXT_OVERFLOW]: FailureLevel.L2,
+  [ErrorType.TIMEOUT]: FailureLevel.L1,
+  [ErrorType.NETWORK_ERROR]: FailureLevel.L1,
+  [ErrorType.AGENT_ERROR]: FailureLevel.L2,
+  [ErrorType.TOOL_ERROR]: FailureLevel.L1,
+  [ErrorType.VALIDATION_ERROR]: FailureLevel.L2,
+  [ErrorType.UNKNOWN]: FailureLevel.L2,
+};

package/src/types/index.ts

@@ -15,12 +15,13 @@ export * from './trace';
 // Performance 类型（Performance Trace 系统）
 export * from './performance';
 
-// 诊断和提案类型（从 monitoring 导入）
-export type { Diagnosis } from '../monitoring/constraint-doctor';
+// 诊断和提案类型（定义已归位 types/monitoring-types.ts，monitoring 改从 types 导入）
+// 显式再导出（不用 export *）：根入口同时星导出 ./monitoring，星-星歧义会静默丢符号
 export type {
+  Diagnosis,
   ConstraintProposal,
   ProposalReviewResult,
-} from '../monitoring/constraint-evolver';
+} from './monitoring-types';
 
 // Session 类型（排除与 passes-gate 冲突的类型）
 export {
@@ -47,7 +48,8 @@ export * from './enforcement';
 // Spec 验证类型
 export * from './spec';
 
-// Failure 类型（从 failure 模块导入）
+// Failure 类型（定义已归位 types/failure.ts，failure 模块经 failure/types.ts 再导出保持兼容）
+// 显式再导出（不用 export *）：根入口同时星导出 ./failure，星-星歧义会静默丢符号
 export {
   ErrorType,
   FailureLevel,
@@ -56,4 +58,4 @@ export {
   ClassificationResult,
   DEFAULT_CLASSIFICATION_RULES,
   DEFAULT_LEVEL_MAPPING,
-} from '../failure/types';
+} from './failure';

package/src/types/monitoring-types.ts

@@ -0,0 +1,150 @@
+/**
+ * 监控域类型（诊断 / 提案）
+ *
+ * 原定义位于 monitoring/constraint-doctor.ts 与 monitoring/constraint-evolver.ts，
+ * 但被 types/index.ts 反向再导出（类型层依赖业务模块，分层倒挂）。
+ * 工单 14 将类型定义归位到 types 层，monitoring 改从 types 导入。
+ */
+
+import type { ExecutionTrace } from './trace';
+
+/**
+ * 诊断结果
+ */
+export interface Diagnosis {
+  /** 异常 ID */
+  anomalyId: string;
+
+  /** 约束 ID */
+  constraintId: string;
+
+  /** 诊断时间 */
+  diagnosedAt: number;
+
+  /** 根因分析 */
+  rootCause: {
+    /** 主要原因 */
+    primary: string;
+
+    /** 次要原因 */
+    secondary?: string[];
+
+    /** 相关 traces */
+    evidence: ExecutionTrace[];
+  };
+
+  /** 影响评估 */
+  impact: {
+    /** 影响程度 */
+    severity: 'low' | 'medium' | 'high';
+
+    /** 影响范围 */
+    scope: 'single_project' | 'multiple_projects' | 'team';
+
+    /** 用户影响 */
+    userImpact: string;
+  };
+
+  /** 改进建议 */
+  recommendations: {
+    /** 建议类型 */
+    type: 'add_exception' | 'adjust_threshold' | 'modify_constraint' | 'user_training';
+
+    /** 建议内容 */
+    content: string;
+
+    /** 预期效果 */
+    expectedOutcome: string;
+
+    /** 实施成本 */
+    implementationCost: 'low' | 'medium' | 'high';
+  }[];
+
+  /** 是否需要变更 */
+  needsChange: boolean;
+
+  /** 紧急程度 */
+  urgency: 'low' | 'medium' | 'high';
+}
+
+/**
+ * 约束提案
+ */
+export interface ConstraintProposal {
+  /** 提案 ID */
+  id: string;
+
+  /** 提案时间 */
+  proposedAt: number;
+
+  /** 来源诊断 */
+  diagnosisId: string;
+
+  /** 约束 ID */
+  constraintId: string;
+
+  /** 提案类型 */
+  type: 'add_exception' | 'remove_exception' | 'adjust_trigger' | 'change_level' | 'modify_message' | 'new_constraint';
+
+  /** 提案内容 */
+  content: {
+    /** 当前值（如果有） */
+    current?: any;
+
+    /** 建议值 */
+    proposed: any;
+
+    /** 变更描述 */
+    description: string;
+  };
+
+  /** 理由 */
+  reasoning: string;
+
+  /** 预期效果 */
+  expectedOutcome: string;
+
+  /** 风险评估 */
+  risk: {
+    /** 风险等级 */
+    level: 'low' | 'medium' | 'high';
+
+    /** 风险描述 */
+    description: string;
+
+    /** 回滚方案 */
+    rollbackPlan?: string;
+  };
+
+  /** 实施信息 */
+  implementation: {
+    /** 改动文件 */
+    files: string[];
+
+    /** 改动量估计 */
+    linesChanged: number;
+
+    /** 测试要求 */
+    testsRequired: boolean;
+  };
+
+  /** 状态 */
+  status: 'proposed' | 'reviewing' | 'accepted' | 'rejected' | 'implemented';
+
+  /** 审核意见 */
+  reviewComment?: string;
+}
+
+/**
+ * 提案审核结果
+ */
+export interface ProposalReviewResult {
+  /** 是否接受 */
+  accepted: boolean;
+
+  /** 审核意见 */
+  comment: string;
+
+  /** 修改建议（如果拒绝） */
+  modifications?: Partial<ConstraintProposal>;
+}

package/src/utils/detect-source-roots.ts

@@ -9,7 +9,7 @@
  * 返回相对 projectPath 的路径数组。全都不存在时返回空数组。
  */
 
-import { existsSync, readdirSync, statSync } from 'fs';
+import { existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 
 export function detectSourceRoots(projectPath: string): string[] {

package/src/utils/file-walk.ts

@@ -0,0 +1,78 @@
+/**
+ * 文件遍历工具（工单 19）
+ *
+ * 收敛此前散落在 sync-docs / cross-project-checker / checker /
+ * spec-baseline-check / doc-freshness-check 中的 5 处递归遍历实现。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface FileWalkOptions {
+  /** 需要整体跳过的目录名（精确匹配） */
+  skipDirs?: string[];
+  /** 是否跳过 `.` 开头的条目，默认 false */
+  skipHidden?: boolean;
+  /** 文件过滤器（文件名, 完整路径）；缺省收集所有文件 */
+  filter?: (fileName: string, fullPath: string) => boolean;
+}
+
+/**
+ * 递归收集 root 下的文件路径（同步）
+ *
+ * 目录不可读时静默跳过（与原各处实现行为一致）。
+ */
+export function walkFiles(root: string, options: FileWalkOptions = {}): string[] {
+  const { skipDirs = [], skipHidden = false, filter } = options;
+  const results: string[] = [];
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (skipHidden && entry.name.startsWith('.')) continue;
+    if (skipDirs.includes(entry.name)) continue;
+
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkFiles(fullPath, options));
+    } else if (entry.isFile()) {
+      if (!filter || filter(entry.name, fullPath)) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  return results;
+}
+
+export interface TsSourceWalkOptions {
+  /** 是否跳过 barrel 文件 index.ts，默认 false */
+  skipIndex?: boolean;
+  /** 跳过的目录名，默认 node_modules/__tests__/dist */
+  skipDirs?: string[];
+  /** 是否跳过 `.` 开头的条目，默认 false */
+  skipHidden?: boolean;
+}
+
+/**
+ * 递归收集 TypeScript 源文件（.ts，排除 .d.ts）
+ */
+export function findTsSourceFiles(root: string, options: TsSourceWalkOptions = {}): string[] {
+  const {
+    skipIndex = false,
+    skipDirs = ['node_modules', '__tests__', 'dist'],
+    skipHidden = false,
+  } = options;
+
+  return walkFiles(root, {
+    skipDirs,
+    skipHidden,
+    filter: (name) =>
+      name.endsWith('.ts') && !name.endsWith('.d.ts') && (!skipIndex || name !== 'index.ts'),
+  });
+}

package/src/verification/rules-based.ts

@@ -10,7 +10,6 @@ import type {
   VerificationRule,
   VerificationContext,
   VerificationResult,
-  VerificationRuleType,
 } from './types';
 
 export class RulesBasedVerification {

package/bin/harness-knowledge-capture.js

@@ -1,99 +0,0 @@
-#!/usr/bin/env node
-/**
- * Harness Knowledge Capture Hook
- *
- * Runs as an afterTurn hook in Claude Code.
- * Detects deep analysis (≥3 source files read) without knowledge-doc output,
- * and warns the user that knowledge may need to be captured.
- *
- * Usage (in settings.json):
- *   "hooks": {
- *     "afterTurn": [{
- *       "command": "node ~/projects/harness/bin/harness-knowledge-capture.js"
- *     }]
- *   }
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// Read turn data from stdin
-let input = '';
-process.stdin.setEncoding('utf-8');
-process.stdin.on('data', (chunk) => input += chunk);
-
-process.stdin.on('end', () => {
-  try {
-    const turn = JSON.parse(input);
-    const result = checkTurn(turn);
-    if (result.shouldWarn) {
-      process.stderr.write(`\n${'='.repeat(60)}\n`);
-      process.stderr.write('  ⚠️  可能遗漏了知识沉淀\n');
-      process.stderr.write(`${'='.repeat(60)}\n`);
-      process.stderr.write(`  本回合读取了 ${result.fileReads} 个文件\n`);
-      process.stderr.write(`  但未写入 .harness/knowledge-docs/\n`);
-      process.stderr.write(`\n`);
-      process.stderr.write(`  如果这是深度分析，请执行：\n`);
-      process.stderr.write(`    npx harness knowledge upsert --scope <scope> --file <file> --source claude\n`);
-      process.stderr.write(`${'='.repeat(60)}\n\n`);
-    }
-  } catch (e) {
-    // Silently ignore parse errors — non-JSON input is fine
-  }
-});
-
-function checkTurn(turn) {
-  let fileReads = 0;
-  let knowledgeWrites = 0;
-
-  // Walk through messages looking for tool calls
-  const messages = turn.messages || [turn];
-  for (const msg of messages) {
-    // Claude Code format: tool_uses array
-    if (msg.role === 'assistant' && msg.tool_uses) {
-      for (const tool of msg.tool_uses) {
-        if (isFileRead(tool)) fileReads++;
-        if (isKnowledgeWrite(tool)) knowledgeWrites++;
-      }
-    }
-    // Plain tool_calls format
-    if (msg.tool_calls) {
-      for (const tool of msg.tool_calls) {
-        if (isFileRead(tool)) fileReads++;
-        if (isKnowledgeWrite(tool)) knowledgeWrites++;
-      }
-    }
-    // Messages content with tool use markers
-    if (msg.content && typeof msg.content === 'string') {
-      const readMatches = msg.content.match(/\bRead\b.*/g);
-      if (readMatches) fileReads += readMatches.length;
-    }
-  }
-
-  return {
-    fileReads,
-    knowledgeWrites,
-    shouldWarn: fileReads >= 3 && knowledgeWrites === 0,
-  };
-}
-
-function isFileRead(tool) {
-  const name = (tool.name || tool.function?.name || '').toLowerCase();
-  const isReadTool = ['read', 'glob', 'grep', 'agent'].includes(name);
-  if (!isReadTool) return false;
-
-  const params = tool.parameters || tool.function?.arguments || {};
-  const filePath = params.file_path || params.path || params.pattern || '';
-  // Only count actual source file reads, not config/memory/docs
-  const isSource = /\/(src|packages|apps)\/|\.(ts|tsx|js|jsx|py|go|rs)$/.test(filePath);
-  return isSource;
-}
-
-function isKnowledgeWrite(tool) {
-  const name = (tool.name || tool.function?.name || '').toLowerCase();
-  if (name !== 'write') return false;
-
-  const params = tool.parameters || tool.function?.arguments || {};
-  const filePath = params.file_path || '';
-  return filePath.includes('.harness/knowledge-docs/') || filePath.includes('.harness/knowledge/');
-}