@dommaker/harness 1.7.0 → 1.8.1

package/src/cli/commands/status.ts

@@ -13,6 +13,7 @@ import { DEFAULT_TRACE_FILE } from '../../types/trace';
 import type { ExecutionTrace } from '../../types/trace';
 import type { TraceSummary, TraceAnomaly } from '../../types/trace';
 import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { fileStateIO, type StateIO } from '../state-io';
 
 export interface StatusOptions {
   /** 项目路径 */
@@ -23,6 +24,13 @@ export interface StatusOptions {
   anomalies?: boolean;
   /** 时间范围（小时） */
   hours?: number;
+  /**
+   * 状态文件接缝（非 CLI flag；ADR-0026）
+   *
+   * 缺省 = 真实 fs 实现（fileStateIO）。注入则 `.harness/.state.json` 的读写
+   * 走替身，测试据此不碰真文件系统。
+   */
+  stateIO?: StateIO;
 }
 
 /**
@@ -32,7 +40,7 @@ export async function status(options: StatusOptions, io: CommandIO = processIO):
   const projectPath = options.projectPath || process.cwd();
   const harnessDir = path.join(projectPath, '.harness');
   const tracesPath = path.join(projectPath, DEFAULT_TRACE_FILE);
-  const statePath = path.join(harnessDir, '.state.json');
+  const stateIO = options.stateIO ?? fileStateIO(projectPath);
 
   log(io, chalk.blue('📊 Harness 状态'));
   log(io);
@@ -139,12 +147,9 @@ export async function status(options: StatusOptions, io: CommandIO = processIO):
     log(io);
   }
 
-  // 更新状态文件
-  const state = {
-    lastStatusRun: new Date().toISOString(),
-  };
-  fs.mkdirSync(path.dirname(statePath), { recursive: true });
-  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+  // 更新状态文件：读-改-写（ADR-0026 决策 2）——不再整文件重写，
+  // 否则 check 写入的 shownHints 会被抹掉、智能提示去重失效
+  stateIO.write({ ...stateIO.read(), lastStatusRun: new Date().toISOString() });
 
   // 下一步建议
   log(io, chalk.blue('💡 下一步建议:'));

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

@@ -0,0 +1,102 @@
+/**
+ * CONTEXT.md 内容判定采集侧测试（harness#142）
+ *
+ * 采集 = fs 遍历 + 导出口径（`export *` 解析、barrel 再导出的类型-only 剔除）。
+ * 判定本体在 core/constraints/context-reconcile（旁测见 context-reconcile.test.ts）。
+ * 与 sync-docs 其余测试同法：临时目录真 fs，零注入。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { collectContextExportSurface } from '../context-syncer';
+
+let tempDir: string;
+
+function write(rel: string, content: string): void {
+  const target = path.join(tempDir, rel);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content);
+}
+
+beforeAll(() => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-context-surface-'));
+});
+
+afterAll(() => {
+  fs.rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('collectContextExportSurface — 目录导出面采集', () => {
+  it('收集目录内（含子目录）.ts 的导出符号；__tests__ 与 .d.ts 不参与', async () => {
+    const dir = 'mod-scan';
+    write(`${dir}/core.ts`, 'export function doCore() {}\nexport interface CoreConfig {}\n');
+    write(`${dir}/nested/deep.ts`, 'export const DEEP_VALUE = 1;');
+    write(`${dir}/__tests__/core.test.ts`, 'export const TEST_ONLY_HELPER = 2;');
+    write(`${dir}/ambient.d.ts`, 'export const GLOBAL_FROM_DTS = 3;');
+
+    const { surface, barrelExports } = await collectContextExportSurface(path.join(tempDir, dir), tempDir);
+
+    expect(surface).toEqual(expect.arrayContaining(['doCore', 'CoreConfig', 'DEEP_VALUE']));
+    expect(surface).not.toContain('TEST_ONLY_HELPER');
+    expect(surface).not.toContain('GLOBAL_FROM_DTS');
+    // 无 index.ts → barrel 方向空转
+    expect(barrelExports).toEqual([]);
+  });
+
+  it('barrel 只交值符号：export type 块、逐项 type、别名取导出名', async () => {
+    const dir = 'mod-barrel';
+    write(`${dir}/impl.ts`, 'export class Widget {}\nexport interface WidgetConfig {}\nexport const WIDGET_LIMIT = 1;\n');
+    write(
+      `${dir}/index.ts`,
+      [
+        "export { Widget, WIDGET_LIMIT as LIMIT } from './impl';",
+        "export type { WidgetConfig } from './impl';",
+        "export { createThing, type ThingShape } from './thing';",
+        'export function barrelLocal() {}',
+      ].join('\n')
+    );
+    write(`${dir}/thing.ts`, 'export function createThing() {}\nexport type ThingShape = string;');
+
+    const { surface, barrelExports } = await collectContextExportSurface(path.join(tempDir, dir), tempDir);
+
+    expect(barrelExports.sort()).toEqual(['LIMIT', 'Widget', 'barrelLocal', 'createThing']);
+    expect(surface).toEqual(expect.arrayContaining(['WidgetConfig', 'ThingShape']));
+  });
+
+  it('`export *` 在同目录内解析目标后并入（值进 barrel、类型不进）', async () => {
+    const dir = 'mod-star';
+    write(`${dir}/types.ts`, 'export interface Shape {}\nexport type Mode = "a" | "b";\nexport enum Kind { A }\n');
+    write(`${dir}/store.ts`, 'export class Store {}\nexport const DEFAULTS = {};\n');
+    write(`${dir}/index.ts`, ["export * from './types';", "export * from './store';", "export * from 'chalk';"].join('\n'));
+
+    const { surface, barrelExports } = await collectContextExportSurface(path.join(tempDir, dir), tempDir);
+
+    expect(barrelExports.sort()).toEqual(['DEFAULTS', 'Kind', 'Store']);
+    expect(surface).toEqual(expect.arrayContaining(['Shape', 'Mode', 'Kind', 'Store', 'DEFAULTS']));
+  });
+
+  it('跨目录再导出的类型按正本声明分型（值侧要求登记，类型侧豁免）', async () => {
+    write('types/external.ts', 'export const EXTERNAL_VALUE = 1;\nexport interface ExternalShape {}\n');
+    const dir = 'mod-cross';
+    write(
+      `${dir}/index.ts`,
+      ["export { EXTERNAL_VALUE, ExternalShape } from '../types/external';", 'export const Own = 2;'].join('\n')
+    );
+
+    const { barrelExports } = await collectContextExportSurface(path.join(tempDir, dir), tempDir);
+
+    expect(barrelExports.sort()).toEqual(['EXTERNAL_VALUE', 'Own']);
+  });
+
+  it('barrel 再导出正本已不存在的名字 → 不计入导出面（改名的虚 barrel 不洗白幽灵）', async () => {
+    const dir = 'mod-phantom';
+    write(`${dir}/impl.ts`, 'export class WidgetSink {}\nexport interface Shape {}\n');
+    write(`${dir}/index.ts`, "export { Widget, WidgetSink } from './impl';\nexport type { Missing } from './impl';");
+
+    const { surface, barrelExports } = await collectContextExportSurface(path.join(tempDir, dir), tempDir);
+
+    expect(surface).toEqual(['WidgetSink', 'Shape']);
+    expect(barrelExports).toEqual(['WidgetSink']);
+  });
+});

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

@@ -0,0 +1,196 @@
+/**
+ * 模块描述提取：并发取数 + 逐字保序（#147 B 票）
+ *
+ * sync-docs 的 file-table 分支要把首行注释提成表格「说明」列。改造前是逐文件
+ * `await` 串行读；改造后按固定上限并发读，但**输出清单的顺序必须与目录遍历序
+ * 逐字一致**（该顺序对外经 `sync-docs --check` 的漂移校验可见，不得变）。
+ *
+ * 手法：替身 `fs/promises.readFile` 给每次读取记「起始序 / 完成序」，并让起始靠后
+ * 的读更快完成——只要真有并发，完成序必然与起始序不同。于是「按完成顺序 append」
+ * 的实现会当场红，而「按原索引回填」的实现保序。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+type IoEvents = {
+  /** .ts/.tsx 内容读的发起顺序（替身按调用到达顺序记账） */
+  started: string[];
+  /** .ts/.tsx 内容读的完成顺序 */
+  finished: string[];
+  inFlight: number;
+  maxInFlight: number;
+};
+
+// 记账挂 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_IO__?: IoEvents };
+  if (!g.__SD147_IO__) {
+    g.__SD147_IO__ = { started: [], finished: [], inFlight: 0, maxInFlight: 0 };
+  }
+  const ev = g.__SD147_IO__;
+  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+  return {
+    ...actual,
+    readFile: jest.fn(async (p: fs.PathLike | unknown, ...rest: unknown[]) => {
+      const name = Buffer.isBuffer(p) ? p.toString('utf8') : String(p);
+      const tracked = /\.(ts|tsx)$/.test(name) && !name.endsWith('.d.ts');
+      if (tracked) {
+        const startedIndex = ev.started.length;
+        ev.started.push(name);
+        ev.inFlight++;
+        if (ev.inFlight > ev.maxInFlight) ev.maxInFlight = ev.inFlight;
+        // 起始靠后的读更快落地：并发一存在，完成序就与起始序错开
+        await sleep(startedIndex % 2 === 0 ? 60 : 2);
+      }
+      try {
+        return await (
+          actual.readFile as unknown as (
+            path: unknown,
+            options?: unknown
+          ) => Promise<string | Buffer>
+        )(p, ...rest);
+      } finally {
+        if (tracked) {
+          ev.inFlight--;
+          ev.finished.push(name);
+        }
+      }
+    }),
+  };
+});
+
+import { extractFileDescriptions, scanSourceModules } from '../project-reader';
+
+const events = (): IoEvents =>
+  ((globalThis as unknown as { __SD147_IO__?: IoEvents }).__SD147_IO__ ||= {
+    started: [],
+    finished: [],
+    inFlight: 0,
+    maxInFlight: 0,
+  });
+
+let tempDir: string;
+
+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');
+}
+
+/** 描述 = `desc:<文件名去扩展名>`，一眼可核对配对 */
+function writeModule(rel: string): void {
+  const base = path.basename(rel).replace(/\.tsx?$/, '');
+  write(rel, `// desc:${base}\nexport const ${/^\w+$/.test(base) ? base : 'x'} = 1;\n`);
+}
+
+function reset(): void {
+  const ev = events();
+  ev.started.length = 0;
+  ev.finished.length = 0;
+  ev.inFlight = 0;
+  ev.maxInFlight = 0;
+}
+
+beforeAll(() => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sd147-descriptions-'));
+});
+
+afterAll(() => {
+  fs.rmSync(tempDir, { recursive: true, force: true });
+});
+
+beforeEach(reset);
+
+describe('scanSourceModules — 描述并发取数且逐字保序（#147）', () => {
+  it('并发真的发生：同一时刻至多 16 份读在途，而非逐文件串行', async () => {
+    const srcDir = path.join(tempDir, 'wide');
+    // 20 份 > 上限：串行的话 maxInFlight 恒为 1
+    for (let i = 0; i < 20; i++) {
+      writeModule(`wide/m${String(i).padStart(2, '0')}.ts`);
+    }
+    // 子目录里的文件同样要进并发池
+    writeModule('wide/nested/deep-a.ts');
+    writeModule('wide/nested/deep-b.ts');
+
+    const modules = await scanSourceModules(srcDir, tempDir);
+
+    const ev = events();
+    expect(modules).toHaveLength(22);
+    expect(ev.started).toHaveLength(22);
+    // 正对照：完成序与起始序确实错开了（夹具没并发能力 = 下面的断言是空跑）
+    expect(ev.finished).not.toEqual(ev.started);
+    expect(ev.maxInFlight).toBeGreaterThan(1);
+    // 上限是固定缺省，不是「有多少文件开多少」
+    expect(ev.maxInFlight).toBeLessThanOrEqual(16);
+  });
+
+  it('输出顺序 = 读取发起顺序（= 目录遍历序），描述与文件一一配对', async () => {
+    const srcDir = path.join(tempDir, 'order');
+    writeModule('order/zeta.ts');
+    writeModule('order/alpha.ts');
+    writeModule('order/mid.tsx');
+    writeModule('order/sub/beta.ts');
+    writeModule('order/sub/gamma.ts');
+
+    const modules = await scanSourceModules(srcDir, tempDir);
+
+    const ev = events();
+    const relStarted = ev.started.map((f) => path.relative(tempDir, f));
+
+    // 回填按原索引，不按完成先后：清单顺序 = 发起顺序
+    expect(modules.map((m) => m.file)).toEqual(relStarted);
+    // 每条描述都得是自己那份文件的（串位即红）
+    expect(modules.map((m) => m.description)).toEqual(
+      modules.map((m) => `desc:${path.basename(m.file).replace(/\.tsx?$/, '')}`)
+    );
+    // 回填既不是「按完成先后 append」，也不是按文件名重排
+    expect(modules.map((m) => m.file)).not.toEqual(
+      ev.finished.map((f) => path.relative(tempDir, f))
+    );
+  });
+
+  it('跳过口径逐字不变：barrel / .d.ts / __tests__ 不进清单也不被读', async () => {
+    const srcDir = path.join(tempDir, 'skips');
+    writeModule('skips/keep.ts');
+    writeModule('skips/index.ts');
+    writeModule('skips/typed.tsx');
+    write('skips/ambient.d.ts', '// desc:should-not-appear\nexport const nope = 1;\n');
+    write('skips/__tests__/keep.test.ts', '// desc:should-not-appear\nexport const nope = 1;\n');
+    write('skips/node_modules/pkg/index.ts', '// desc:should-not-appear\n');
+    write('skips/dist/built.ts', '// desc:should-not-appear\n');
+
+    const modules = await scanSourceModules(srcDir, tempDir);
+
+    expect(modules.map((m) => m.file)).toEqual(['skips/keep.ts', 'skips/typed.tsx']);
+    expect(events().started.map((f) => path.basename(f))).toEqual(['keep.ts', 'typed.tsx']);
+  });
+
+  it('两条兜底逐字保留：JSDoc 首行进描述、无注释回退文件名', async () => {
+    const srcDir = path.join(tempDir, 'bare');
+    write('bare/no-comment.ts', 'export const a = 1;\n');
+    write('bare/jsdoc.ts', '/**\n * JSDoc 首行描述\n */\nexport const b = 2;\n');
+
+    const modules = await scanSourceModules(srcDir, tempDir);
+    const byFile = new Map(modules.map((m) => [m.file, m.description]));
+
+    expect([...modules.map((m) => m.name)].sort()).toEqual(['jsdoc', 'no-comment']);
+    expect(byFile.get('bare/jsdoc.ts')).toBe('JSDoc 首行描述');
+    expect(byFile.get('bare/no-comment.ts')).toBe('no-comment');
+  });
+
+  it('读失败的文件交回文件名（并发回填不改变原 try/catch 兜底语义）', async () => {
+    write('fallback/here.ts', '/**\n * 在场文件的描述\n */\nexport const c = 3;\n');
+
+    const descriptions = await extractFileDescriptions([
+      path.join(tempDir, 'fallback', 'here.ts'),
+      path.join(tempDir, 'fallback', 'gone.ts'),
+      path.join(tempDir, 'fallback', 'also-here.ts'),
+    ]);
+
+    expect(descriptions).toEqual(['在场文件的描述', 'gone', 'also-here']);
+  });
+});

