@dommaker/harness 1.3.0 → 1.4.0

package/src/__tests__/context-files-resolution.test.ts

@@ -0,0 +1,116 @@
+/**
+ * resolveContextFiles 三态访问器测试（工单 84）
+ *
+ * 测试面 = project-config-loader 上的 governance.context_files 访问器：
+ * 未配置 / enabled 但无目标 / enabled 且非空 三态可分辨；访问器基于
+ * loadRawProjectConfig 的进程级 memoize，不触发第二次 yaml 解析。
+ * 临时目录由 src/test-setup/mkdtemp-cleanup.ts 统一回收。
+ */
+
+import { describe, it, expect, jest } from '@jest/globals';
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveContextFiles, loadRawProjectConfig } from '../core/project-config-loader';
+import { createProjectFixture } from '../test-setup/project-fixture';
+
+// ts-jest 的 namespace 导入属性不可重定义（jest.spyOn 会抛），改为只包一层
+// readFileSync 的部分 mock——其余 fs 能力用真实实现，fixture 搭建不受影响。
+jest.mock('fs', () => {
+  const actual = jest.requireActual<typeof import('fs')>('fs');
+  return { ...actual, readFileSync: jest.fn(actual.readFileSync) };
+});
+
+const readSpy = (fs as unknown as { readFileSync: jest.Mock }).readFileSync;
+
+function setupProject(name: string, configYml: string | null): string {
+  return createProjectFixture({ name: `ctx-files-${name}`, config: configYml ?? undefined });
+}
+
+const CTX_FILES = (enabled: boolean, dirs?: string[]) =>
+  `governance:\n  context_files:\n    enabled: ${enabled}\n` +
+  (dirs ? `    required_dirs: [${dirs.map(d => `'${d}'`).join(', ')}]\n` : '');
+
+describe('resolveContextFiles — 三态分辨率（工单 84 triage 裁决口径）', () => {
+  it('无 config.yml → unconfigured', () => {
+    expect(resolveContextFiles(setupProject('no-config', null))).toEqual({
+      state: 'unconfigured',
+    });
+  });
+
+  it('governance / context_files 段缺失 → unconfigured', () => {
+    expect(resolveContextFiles(setupProject('no-section', 'preset: standard\n'))).toEqual({
+      state: 'unconfigured',
+    });
+  });
+
+  it('enabled: false → unconfigured（约定未采用，与段缺失同态）', () => {
+    expect(resolveContextFiles(setupProject('disabled', CTX_FILES(false, ['src'])))).toEqual({
+      state: 'unconfigured',
+    });
+  });
+
+  it('enabled 但 required_dirs 缺失 / 非数组 / 空数组 → enabled-empty', () => {
+    expect(resolveContextFiles(setupProject('no-dirs', CTX_FILES(true)))).toEqual({
+      state: 'enabled-empty',
+    });
+    expect(
+      resolveContextFiles(
+        setupProject('bad-dirs', 'governance:\n  context_files:\n    enabled: true\n    required_dirs: src\n')
+      )
+    ).toEqual({ state: 'enabled-empty' });
+    expect(resolveContextFiles(setupProject('empty-dirs', CTX_FILES(true, [])))).toEqual({
+      state: 'enabled-empty',
+    });
+  });
+
+  it('enabled 且 required_dirs 含非字符串项 → enabled-empty（脏配置目标不可用，不得流入 path.join 抛错）', () => {
+    expect(
+      resolveContextFiles(
+        setupProject('dirty-dirs', 'governance:\n  context_files:\n    enabled: true\n    required_dirs: [1, null]\n')
+      )
+    ).toEqual({ state: 'enabled-empty' });
+  });
+
+  it('enabled 且 required_dirs 非空 → enabled + dirs', () => {
+    expect(resolveContextFiles(setupProject('ok', CTX_FILES(true, ['src', 'bin'])))).toEqual({
+      state: 'enabled',
+      dirs: ['src', 'bin'],
+    });
+  });
+
+  it('governance 段形状不符（null / 标量）→ unconfigured（钻取点形状守护）', () => {
+    expect(resolveContextFiles(setupProject('null-gov', 'governance:\n'))).toEqual({
+      state: 'unconfigured',
+    });
+    expect(resolveContextFiles(setupProject('scalar-gov', 'governance: context_files\n'))).toEqual({
+      state: 'unconfigured',
+    });
+  });
+
+  it('YAML 解析失败 → unconfigured（访问器不抛出，由调用方按未配置处理）', () => {
+    expect(resolveContextFiles(setupProject('bad-yaml', 'governance: [\n  broken: {{\n'))).toEqual({
+      state: 'unconfigured',
+    });
+  });
+});
+
+describe('resolveContextFiles — memoize 语义（工单 84：不引入第二次解析）', () => {
+  it('访问器多次调用 + 直接读 raw 共享单次 config.yml 读取', () => {
+    const dir = setupProject('memo', CTX_FILES(true, ['src']));
+    const configReads = () =>
+      readSpy.mock.calls.filter(call =>
+        String(call[0]).endsWith(path.join('.harness', 'config.yml'))
+      ).length;
+
+    readSpy.mockClear();
+    expect(configReads()).toBe(0); // 探针有效：fixture 搭建不读 config
+
+    resolveContextFiles(dir);
+    expect(configReads()).toBe(1); // 首次真读取+解析
+
+    resolveContextFiles(dir);
+    resolveContextFiles(dir);
+    loadRawProjectConfig(dir);
+    expect(configReads()).toBe(1); // 复用进程级 memoize，无第二次解析
+  });
+});

