@dommaker/harness 1.0.0 → 1.1.0

package/src/completion-checkers/__tests__/tdd-chain.test.ts

@@ -0,0 +1,99 @@
+/**
+ * verifyTddChain 测试（studio#160 验收：伪造引用三形态 / Tests: none waiver / 免检分类）
+ */
+
+import { verifyTddChain } from '../tdd-chain';
+import type { CommitInput } from '../types';
+
+const sha = (n: number) => n.toString(16).padStart(40, '0');
+
+function commit(partial: Partial<CommitInput> & { sha: string }): CommitInput {
+  return { subject: 'phase(impl): x', body: '', files: ['src/a.ts'], ...partial };
+}
+
+describe('verifyTddChain', () => {
+  it('合法引用链 → pass（测试 commit 在前，实现 commit 引用它）', () => {
+    const commits = [
+      commit({ sha: sha(1), files: ['src/a.test.ts'], subject: 'phase(test): add test' }),
+      commit({ sha: sha(2), files: ['src/a.ts'], body: 'impl\n\nTested-By: ' + sha(1) }),
+    ];
+    const result = verifyTddChain(commits);
+    expect(result.verdict).toBe('pass');
+    expect(result.commits.map((c) => c.verdict)).toEqual(['skip', 'pass']);
+  });
+
+  it('短 sha（7 位前缀）引用可命中', () => {
+    const commits = [
+      commit({ sha: sha(1), files: ['__tests__/a.ts'] }),
+      commit({ sha: sha(2), body: 'Tested-By: ' + sha(1).slice(0, 7) }),
+    ];
+    expect(verifyTddChain(commits).verdict).toBe('pass');
+  });
+
+  it('伪造引用：sha 不在提交集内 → violation', () => {
+    const commits = [commit({ sha: sha(2), body: 'Tested-By: ' + sha(9) })];
+    const result = verifyTddChain(commits);
+    expect(result.verdict).toBe('violation');
+    expect(result.commits[0].reason).toContain('不在本 WU 提交集内');
+  });
+
+  it('伪造引用：被引 commit 位置在本 commit 之后 → violation', () => {
+    const commits = [
+      commit({ sha: sha(2), body: 'Tested-By: ' + sha(1) }),
+      commit({ sha: sha(1), files: ['src/a.test.ts'] }),
+    ];
+    const result = verifyTddChain(commits);
+    expect(result.verdict).toBe('violation');
+    expect(result.commits[0].reason).toContain('位置不在本 commit 之前');
+  });
+
+  it('伪造引用：被引 commit 文件清单不含测试文件 → violation', () => {
+    const commits = [
+      commit({ sha: sha(1), files: ['src/b.ts'] }),
+      commit({ sha: sha(2), body: 'Tested-By: ' + sha(1) }),
+    ];
+    const result = verifyTddChain(commits);
+    expect(result.verdict).toBe('violation');
+    expect(result.commits[1].reason).toContain('未命中 test_globs');
+  });
+
+  it('缺 Tested-By trailer → violation', () => {
+    const result = verifyTddChain([commit({ sha: sha(1) })]);
+    expect(result.verdict).toBe('violation');
+    expect(result.commits[0].reason).toContain('缺 Tested-By trailer');
+  });
+
+  it('Tests: none trailer → waiver（放行，不算 violation）', () => {
+    const result = verifyTddChain([commit({ sha: sha(1), body: 'chore\n\nTests: none' })]);
+    expect(result.verdict).toBe('pass');
+    expect(result.commits[0].verdict).toBe('waiver');
+  });
+
+  it('纯测试 commit 与纯非代码 commit 天然免检', () => {
+    const commits = [
+      commit({ sha: sha(1), files: ['src/a.test.ts'] }),
+      commit({ sha: sha(2), files: ['README.md', 'docs/guide.md'] }),
+    ];
+    const result = verifyTddChain(commits);
+    expect(result.verdict).toBe('pass');
+    expect(result.commits.every((c) => c.verdict === 'skip')).toBe(true);
+  });
+
+  it('混合 commit（代码+测试同 commit）仍需引用链', () => {
+    const commits = [commit({ sha: sha(1), files: ['src/a.ts', 'src/a.test.ts'] })];
+    expect(verifyTddChain(commits).verdict).toBe('violation');
+  });
+
+  it('自定义 test_globs / noncode_globs 生效', () => {
+    const commits = [commit({ sha: sha(1), files: ['assets/logo.png'] })];
+    const withGlob = verifyTddChain(commits, { noncodeGlobs: ['**/*.png'] });
+    expect(withGlob.commits[0].verdict).toBe('skip');
+    expect(verifyTddChain(commits).commits[0].verdict).toBe('violation');
+  });
+
+  it('checker 关闭 / 总开关关闭 → skip', () => {
+    const commits = [commit({ sha: sha(1) })];
+    expect(verifyTddChain(commits, { checkers: { tddChain: false } }).verdict).toBe('skip');
+    expect(verifyTddChain(commits, { enabled: false }).verdict).toBe('skip');
+  });
+});

