@dommaker/harness 1.7.0 → 1.8.0

package/src/cli/commands/__tests__/sync-docs-context-drift.test.ts

@@ -0,0 +1,232 @@
+/**
+ * sync-docs 的 CONTEXT.md 内容漂移判定接线测试（harness#142）
+ *
+ * 钉四件事：
+ * 1. 内容漂移（幽灵 / barrel 未登记）在 `--check` 下判 fail，reason 点名文件与符号；
+ * 2. mtime 漂移降级为本地提示——不再影响退出码，且 CI 环境下连提示都抑制；
+ * 3. `--json` 有 contentDrift 结构（供 LLM/CI 消费）；
+ * 4. 写入模式不改写 CONTEXT.md（散文不可机械生成），退出码面不变。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { captureIO, type CapturingIO, type CommandResult } from '../../command-contract';
+import { syncDocs } from '../sync-docs';
+
+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),
+}));
+
+/** 取 fail 的 reason（判别联合窄化只在测试里做一次） */
+function failReason(result: CommandResult): string {
+  if (result.kind !== 'fail' && result.kind !== 'usage-error') {
+    throw new Error(`期望 fail，实得 ${result.kind}`);
+  }
+  return result.reason;
+}
+
+let tempDir: string;
+const CI = process.env.CI;
+
+let io: CapturingIO;
+
+/** 建一个「CAPABILITIES 已覆盖 src/」的最小项目，把漂移轴隔离到 CONTEXT.md */
+function makeProject(name: string, contextMd: string, indexTs: string): string {
+  const projectPath = path.join(tempDir, name);
+  const modDir = path.join(projectPath, 'src', 'mod');
+  fs.mkdirSync(modDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(projectPath, 'CAPABILITIES.md'),
+    '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| all | src/ | 全量记录 |\n'
+  );
+  fs.writeFileSync(path.join(modDir, 'CONTEXT.md'), contextMd);
+  fs.writeFileSync(path.join(modDir, 'index.ts'), indexTs);
+  fs.writeFileSync(
+    path.join(modDir, 'impl.ts'),
+    'export class Widget {}\nexport function createWidget() {}\nexport const WIDGET_KIND = "a";\n'
+  );
+  return projectPath;
+}
+
+const CLEAN_DOC = [
+  '# mod/',
+  '',
+  '## 核心导出',
+  '- `Widget` — 主体',
+  '- `createWidget` — 工厂',
+  '- `WIDGET_KIND` — 常量',
+  '',
+  '## 约定',
+  '- 无',
+  '',
+].join('\n');
+
+const BARREL = [
+  "export { Widget, createWidget, WIDGET_KIND } from './impl';",
+  "export type { WidgetConfig } from './impl';",
+].join('\n');
+
+beforeEach(() => {
+  io = captureIO();
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-sync-docs-drift-'));
+  delete process.env.CI;
+});
+
+afterEach(() => {
+  fs.rmSync(tempDir, { recursive: true, force: true });
+  if (CI === undefined) delete process.env.CI;
+  else process.env.CI = CI;
+});
+
+describe('sync-docs — CONTEXT.md 内容漂移判 fail（--check）', () => {
+  it('文档与导出面一致 → ok（新闸不制造存量噪音）', async () => {
+    const projectPath = makeProject('clean', CLEAN_DOC, BARREL);
+    await expect(syncDocs({ projectPath, check: true }, io)).resolves.toEqual({ kind: 'ok' });
+  });
+
+  it('幽灵符号（代码改名不回灌文档）→ fail 并指名文件与符号', async () => {
+    const projectPath = makeProject(
+      'ghost',
+      CLEAN_DOC.replace('`Widget`', '`WidgetRenamed`'),
+      BARREL
+    );
+
+    const result = await syncDocs({ projectPath, check: true }, io);
+
+    expect(failReason(result)).toContain('src/mod/CONTEXT.md');
+    expect(failReason(result)).toContain('WidgetRenamed');
+    expect(io.outText()).toContain('WidgetRenamed');
+  });
+
+  it('barrel 未跟着改名的虚再导出不洗白幽灵（正本改名即撞）', async () => {
+    const projectPath = makeProject('ghost-barrel', CLEAN_DOC, BARREL);
+    // 只改声明侧（Widget → WidgetSink），index.ts 的再导出与文档都不动
+    fs.writeFileSync(
+      path.join(projectPath, 'src', 'mod', 'impl.ts'),
+      'export class WidgetSink {}\nexport function createWidget() {}\nexport const WIDGET_KIND = "a";\n'
+    );
+
+    const result = await syncDocs({ projectPath, check: true }, io);
+
+    expect(failReason(result)).toContain('src/mod/CONTEXT.md');
+    expect(failReason(result)).toContain('Widget');
+  });
+
+  it('barrel 新增值符号未登记 → fail 并指名该符号', async () => {
+    const projectPath = makeProject(
+      'unlisted',
+      CLEAN_DOC.replace('- `WIDGET_KIND` — 常量\n', ''),
+      BARREL
+    );
+
+    const result = await syncDocs({ projectPath, check: true }, io);
+
+    expect(failReason(result)).toContain('src/mod/CONTEXT.md');
+    expect(failReason(result)).toContain('WIDGET_KIND');
+  });
+
+  it('barrel 新增类型符号 → 不要求登记（类型面豁免）', async () => {
+    const projectPath = makeProject(
+      'type-only',
+      CLEAN_DOC,
+      [BARREL, "export { type ExtraShape } from './impl';"].join('\n')
+    );
+
+    await expect(syncDocs({ projectPath, check: true }, io)).resolves.toEqual({ kind: 'ok' });
+  });
+
+  it('无 index.ts 的目录跳过覆盖方向（内部导出不要求登记）', async () => {
+    const projectPath = makeProject('no-barrel', CLEAN_DOC, BARREL);
+    fs.rmSync(path.join(projectPath, 'src', 'mod', 'index.ts'));
+
+    await expect(syncDocs({ projectPath, check: true }, io)).resolves.toEqual({ kind: 'ok' });
+  });
+});
+
+describe('sync-docs — mtime 判定降级为提示', () => {
+  /** 只把源码时间戳推到 CONTEXT.md 之后，内容一字不改 */
+  function touchSourceLater(projectPath: string): void {
+    const contextPath = path.join(projectPath, 'src', 'mod', 'CONTEXT.md');
+    const contextMtime = new Date(Date.now() - 60_000);
+    fs.utimesSync(contextPath, contextMtime, contextMtime);
+    const impl = path.join(projectPath, 'src', 'mod', 'impl.ts');
+    const later = new Date();
+    fs.utimesSync(impl, later, later);
+  }
+
+  it('mtime 漂移不再判 fail，只在本地给提示', async () => {
+    const projectPath = makeProject('mtime', CLEAN_DOC, BARREL);
+    touchSourceLater(projectPath);
+
+    await expect(syncDocs({ projectPath, check: true }, io)).resolves.toEqual({ kind: 'ok' });
+    expect(io.outText()).toContain('源码比文档新');
+  });
+
+  it('CI 环境下 mtime 提示抑制（全新 checkout 的 mtime 无意义）', async () => {
+    const projectPath = makeProject('mtime-ci', CLEAN_DOC, BARREL);
+    touchSourceLater(projectPath);
+    process.env.CI = 'true';
+
+    await expect(syncDocs({ projectPath, check: true }, io)).resolves.toEqual({ kind: 'ok' });
+    expect(io.outText()).not.toContain('源码比文档新');
+  });
+
+  it('内容漂移在 CI 环境下照样 fail', async () => {
+    const projectPath = makeProject('content-ci', CLEAN_DOC.replace('`Widget`', '`Gone`'), BARREL);
+    process.env.CI = 'true';
+
+    const result = await syncDocs({ projectPath, check: true }, io);
+    expect(failReason(result)).toContain('Gone');
+  });
+});
+
+describe('sync-docs — --json 与写入模式', () => {
+  it('--json 输出 contentDrift（dir/file/ghosts/unlisted）', async () => {
+    const projectPath = makeProject(
+      'json',
+      CLEAN_DOC.replace('- `WIDGET_KIND` — 常量\n', '').replace('`Widget`', '`Ghost`'),
+      BARREL
+    );
+
+    await syncDocs({ projectPath, check: true, json: true }, io);
+
+    const payload = JSON.parse(io.outText());
+    expect(payload.stale).toBe(true);
+    expect(payload.summary.contextContentDrift).toBe(1);
+    expect(payload.contentDrift).toEqual([
+      {
+        dir: 'src/mod',
+        file: 'src/mod/CONTEXT.md',
+        ghosts: ['Ghost'],
+        unlisted: ['Widget', 'WIDGET_KIND'],
+      },
+    ]);
+  });
+
+  it('--json 干净时 contentDrift 为空数组', async () => {
+    const projectPath = makeProject('json-clean', CLEAN_DOC, BARREL);
+
+    await syncDocs({ projectPath, check: true, json: true }, io);
+
+    expect(JSON.parse(io.outText()).contentDrift).toEqual([]);
+  });
+
+  it('写入模式给提示但不改 CONTEXT.md、退出码面不变', async () => {
+    const projectPath = makeProject('write', CLEAN_DOC.replace('`Widget`', '`Ghost`'), BARREL);
+    const contextPath = path.join(projectPath, 'src', 'mod', 'CONTEXT.md');
+    const before = fs.readFileSync(contextPath, 'utf-8');
+
+    const result = await syncDocs({ projectPath }, io);
+
+    expect(result.kind).toBe('ok');
+    expect(io.outText()).toContain('Ghost');
+    expect(fs.readFileSync(contextPath, 'utf-8')).toBe(before);
+  });
+});