package/src/__tests__/effective-constraints.test.ts

@@ -6,11 +6,11 @@
 
 import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
 import * as fs from 'fs';
-import * as path from 'path';
 import {
   getEffectiveConstraints,
   lintEffectiveConfig,
 } from '../core/effective-constraints';
+import { createProjectFixture } from '../test-setup/project-fixture';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from '../core/constraints/definitions';
 
 const BUILTIN_TOTAL =
@@ -24,20 +24,17 @@ describe('getEffectiveConstraints / lintEffectiveConfig', () => {
   let tempDir: string;
   let counter = 0;
 
-  const setupProject = (configYaml?: string, customYaml?: string): string => {
-    const dir = path.join(tempDir, `p${counter++}`);
-    fs.mkdirSync(path.join(dir, '.harness'), { recursive: true });
-    if (configYaml !== undefined) {
-      fs.writeFileSync(path.join(dir, '.harness', 'config.yml'), configYaml);
-    }
-    if (customYaml !== undefined) {
-      fs.writeFileSync(path.join(dir, '.harness', 'custom-constraints.yml'), customYaml);
-    }
-    return dir;
-  };
+  const setupProject = (configYaml?: string, customYaml?: string): string =>
+    createProjectFixture({
+      parentDir: tempDir,
+      name: `p${counter++}`,
+      config: configYaml,
+      files: customYaml === undefined ? undefined : { '.harness/custom-constraints.yml': customYaml },
+    });
 
   beforeEach(() => {
-    tempDir = fs.mkdtempSync(path.join(process.cwd(), 'temp-test-effective-'));
+    // cwd 锚定套件：parentDir 显式 opt-out，缺省 tmpdir 会改变路径锚定结论（harness#90）
+    tempDir = createProjectFixture({ name: 'temp-test-effective', parentDir: process.cwd() });
   });
 
   afterEach(() => {

package/src/__tests__/exec.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from '@jest/globals';
-import { runCommand, isCommandAvailable, normalizeTriggers, delay } from '../utils/exec';
+import { runCommand, isCommandAvailable, normalizeTriggers, matchesTrigger, delay } from '../utils/exec';
 
 describe('exec utils', () => {
   describe('runCommand', () => {
@@ -73,6 +73,40 @@ describe('exec utils', () => {
     });
   });
 
+  describe('matchesTrigger', () => {
+    it('单值 trigger 命中操作返回 true', () => {
+      expect(matchesTrigger({ trigger: 'a' }, ['a'])).toBe(true);
+    });
+
+    it('单值 trigger 未命中返回 false', () => {
+      expect(matchesTrigger({ trigger: 'a' }, ['b'])).toBe(false);
+    });
+
+    it('数组 trigger 任一命中即返回 true', () => {
+      expect(matchesTrigger({ trigger: ['a', 'b'] }, ['b'])).toBe(true);
+    });
+
+    it('数组 trigger 全部未命中返回 false', () => {
+      expect(matchesTrigger({ trigger: ['a', 'b'] }, ['c', 'd'])).toBe(false);
+    });
+
+    it('operations 中任一命中即返回 true', () => {
+      expect(matchesTrigger({ trigger: 'a' }, ['x', 'a'])).toBe(true);
+    });
+
+    it('trigger 为 undefined 时不匹配任何操作', () => {
+      expect(matchesTrigger({ trigger: undefined }, ['a'])).toBe(false);
+    });
+
+    it('trigger 为空数组时不匹配任何操作', () => {
+      expect(matchesTrigger({ trigger: [] }, ['a'])).toBe(false);
+    });
+
+    it('operations 为空数组时返回 false', () => {
+      expect(matchesTrigger({ trigger: 'a' }, [])).toBe(false);
+    });
+  });
+
   describe('delay', () => {
     it('应该延迟指定时间', async () => {
       const start = Date.now();

package/src/__tests__/layering.test.ts

@@ -0,0 +1,152 @@
+/**
+ * 单向分层守卫（架构评审 2026-09-02 · 候选9 / harness#88）
+ *
+ * 分层 `types → utils → core → 领域层 → cli` 此前只是文档约定。本文件把它落成两件事：
+ * 1. 真扫描：src/core/** 对 cli / gates / monitoring 零**值**导入（type-only 允许）
+ * 2. 真规则：eslint.config.mjs 的 no-restricted-imports 对上行值导入报 error，
+ *    并允许 type-only（探针在纯 node 进程里跑仓内真配置，代码不落盘）
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+
+interface LintMessage {
+  ruleId: string | null;
+  severity: number;
+  message: string;
+}
+
+/**
+ * 探针脚本：在**纯 node** 里跑 FlatESLint（jest 的模块注册表拦截 flat config
+ * 的 ESM 动态 import，需 --experimental-vm-modules；这里用真 node + 真配置文件）
+ */
+const LINT_PROBE_SCRIPT = `
+const { FlatESLint } = require('eslint/use-at-your-own-risk');
+const { code, filePath } = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+new FlatESLint({ cwd: process.cwd() })
+  .lintText(code, { filePath })
+  .then(r => process.stdout.write(JSON.stringify(r[0].messages)))
+  .catch(e => { process.stderr.write(String(e && e.message)); process.exit(1); });
+`;
+
+const REPO_ROOT = path.resolve(__dirname, '../..');
+const CORE_DIR = path.join(REPO_ROOT, 'src', 'core');
+/** core 之下不得出现值导入的上层目录 */
+const UPPER_LAYERS = ['cli', 'gates', 'monitoring'];
+
+/** import / export-from / require / 动态 import 的源串 + 子句 */
+const MODULE_SOURCE_REGEX =
+  /(?:^|\n)\s*(?:import|export)\s+([\s\S]*?)\s*from\s*['"]([^'"]+)['"]|(?:^|\n)\s*(?:require|import)\s*\(\s*['"]([^'"]+)['"]/g;
+
+function listTsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...listTsFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/** 去注释，避免文档里的示例 import 被当成真依赖 */
+function stripComments(code: string): string {
+  return code.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+}
+
+/** `import type {X}` / `export type {X}` = type-only；混合 `import { type A, B }` 算值导入 */
+function isTypeOnlyClause(clause: string): boolean {
+  return /^\s*type(\s|\{|$)/.test(clause);
+}
+
+/** 收集一个文件里所有指向上层的值导入源串 */
+function upwardValueImports(file: string): string[] {
+  const text = stripComments(fs.readFileSync(file, 'utf-8'));
+  const hits: string[] = [];
+  MODULE_SOURCE_REGEX.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = MODULE_SOURCE_REGEX.exec(text)) !== null) {
+    const clause = match[1] ?? '';
+    const source = match[2] ?? match[3];
+    if (match[1] && isTypeOnlyClause(clause)) continue;
+    if (!source.startsWith('.')) continue;
+    const resolved = path.resolve(path.dirname(file), source);
+    const relToSrc = path.relative(path.join(REPO_ROOT, 'src'), resolved);
+    if (UPPER_LAYERS.some(layer => relToSrc === layer || relToSrc.startsWith(layer + path.sep))) {
+      hits.push(source);
+    }
+  }
+  return hits;
+}
+
+/** 在纯 node 子进程里用仓内真配置 lint 一段 core 侧探针代码，返回命中的方向规则 */
+function probeCore(code: string, filePath = 'src/core/constraints/__layering_probe__.ts'): LintMessage[] {
+  const out = execFileSync(process.execPath, ['-e', LINT_PROBE_SCRIPT], {
+    cwd: REPO_ROOT,
+    input: JSON.stringify({ code, filePath }),
+    encoding: 'utf-8',
+  });
+  const messages = JSON.parse(out) as LintMessage[];
+  return messages.filter(m => m.ruleId === '@typescript-eslint/no-restricted-imports');
+}
+
+describe('core 单向分层（harness#88）', () => {
+  describe('真扫描：core/** 零上行值导入', () => {
+    it('src/core 下每个文件对 cli/gates/monitoring 都没有值导入', () => {
+      const offenders = listTsFiles(CORE_DIR)
+        .map(file => ({ file: path.relative(REPO_ROOT, file), hits: upwardValueImports(file) }))
+        .filter(entry => entry.hits.length > 0);
+
+      expect(offenders).toEqual([]);
+    });
+  });
+
+  describe('真规则：eslint 上行值导入报 error', () => {
+    it.each([
+      ['monitoring', '../../monitoring/traces'],
+      ['cli', '../../cli/commands/definitions'],
+      ['gates', '../../gates/definitions'],
+    ])('core 值导入 %s 报 error（%s）', (_layer, source) => {
+      const messages = probeCore(
+        `import { something } from '${source}';\nexport const use = something;\n`
+      );
+      expect(messages).toHaveLength(1);
+      expect(messages[0].severity).toBe(2);
+      expect(messages[0].message).toContain('harness#88');
+    });
+
+    it('type-only 上行导入放行', () => {
+      const messages = probeCore(
+        `import type { GateDefinition } from '../../gates/definitions';\nexport type Local = GateDefinition;\n`
+      );
+      expect(messages).toEqual([]);
+    });
+
+    it('同层/下层导入与上层目录名的字面量不误报', () => {
+      const messages = probeCore(
+        [
+          `import { CheckCache } from './check-cache';`,
+          `import type { ExecutionTrace } from '../../types/trace';`,
+          `import * as fs from 'fs';`,
+          `const gateDocs = 'src/gates/definitions.ts';`,
+          `export const cache = new CheckCache({ ttlMs: 1 });`,
+          `export const traceType: ExecutionTrace | null = null;`,
+          `export const docs = gateDocs;`,
+          `export const fsMod = fs;`,
+        ].join('\n')
+      );
+      expect(messages).toEqual([]);
+    });
+
+    it('规则只作用于 src/core/**：cli 侧值导入 monitoring 不误报', () => {
+      const messages = probeCore(
+        `import { getTraceCollector } from '../../monitoring/traces';\nexport const c = getTraceCollector();\n`,
+        'src/cli/commands/__layering_probe__.ts'
+      );
+      expect(messages).toEqual([]);
+    });
+  });
+});

package/src/__tests__/passes-gate-extra.test.ts

@@ -90,149 +90,4 @@ describe('PassesGate - 补充覆盖', () => {
       expect(Array.isArray(changes)).toBe(true);
     });
   });
-
-  describe('getExtensionNames', () => {
-    it('初始应该为空数组', () => {
-      const names = gate.getExtensionNames();
-      expect(names).toEqual([]);
-    });
-
-    it('注册扩展后应该返回名称', () => {
-      gate.registerExtension('puppeteer', {
-        name: 'puppeteer',
-        run: async () => ({
-          passed: true,
-          command: 'puppeteer',
-          timestamp: new Date(),
-        }),
-      });
-
-      expect(gate.getExtensionNames()).toContain('puppeteer');
-      
-      gate.unregisterExtension('puppeteer');
-    });
-  });
-
-  describe('unregisterExtension', () => {
-    it('注销不存在扩展应该返回 false', () => {
-      expect(gate.unregisterExtension('nonexistent')).toBe(false);
-    });
-
-    it('注销已注册扩展应该返回 true', () => {
-      gate.registerExtension('temp', {
-        name: 'temp',
-        run: async () => ({ passed: true, command: 'temp', timestamp: new Date() }),
-      });
-
-      expect(gate.unregisterExtension('temp')).toBe(true);
-    });
-  });
-
-  describe('runAllTests', () => {
-    it('应该运行单元测试和扩展测试', async () => {
-      writeFileSync(join(tempDir, 'package.json'), JSON.stringify({
-        name: 'multi-test',
-        scripts: { test: 'echo "1 passed"' },
-      }));
-
-      gate.registerExtension('mock-ext', {
-        name: 'mock-ext',
-        run: async () => ({
-          passed: true,
-          command: 'mock-ext',
-          timestamp: new Date(),
-        }),
-      });
-
-      const results = await gate.runAllTests(tempDir);
-      
-      expect(results.length).toBeGreaterThan(0);
-      expect(results.some(r => r.type === 'mock-ext')).toBe(true);
-      
-      gate.unregisterExtension('mock-ext');
-    });
-
-    it('扩展失败应该返回失败结果', async () => {
-      writeFileSync(join(tempDir, 'package.json'), JSON.stringify({
-        name: 'ext-fail',
-        scripts: { test: 'echo "1 passed"' },
-      }));
-
-      gate.registerExtension('fail-ext', {
-        name: 'fail-ext',
-        run: async () => ({
-          passed: false,
-          command: 'fail-ext',
-          error: 'Extension failed',
-          timestamp: new Date(),
-        }),
-      });
-
-      const results = await gate.runAllTests(tempDir);
-      
-      expect(results.some(r => !r.passed)).toBe(true);
-      
-      gate.unregisterExtension('fail-ext');
-    });
-
-    it('扩展抛异常应该捕获', async () => {
-      writeFileSync(join(tempDir, 'package.json'), JSON.stringify({
-        name: 'ext-error',
-        scripts: { test: 'echo "1 passed"' },
-      }));
-
-      gate.registerExtension('error-ext', {
-        name: 'error-ext',
-        run: async () => {
-          throw new Error('Extension error');
-        },
-      });
-
-      const results = await gate.runAllTests(tempDir);
-      
-      expect(results.some(r => r.type === 'error-ext' && !r.passed)).toBe(true);
-      
-      gate.unregisterExtension('error-ext');
-    });
-  });
-
-  describe('checkAllPasses', () => {
-    it('所有测试通过应该返回 passed=true', async () => {
-      writeFileSync(join(tempDir, 'package.json'), JSON.stringify({
-        name: 'all-pass',
-        scripts: { test: 'echo "1 passed"' },
-      }));
-
-      gate.registerExtension('pass-ext', {
-        name: 'pass-ext',
-        run: async () => ({ passed: true, command: 'pass-ext', timestamp: new Date() }),
-      });
-
-      const { passed, failedTypes } = await gate.checkAllPasses(tempDir);
-      
-      expect(passed).toBe(true);
-      expect(failedTypes.length).toBe(0);
-      
-      gate.unregisterExtension('pass-ext');
-    });
-
-    it('有失败测试应该返回 passed=false', async () => {
-      writeFileSync(join(tempDir, 'package.json'), JSON.stringify({
-        name: 'some-fail',
-        scripts: { test: 'echo "1 passed"' },
-      }));
-
-      gate.registerExtension('fail-ext', {
-        name: 'fail-ext',
-        run: async () => ({ passed: false, command: 'fail-ext', timestamp: new Date() }),
-      });
-
-      const { passed, failedTypes } = await gate.checkAllPasses(tempDir);
-      
-      expect(passed).toBe(false);
-      expect(failedTypes).toContain('fail-ext');
-      
-      gate.unregisterExtension('fail-ext');
-    });
-  });
 });