@dommaker/harness 1.3.0 → 1.4.0

package/src/core/constraints/__tests__/capabilities-reconcile.test.ts

@@ -0,0 +1,200 @@
+/**
+ * capabilities-reconcile 纯判定测试（ADR-0009）
+ *
+ * interface 即测试面：喂文档内容与文件清单，断言判定结果；无 fs/git fixture。
+ */
+
+import {
+  reconcileCapabilities,
+  significantCodeChanges,
+  collectSourceFiles,
+} from '../capabilities-reconcile';
+
+const TABLE = [
+  '| 模块 | 文件 | 说明 |',
+  '|------|------|------|',
+  '| Core | src/core/checker.ts | 引擎 |',
+  '| Gates | src/gates/ | 门禁目录 |',
+].join('\n');
+
+function withExtras(extraLines: string[]): string {
+  return [TABLE, ...extraLines].join('\n');
+}
+
+describe('reconcileCapabilities — 解析口径', () => {
+  it('收集所有单元格的文件与目录条目，不再只看第二列', () => {
+    const content = withExtras(['| src/utils/helper.ts | 名字在首列 | x |']);
+    const v = reconcileCapabilities({
+      content,
+      populationFiles: [],
+    });
+    expect(v.fileEntries).toContain('src/core/checker.ts');
+    expect(v.fileEntries).toContain('src/utils/helper.ts');
+    expect(v.dirEntries).toEqual(['src/gates/']);
+  });
+
+  it('hasTable 区分散文文档与有表格零条目；listingFormat 识别计数行', () => {
+    expect(reconcileCapabilities({ content: '随便写点什么', populationFiles: [] }).hasTable).toBe(false);
+    const emptyTable = '| 模块 | 文件 |\n|---|---|';
+    expect(reconcileCapabilities({ content: emptyTable, populationFiles: [] }).hasTable).toBe(true);
+    const listing = '# 能力\nCLI Commands (9)\nIron Laws (3)';
+    expect(reconcileCapabilities({ content: listing, populationFiles: [] }).listingFormat).toBe(true);
+  });
+});
+
+describe('reconcileCapabilities — 代码→文档（漏登记）', () => {
+  const population = ['src/core/checker.ts', 'src/gates/command.ts', 'src/knowledge/store.ts'];
+
+  it('module 模式：目录条目参与覆盖，未覆盖文件聚合为目录', () => {
+    const v = reconcileCapabilities({
+      content: TABLE,
+      populationFiles: population,
+      sourceRoots: ['src'],
+    });
+    expect(v.uncoveredFiles).toEqual(['src/knowledge/store.ts']);
+    expect(v.uncoveredDirs).toEqual(['src/knowledge/']);
+  });
+
+  it('目录条目恒参与覆盖（check/fix 同规则），mode 只是调用方取哪份输出形状', () => {
+    const v = reconcileCapabilities({
+      content: TABLE,
+      populationFiles: population,
+      sourceRoots: ['src'],
+    });
+    expect(v.coverageEntries).toContain('src/gates/');
+    expect(v.uncoveredFiles).toEqual(['src/knowledge/store.ts']);
+    // file 模式调用方读 uncoveredFiles；module 模式读 uncoveredDirs——同一判定两种投影
+    expect(v.uncoveredDirs).toEqual(['src/knowledge/']);
+  });
+
+  it('文件条目路径边界后缀匹配：兼容 basename 登记但拒绝模糊碰撞', () => {
+    const content = withExtras(['| 局部 | core/checker.ts | 相对路径条目 |']);
+    const v = reconcileCapabilities({
+      content,
+      populationFiles: ['src/core/checker.ts', 'src/otherchecker.ts', 'src/docs/src/checked.ts'],
+    });
+    expect(v.uncoveredFiles).toEqual(['src/otherchecker.ts', 'src/docs/src/checked.ts']);
+  });
+
+  it('增量判定独立于全量：changedFiles 未被覆盖的进入 uncoveredChanges', () => {
+    const v = reconcileCapabilities({
+      content: TABLE,
+      populationFiles: population,
+      changedFiles: ['src/core/checker.ts', 'src/knowledge/store.ts'],
+      sourceRoots: ['src'],
+    });
+    expect(v.uncoveredChanges).toEqual(['src/knowledge/store.ts']);
+  });
+});
+
+describe('reconcileCapabilities — 文档→代码（幽灵）', () => {
+  it('文件条目多根相对路径：项目根或任一源码根下存在即算活', () => {
+    const content = '| 模块 | 文件 | 说明 |\n|---|---|---|\n| API | apps/routes.ts | studio 式多根 |';
+    const v = reconcileCapabilities({
+      content,
+      populationFiles: [],
+      sourceRoots: ['src', 'apps/api'],
+      fileExists: (rel) => rel === 'apps/api/apps/routes.ts',
+    });
+    expect(v.deadEntries).toEqual([]);
+  });
+
+  it('目录条目也查幽灵（口径从严，Q6a）：磁盘不存在且实况无文件才算死', () => {
+    const v = reconcileCapabilities({
+      content: TABLE,
+      populationFiles: ['src/core/checker.ts'],
+      fileExists: (rel) => !rel.startsWith('src/gates'),
+    });
+    expect(v.deadEntries).toEqual(['src/gates/']);
+  });
+
+  it('目录条目实况有文件即活（oracle 缺省的纯清单场景）', () => {
+    const v = reconcileCapabilities({
+      content: TABLE,
+      populationFiles: ['src/core/checker.ts', 'src/gates/command.ts'],
+    });
+    expect(v.deadEntries).toEqual([]);
+  });
+
+  it('裸文件名条目按实况兜底：无任何文件命中才算幽灵', () => {
+    const content = withExtras(['| 别名 | routes.ts | 裸 basename |']);
+    const v = reconcileCapabilities({
+      content,
+      populationFiles: [
+        'src/core/checker.ts',
+        'src/gates/command.ts',
+        'src/agent-configs/routes.ts',
+      ],
+    });
+    expect(v.deadEntries).toEqual([]);
+  });
+
+  it(' basename 碰撞场景：全路径幽灵即使同名文件存活仍被报出（2026-08-08 事故回归）', () => {
+    const content = withExtras(['| 旧 | src/agent-configs/routes.ts | 已删 |']);
+    const v = reconcileCapabilities({
+      content,
+      populationFiles: ['src/agents/routes.ts'],
+      fileExists: () => false,
+    });
+    expect(v.deadEntries).toContain('src/agent-configs/routes.ts');
+  });
+});
+
+describe('significantCodeChanges', () => {
+  it('只留有意义的代码变更：扩展名过滤 + 排除测试文件', () => {
+    const names = [
+      'src/core/checker.ts',
+      'src/web/App.tsx',
+      'scripts/run.js',
+      'src/__tests__/checker-extra.test.ts',
+      'src/core/checker.test.ts',
+      'src/core/checker.spec.ts',
+      'docs/readme.md',
+      'package.json',
+    ];
+    expect(significantCodeChanges(names)).toEqual([
+      'src/core/checker.ts',
+      'src/web/App.tsx',
+      'scripts/run.js',
+    ]);
+  });
+});
+
+describe('collectSourceFiles', () => {
+  const fs = require('fs') as typeof import('fs');
+  const os = require('os') as typeof import('os');
+  const path = require('path') as typeof import('path');
+
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'reconcile-scan-'));
+    fs.mkdirSync(path.join(tmpDir, 'src/core'), { recursive: true });
+    fs.mkdirSync(path.join(tmpDir, 'src/__tests__'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, 'src/core/index.ts'), '');
+    fs.writeFileSync(path.join(tmpDir, 'src/core/foo.ts'), '');
+    fs.writeFileSync(path.join(tmpDir, 'src/core/types.d.ts'), '');
+    fs.writeFileSync(path.join(tmpDir, 'src/core/App.tsx'), '');
+    fs.writeFileSync(path.join(tmpDir, 'src/__tests__/foo.test.ts'), '');
+  });
+
+  it('返回项目相对路径；跳过 barrel/声明文件/测试目录；默认不含 tsx', () => {
+    expect(collectSourceFiles(tmpDir, ['src']).sort()).toEqual(['src/core/foo.ts']);
+  });
+
+  it('includeTsx 时纳入 .tsx', () => {
+    expect(collectSourceFiles(tmpDir, ['src'], { includeTsx: true }).sort()).toEqual([
+      'src/core/App.tsx',
+      'src/core/foo.ts',
+    ]);
+  });
+
+  it('多根收集并集', () => {
+    fs.mkdirSync(path.join(tmpDir, 'apps/api/src'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, 'apps/api/src/main.ts'), '');
+    expect(collectSourceFiles(tmpDir, ['src', 'apps/api/src']).sort()).toEqual([
+      'apps/api/src/main.ts',
+      'src/core/foo.ts',
+    ]);
+  });
+});