package/src/completion-checkers/classify.ts

@@ -0,0 +1,47 @@
+/**
+ * commit 文件分类（tdd-chain 与 phase-format 共享同一份分类结果，Q4 定稿）
+ *
+ * - 纯非代码（全部命中 noncode_globs）与纯测试（全部命中 test_globs）commit 天然免检
+ * - 混合 commit 只要触到代码文件即需走引用链
+ * - 空文件清单按免检处理
+ */
+
+import type { CommitInput, CompletionCheckersConfig } from './types';
+import { DEFAULT_NONCODE_GLOBS, DEFAULT_TEST_GLOBS, matchAnyGlob } from './glob-match';
+
+/** 单 commit 文件分类结果 */
+export interface CommitFileClassification {
+  /** 无代码文件（纯测试 / 纯非代码 / 空清单）→ 天然免检 */
+  exempt: boolean;
+  /** 文件清单命中 test_globs（被引 commit 须满足） */
+  hasTests: boolean;
+}
+
+/** 从配置取 glob（缺省落默认） */
+export function resolveGlobs(config: CompletionCheckersConfig): { testGlobs: string[]; noncodeGlobs: string[] } {
+  return {
+    testGlobs: config.testGlobs ?? DEFAULT_TEST_GLOBS,
+    noncodeGlobs: config.noncodeGlobs ?? DEFAULT_NONCODE_GLOBS,
+  };
+}
+
+/** 分类单 commit 的文件清单 */
+export function classifyCommitFiles(
+  commit: CommitInput,
+  testGlobs: string[],
+  noncodeGlobs: string[],
+): CommitFileClassification {
+  if (commit.files.length === 0) {
+    return { exempt: true, hasTests: false };
+  }
+  let hasTests = false;
+  let hasCode = false;
+  for (const file of commit.files) {
+    if (matchAnyGlob(file, testGlobs)) {
+      hasTests = true;
+    } else if (!matchAnyGlob(file, noncodeGlobs)) {
+      hasCode = true;
+    }
+  }
+  return { exempt: !hasCode, hasTests };
+}

package/src/completion-checkers/contract-presence.ts

@@ -0,0 +1,40 @@
+/**
+ * contract-presence：通用契约在场引擎（Q5 定稿）
+ *
+ * - 按 yml contracts 类型清单查表：类型不在清单内 = skip（不算违规）
+ * - 类型 → 判定方法的映射是代码不是配置（CONTRACT_JUDGMENTS）；
+ *   首个活跃条目 review → context.reviewReport 在场（studio agent-loop 已解析字段，不重复解析）
+ * - 类型在清单内但无判定方法注册 = violation（暴露配置与代码失配）
+ */
+
+import type { CompletionCheckersConfig, ContractPresenceContext, ContractPresenceResult } from './types';
+
+/** 类型 → 判定方法映射（代码，不是配置）。新增契约类型 = 在此加一条 + 测试 */
+const CONTRACT_JUDGMENTS: Record<string, (context: ContractPresenceContext) => boolean> = {
+  review: (context) => context.reviewReport != null,
+};
+
+/** 契约在场判定 */
+export function verifyContractPresence(
+  type: string,
+  context: ContractPresenceContext,
+  config: CompletionCheckersConfig = {},
+): ContractPresenceResult {
+  if (config.enabled === false || config.checkers?.contractPresence === false) {
+    return { checker: 'contract-presence', verdict: 'skip', detail: 'checker 已禁用' };
+  }
+  if (!(config.contracts ?? []).includes(type)) {
+    return { checker: 'contract-presence', verdict: 'skip', detail: `类型 ${type} 无 contracts 表项` };
+  }
+  const judge = CONTRACT_JUDGMENTS[type];
+  if (!judge) {
+    return {
+      checker: 'contract-presence',
+      verdict: 'violation',
+      detail: `类型 ${type} 已在 contracts 声明但无判定方法注册（配置与代码失配）`,
+    };
+  }
+  return judge(context)
+    ? { checker: 'contract-presence', verdict: 'pass' }
+    : { checker: 'contract-presence', verdict: 'violation', detail: `类型 ${type} 契约标记缺失` };
+}