package/src/cli/commands/__tests__/sync-docs-module-order.test.ts

@@ -0,0 +1,111 @@
+/**
+ * sync-docs 生成的模块清单顺序冻结（#147 B 票）
+ *
+ * `sync-docs` 写出的 CAPABILITIES.md 模块表格行序 = 源码目录遍历序，这个顺序此前
+ * **无任何测试覆盖**，而它对外可见（`--check` 逐行比对、人工看 diff）。#147 把描述
+ * 提取从串行改并发，票面裁决「输出顺序逐字保持现状」，本文件就是那条裁决的闸。
+ *
+ * 不写死字面顺序：`readdir` 的返回顺序由文件系统决定（本仓 tmpfs 上是字典序、ext4 上
+ * 是哈希序），写死等于把断言建立在机器上。这里的口径是**目录遍历序**本身——用测试内
+ * 独立推导的遍历序（`readdirSync` + 同一份跳过口径）作对照，另加两次运行的自复现，
+ * 任何「按并发完成顺序 append」「改成字典序」「子目录结果挪到末尾」都会撞红。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { syncDocs } from '../sync-docs';
+import { scanSourceModules } from '../sync-docs/project-reader';
+import { captureIO } from '../../command-contract';
+import { DEFAULT_SKIP_DIRS, isTsSourceFile } from '../../../utils/file-walk';
+
+let tempDir: string;
+const io = captureIO();
+
+function write(rel: string, content: string): void {
+  const target = path.join(tempDir, rel);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content, 'utf-8');
+}
+
+/** 口径对照：目录遍历序 = readdir 序，子目录结果就地展开在父条目所在位置 */
+function traversalOrder(dir: string, root: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir)) {
+    if (DEFAULT_SKIP_DIRS.includes(entry)) continue;
+    const entryPath = path.join(dir, entry);
+    if (fs.statSync(entryPath).isDirectory()) {
+      out.push(...traversalOrder(entryPath, root));
+    } else if (isTsSourceFile(entry, { skipIndex: true, includeTsx: true })) {
+      out.push(path.relative(root, entryPath));
+    }
+  }
+  return out;
+}
+
+/** 生成后的 CAPABILITIES.md 表格行序（文件列） */
+function tableRows(capabilitiesPath: string): string[] {
+  return fs
+    .readFileSync(capabilitiesPath, 'utf-8')
+    .split('\n')
+    .filter((line) => /^\|[^|]+\|[^|]+\.tsx?\s*\|[^|]+\|\s*$/.test(line))
+    .map((line) => line.split('|')[2].trim());
+}
+
+beforeAll(() => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sd147-module-order-'));
+  // 一个子目录恰好排在两份顶层文件之间（顺序若被重排，这里最容易露馅）
+  write('src/alpha.ts', '// 描述-甲\nexport const a = 1;\n');
+  write('src/mid/beta.ts', '/**\n * 描述-乙\n */\nexport const b = 1;\n');
+  write('src/mid/gamma.ts', '// 描述-丙\nexport const c = 1;\n');
+  write('src/zeta.ts', '// 描述-丁\nexport const d = 1;\n');
+  // 同一条规则下的旁支：barrel 与 .d.ts 不进清单
+  write('src/index.ts', 'export * from "./alpha";\n');
+  write('src/ambient.d.ts', 'export const t = 1;\n');
+});
+
+afterAll(() => {
+  fs.rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('sync-docs 模块清单顺序冻结（#147）', () => {
+  it('扫描产出的清单顺序 = 目录遍历序，且描述与文件配对不串位', async () => {
+    const modules = await scanSourceModules(path.join(tempDir, 'src'), tempDir);
+    const expected = traversalOrder(path.join(tempDir, 'src'), tempDir);
+
+    expect(modules.map((m) => m.file)).toEqual(expected);
+    // 并发取数后每条描述仍是自己那份文件的（回填按原索引，不按完成先后）
+    expect(modules.map((m) => `${m.file}=${m.description}`).sort()).toEqual(
+      [
+        'src/alpha.ts=描述-甲',
+        'src/mid/beta.ts=描述-乙',
+        'src/mid/gamma.ts=描述-丙',
+        'src/zeta.ts=描述-丁',
+      ].sort()
+    );
+  });
+
+  it('写出的 CAPABILITIES.md 行序 = 同一次扫描的清单顺序（对外可见面被锁住）', async () => {
+    const capPath = path.join(tempDir, 'CAPABILITIES.md');
+    expect(fs.existsSync(capPath)).toBe(false);
+
+    await syncDocs({ projectPath: tempDir }, io);
+
+    expect(tableRows(capPath)).toEqual(traversalOrder(path.join(tempDir, 'src'), tempDir));
+  });
+
+  it('同一次生成的清单顺序两次运行逐字复现（并发不引入运行间抖动）', async () => {
+    const capPath = path.join(tempDir, 'CAPABILITIES.md');
+
+    fs.rmSync(capPath, { force: true });
+    await syncDocs({ projectPath: tempDir }, io);
+    const first = tableRows(capPath);
+    expect(first.length).toBe(4);
+
+    fs.rmSync(capPath, { force: true });
+    await syncDocs({ projectPath: tempDir }, io);
+
+    expect(tableRows(capPath)).toEqual(first);
+    fs.rmSync(capPath, { force: true });
+  });
+});

package/src/cli/commands/__tests__/sync-docs-read-count.test.ts

@@ -0,0 +1,192 @@
+/**
+ * sync-docs 的 .ts 内容读取计数闸（#147 B 票，母票 #140「verifier 自己找文件」之二）
+ *
+ * 形状照 `check-read-count.test.ts` / `spec-baseline-read-count.test.ts`：真执行、
+ * 只在中间记一笔，不改任何行为。数的是**底层文件内容读取发生了几次**。
+ *
+ * 本票的承诺面 = **capability-listing 格式下模块清单无人消费，一份 `.ts` 内容都不读**
+ * （改造前：入口无条件全树扫描，逐文件 `await readFile` 只为首行注释）。
+ * 反证用同一棵源码树换成 file-table 格式：描述照旧提取，每份文件一次运行内恰读一次。
+ *
+ * 夹具一律不放 CONTEXT.md：CONTEXT 侧的 `.ts` 读取属导出面采集（#142），不在本票范围，
+ * 放进来会把「扫描分支零内容读」这条闸洗成模糊口径。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { syncDocs } from '../sync-docs';
+import { captureIO, type CapturingIO } from '../../command-contract';
+
+type ReadCall = { file: string; via: 'readFile' | 'readFileSync' };
+
+// 计数器挂在 globalThis：jest.mock 工厂会被提前调用，闭包外提会撞 TDZ
+jest.mock('fs/promises', () => {
+  const actual = jest.requireActual<typeof import('fs/promises')>('fs/promises');
+  const g = globalThis as unknown as { __SD147_READS__?: ReadCall[] };
+  if (!g.__SD147_READS__) g.__SD147_READS__ = [];
+  const bucket = g.__SD147_READS__;
+  const name = (p: unknown): string => (Buffer.isBuffer(p) ? p.toString('utf8') : String(p));
+
+  return {
+    ...actual,
+    readFile: jest.fn((p: unknown, ...rest: unknown[]) => {
+      bucket.push({ file: name(p), via: 'readFile' });
+      return actual.readFile(p as fs.PathLike, ...(rest as [BufferEncoding])) as Promise<string>;
+    }),
+  };
+});
+
+jest.mock('fs', () => {
+  const actual = jest.requireActual<typeof import('fs')>('fs');
+  const g = globalThis as unknown as { __SD147_READS__?: ReadCall[] };
+  if (!g.__SD147_READS__) g.__SD147_READS__ = [];
+  const bucket = g.__SD147_READS__;
+  const name = (p: unknown): string => (Buffer.isBuffer(p) ? p.toString('utf8') : String(p));
+
+  return {
+    ...actual,
+    readFileSync: jest.fn((p: unknown, ...rest: unknown[]) => {
+      bucket.push({ file: name(p), via: 'readFileSync' });
+      return (actual.readFileSync as unknown as (path: unknown, options?: unknown) => unknown)(
+        p,
+        ...rest
+      );
+    }),
+  };
+});
+
+const reads = () =>
+  ((globalThis as unknown as { __SD147_READS__?: ReadCall[] }).__SD147_READS__ ||= []);
+
+const SOURCE_FILES = [
+  'src/alpha.ts',
+  'src/beta.tsx',
+  'src/nested/gamma.ts',
+  'src/nested/deep/delta.ts',
+];
+
+/** 清单格式与文件表格式共用的源码树（含三处必须被跳过口径排除的同名内容） */
+function fixtureProject(capabilities: 'listing' | 'table' | 'absent'): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sd147-read-count-'));
+  const write = (rel: string, content: string): void => {
+    const target = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf-8');
+  };
+
+  write('src/alpha.ts', '// alpha 的描述\nexport const a = 1;\n');
+  write('src/beta.tsx', 'export const b = 1;\n');
+  write('src/nested/gamma.ts', '/**\n * gamma 的描述\n */\nexport const c = 1;\n');
+  write('src/nested/deep/delta.ts', 'export const d = 1;\n');
+  // 跳过口径的三份对照：barrel、.d.ts、__tests__（外加 node_modules 与 dist）
+  write('src/index.ts', 'export * from "./alpha";\n');
+  write('src/ambient.d.ts', 'export const t = 1;\n');
+  write('src/__tests__/alpha.test.ts', '// 不该被读\nexport const x = 1;\n');
+  write('src/node_modules/pkg/index.ts', '// 不该被读\n');
+  write('src/dist/built.ts', '// 不该被读\n');
+
+  if (capabilities === 'listing') {
+    write(
+      'CAPABILITIES.md',
+      '# Harness Capabilities\n\n## CLI Commands (21)\ncheck, validate, sync-docs\n'
+    );
+  } else if (capabilities === 'table') {
+    write(
+      'CAPABILITIES.md',
+      [
+        '# Harness Capabilities',
+        '',
+        '| 模块 | 文件 | 说明 |',
+        '|------|------|------|',
+        '| alpha | src/alpha.ts | alpha 的描述 |',
+        '',
+      ].join('\n')
+    );
+  }
+  return dir;
+}
+
+const isTsContent = (rel: string): boolean => /\.tsx?$/.test(rel) && !rel.endsWith('.d.ts');
+
+describe('sync-docs 的 .ts 内容读取计数闸（#147）', () => {
+  let io: CapturingIO;
+  let dir: string;
+
+  /** 相对项目根的落点 → 内容读取次数（readFileSync 与异步 readFile 各算一次） */
+  function contentCounts(): Map<string, number> {
+    const counts = new Map<string, number>();
+    for (const call of reads()) {
+      const rel = path.relative(dir, call.file);
+      if (!rel || rel.startsWith('..')) continue; // 非本项目文件（模块加载等）不计
+      counts.set(rel, (counts.get(rel) ?? 0) + 1);
+    }
+    return counts;
+  }
+
+  function tsContentReads(): Array<[string, number]> {
+    return [...contentCounts().entries()].filter(([rel]) => isTsContent(rel)).sort();
+  }
+
+  beforeEach(() => {
+    // 原地清空：mock 工厂在装载时就 captured 了这个数组引用，换新数组计数会落到旧的去向（假绿）
+    reads().length = 0;
+    io = captureIO();
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('capability-listing 模式：模块清单无人消费 → 一份 .ts 内容都不读', async () => {
+    dir = fixtureProject('listing');
+
+    await syncDocs({ projectPath: dir, check: true, json: true }, io);
+
+    // 正对照：真走了 listing 分支（否则下面的 0 是空跑出来的）
+    expect(JSON.parse(io.outText()).format).toBe('capability-listing');
+    expect(tsContentReads()).toEqual([]);
+  });
+
+  it('反证：file-table 格式照旧逐文件取描述，且每份文件一次运行内恰读一次', async () => {
+    dir = fixtureProject('table');
+
+    await syncDocs({ projectPath: dir, check: true, json: true }, io);
+
+    // 正对照：走了 file-table 分支，描述确实进了对外 JSON（判定面未被这次改造削掉）
+    const json = JSON.parse(io.outText());
+    expect(json.format).toBe('file-table');
+    const described = json.added.map(
+      (a: { module: { file: string; description: string } }) => `${a.module.file}#${a.module.description}`
+    );
+    expect(described.sort()).toEqual([
+      'src/beta.tsx#beta',
+      'src/nested/deep/delta.ts#delta',
+      'src/nested/gamma.ts#gamma 的描述',
+    ]);
+
+    expect(tsContentReads()).toEqual(
+      SOURCE_FILES.map((f) => [f, 1]).sort()
+    );
+  });
+
+  it('CAPABILITIES.md 缺席时同样走 file-table 分支：读取表只含源码清单那几份文件', async () => {
+    dir = fixtureProject('absent');
+
+    await syncDocs({ projectPath: dir, check: true, json: true }, io);
+
+    expect(JSON.parse(io.outText()).format).toBe('file-table');
+    expect(tsContentReads()).toEqual(SOURCE_FILES.map((f) => [f, 1]).sort());
+  });
+
+  it('listing 模式的整张读取表冻结：本次运行只碰 CAPABILITIES.md，源码树零读取', async () => {
+    dir = fixtureProject('listing');
+
+    await syncDocs({ projectPath: dir, check: true, json: true }, io);
+
+    expect([...contentCounts().entries()].sort()).toEqual([['CAPABILITIES.md', 5]]);
+    // CAPABILITIES.md = 5 是**本票范围外的既有重复读**：入口一次异步读 + 计数核对
+    // （checkCapabilityCounts → FreshnessRunner 每条计数规则各读一次）。此处如实冻结，
+    // 既不为它改动也不放行——数字变了就是扫描分支被改动的信号（登记在 #147 resolution）。
+  });
+});

package/src/cli/commands/__tests__/sync-docs.test.ts

@@ -5,6 +5,7 @@
 import * as fs from 'fs';
 import { captureIO, type CapturingIO } from '../../command-contract';
 import * as path from 'path';
+import * as os from 'os';
 import { syncDocs } from '../sync-docs';
 
 let io: CapturingIO;
@@ -13,10 +14,10 @@ beforeEach(() => {
 });
 
 describe('sync-docs command', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-sync-docs');
+  let tempDir: string;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-sync-docs-'));
   });
 
   afterAll(() => {

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

@@ -2,7 +2,7 @@
  * validate 命令测试
  */
 
-import { validate, createExampleCheckpoint, createExampleResolutions } from '../validate';
+import { validate } from '../validate';
 import { captureIO, type CapturingIO } from '../../command-contract';
 import * as fs from 'fs/promises';
 import { CheckpointValidator } from '../../../core/validators/checkpoint';
@@ -126,51 +126,4 @@ describe('validate command', () => {
       expect(result).toEqual({ kind: 'fail', reason: '1 个检查点未通过: test-1' });
     });
   });
-
-  describe('createExampleCheckpoint', () => {
-    it('应该创建示例检查点文件', async () => {
-      mockFs.access.mockRejectedValue(new Error('ENOENT'));
-      mockFs.mkdir.mockResolvedValue(undefined);
-      mockFs.writeFile.mockResolvedValue(undefined);
-      mockYaml.dump.mockReturnValue('yaml content');
-
-      await createExampleCheckpoint('/project', io);
-      
-      expect(mockFs.mkdir).toHaveBeenCalled();
-      expect(mockFs.writeFile).toHaveBeenCalled();
-      expect(io.outText()).toContain('已创建示例检查点');
-    });
-
-    it('已存在时不覆盖', async () => {
-      mockFs.access.mockResolvedValue(undefined);
-
-      await createExampleCheckpoint('/project', io);
-
-      expect(mockFs.writeFile).not.toHaveBeenCalled();
-      expect(io.outText()).toContain('checkpoints.yml 已存在，跳过');
-    });
-  });
-
-  describe('createExampleResolutions', () => {
-    it('应该创建 Resolutions 文件', async () => {
-      mockFs.access.mockRejectedValue(new Error('ENOENT'));
-      mockFs.mkdir.mockResolvedValue(undefined);
-      mockFs.writeFile.mockResolvedValue(undefined);
-
-      await createExampleResolutions('/project', io);
-
-      expect(mockFs.mkdir).toHaveBeenCalled();
-      expect(mockFs.writeFile).toHaveBeenCalled();
-      expect(io.outText()).toContain('已创建 Resolutions 文件');
-    });
-
-    it('已存在时不覆盖', async () => {
-      mockFs.access.mockResolvedValue(undefined);
-
-      await createExampleResolutions('/project', io);
-
-      expect(mockFs.writeFile).not.toHaveBeenCalled();
-      expect(io.outText()).toContain('resolutions.json 已存在，跳过');
-    });
-  });
 });