package/src/cli/commands/sync-docs/context-syncer.ts

@@ -1,43 +1,37 @@
 /**
  * CONTEXT.md 同步器（工单 22）：缺失模板生成 + 既有文件发现 + 过时判定
+ * + 目录导出面采集（harness#142，供 context-reconcile 的内容判定喂数）
  */
 
 import * as fs from 'fs/promises';
+import { existsSync } from 'fs';
 import * as path from 'path';
-import { DEFAULT_SKIP_DIRS } from '../../../utils/file-walk';
+import { DEFAULT_SKIP_DIRS, findTsSourceFiles } from '../../../utils/file-walk';
+import { parseExportStatements } from '../../../core/constraints/context-reconcile';
+import type { CommandIO } from '../../command-contract';
+import {
+  contextDocFile,
+  nodeScaffoldFs,
+  runPlan,
+  type ScaffoldFileSystem,
+  type ScaffoldOutcome,
+} from '../scaffold';
 
 /**
- * 创建 CONTEXT.md 模板
+ * 创建 CONTEXT.md 模板：走 scaffold 正本站点（contextDocFile + runPlan），
+ * 与 init 的 CONTEXT.md 落点共用同一份模板正文（harness#150，#132 口径外的第 9 处）。
+ *
+ * 只在 `contextMissing` 的目录上被调用，故正常只走 `created`；若落到 `exists`
+ * 说明 sync-docs 的缺失判定与 scaffold 的在场判定口径不一致（不静默兜，交由调用方感知）。
  */
