@dommaker/harness 1.3.0 → 1.4.0

package/src/core/constraints/checkers/no-test-simplification.ts

@@ -4,10 +4,11 @@
 
 import type { ConstraintCheck } from './types';
 
+// m 标志必需：真实 diff 首行恒为 `diff --git`，缺 m 则 ^ 永不命中删除行（铁律静默失效）
 const DELETED_TEST_PATTERNS = [
-  /^-\s*(test|it|describe)\s*\(/, // 删除 test/it/describe
-  /^-\s*expect\s*\(/,              // 删除 expect
-  /^-\s*\/\/\s*test/,              // 删除注释的 test
+  /^-\s*(test|it|describe)\s*\(/m, // 删除 test/it/describe
+  /^-\s*expect\s*\(/m,              // 删除 expect
+  /^-\s*\/\/\s*test/m,              // 删除注释的 test
 ];
 
 export const noTestSimplification: ConstraintCheck = {

package/src/core/constraints/checkers/types.ts

@@ -29,8 +29,8 @@ export interface CheckEnv {
 /**
  * 证据提供者组：git diff / 源码扫描的 memoized I/O
  *
- * 由调用方绑定后传入 buildCheckEnv（如 ConstraintChecker 绑实例级
- * run 缓存的方法）；工厂本身不做 memoization。
+ * 由调用方绑定后传入 buildCheckEnv（#87：git 两项绑 GitEvidence adapter 实例，
+ * 一次 run 一份，命令级 memo 在 adapter 层）；工厂本身不做 memoization。
  */
 export interface EvidenceProviders {
   /** staged 全量 diff */

package/src/core/constraints/context-builder.ts

@@ -4,55 +4,25 @@
  * 从仓库状态（git diff / traces / 文档标记）推断 ConstraintContext：
  * 触发条件 + 各类证据标志。此前散落在 cli/commands/check.ts，
  * 迁入 core 供 CLI 与其他调用方共用。
+ *
+ * 架构评审 #87：本模块只做装配不做取证——git 证据一律经 git-evidence
+ * adapter 取（缺省真 git adapter，调用方可注入与 checker 层同源的那一份），
+ * 因此此处不再有 child_process / raw execSync。
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { execSync } from 'child_process';
-import { execAsync } from '../../utils/exec';
 import { detectSourceRoots } from '../../utils/detect-source-roots';
+import { readJsonl } from '../../utils/jsonl';
 import { DEFAULT_TRACE_FILE } from '../../types/trace';
+import type { ExecutionTrace } from '../../types/trace';
 import type { ConstraintContext, ConstraintTrigger } from '../../types/constraint';
-
-/**
- * 从 git diff 获取变更的文件
- */
-export async function getChangedFiles(staged: boolean, projectPath?: string): Promise<string[]> {
-  try {
-    const command = staged ? 'git diff --cached --name-only' : 'git diff --name-only';
-    const { stdout } = projectPath
-      ? await execAsync(command, { cwd: projectPath })
-      : await execAsync(command);
-    return String(stdout).trim().split('\n').filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-/**
- * 一次性列出 HEAD 中存在的所有目录（工单 18：替代逐文件 git ls-tree）
- *
- * 返回 null 表示命令失败（按惯例视所有目录为"新"）。
- */
-export function listHeadDirs(projectPath: string): Set<string> | null {
-  try {
-    const output = execSync('git ls-tree -r --name-only HEAD', { cwd: projectPath, stdio: 'pipe', encoding: 'utf-8' });
-    const dirs = new Set<string>();
-    for (const file of String(output).split('\n')) {
-      if (!file) continue;
-      const parts = file.split('/');
-      for (let i = 1; i < parts.length; i++) {
-        dirs.add(parts.slice(0, i).join('/'));
-      }
-    }
-    return dirs;
-  } catch {
-    return null;
-  }
-}
+import { createGitEvidence, splitFileNames, type GitEvidence } from './git-evidence';
 
 /**
  * 检查文件所在目录是否在 git HEAD 中不存在（即新目录）
+ *
+ * headDirs 由 git-evidence adapter 取证（null = 命令失败，按惯例视所有目录为"新"）。
  */
 export function isNewDirectory(headDirs: Set<string> | null, filePath: string): boolean {
   if (headDirs === null) return true; // 命令失败 = 假定为新
@@ -71,10 +41,17 @@ const CODE_FILE_REGEX = /\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|c
  *
  * ADR-0001：变更包含代码文件时，在主推断之外附加 code_implementation
  * （返回数组 [主推断, 'code_implementation']；主推断逻辑保持不变）。
+ *
+ * 新目录判定所需的 HEAD 目录集经 git 证据 adapter 取（#87）：
+ * 调用方注入即与 checker 层同一份证据，缺省走真 git adapter。
  */
 export function detectTrigger(
   changedFiles: string[],
-  options: { trigger?: ConstraintTrigger; projectPath?: string }
+  options: {
+    trigger?: ConstraintTrigger;
+    projectPath?: string;
+    evidence?: GitEvidence;
+  }
 ): ConstraintTrigger | ConstraintTrigger[] {
   if (options.trigger) return options.trigger;
 
@@ -89,7 +66,10 @@ export function detectTrigger(
   const hasModuleChange = changedFiles.some(f =>
     sourceRoots.some(root => f.startsWith(root + '/') || f.startsWith(root + '\\')) && !f.includes('__tests__')
   );
-  const headDirs = hasModuleChange ? listHeadDirs(projectPath) : null;
+  // 工单 18 的批量语义保留在 adapter 层：一次 ls-tree，且仅在有模块变更时才取证
+  const headDirs = hasModuleChange
+    ? (options.evidence ?? createGitEvidence(projectPath)).headDirs()
+    : null;
   const hasModuleCreation = changedFiles.some(f =>
     sourceRoots.some(root => f.startsWith(root + '/') || f.startsWith(root + '\\')) &&
     isNewDirectory(headDirs, f)
@@ -111,22 +91,11 @@ export function detectTrigger(
 export async function detectFailingTest(projectPath: string): Promise<boolean> {
   try {
     const traceFile = path.join(projectPath, DEFAULT_TRACE_FILE);
-    if (!fs.existsSync(traceFile)) return false;
-
-    const content = fs.readFileSync(traceFile, 'utf-8');
-    const lines = content.trim().split('\n').filter(Boolean);
-    if (lines.length === 0) return false;
-
-    // 检查最近 20 条记录是否有 fail
-    const recent = lines.slice(-20);
-    return recent.some(line => {
-      try {
-        const trace = JSON.parse(line);
-        return trace.result === 'fail';
-      } catch {
-        return false;
-      }
-    });
+    // 坏行策略：skip（原逐行 catch→false 语义不变）；只 parse 最近 20 行
+    // 计数去向：豁免（harness#100）——布尔证据探测，坏行只会让证据变少（判定方向保守），
+    // 消费面是 check 的 pass/fail 判定，没有可挂计数的输出位
+    const { records } = readJsonl<ExecutionTrace>(traceFile, 'skip', { tail: 20 });
+    return records.some(trace => trace.result === 'fail');
   } catch {
     return false;
   }
@@ -161,22 +130,12 @@ export function detectRootCauseInvestigation(projectPath: string): boolean {
 export async function detectVerificationEvidence(projectPath: string): Promise<boolean> {
   try {
     const traceFile = path.join(projectPath, DEFAULT_TRACE_FILE);
-    if (!fs.existsSync(traceFile)) return false;
-
-    const content = fs.readFileSync(traceFile, 'utf-8');
-    const lines = content.trim().split('\n').filter(Boolean);
-    if (lines.length === 0) return false;
-
-    // 检查最近 10 条记录是否有 pass
-    const recent = lines.slice(-10);
-    return recent.some(line => {
-      try {
-        const trace = JSON.parse(line);
-        return trace.result === 'pass';
-      } catch {
-        return false;
-      }
-    });
+    // 坏行策略：skip（原逐行 catch→false 语义不变）；只 parse 最近 10 行
+    // tail 在 parse 之前截断 → 坏行会占用尾部槽位（#82 裁决范围外的既有口径，本票不改）
+    // 计数去向：豁免（harness#100）——同 detectFailingTest：布尔证据探测无计数输出位，
+    // 坏行只会让证据变少
+    const { records } = readJsonl<ExecutionTrace>(traceFile, 'skip', { tail: 10 });
+    return records.some(trace => trace.result === 'pass');
   } catch {
     return false;
   }
@@ -209,21 +168,6 @@ export function detectRequirement(projectPath: string): boolean {
   return indicators.some(f => fs.existsSync(path.join(projectPath, f)));
 }
 
-/**
- * 检测是否在 git worktree 中
- */
-export function detectWorktree(projectPath: string): boolean {
-  try {
-    const gitDir = path.join(projectPath, '.git');
-    if (fs.existsSync(gitDir)) {
-      const content = fs.readFileSync(gitDir, 'utf-8');
-      // 实际 worktree 的 .git 是文件（指向主 repo），不是目录
-      return content.startsWith('gitdir:');
-    }
-  } catch { /* ignore */ }
-  return false;
-}
-
 /**
  * 检测是否有复用检查
  * 检查 .harness/reuse/ 目录或相关文档
@@ -244,15 +188,20 @@ export function detectReuseCheck(projectPath: string): boolean {
 
 /**
  * 构建约束上下文：变更文件 + 触发条件推断 + 证据标志检测
+ *
+ * options.evidence（#87）：git 证据适配器。调用方（CLI check）注入同一实例给
+ * checkConstraints，即可让 context-builder 与 checker 层共用同一证据来源。
  */
 export async function buildConstraintContext(options: {
   projectPath?: string;
   staged: boolean;
   trigger?: ConstraintTrigger;
+  evidence?: GitEvidence;
 }): Promise<ConstraintContext> {
   const projectPath = options.projectPath || process.cwd();
-  const changedFiles = await getChangedFiles(options.staged, options.projectPath);
-  const inferred = detectTrigger(changedFiles, { trigger: options.trigger, projectPath });
+  const evidence = options.evidence ?? createGitEvidence(projectPath);
+  const changedFiles = splitFileNames(evidence.changedFileNames(options.staged));
+  const inferred = detectTrigger(changedFiles, { trigger: options.trigger, projectPath, evidence });
   const triggers = Array.isArray(inferred) ? inferred : [inferred];
 
   return {
@@ -266,6 +215,5 @@ export async function buildConstraintContext(options: {
     hasVerificationEvidence: await detectVerificationEvidence(projectPath),
     hasReuseCheck: detectReuseCheck(projectPath),
     hasRequirement: detectRequirement(projectPath),
-    hasWorktree: detectWorktree(projectPath),
   };
 }

package/src/core/constraints/doc-freshness/runner.ts

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
+import { DEFAULT_SKIP_DIRS } from '../../../utils/file-walk';
 import type {
   DocFreshnessCheck,
   DocFreshnessConfig,
@@ -238,7 +239,7 @@ export class FreshnessRunner {
       if (!check.skip_reverse_check) {
         // 从文档目录中推断要扫描的根目录集
         const rootDirs = this.inferRootDirs(docDirs, ctx.projectPath);
-        const excludeSet = new Set(check.exclude || ['__tests__', 'node_modules', 'dist']);
+        const excludeSet = new Set(check.exclude || DEFAULT_SKIP_DIRS);
 
         for (const rootDir of rootDirs) {
           const absRoot = join(ctx.projectPath, rootDir);

package/src/core/constraints/git-evidence.ts

@@ -0,0 +1,120 @@
+/**
+ * git 证据适配器（架构评审 #87）
+ *
+ * 全仓唯一的 git 取证点：context-builder（触发推断）与 checker 层（CheckEnv 证据）
+ * 共用同一实例 = 共用同一证据来源。此前两处各自抓真 git，一次 CLI check 里
+ * `git diff --cached --name-only` 实跑两遍。
+ *
+ * seam 上的两个真 adapter：
+ * - 缺省 realGitCommandRunner：真 git 子进程
+ * - 注入 runner：委托/计数/命令表（测试与定制场景）
+ *
+ * memo 落在实例层（命令 → 结果，含失败结果），实例生命周期 = 一次 check run，
+ * 因此不存在隐式全局（工单 18 的 run 级收益保留，形状改为显式传递）。
+ */
+
+import { execSync } from 'child_process';
+
+/**
+ * git 命令执行器：返回 trim 后的 stdout，失败抛错（由 adapter 归类为「无该证据」）
+ *
+ * command 恒为本模块内的固定字面量，cwd 来自调用方（非 shell 拼接），无注入面。
+ */
+export type GitCommandRunner = (command: string, cwd: string) => string;
+
+/**
+ * git 证据：一次 run 内的 git 事实快照，同类命令至多执行一次
+ *
+ * 判定语义与原 context-builder / checker 私有实现逐条对齐：
+ * - diff 类命令失败 → 空串（无变更证据）
+ * - ls-tree 失败 → null（调用方按「所有目录都是新目录」处理）
+ */
+export interface GitEvidence {
+  /** 取证基准目录（git 命令的 cwd） */
+  readonly projectPath: string;
+  /** staged 全量 diff（`git diff --cached`） */
+  stagedDiff(): string;
+  /** 变更文件名列表，\n 分隔（staged → `git diff --cached --name-only`） */
+  changedFileNames(staged: boolean): string;
+  /** HEAD 中存在的目录集合；命令失败 → null */
+  headDirs(): Set<string> | null;
+}
+
+/** 与 utils/exec.runCommand 同一缓冲上限（大 diff 不 ENOBUFS） */
+const GIT_MAX_BUFFER = 1024 * 1024;
+
+/**
+ * 真 git adapter：同步 spawn，失败抛错交由 memo 归类
+ *
+ * execSync 声明返回 string | Buffer（Buffer 无 trim），故显式归一为 string——
+ * 与迁移前 context-builder 的 `String(output)` 取值语义一致。
+ */
+export const realGitCommandRunner: GitCommandRunner = (command, cwd) =>
+  String(
+    execSync(command, { cwd, stdio: 'pipe', encoding: 'utf-8', maxBuffer: GIT_MAX_BUFFER })
+  ).trim();
+
+const STAGED_DIFF = 'git diff --cached';
+const STAGED_DIFF_NAMES = 'git diff --cached --name-only';
+const UNSTAGED_DIFF_NAMES = 'git diff --name-only';
+const HEAD_TREE = 'git ls-tree -r --name-only HEAD';
+
+/**
+ * 从 `git ls-tree -r --name-only HEAD` 输出提取 HEAD 中存在的所有目录
+ *
+ * 工单 18 批量语义：一次命令替代逐文件 ls-tree。
+ */
+export function parseHeadDirs(treeOutput: string): Set<string> {
+  const dirs = new Set<string>();
+  for (const file of treeOutput.split('\n')) {
+    if (!file) continue;
+    const parts = file.split('/');
+    for (let i = 1; i < parts.length; i++) {
+      dirs.add(parts.slice(0, i).join('/'));
+    }
+  }
+  return dirs;
+}
+
+/**
+ * 构造 git 证据 adapter（生产侧唯一构造点）
+ *
+ * @param projectPath 取证目录
+ * @param run 命令执行器，缺省真 git；测试注入计数/替身执行器即可脱离子进程
+ */
+export function createGitEvidence(
+  projectPath: string,
+  run: GitCommandRunner = realGitCommandRunner
+): GitEvidence {
+  type CommandResult = { ok: boolean; stdout: string };
+  const memo = new Map<string, CommandResult>();
+
+  const once = (command: string): CommandResult => {
+    let result = memo.get(command);
+    if (!result) {
+      try {
+        result = { ok: true, stdout: run(command, projectPath) };
+      } catch {
+        result = { ok: false, stdout: '' };
+      }
+      memo.set(command, result);
+    }
+    return result;
+  };
+
+  return {
+    projectPath,
+    stagedDiff: () => once(STAGED_DIFF).stdout,
+    changedFileNames: (staged: boolean) =>
+      once(staged ? STAGED_DIFF_NAMES : UNSTAGED_DIFF_NAMES).stdout,
+    headDirs: () => {
+      const result = once(HEAD_TREE);
+      return result.ok ? parseHeadDirs(result.stdout) : null;
+    },
+  };
+}
+
+/** 变更文件名列表 → 路径数组（git 无输出时为空集合） */
+export function splitFileNames(names: string): string[] {
+  return names.split('\n').filter(Boolean);
+}

package/src/core/constraints/injection-drift.ts

@@ -17,18 +17,18 @@
  * 两处均无标记段 = 未注入，不算漂移（report 一句话提示，check 不警告）。
  */
 
-import * as fs from 'fs';
 import * as path from 'path';
 import { getEffectiveConstraints } from '../effective-constraints';
+import { getHarnessPackageVersion } from '../../utils/package-version';
+import { CONSTRAINTS_END_MARKER, renderConstraintsSection } from './injection-renderer';
 import {
-  CONSTRAINTS_START_MARKER,
-  CONSTRAINTS_END_MARKER,
-  renderConstraintsSection,
-} from './injection-renderer';
+  resolveInjectionTarget,
+  readIfExists,
+  countGovernanceHeadings,
+  type InjectionFile,
+} from './injection-writer';
 
-/** 注入段落点文件名（检测顺序即路由优先级：旧模型仓 CLAUDE.md 豁免优先） */
-const INJECTION_FILES = ['CLAUDE.md', 'AGENTS.md'] as const;
-export type InjectionFile = (typeof INJECTION_FILES)[number];
+export type { InjectionFile };
 
 /** 注入漂移检测结果 */
 export interface InjectionDrift {
@@ -57,20 +57,6 @@ export const INJECTION_DRIFT_FIX_HINT = '重跑 `npx @dommaker/harness init` 同
 const VERSION_LINE_RE = /<!-- version: ([^ ]+) -->/;
 const ENTRY_LINE_RE = /^- \*\*.+?\*\*: .+$/;
 const GROUP_HEADING_RE = /^### .+$/;
-const GOVERNANCE_HEADING_RE = /^## Governance Rules[ \t]*$/gm;
-
-/**
- * 读取当前 harness 包版本（与 init 注入时写入的版本同源）
- */
-function getPackageVersion(): string {
-  try {
-    const pkgPath = path.join(__dirname, '..', '..', '..', 'package.json');
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-    return pkg.version ?? 'unknown';
-  } catch {
-    return 'unknown';
-  }
-}
 
 /**
  * 提取参与条目级比对的"有效行"：注入条目（- **id**: text）与分组标题（### ...）。
@@ -83,48 +69,15 @@ function significantLines(section: string): string[] {
     .filter(l => ENTRY_LINE_RE.test(l) || GROUP_HEADING_RE.test(l));
 }
 
-function readIfExists(filePath: string): string | null {
-  try {
-    const content = fs.readFileSync(filePath, 'utf-8');
-    return typeof content === 'string' ? content : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 解析治理约束注入段落点（studio #307，ADR 2026-08-21 落点模型）
- *
- * 与 init 的 setupGovernanceConstraints 路由一致：CLAUDE.md 含标记段优先
- * （旧模型仓豁免），否则看 AGENTS.md（新模型仓注入段在 PRESERVE:governance 内）；
- * 两处均无完整标记段 → null（未注入）。
- *
- * detectInjectionDrift 与 constraints retire 的注入段同步共用本路由。
- */
-export function resolveInjectionTarget(
-  projectRoot: string
-): { file: InjectionFile; content: string; startIdx: number; endIdx: number } | null {
-  for (const file of INJECTION_FILES) {
-    const content = readIfExists(path.join(projectRoot, file));
-    if (content === null) continue;
-    const startIdx = content.indexOf(CONSTRAINTS_START_MARKER);
-    const endIdx = content.indexOf(CONSTRAINTS_END_MARKER);
-    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-      return { file, content, startIdx, endIdx };
-    }
-  }
-  return null;
-}
-
 /**
  * 检测约束注入段漂移
  *
  * @param projectRoot 项目根路径
- * @param currentVersion 当前 harness 版本（缺省读 package.json；测试可显式传入）
+ * @param currentVersion 当前 harness 版本（缺省经 getHarnessPackageVersion 正本读取；测试可显式传入）
  */
 export function detectInjectionDrift(
   projectRoot: string,
-  currentVersion: string = getPackageVersion()
+  currentVersion: string = getHarnessPackageVersion()
 ): InjectionDrift {
   const result: InjectionDrift = {
     hasDrift: false,
@@ -141,7 +94,7 @@ export function detectInjectionDrift(
       readIfExists(path.join(projectRoot, 'CLAUDE.md')) ??
       readIfExists(path.join(projectRoot, 'AGENTS.md'));
     if (legacy !== null) {
-      result.duplicateHeading = (legacy.match(GOVERNANCE_HEADING_RE) ?? []).length > 1;
+      result.duplicateHeading = countGovernanceHeadings(legacy) > 1;
     }
     result.notInjected = true;
     return result;
@@ -150,8 +103,8 @@ export function detectInjectionDrift(
   result.injectionFile = target.file;
   const { content, startIdx, endIdx } = target;
 
-  // 重复章节：全文统计 `## Governance Rules` 标题数（含标记段所属的合法标题）
-  const headingCount = (content.match(GOVERNANCE_HEADING_RE) ?? []).length;
+  // 重复章节：全文统计治理标题数（严格计数 injection-writer.countGovernanceHeadings，#83）
+  const headingCount = countGovernanceHeadings(content);
   result.duplicateHeading = headingCount > 1;
 
   const actualSection = content.slice(startIdx, endIdx + CONSTRAINTS_END_MARKER.length);