@dommaker/harness 1.7.0 → 1.8.0

package/src/cli/commands/__tests__/context-syncer.test.ts

@@ -0,0 +1,141 @@
+/**
+ * sync-docs 的 CONTEXT.md 落点测试（harness#150）
+ *
+ * #132 把 init/validate 的脚手架三态收进 scaffold 模块，但 sync-docs 的
+ * `createContextMd` 是票口径外的第 9 处同形写手：自带一份 CONTEXT.md 模板正文，
+ * 与正本 `renderContextDoc` 已漂移。本票把它改消费正本（contextDocFile + runPlan）。
+ *
+ * 这里零真实文件系统（注入内存 fs 替身，手法照 scaffold.test.ts）钉三件事：
+ * 1. 对撞：同一目录经 init（contextDocFile）与 sync-docs（createContextMd）生成的
+ *    CONTEXT.md 骨架逐字相同（两条路径归一到单一正本）。
+ * 2. 正本文案：并入副本独有的两行引导、四节占位取 HTML 注释形。
+ * 3. 只在缺失时写：present → exists 分支不覆盖，正常 contextMissing 只走 created。
+ */
+
+import * as path from 'path';
+import chalk from 'chalk';
+import { captureIO, type CapturingIO } from '../../command-contract';
+import { contextDocFile, type ScaffoldFileSystem } from '../scaffold';
+import { createContextMd } from '../sync-docs/context-syncer';
+
+jest.mock('chalk', () => ({
+  blue: jest.fn((s: string) => s),
+  yellow: jest.fn((s: string) => s),
+  green: jest.fn((s: string) => s),
+  gray: jest.fn((s: string) => s),
+  red: jest.fn((s: string) => s),
+  cyan: jest.fn((s: string) => s),
+  bold: jest.fn((s: string) => s),
+}));
+
+/** 内存 fs 替身：写盘内容、建过的目录可断言 */
+class MemoryFs implements ScaffoldFileSystem {
+  readonly files = new Map<string, string>();
+  readonly dirs: string[] = [];
+
+  seed(target: string, content: string): void {
+    this.files.set(target, content);
+  }
+  async exists(target: string): Promise<boolean> {
+    return this.files.has(target);
+  }
+  async mkdir(dir: string): Promise<void> {
+    this.dirs.push(dir);
+  }
+  async writeFile(target: string, content: string): Promise<void> {
+    this.files.set(target, content);
+  }
+  async chmod(): Promise<void> {
+    /* CONTEXT.md 无权限位 */
+  }
+}
+
+const PROJECT = '/srv/project';
+const USER_CONTENT = '# src\n\n我自己写的，不许覆盖\n';
+
+/**
+ * CONTEXT.md 骨架正文的冻结字面量（harness#158）：正本 `renderContextDoc('src')` 被改必红。
+ * 上面的对撞闸只证明「init 与 sync-docs 同源」——两侧一起漂它看不见（复审 M3：给正本
+ * 加一行 → 60/60 全绿）。骨架正文整体由此处逐字钉住，改骨架必须显式改这份字面量。
+ */
+const CONTEXT_MD_SKELETON = `# src
+
+> 此文件描述 src 目录的职责和上下文
+> 请阅读本目录的源代码，然后填写以下各节。
+> 如果使用 AI 编码助手，将本文件内容作为 prompt 请求它分析并填写。
+
+## 职责
+
+<!-- 本目录的核心职责是什么 -->
+
+## 核心导出
+
+<!-- 本目录对外暴露的主要模块/函数 -->
+
+## 依赖关系
+
+<!-- 本目录依赖哪些其他模块，谁依赖本目录 -->
+
+## 注意事项
+
+<!-- 开发时需要注意的约束或约定 -->
+`;
+
+let fs: MemoryFs;
+let io: CapturingIO;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  fs = new MemoryFs();
+  io = captureIO();
+});
+
+describe('createContextMd 消费 scaffold 正本（harness#150）', () => {
+  it('对撞：sync-docs 落点与 init 站点生成的骨架逐字相同', async () => {
+    await expect(createContextMd(PROJECT, 'src', io, fs)).resolves.toBe('created');
+    const written = fs.files.get(path.join(PROJECT, 'src', 'CONTEXT.md'));
+
+    // init 侧经由同一个 contextDocFile 工厂落盘（见 init.ts 的 contextDocPlan）——
+    // 两侧共用单一正本，任何一份偷偷漂移都会在这里撞红
+    expect(written).toBe(contextDocFile(PROJECT, 'src').content);
+  });
+
+  it('骨架正文逐字冻结：正本 renderContextDoc 被改必红（#158，M3 假闸补钉）', () => {
+    expect(contextDocFile(PROJECT, 'src').content).toBe(CONTEXT_MD_SKELETON);
+  });
+
+  it('正本文案钉住：并入的两行引导 + 注释形占位（散文式提问已消失）', async () => {
+    const content = contextDocFile(PROJECT, 'src').content;
+
+    expect(content).toContain('> 请阅读本目录的源代码，然后填写以下各节。');
+    expect(content).toContain(
+      '> 如果使用 AI 编码助手，将本文件内容作为 prompt 请求它分析并填写。',
+    );
+    expect(content).toContain('<!-- 本目录的核心职责是什么 -->');
+    expect(content).not.toContain('本目录的核心职责是？');
+  });
+
+  it('缺失才写：present → exists 分支，用户内容一字节不动', async () => {
+    const target = path.join(PROJECT, 'src', 'CONTEXT.md');
+    fs.seed(target, USER_CONTENT);
+
+    await expect(createContextMd(PROJECT, 'src', io, fs)).resolves.toBe('exists');
+
+    expect(fs.files.get(target)).toBe(USER_CONTENT);
+    expect(fs.dirs).toEqual([]);
+    expect(printed(io)).toEqual(['src/CONTEXT.md 已存在']);
+    expect(chalk.gray).toHaveBeenCalledWith('src/CONTEXT.md 已存在');
+  });
+
+  it('created 态：绿字文案由 runPlan 打印，与 init 落盘态同源', async () => {
+    await createContextMd(PROJECT, 'src', io, fs);
+
+    expect(printed(io)).toEqual(['✅ 已创建 src/CONTEXT.md']);
+    expect(chalk.green).toHaveBeenCalledWith('✅ 已创建 src/CONTEXT.md');
+  });
+});
+
+/** stdout 每次写入的文本（去掉 log 补的换行） */
+function printed(capture: CapturingIO): string[] {
+  return capture.outRecords().map(chunk => chunk.replace(/\n$/, ''));
+}