package/src/completion-checkers/glob-match.ts

@@ -0,0 +1,54 @@
+/**
+ * 轻量 glob 匹配（支持 `**`、`*`、`?`），用于 commits 文件清单分类。
+ * 不匹配文件系统，纯字符串判定。
+ */
+
+/** 默认测试文件 glob（Q2 定稿） */
+export const DEFAULT_TEST_GLOBS = ['**/*.test.ts', '**/*.spec.ts', '**/__tests__/**'];
+
+/** 默认非代码文件 glob（兜底；权威清单由 yml noncode_globs 供给） */
+export const DEFAULT_NONCODE_GLOBS = ['**/*.md', '**/*.mdx', '**/*.txt', 'docs/**'];
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+
+/** glob → 锚定正则。前缀 `**` + `/` 匹配零或多段路径；`*` 不跨 `/`；`?` 匹配单个非 `/` 字符 */
+function globToRegExp(glob: string): RegExp {
+  let re = '';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        if (glob[i + 2] === '/') {
+          re += '(?:[^/]+/)*';
+          i += 3;
+        } else {
+          re += '.*';
+          i += 2;
+        }
+      } else {
+        re += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+      i += 1;
+    } else {
+      re += escapeRegExp(c);
+      i += 1;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+/** 单 glob 匹配 */
+export function matchGlob(file: string, glob: string): boolean {
+  return globToRegExp(glob).test(file);
+}
+
+/** 命中任一 glob */
+export function matchAnyGlob(file: string, globs: string[]): boolean {
+  return globs.some((g) => matchGlob(file, g));
+}

package/src/completion-checkers/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Completion Checkers（T7-E1，studio#160）
+ *
+ * WU 收尾软观测三件套——纯判定函数库：
+ * - verifyTddChain：实现 commit 的 Tested-By 引用链验证
+ * - verifyPhaseFormat：phase(...) subject 结构验证
+ * - verifyContractPresence：通用契约在场引擎
+ *
+ * 与 ConstraintCheck 闭环注册表无关：直接 export，不注册、不碰 checkers/index.ts。
+ * 函数不碰文件系统与 git；commits 由调用方（studio 第四段守卫，T7-E2）供给。
+ */
+
+export * from './types';
+export { DEFAULT_TEST_GLOBS, DEFAULT_NONCODE_GLOBS, matchGlob, matchAnyGlob } from './glob-match';
+export { classifyCommitFiles, resolveGlobs } from './classify';
+export type { CommitFileClassification } from './classify';
+export { verifyTddChain, TESTED_BY_RE, TESTS_NONE_RE } from './tdd-chain';
+export { verifyPhaseFormat, PHASE_SUBJECT_RE } from './phase-format';
+export { verifyContractPresence } from './contract-presence';

package/src/completion-checkers/phase-format.ts

@@ -0,0 +1,48 @@
+/**
+ * phase-format：WU 提交 subject 的 phase 结构验证（Q4 定稿）
+ *
+ * 协议（正则写死在函数里，不进配置）：
+ * - 全部非 merge commit 的 subject 命中 `^phase\([a-z0-9-]+\):\s+\S`
+ * - merge commit 出现即记违规
+ * - 阶段名不维护词表不查
+ * - 文件分类口径与 tdd-chain 共享（classify.ts），本 checker 不做免检——subject 结构要求覆盖全部非 merge commit
+ */
+
+import type { CommitInput, CommitVerdict, CompletionCheckersConfig, PhaseFormatResult } from './types';
+
+/** phase subject 结构（写死） */
+export const PHASE_SUBJECT_RE = /^phase\([a-z0-9-]+\):\s+\S/;
+
+/** merge commit 的 subject 启发式（调用方未显式给 isMerge 时兜底） */
+const MERGE_SUBJECT_RE = /^Merge\s/;
+
+/** 判定 merge commit：优先 isMerge 显式字段，缺省按 subject 启发式 */
+function isMergeCommit(commit: CommitInput): boolean {
+  return commit.isMerge ?? MERGE_SUBJECT_RE.test(commit.subject);
+}
+
+/** phase 格式验证 */
+export function verifyPhaseFormat(
+  commits: CommitInput[],
+  config: CompletionCheckersConfig = {},
+): PhaseFormatResult {
+  if (config.enabled === false || config.checkers?.phaseFormat === false) {
+    return { checker: 'phase-format', verdict: 'skip', commits: [] };
+  }
+
+  const verdicts: CommitVerdict[] = commits.map((commit) => {
+    if (isMergeCommit(commit)) {
+      return { sha: commit.sha, verdict: 'violation', reason: 'WU 提交集内出现 merge commit' };
+    }
+    if (!PHASE_SUBJECT_RE.test(commit.subject)) {
+      return { sha: commit.sha, verdict: 'violation', reason: `subject 不合规：${commit.subject}` };
+    }
+    return { sha: commit.sha, verdict: 'pass' };
+  });
+
+  return {
+    checker: 'phase-format',
+    verdict: verdicts.some((v) => v.verdict === 'violation') ? 'violation' : 'pass',
+    commits: verdicts,
+  };
+}

package/src/completion-checkers/tdd-chain.ts

@@ -0,0 +1,63 @@
+/**
+ * tdd-chain：实现 commit 的测试引用链验证（Q2/Q3 定稿）
+ *
+ * 协议（写死为机制本体，不进配置）：
+ * - 实现 commit 必须带 trailer `Tested-By: <sha>`
+ * - 被引 sha 须 a) 在本 WU 提交集内 b) 序列位置在本 commit 之前（比位置不比时间戳）c) 其文件清单命中 test_globs
+ * - 豁免：trailer `Tests: none` → waiver（放行记台账）；纯非代码/纯测试 commit 天然免检
+ */
+
+import type { CommitInput, CommitVerdict, CompletionCheckersConfig, TddChainResult } from './types';
+import { classifyCommitFiles, resolveGlobs } from './classify';
+
+/** Tested-By 引用协议（写死） */
+export const TESTED_BY_RE = /^Tested-By:\s*([0-9a-f]{7,40})\s*$/gim;
+
+/** Tests: none 豁免协议（写死） */
+export const TESTS_NONE_RE = /^Tests:\s*none\s*$/im;
+
+/** 引用链验证：伪造引用（不存在 / 位置在后 / 不含测试文件）一律记 violation */
+export function verifyTddChain(
+  commits: CommitInput[],
+  config: CompletionCheckersConfig = {},
+): TddChainResult {
+  if (config.enabled === false || config.checkers?.tddChain === false) {
+    return { checker: 'tdd-chain', verdict: 'skip', commits: [] };
+  }
+
+  const { testGlobs, noncodeGlobs } = resolveGlobs(config);
+  // 文件分类一次性算好，与同批 commit 的其他 checker 共享口径
+  const classifications = commits.map((c) => classifyCommitFiles(c, testGlobs, noncodeGlobs));
+
+  const verdicts: CommitVerdict[] = commits.map((commit, i) => {
+    if (classifications[i].exempt) {
+      return { sha: commit.sha, verdict: 'skip', reason: '纯测试/纯非代码 commit，天然免检' };
+    }
+    if (TESTS_NONE_RE.test(commit.body)) {
+      return { sha: commit.sha, verdict: 'waiver', reason: 'Tests: none 显式豁免' };
+    }
+    TESTED_BY_RE.lastIndex = 0;
+    const m = TESTED_BY_RE.exec(commit.body);
+    if (!m) {
+      return { sha: commit.sha, verdict: 'violation', reason: '缺 Tested-By trailer 且未声明 Tests: none' };
+    }
+    const ref = m[1].toLowerCase();
+    const j = commits.findIndex((c) => c.sha.toLowerCase().startsWith(ref));
+    if (j === -1) {
+      return { sha: commit.sha, verdict: 'violation', reason: `Tested-By 引用 ${ref} 不在本 WU 提交集内` };
+    }
+    if (j >= i) {
+      return { sha: commit.sha, verdict: 'violation', reason: `Tested-By 引用 ${ref} 位置不在本 commit 之前` };
+    }
+    if (!classifications[j].hasTests) {
+      return { sha: commit.sha, verdict: 'violation', reason: `被引 commit ${ref} 文件清单未命中 test_globs` };
+    }
+    return { sha: commit.sha, verdict: 'pass' };
+  });
+
+  return {
+    checker: 'tdd-chain',
+    verdict: verdicts.some((v) => v.verdict === 'violation') ? 'violation' : 'pass',
+    commits: verdicts,
+  };
+}

package/src/completion-checkers/types.ts

@@ -0,0 +1,84 @@
+/**
+ * Completion Checkers 类型定义（T7-E1，studio#160）
+ *
+ * 三个纯判定函数共享的输入/输出/配置类型。
+ * 与 ConstraintCheck 闭环注册表无关：直接 export，不注册、不碰 checkers/index.ts。
+ * 函数不碰文件系统与 git，commits 由调用方（studio 侧 git log）供给。
+ */
+
+/** WU 提交输入（有序，base..HEAD 升序） */
+export interface CommitInput {
+  /** 完整 sha */
+  sha: string;
+  /** commit subject（第一行） */
+  subject: string;
+  /** commit body（trailer 所在） */
+  body: string;
+  /** 本 commit 触碰的文件清单（相对路径） */
+  files: string[];
+  /**
+   * 是否 merge commit。调用方有 git 数据时应显式供给（如 %P 父数 > 1）；
+   * 缺省时按 subject 启发式判定（`/^Merge\s/`）。
+   */
+  isMerge?: boolean;
+}
+
+/** 判定结论：pass / violation / waiver（豁免放行，记台账）/ skip（不适用，不记台账） */
+export type CheckerVerdict = 'pass' | 'violation' | 'waiver' | 'skip';
+
+/** 单 commit 判定明细 */
+export interface CommitVerdict {
+  sha: string;
+  verdict: CheckerVerdict;
+  reason?: string;
+}
+
+/** verifyTddChain 结果。整体 verdict 只取 pass/violation/skip；waiver 是 commit 级结论 */
+export interface TddChainResult {
+  checker: 'tdd-chain';
+  verdict: 'pass' | 'violation' | 'skip';
+  commits: CommitVerdict[];
+}
+
+/** verifyPhaseFormat 结果 */
+export interface PhaseFormatResult {
+  checker: 'phase-format';
+  verdict: 'pass' | 'violation' | 'skip';
+  commits: CommitVerdict[];
+}
+
+/** verifyContractPresence 上下文（类型→字段的判定方法映射是代码不是配置） */
+export interface ContractPresenceContext {
+  /** review 类型契约：studio agent-loop 已解析的 metadata.reviewReport */
+  reviewReport?: unknown;
+  [key: string]: unknown;
+}
+
+/** verifyContractPresence 结果 */
+export interface ContractPresenceResult {
+  checker: 'contract-presence';
+  verdict: 'pass' | 'violation' | 'skip';
+  detail?: string;
+}
+
+/**
+ * completion_checkers 配置（对应 yml 顶层键 `completion_checkers:`，studio 侧自解）。
+ * 只配开关/glob/契约类型清单；协议格式（Tested-By、Tests: none、phase 结构）写死为机制本体。
+ * 缺省 = 全开 + 默认 glob。
+ */
+export interface CompletionCheckersConfig {
+  /** 总开关，缺省 true */
+  enabled?: boolean;
+  /** 各 checker 开关，缺省全开 */
+  checkers?: {
+    tddChain?: boolean;
+    phaseFormat?: boolean;
+    contractPresence?: boolean;
+  };
+  /** 测试文件 glob，缺省 DEFAULT_TEST_GLOBS */
+  testGlobs?: string[];
+  /** 非代码文件 glob，缺省 DEFAULT_NONCODE_GLOBS */
+  noncodeGlobs?: string[];
+  /** 契约类型清单：类型在清单内才判定，无表项 = skip */
+  contracts?: string[];
+}

package/src/index.ts

@@ -66,6 +66,13 @@ export * from './safety';
 // ========================================
 export * from './verification';
 
+// ========================================
+// Completion Checkers 导出（T7-E1，studio#160）
+// WU 收尾软观测三纯判定函数：tdd-chain / phase-format / contract-presence。
+// 纯函数直接 export，不进 ConstraintCheck 闭环注册表。
+// ========================================
+export * from './completion-checkers';
+
 // ========================================
 // Dashboard 数据导出
 // ========================================

package/src/pretool-use-hook.ts

@@ -0,0 +1,68 @@
+/**
+ * PreToolUse 执法脚本 — command-gate hook 固化版（studio#153）
+ *
+ * 内容 = studio-agent provider-hooks.buildHookScriptContent 生成脚本（#147）的固化版，
+ * 归属归位：谁的东西谁发货——CommandGate 是 harness 的，hook 脚本随 harness 包出厂。
+ * 编译产物 = 包内 dist/pretool-use-hook.js，provider hook 配置（codex hooks.json /
+ * kimi config.toml）直接指向 require.resolve('@dommaker/harness') 同目录的该文件，
+ * 不再由 studio-agent 按 worktree 生成、不再内嵌绝对路径。
+ *
+ * 语义（与生成版一致）：
+ * - stdin 收 provider PreToolUse JSON（tool_input.command）；
+ * - CommandGate.isAllowed 判定 block 级黑名单，命中 → stderr 写原因 + exit 2
+ *   （codex/kimi 阻断语义：exit 2 + stderr 阻断，其余 exit code fail-open）；
+ * - fail-open：stdin 非 JSON / 缺字段 / CommandGate 异常一律放行——宁可漏拦
+ *   也不全体 Bash 秒断，拦截层只是纵深防御的一道；
+ * - warn/audit 级命中同样放行（isAllowed 只看 block 级），与生成版行为一致。
+ */
+import { CommandGate } from './gates/command';
+
+/** hook 标识：与 studio-agent 生成版同一 marker（配置幂等检测共用口径） */
+export const HOOK_MARKER = 'harness-command-gate';
+
+interface PreToolUseInput {
+  tool_input?: { command?: string };
+}
+
+/**
+ * 判定一次 PreToolUse 是否放行。
+ * block 级命中 → allowed=false；warn/audit/干净命令/坏输入一律 allowed=true。
+ */
+export function decidePreToolUse(rawStdin: string): { allowed: boolean; command: string } {
+  let input: PreToolUseInput = {};
+  try {
+    input = JSON.parse(rawStdin || '{}') as PreToolUseInput;
+  } catch {
+    // 非 JSON stdin：放行
+  }
+  const command = (input.tool_input && input.tool_input.command) || '';
+  try {
+    const gate = new CommandGate();
+    return { allowed: gate.isAllowed(command), command };
+  } catch {
+    // CommandGate 加载/判定异常：fail-open
+    return { allowed: true, command };
+  }
+}
+
+/**
+ * 执行一次 hook：返回进程 exit code（2 = 阻断，0 = 放行）。
+ * 阻断时原因写 stderr（provider 把 stderr 作为阻断原因回填模型）。
+ */
+export function runPreToolUseHook(rawStdin: string): number {
+  const { allowed, command } = decidePreToolUse(rawStdin);
+  if (!allowed) {
+    console.error(`[${HOOK_MARKER}] blocked: ${command}`);
+    return 2;
+  }
+  return 0;
+}
+
+/* istanbul ignore next -- 进程入口仅做 stdin 收集 + exit，逻辑由 runPreToolUseHook 单测覆盖 */
+if (require.main === module) {
+  let raw = '';
+  process.stdin.on('data', (c) => { raw += c; });
+  process.stdin.on('end', () => {
+    process.exit(runPreToolUseHook(raw));
+  });
+}