package/src/core/constraints/__tests__/capability-counts.test.ts

@@ -0,0 +1,94 @@
+/**
+ * 能力清单计数注入测试（架构评审 2026-09-02 · 候选9 / harness#88）
+ *
+ * capabilities-parser 属 core，此前**值导入** cli/commands/definitions 与
+ * gates/definitions 来数命令数——core 向上的运行时依赖。现在计数所需的定义
+ * 由调用方（cli 侧）注入，core 只消费最小形状（命令条目集合 + 门禁的 cli 字段）。
+ *
+ * 断言口径：计数由注入源推导，与宿主仓真实定义表无关。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { IRON_LAWS, GUIDELINES } from '../definitions';
+import {
+  checkCapabilityCounts,
+  updateCapabilityCounts,
+  type CapabilityDefinitionSource,
+} from '../capabilities-parser';
+
+/** 3 条非门禁命令 + 4 条门禁（其中 2 条带 cli 元数据）→ CLI Commands = 5 */
+const SOURCE: CapabilityDefinitionSource = {
+  commands: [{}, {}, {}],
+  gates: [{}, { cli: {} }, { cli: {} }, {}],
+};
+
+describe('能力清单计数（注入定义源，harness#88）', () => {
+  let projectDir: string;
+
+  beforeAll(() => {
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-capability-counts-'));
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  function writeCapabilities(content: string): string {
+    const dir = fs.mkdtempSync(path.join(projectDir, 'case-'));
+    fs.writeFileSync(path.join(dir, 'CAPABILITIES.md'), content, 'utf-8');
+    return dir;
+  }
+
+  describe('updateCapabilityCounts', () => {
+    it('CLI Commands 计数 = 注入命令数 + 带 cli 的门禁数', () => {
+      const out = updateCapabilityCounts('## CLI Commands (999)\n', SOURCE);
+      expect(out).toContain('CLI Commands (5)');
+    });
+
+    it('Quality Gates 计数 = 注入门禁总数（不看 cli 字段）', () => {
+      const out = updateCapabilityCounts('## Quality Gates (999)\n', SOURCE);
+      expect(out).toContain('Quality Gates (4)');
+    });
+
+    it('Iron Laws / Guidelines 计数仍来自 core 自身定义表（同层，不注入）', () => {
+      const out = updateCapabilityCounts('Iron Laws (999)\nGuidelines (999)\n', SOURCE);
+      expect(out).toContain(`Iron Laws (${Object.keys(IRON_LAWS).length})`);
+      expect(out).toContain(`Guidelines (${Object.keys(GUIDELINES).length})`);
+    });
+
+    it('不触碰文档中不存在的计数行', () => {
+      const out = updateCapabilityCounts('# Harness Capabilities\n\n无计数行\n', SOURCE);
+      expect(out).toBe('# Harness Capabilities\n\n无计数行\n');
+    });
+
+    it('同一注入源下写回幂等', () => {
+      const once = updateCapabilityCounts('CLI Commands (0)\nQuality Gates (0)\n', SOURCE);
+      expect(updateCapabilityCounts(once, SOURCE)).toBe(once);
+    });
+  });
+
+  describe('checkCapabilityCounts', () => {
+    it('计数与注入源一致 → match', () => {
+      const dir = writeCapabilities('## CLI Commands (5)\n## Quality Gates (4)\n');
+      expect(checkCapabilityCounts(dir, SOURCE)).toEqual({ match: true, mismatches: [] });
+    });
+
+    it('计数漂移 → match=false 并报出注入源的 actual', () => {
+      const dir = writeCapabilities('## CLI Commands (999)\n## Quality Gates (4)\n');
+      const { match, mismatches } = checkCapabilityCounts(dir, SOURCE);
+      expect(match).toBe(false);
+      expect(mismatches.join('\n')).toContain('CLI Commands: 文档 999 → 实际 5');
+    });
+
+    it('CAPABILITIES.md 不存在 → 跳过（无 mismatch）', () => {
+      const dir = fs.mkdtempSync(path.join(projectDir, 'empty-'));
+      expect(checkCapabilityCounts(dir, SOURCE)).toEqual({ match: true, mismatches: [] });
+    });
+  });
+});

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

@@ -0,0 +1,208 @@
+/**
+ * git 证据适配器测试（架构评审 #87）
+ *
+ * 覆盖：
+ * - 真 git adapter 在三类证据（staged diff / 变更名 / HEAD 目录）上的取证正确性
+ * - 命令失败语义：diff → ''、ls-tree → null（全部视为新目录）
+ * - memo 落在实例层：同一实例内每条 git 命令至多执行一次
+ * - context-builder 与 checker 共用同一实例 → 一次 run 内无重复 git 命令
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+import {
+  createGitEvidence,
+  parseHeadDirs,
+  realGitCommandRunner,
+  type GitCommandRunner,
+  type GitEvidence,
+} from '../git-evidence';
+import { buildConstraintContext } from '../context-builder';
+import { ConstraintChecker } from '../checker';
+import { GUIDELINES } from '../definitions';
+import type { MergedConstraintsConfig } from '../../../types/project-config';
+
+/** 建一个真 git fixture：committed src/existing.ts + 一个 staged 修改 */
+function makeRepo(options: { stagedChange?: boolean } = {}): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-git-evidence-'));
+  execSync('git init -q', { cwd: dir, stdio: 'pipe' });
+  execSync('git config user.email "test@example.com"', { cwd: dir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: dir, stdio: 'pipe' });
+  fs.mkdirSync(path.join(dir, 'src', 'nested'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'src', 'existing.ts'), 'export const a = 1;\n');
+  fs.writeFileSync(path.join(dir, 'src', 'nested', 'deep.ts'), 'export const b = 1;\n');
+  fs.writeFileSync(path.join(dir, 'README.md'), '# fixture\n');
+  execSync('git add .', { cwd: dir, stdio: 'pipe' });
+  execSync('git commit -q -m init', { cwd: dir, stdio: 'pipe' });
+  if (options.stagedChange !== false) {
+    fs.writeFileSync(path.join(dir, 'src', 'existing.ts'), 'export const a = 2;\n');
+    execSync('git add src/existing.ts', { cwd: dir, stdio: 'pipe' });
+  }
+  return dir;
+}
+
+/** 记录每条实际执行的 git 命令，执行本身委托真 adapter */
+function countingRunner(): { runner: GitCommandRunner; commands: string[] } {
+  const commands: string[] = [];
+  return {
+    commands,
+    runner: (command, cwd) => {
+      commands.push(command);
+      return realGitCommandRunner(command, cwd);
+    },
+  };
+}
+
+/** 包住一份证据实例，记录「哪个 phase 调了哪个证据方法」（取证是否同源的可观测面） */
+function recordingEvidence(
+  source: GitEvidence,
+  phase: () => string,
+  calls: string[]
+): GitEvidence {
+  return {
+    projectPath: source.projectPath,
+    stagedDiff: () => {
+      calls.push(`${phase()}:stagedDiff`);
+      return source.stagedDiff();
+    },
+    changedFileNames: (staged: boolean) => {
+      calls.push(`${phase()}:changedFileNames`);
+      return source.changedFileNames(staged);
+    },
+    headDirs: () => {
+      calls.push(`${phase()}:headDirs`);
+      return source.headDirs();
+    },
+  };
+}
+
+describe('git 证据适配器（#87）', () => {
+  describe('真 git adapter 取证', () => {
+    it('stagedDiff 返回 staged 全量 diff；changedFileNames 按 staged 选择命令', () => {
+      const dir = makeRepo();
+      const evidence = createGitEvidence(dir);
+
+      expect(evidence.stagedDiff()).toContain('+export const a = 2;');
+      expect(evidence.changedFileNames(true)).toBe('src/existing.ts');
+      // 无未暂存变更 → unstaged diff 为空
+      expect(evidence.changedFileNames(false)).toBe('');
+
+      fs.writeFileSync(path.join(dir, 'src', 'existing.ts'), 'export const a = 3;\n');
+      expect(evidence.changedFileNames(false)).toBe(''); // 实例已 memo，取同一快照
+      expect(createGitEvidence(dir).changedFileNames(false)).toBe('src/existing.ts');
+    });
+
+    it('headDirs 覆盖已提交目录，未提交目录不在集合内', () => {
+      const dir = makeRepo();
+      const dirs = createGitEvidence(dir).headDirs();
+
+      expect(dirs).not.toBeNull();
+      expect(dirs!.has('src')).toBe(true);
+      expect(dirs!.has('src/nested')).toBe(true);
+      fs.mkdirSync(path.join(dir, 'src', 'brand-new'), { recursive: true });
+      expect(createGitEvidence(dir).headDirs()!.has('src/brand-new')).toBe(false);
+    });
+
+    it('非 git 目录：diff 类证据为空串，headDirs 为 null（不重试、不抛错）', () => {
+      const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-git-evidence-'));
+      const { runner, commands } = countingRunner();
+      const evidence = createGitEvidence(dir, runner);
+
+      expect(evidence.stagedDiff()).toBe('');
+      expect(evidence.changedFileNames(true)).toBe('');
+      expect(evidence.headDirs()).toBeNull();
+      // 失败结果同样 memo：重复调用不再 spawn
+      expect(evidence.headDirs()).toBeNull();
+      expect(evidence.changedFileNames(true)).toBe('');
+      expect(commands.length).toBe(3);
+    });
+  });
+
+  describe('parseHeadDirs', () => {
+    it('逐层展开文件路径的父目录', () => {
+      const dirs = parseHeadDirs('src/a/b.ts\nREADME.md\n');
+      expect([...dirs].sort()).toEqual(['src', 'src/a']);
+    });
+  });
+
+  describe('memo 落在实例层', () => {
+    it('同一实例内同类 git 命令至多执行一次', () => {
+      const dir = makeRepo();
+      const { runner, commands } = countingRunner();
+      const evidence = createGitEvidence(dir, runner);
+
+      const first = evidence.stagedDiff();
+      const stagedNames = evidence.changedFileNames(true);
+      const unstagedNames = evidence.changedFileNames(false);
+      const dirs = evidence.headDirs();
+
+      expect(evidence.stagedDiff()).toBe(first);
+      expect(evidence.changedFileNames(true)).toBe(stagedNames);
+      expect(evidence.changedFileNames(false)).toBe(unstagedNames);
+      expect(evidence.headDirs()).toEqual(dirs);
+
+      expect(commands).toEqual([
+        'git diff --cached',
+        'git diff --cached --name-only',
+        'git diff --name-only',
+        'git ls-tree -r --name-only HEAD',
+      ]);
+      expect(new Set(commands).size).toBe(commands.length);
+    });
+
+    it('两个实例 = 两次取证（memo 不是隐式全局）', () => {
+      const dir = makeRepo();
+      const { runner, commands } = countingRunner();
+
+      createGitEvidence(dir, runner).stagedDiff();
+      createGitEvidence(dir, runner).stagedDiff();
+
+      expect(commands.filter(c => c === 'git diff --cached')).toHaveLength(2);
+    });
+  });
+
+  describe('context-builder 与 checker 共用同一证据来源（#87 验收）', () => {
+    it('一次 check run 内同类 git 命令至多执行一次', async () => {
+      const dir = makeRepo();
+      fs.writeFileSync(
+        path.join(dir, 'CAPABILITIES.md'),
+        '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| existing | src/existing.ts | 条目 |\n'
+      );
+      const { runner, commands } = countingRunner();
+      const shared = createGitEvidence(dir, runner);
+      // 记录器：哪个消费者（phase）调了哪个证据方法
+      const phase = { current: 'context' };
+      const calls: string[] = [];
+      const evidence = recordingEvidence(shared, () => phase.current, calls);
+
+      const context = await buildConstraintContext({ projectPath: dir, staged: true, evidence });
+      // capability_sync 经 CheckEnv.stagedDiffNames() 取同一份 git 证据
+      const merged: MergedConstraintsConfig = {
+        ironLaws: {},
+        guidelines: { capability_sync: GUIDELINES['capability_sync'] },
+        prompts: {},
+        custom: [],
+        disabled: [],
+        unknownIds: [],
+      };
+      const checker = new ConstraintChecker({ record: () => undefined });
+      phase.current = 'checker';
+      const runResult = await checker.checkConstraints(context, merged, evidence);
+
+      // capability_sync 确实被评估（非 skip）→ 它经 env.stagedDiffNames() 取过证据
+      expect(runResult.guidelines.map(r => r.id)).toEqual(['capability_sync']);
+      expect(runResult.guidelines[0].skipped).toBeUndefined();
+      // 两个消费者都从注入的这一份实例取证据（checker 没有另起炉灶）
+      expect(calls).toContain('context:changedFileNames');
+      expect(calls).toContain('checker:changedFileNames');
+      // 两侧各自需要同一份 staged 名单，合计只 spawn 一次
+      expect(commands).toEqual([
+        'git diff --cached --name-only',
+        'git ls-tree -r --name-only HEAD',
+      ]);
+    });
+  });
+});

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

@@ -11,7 +11,6 @@
  */
 
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
 import { detectInjectionDrift, INJECTION_DRIFT_FIX_HINT } from '../injection-drift';
 import {
@@ -19,12 +18,11 @@ import {
   CONSTRAINTS_START_MARKER,
 } from '../injection-renderer';
 import { getEffectiveConstraints } from '../../effective-constraints';
+import { createProjectFixture, writeProjectConfig } from '../../../test-setup/project-fixture';
 
 const TEST_VERSION = '9.9.9-test';
 
-function makeTmpProject(): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'harness-drift-test-'));
-}
+const makeTmpProject = (): string => createProjectFixture({ name: 'harness-drift-test' });
 
 /** 写入与当前生效集完全一致的注入段（版本 TEST_VERSION） */
 function writeSyncedClaudeMd(root: string, extra = ''): string {
@@ -102,12 +100,7 @@ describe('detectInjectionDrift', () => {
     const root = makeTmpProject();
     writeSyncedClaudeMd(root);
     // 注入后禁用一条 prompt，但不重跑 init
-    fs.mkdirSync(path.join(root, '.harness'), { recursive: true });
-    fs.writeFileSync(
-      path.join(root, '.harness', 'config.yml'),
-      'constraints:\n  no_fuzzy_completion_claim:\n    enabled: false\n',
-      'utf-8'
-    );
+    writeProjectConfig(root, 'constraints:\n  no_fuzzy_completion_claim:\n    enabled: false\n');
 
     const drift = detectInjectionDrift(root, TEST_VERSION);