package/src/cli/commands/__tests__/contract.test.ts

@@ -4,6 +4,7 @@
 
 import { contract, validateSchema } from '../contract';
 import { captureIO, type CapturingIO } from '../../command-contract';
+import { decide, fakeGate, throwingGate } from './gate-decision';
 import * as fs from 'fs/promises';
 import { ContractGate } from '../../../gates/contract';
 
@@ -14,7 +15,7 @@ jest.mock('fs/promises', () => ({
 
 jest.mock('../../../gates/contract', () => ({
   ContractGate: jest.fn().mockImplementation(() => ({
-    check: jest.fn(),
+    evaluate: jest.fn(),
   })),
 }));
 
@@ -46,16 +47,15 @@ describe('contract command', () => {
   describe('contract', () => {
     it('should print success when check passes', async () => {
       mockFs.access.mockResolvedValue(undefined);
-      const mockCheck = jest.fn().mockResolvedValue({
-        passed: true,
-        message: 'ok',
-        details: { endpoints: 10, breakingChanges: false },
-      });
-      MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
+      MockGate.mockImplementation(() =>
+        fakeGate(decide('contract', true, 'ok', { endpoints: 10, breakingChanges: false })) as any
+      );
 
       const result = await contract({}, io);
 
       expect(io.outText()).toContain('契约门控检查通过');
+      expect(io.outText()).toContain('   端点数: 10');
+      expect(io.outText()).toContain('   破坏性变更: 无');
       expect(result.kind).toBe('ok');
     });
 
@@ -70,31 +70,31 @@ describe('contract command', () => {
 
     it('should print failure and exit 1 when check fails', async () => {
       mockFs.access.mockResolvedValue(undefined);
-      const mockCheck = jest.fn().mockResolvedValue({
-        passed: false,
-        message: 'validation errors',
-        details: {
-          errors: ['missing field X', 'invalid type Y'],
-          breakingChanges: [{ type: 'removed', path: '/api/v1/users' }],
-        },
-      });
-      MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
+      MockGate.mockImplementation(() =>
+        fakeGate(
+          decide('contract', false, 'validation errors', {
+            errors: ['missing field X', 'invalid type Y'],
+            breakingChanges: [{ type: 'removed', path: '/api/v1/users' }],
+          })
+        ) as any
+      );
 
       const result = await contract({}, io);
 
       expect(io.outText()).toContain('契约门控检查失败');
-      expect(result.kind).toBe('fail');
+      expect(io.outText()).toContain('  - missing field X');
+      expect(io.outText()).toContain('  - removed: /api/v1/users');
+      expect(result).toEqual({ kind: 'fail', reason: 'contract gate denied: validation errors' });
     });
 
     it('should handle thrown errors and exit 1', async () => {
       mockFs.access.mockResolvedValue(undefined);
-      const mockCheck = jest.fn().mockRejectedValue(new Error('gate error'));
-      MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
+      MockGate.mockImplementation(() => throwingGate(new Error('gate error')) as any);
 
       const result = await contract({}, io);
 
       expect(io.outText()).toContain('契约门控检查出错');
-      expect(result.kind).toBe('fail');
+      expect(result).toEqual({ kind: 'fail', reason: 'contract gate error: gate error' });
     });
   });
 

package/src/cli/commands/__tests__/failure.test.ts

@@ -5,9 +5,10 @@
 import * as fs from 'fs';
 import { captureIO, type CapturingIO } from '../../command-contract';
 import * as path from 'path';
+import * as os from 'os';
 import { FailureRecorder } from '../../../failure/recorder';
-import { ErrorType, FailureLevel } from '../../../failure/types';
-import type { FailureRecord } from '../../../failure/types';
+import { ErrorType, FailureLevel } from '../../../types/failure';
+import type { FailureRecord } from '../../../types/failure';
 
 // Mock FailureRecorder
 jest.mock('../../../failure/recorder');
@@ -18,7 +19,7 @@ beforeEach(() => {
 });
 
 describe('failure CLI commands', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-failure-cli');
+  let tempDir: string;
   let mockRecorderInstance: {
     record: jest.Mock;
     getHistory: jest.Mock;
@@ -39,7 +40,7 @@ describe('failure CLI commands', () => {
   };
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-failure-cli-'));
   });
 
   afterAll(() => {

package/src/cli/commands/__tests__/gate-decision.ts

@@ -0,0 +1,30 @@
+/**
+ * 门禁命令测试的决策替身
+ *
+ * 命令的唯一入口是 `evaluate()`，所以替身是「产一枚决策的假门禁」——
+ * 映射与报告构造器用真实现（decisionFromResult / gateResult），
+ * 六个命令的测试因此不需要 git、gh 或真扫描。
+ */
+
+import { decisionFromResult } from '../../../gates/decision';
+import { gateResult } from '../../../gates/types';
+import type { GateDecision } from '../../../gates/types';
+
+export function decide(
+  gateId: string,
+  passed: boolean,
+  message: string,
+  details?: Record<string, any>
+): GateDecision {
+  return decisionFromResult(gateResult(gateId, passed, message, Date.now(), details));
+}
+
+/** 恒产同一枚决策的假门禁（evaluate 记录调用参数，供断言上下文） */
+export function fakeGate(decision: GateDecision): { evaluate: jest.Mock } {
+  return { evaluate: jest.fn().mockResolvedValue(decision) };
+}
+
+/** evaluate 直接抛出的假门禁：命令出错分支测的是门禁之外的失败（git / fs） */
+export function throwingGate(error: unknown): { evaluate: jest.Mock } {
+  return { evaluate: jest.fn().mockRejectedValue(error) };
+}

package/src/cli/commands/__tests__/init-dead-options.test.ts

@@ -0,0 +1,50 @@
+/**
+ * init 死选项 `-t/--type` 已删除（harness#132 grilling 落定）
+ *
+ * `-t, --type <type>` 自始只有定义表一条与 `InitOptions.type` 一个字段，全仓无读取方——
+ * `harness init -t nextjs-app` 恒不生效。scaffold 收口时按 ADR-0018 判据（只执法有真实现的
+ * 维度）连旗帜与字段一并删除。手法同 passes-gate-dead-options.test.ts：编译期
+ * `@ts-expect-error` 钉字段不存在 + 运行期钉定义表旗帜面。
+ */
+
+import { COMMAND_DEFINITIONS } from '../definitions';
+import type { InitOptions } from '../init';
+
+const initCommand = COMMAND_DEFINITIONS.find(d => d.command === 'init');
+
+describe('init 的 -t/--type 已删除（#132）', () => {
+  it('定义表已注册 init（前提）', () => {
+    expect(initCommand).toBeDefined();
+  });
+
+  it('init 旗帜面逐字冻结，不含 --type', () => {
+    expect((initCommand?.options || []).map(o => o.flags)).toEqual([
+      '-p, --preset <preset>',
+      '-g, --governance <level>',
+      '--project-path <path>',
+      '--no-git-hooks',
+      '--ci <platform>',
+      '--no-github-actions',
+      '--print-snippets',
+    ]);
+  });
+
+  it('InitOptions 的 type 字段已从类型面消失（编译期钉）', () => {
+    // @ts-expect-error -t/--type 无实现，随 #132 从 InitOptions 删除
+    const removed: InitOptions = { preset: 'standard', type: 'nextjs-app' };
+    expect(removed).toBeDefined();
+  });
+
+  it('活旗帜仍可赋值（防止删多）', () => {
+    const live: InitOptions = {
+      preset: 'strict',
+      governance: 'minimal',
+      projectPath: '/tmp/p',
+      gitHooks: false,
+      githubActions: false,
+      ci: 'gitlab',
+      printSnippets: true,
+    };
+    expect(Object.keys(live)).toHaveLength(7);
+  });
+});

package/src/cli/commands/__tests__/init-governance-io.test.ts

@@ -0,0 +1,139 @@
+/**
+ * 治理链路的 io 注入不逃逸（harness#149）
+ *
+ * setupGovernance 手握 io，却在两个调用点把它丢了（`setupClaudeMdOutputStyle(projectPath)`
+ * / `setupGovernanceConstraints(projectPath)`），被调方一律 `io: CommandIO = processIO`
+ * 兜成真实 stdout。真机输出正常，但注入面的测试看不见那 14 条提示——`⚠️ …标记残缺…`
+ * 这类唯一提示写坏了没有测试会红。
+ *
+ * 本文件不 mock 任何 IO：在临时目录里真跑 init，断言治理段提示落在**注入面**。
+ * 改造前这些断言逐条为红（文本逃到了 process.stdout）。
+ */
+
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { init, type InitOptions } from '../init';
+import { captureIO, type CapturingIO } from '../../command-contract';
+
+jest.mock('chalk', () => ({
+  blue: jest.fn((s: string) => s),
+  yellow: jest.fn((s: string) => s),
+  green: jest.fn((s: string) => s),
+  gray: jest.fn((s: string) => s),
+  red: jest.fn((s: string) => s),
+  cyan: jest.fn((s: string) => s),
+  bold: jest.fn((s: string) => s),
+}));
+
+const INIT_SOURCE = fsSync.readFileSync(path.join(__dirname, '..', 'init.ts'), 'utf-8');
+
+const INIT_OPTIONS: Partial<InitOptions> = { preset: 'standard', governance: 'standard' };
+
+/** 真临时工程根：带 .git 与 src/，让 init 走完治理链路而不必先落别的文件 */
+async function makeProject(files: Record<string, string> = {}): Promise<string> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'harness-governance-io-'));
+  await fs.mkdir(path.join(root, 'src'));
+  await fs.writeFile(path.join(root, 'src', 'index.ts'), 'export const x = 1;\n');
+  await fs.mkdir(path.join(root, '.git'));
+  for (const [rel, content] of Object.entries(files)) {
+    await fs.writeFile(path.join(root, rel), content, 'utf-8');
+  }
+  return root;
+}
+
+async function runInit(files: Record<string, string>): Promise<CapturingIO> {
+  const root = await makeProject(files);
+  roots.push(root);
+  const io = captureIO();
+  expect(await init({ ...INIT_OPTIONS, projectPath: root } as InitOptions, io)).toEqual({ kind: 'ok' });
+  return io;
+}
+
+const roots: string[] = [];
+
+afterAll(async () => {
+  await Promise.all(roots.map(root => fs.rm(root, { recursive: true, force: true })));
+});
+
+describe('init 治理链路的提示落在注入面（harness#149）', () => {
+  it('Output Style 段（setupClaudeMdOutputStyle 调用点曾丢 io）：写入提示进捕获 stdout', async () => {
+    const io = await runInit({ 'CLAUDE.md': '# CLAUDE.md\n\n项目说明\n' });
+    expect(io.outText()).toContain('✅ 已在 CLAUDE.md 顶部写入 Output Style 段');
+  });
+
+  it('治理契约追加到既有 AGENTS.md：`已追加治理契约` 进捕获 stdout', async () => {
+    const io = await runInit({ 'AGENTS.md': '# AGENTS.md\n\n既有导读\n' });
+    expect(io.outText()).toContain('✅ 已追加治理契约 PRESERVE:governance 段到 AGENTS.md');
+  });
+
+  it('标记残缺（唯一提示）：`标记残缺…请人工修复` 进捕获 stdout', async () => {
+    const io = await runInit({ 'AGENTS.md': '# AGENTS.md\n\n<!-- PRESERVE:governance -->\n残缺段\n' });
+    expect(io.outText()).toContain('⚠️  AGENTS.md 中 PRESERVE:governance 标记残缺（只有单边），跳过治理契约写入，请人工修复');
+  });
+
+  // #158 补钉：这类提示在 init.ts 实测有四处，#149 只钉住上面一条——其余三处各补一条
+  // 捕获面断言。四处分支不同文件/不同段位，fixture 各自单建，不共用残缺文件。
+
+  it('标记残缺四处之二：CLAUDE.md 的 HARNESS_OUTPUT_STYLE 单边 → Output Style 注入告警', async () => {
+    const io = await runInit({ 'CLAUDE.md': '# CLAUDE.md\n\n<!-- HARNESS_OUTPUT_STYLE_START -->\n半残段\n' });
+    expect(io.outText()).toContain('⚠️  CLAUDE.md 中 HARNESS_OUTPUT_STYLE 标记残缺（单边或乱序），跳过 Output Style 注入，请人工修复');
+  });
+
+  it('标记残缺四处之三：AGENTS.md 的 PRESERVE 段内 HARNESS_CONSTRAINTS 单边 → 段内告警', async () => {
+    const broken = [
+      '# AGENTS.md',
+      '',
+      '<!-- PRESERVE:governance -->',
+      '手写契约',
+      '',
+      '<!-- HARNESS_CONSTRAINTS_START -->',
+      '半残注入',
+      '<!-- /PRESERVE:governance -->',
+      '',
+    ].join('\n');
+    const io = await runInit({ 'AGENTS.md': broken });
+    expect(io.outText()).toContain('⚠️  AGENTS.md PRESERVE:governance 段内 HARNESS_CONSTRAINTS 标记残缺（单边或乱序），跳过治理契约写入，请人工修复');
+  });
+
+  it('标记残缺四处之四：CLAUDE.md 的 HARNESS_CONSTRAINTS 单边 → 治理约束注入告警（旧模型仓落点）', async () => {
+    const io = await runInit({ 'CLAUDE.md': '# CLAUDE.md\n\n<!-- HARNESS_CONSTRAINTS_START -->\n半残段\n' });
+    expect(io.outText()).toContain('⚠️  CLAUDE.md 中 HARNESS_CONSTRAINTS 标记残缺（单边或乱序），跳过治理约束注入，请人工修复');
+  });
+
+  it('新仓创建 AGENTS.md 治理段：创建提示进捕获 stdout', async () => {
+    const io = await runInit({});
+    expect(io.outText()).toContain('✅ 已创建 AGENTS.md 并写入治理契约 PRESERVE:governance 段');
+  });
+});
+
+describe('writer 层 io 必传（源形状闸，防缺省兜底再回来）', () => {
+  it('init.ts 里 `io: CommandIO = processIO` 只剩 init() 一处（对外入口保留缺省）', () => {
+    const sites = INIT_SOURCE.split('\n').filter(line => line.includes('io: CommandIO = processIO'));
+    expect(sites).toHaveLength(1);
+    expect(sites[0]).toMatch(/^export async function init\(/);
+  });
+
+  it('三个 writer 与落点路由的 io 均为必传形参', () => {
+    for (const writer of [
+      'setupClaudeMdOutputStyle',
+      'setupAgentsMdConstraints',
+      'setupClaudeMdConstraints',
+      'setupGovernanceConstraints',
+    ]) {
+      expect(INIT_SOURCE).toMatch(
+        new RegExp(`export async function ${writer}\\(projectPath: string, io: CommandIO\\)`),
+      );
+    }
+  });
+
+  it('setupGovernance 的调用点逐个传 io（不留裸 projectPath 调用）', () => {
+    const governanceBody = INIT_SOURCE.slice(
+      INIT_SOURCE.indexOf('async function setupGovernance('),
+      INIT_SOURCE.indexOf('/**\n * 目录 CONTEXT.md 骨架的 plan'),
+    );
+    expect(governanceBody).toMatch(/await setupClaudeMdOutputStyle\(projectPath, io\)/);
+    expect(governanceBody).toMatch(/await setupGovernanceConstraints\(projectPath, io\)/);
+  });
+});

package/src/cli/commands/__tests__/init-injection.test.ts

@@ -422,7 +422,7 @@ describe('setupGovernanceConstraints（落点路由）', () => {
   });
 
   it('新仓（无 CLAUDE.md）：治理契约写向 AGENTS.md，不创建 CLAUDE.md', async () => {
-    await setupGovernanceConstraints(tempDir);
+    await setupGovernanceConstraints(tempDir, io);
 
     expect(fs.existsSync(path.join(tempDir, 'AGENTS.md'))).toBe(true);
     expect(fs.existsSync(path.join(tempDir, 'CLAUDE.md'))).toBe(false);
@@ -444,7 +444,7 @@ describe('setupGovernanceConstraints（落点路由）', () => {
     ].join('\n'));
     fs.writeFileSync(path.join(tempDir, 'AGENTS.md'), '# AGENTS.md\n\n既有导读\n');
 
-    await setupGovernanceConstraints(tempDir);
+    await setupGovernanceConstraints(tempDir, io);
 
     const claude = fs.readFileSync(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
     expect(claude).not.toContain('旧约束');
@@ -456,7 +456,7 @@ describe('setupGovernanceConstraints（落点路由）', () => {
   it('旧模型仓（CLAUDE.md 有无标记 Governance Rules 块）：路由到 CLAUDE.md', async () => {
     fs.writeFileSync(path.join(tempDir, 'CLAUDE.md'), '# CLAUDE.md\n\n## Governance Rules\n\n手写条款\n');
 
-    await setupGovernanceConstraints(tempDir);
+    await setupGovernanceConstraints(tempDir, io);
 
     const claude = fs.readFileSync(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
     expect(claude).toContain('手写条款');