-export async function createContextMd(projectPath: string, dir: string): Promise<void> {
-  const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
-  const dirName = path.basename(dir);
-
-  const content = `# ${dirName}
-
-> 此文件描述 ${dir} 目录的职责和上下文。
-> 请阅读本目录的源代码，然后填写以下各节。
-> 如果使用 AI 编码助手，将本文件内容作为 prompt 请求它分析并填写。
-
-## 职责
-
-本目录的核心职责是？
-
-## 核心导出
-
-本目录对外暴露的主要模块/函数：
-
-## 依赖关系
-
-本目录依赖哪些其他模块，谁依赖本目录？
-
-## 注意事项
-
-开发时需要注意的约束或约定：
-`;
-
-  await fs.mkdir(path.join(projectPath, dir), { recursive: true });
-  await fs.writeFile(contextPath, content, 'utf-8');
+export async function createContextMd(
+  projectPath: string,
+  dir: string,
+  io: CommandIO,
+  scaffoldFs: ScaffoldFileSystem = nodeScaffoldFs,
+): Promise<ScaffoldOutcome> {
+  const [outcome] = await runPlan([contextDocFile(projectPath, dir)], io, scaffoldFs);
+  return outcome;
 }
 
 /**
@@ -107,3 +101,115 @@ export async function getLatestTsMtime(dirPath: string): Promise<number | null>
   await scan(dirPath);
   return latest;
 }
+
+/** 目录导出面采集结果（harness#142） */
+export interface ContextExportSurface {
+  /** 目录内所有 .ts 导出的符号名（值 + 类型，含 barrel 再导出） */
+  surface: string[];
+  /** `index.ts` barrel 再导出的**值**符号（类型-only 已剔除）；无 index.ts → 空 */
+  barrelExports: string[];
+}
+
+/** 文件名的导出表：name → typeOnly（口径正本是 context-reconcile 的语句解析） */
+type ExportMap = Map<string, boolean>;
+
+/**
+ * 把相对 spec 解析为仓内可读的 .ts 文件（`./x` → `x.ts` 或 `x/index.ts`）；
+ * 非相对 spec、越出项目根、命中 `.d.ts`/`node_modules`/跳过目录一律 null（不并入导出面）。
+ */
+function resolveTsTarget(fromFile: string, spec: string, projectPath: string): string | null {
+  if (!spec.startsWith('.')) return null;
+  const base = path.resolve(path.dirname(fromFile), spec);
+  for (const candidate of [`${base}.ts`, path.join(base, 'index.ts')]) {
+    if (candidate.endsWith('.d.ts')) continue;
+    const rel = path.relative(projectPath, candidate);
+    if (!rel || rel.startsWith('..') || rel.includes('node_modules')) continue;
+    if (rel.split(path.sep).some((segment) => DEFAULT_SKIP_DIRS.includes(segment))) continue;
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * 单文件导出表（含再导出与 `export *` 展开），memo 化 + 在途集合破环。
+ *
+ * 递归只沿 `export *` 与具名再导出的来源走，读到的都是仓内 .ts；
+ * 环上（A `export * from './b'`、B `export * from './a'`）在途文件交空表，
+ * 与 tsc 的星号环语义一致（不因此丢名字——真实名字总有非环上的一条声明路径）。
+ */
+async function collectFileExports(
+  file: string,
+  projectPath: string,
+  cache: Map<string, ExportMap>,
+  inProgress: Set<string>
+): Promise<ExportMap> {
+  const cached = cache.get(file);
+  if (cached) return cached;
+  if (inProgress.has(file)) return new Map();
+  inProgress.add(file);
+
+  const out: ExportMap = new Map();
+  let source: string;
+  try {
+    source = await fs.readFile(file, 'utf-8');
+  } catch {
+    inProgress.delete(file);
+    cache.set(file, out);
+    return out;
+  }
+
+  const { symbols, starFrom } = parseExportStatements(source);
+  for (const symbol of symbols) {
+    let typeOnly = symbol.typeOnly;
+    if (symbol.from) {
+      const origin = resolveTsTarget(file, symbol.from, projectPath);
+      // 环上（origin 在途）时交回的是空表，那是「不知道」不是「没有」→ 不做虚判
+      if (origin && !inProgress.has(origin)) {
+        const originExports = await collectFileExports(origin, projectPath, cache, inProgress);
+        // 正本没有这个本名 → 这条再导出是虚的（改名未跟上的 barrel），不计入导出面，
+        // 否则文档里的幽灵会被 barrel 自己洗白（harness#142 反证撞出的口径漏洞）
+        if (!originExports.has(symbol.localName)) continue;
+        if (!typeOnly && originExports.get(symbol.localName) === true) typeOnly = true;
+      }
+    }
+    out.set(symbol.name, typeOnly);
+  }
+
+  for (const spec of starFrom) {
+    const target = resolveTsTarget(file, spec, projectPath);
+    if (!target) continue;
+    const targetExports = await collectFileExports(target, projectPath, cache, inProgress);
+    for (const [name, typeOnly] of targetExports) if (!out.has(name)) out.set(name, typeOnly);
+  }
+
+  inProgress.delete(file);
+  cache.set(file, out);
+  return out;
+}
+
+/**
+ * 采集目录导出面（内容判定的代码侧）：目录内 .ts（排 `__tests__/`、`.d.ts`）的导出符号全集，
+ * 以及 barrel（`index.ts`）再导出的值符号清单。fs IO 全在此，判定不在（ADR-0025）。
+ */
+export async function collectContextExportSurface(
+  dirPath: string,
+  projectPath: string
+): Promise<ContextExportSurface> {
+  const files = findTsSourceFiles(dirPath);
+  const cache = new Map<string, ExportMap>();
+  const surface = new Set<string>();
+
+  for (const file of files) {
+    const fileExports = await collectFileExports(file, projectPath, cache, new Set());
+    for (const name of fileExports.keys()) surface.add(name);
+  }
+
+  const barrelExports: string[] = [];
+  const barrelFile = path.join(dirPath, 'index.ts');
+  if (files.includes(barrelFile)) {
+    const barrel = await collectFileExports(barrelFile, projectPath, cache, new Set());
+    for (const [name, typeOnly] of barrel) if (!typeOnly) barrelExports.push(name);
+  }
+
+  return { surface: [...surface], barrelExports };
+}