@dommaker/harness 1.3.0 → 1.5.0

package/src/release/__tests__/barrel.test.ts

@@ -0,0 +1,60 @@
+/**
+ * release barrel 导出面守卫（harness#92，ADR-0003 一致性收口）
+ *
+ * barrel 只再导出包根公开面：`getCriticalArtifacts` / `verifyReleaseArtifacts` /
+ * `ArtifactIntegrityResult`。构件清单助手（HARNESS_PACKAGE_NAME、
+ * EXTRA_CRITICAL_ARTIFACTS、deriveCriticalArtifacts、resolvePackageRoot +
+ * PackagePublishManifest、PackageExports 类型）属 integrity.ts 内部 seam，
+ * 唯一消费方 integrity.test.ts 直接 `from '../integrity'`，不经 barrel。
+ * 值面靠下面的运行时键集合断言；类型面无运行时痕迹，靠两条 @ts-expect-error
+ * 在编译期把关——barrel 一旦恢复再导出，指令失效即报错。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  HARNESS_PACKAGE_NAME,
+  EXTRA_CRITICAL_ARTIFACTS,
+  deriveCriticalArtifacts,
+  resolvePackageRoot,
+} from '../integrity';
+import type { PackagePublishManifest as InternalManifest } from '../integrity';
+// @ts-expect-error PackagePublishManifest 属 integrity.ts 内部类型，不经 barrel 导出（harness#92）
+import type { PackagePublishManifest } from '../index';
+// @ts-expect-error PackageExports 属 integrity.ts 内部类型，不经 barrel 导出（harness#92）
+import type { PackageExports } from '../index';
+
+describe('release barrel 导出面（harness#92）', () => {
+  it('barrel 运行时只再导出包根公开的两个函数', async () => {
+    const mod = await import('../index');
+    expect(Object.keys(mod).sort()).toEqual(['getCriticalArtifacts', 'verifyReleaseArtifacts']);
+  });
+
+  it('barrel 导出面不含内部清单符号与清单类型名', async () => {
+    const mod = await import('../index');
+    for (const internal of [
+      'HARNESS_PACKAGE_NAME',
+      'EXTRA_CRITICAL_ARTIFACTS',
+      'deriveCriticalArtifacts',
+      'resolvePackageRoot',
+      'PackagePublishManifest',
+      'PackageExports',
+    ]) {
+      expect(mod).not.toHaveProperty(internal);
+    }
+    // 两个清单类型只能在编译期证伪，此处消费导入名让上面的 @ts-expect-error 进入生效路径
+    const manifestFromBarrel = null as PackagePublishManifest | null;
+    const exportsFromBarrel = null as PackageExports | null;
+    expect([manifestFromBarrel, exportsFromBarrel]).toEqual([null, null]);
+  });
+
+  it('收回私有不等于删除：内部 seam 仍在 integrity.ts 就地可达', () => {
+    const manifest: InternalManifest = { name: HARNESS_PACKAGE_NAME };
+    expect(deriveCriticalArtifacts(manifest)).toEqual([]);
+    expect(EXTRA_CRITICAL_ARTIFACTS.length).toBeGreaterThan(0);
+    const pkgRoot = resolvePackageRoot(__dirname);
+    const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
+    expect(pkg.name).toBe(HARNESS_PACKAGE_NAME);
+  });
+});

package/src/release/index.ts

@@ -1,13 +1,2 @@
-export {
-  HARNESS_PACKAGE_NAME,
-  EXTRA_CRITICAL_ARTIFACTS,
-  deriveCriticalArtifacts,
-  resolvePackageRoot,
-  getCriticalArtifacts,
-  verifyReleaseArtifacts,
-} from './integrity';
-export type {
-  PackagePublishManifest,
-  PackageExports,
-  ArtifactIntegrityResult,
-} from './integrity';
+export { getCriticalArtifacts, verifyReleaseArtifacts } from './integrity';
+export type { ArtifactIntegrityResult } from './integrity';

package/src/sdd/__tests__/index-generator.test.ts

@@ -147,4 +147,75 @@ describe('SDDIndexGenerator', () => {
     expect(result.entries[0].slug).toBe('alpha');
     expect(result.entries[1].slug).toBe('zebra');
   });
+
+  describe('frontmatter 收口（harness#89）', () => {
+    let errorSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+      errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      errorSpy.mockRestore();
+    });
+
+    function writeRaw(slug: string, raw: string): void {
+      const dir = path.join(sddDir, slug);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, 'requirement.md'), raw);
+    }
+
+    it('未闭合：跳过并显式上报（收口前静默跳过）', () => {
+      writeRaw('broken-open', '---\nslug: broken-open\nstatus: done\ntitle: "断头"\n');
+
+      const result = new SDDIndexGenerator(tmpDir).regenerate();
+
+      expect(result.count).toBe(0);
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[harness\].*unterminated.*broken-open/);
+    });
+
+    it('闭合行不完整（--- 后带内容）：不再当闭合——上报并跳过（收口前会静默收录该条）', () => {
+      writeRaw('bad-close', '---\nslug: bad-close\nstatus: done\n---broken\n\n# 正文\n');
+
+      const result = new SDDIndexGenerator(tmpDir).regenerate();
+
+      expect(result.count).toBe(0);
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[harness\].*unterminated/);
+    });
+
+    it('YAML 非法：跳过并上报 invalid-yaml（收口前静默跳过）', () => {
+      writeRaw('bad-yaml', '---\nslug: [1,\n---\n\n# 正文\n');
+
+      const result = new SDDIndexGenerator(tmpDir).regenerate();
+
+      expect(result.count).toBe(0);
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[harness\].*invalid-yaml/);
+    });
+
+    it('缺 frontmatter 与空 meta：静默跳过（absent 是合法输入，不上报）', () => {
+      writeRaw('no-fm', '# 没有 frontmatter\n\n正文\n');
+      writeRaw('empty-meta', '---\n\n---\n\n# 空头\n');
+
+      const result = new SDDIndexGenerator(tmpDir).regenerate();
+
+      expect(result.count).toBe(0);
+      expect(errorSpy).not.toHaveBeenCalled();
+    });
+
+    it('正文含 --- 分隔线不影响 meta 解析（sdd 只取 meta，body 有意忽略）', () => {
+      writeRaw(
+        'with-rules',
+        '---\nslug: with-rules\nstatus: done\ntitle: "带分隔线"\n---\n\n# 带分隔线\n\n---\n\n## 处置\n'
+      );
+
+      const result = new SDDIndexGenerator(tmpDir).regenerate();
+
+      expect(result.count).toBe(1);
+      expect(result.entries[0].title).toBe('带分隔线');
+      expect(errorSpy).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/sdd/index-generator.ts

@@ -4,7 +4,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'js-yaml';
+import { splitFrontmatter } from '../utils/frontmatter';
 
 const INDEX_FILENAME = '_index.md';
 
@@ -54,7 +54,7 @@ export class SDDIndexGenerator {
       if (!fs.existsSync(reqPath)) continue;
 
       const content = fs.readFileSync(reqPath, 'utf-8');
-      const fm = this.parseFrontmatter(content);
+      const fm = this.parseFrontmatter(reqPath, content);
       if (!fm) continue;
 
       // Skip stale SDDs
@@ -73,14 +73,14 @@ export class SDDIndexGenerator {
     return entries;
   }
 
-  private parseFrontmatter(content: string): Record<string, unknown> | null {
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match) return null;
-    try {
-      return yaml.load(match[1]) as Record<string, unknown> || null;
-    } catch {
-      return null;
+  private parseFrontmatter(filePath: string, content: string): Record<string, unknown> | null {
+    const fm = splitFrontmatter(content);
+    if (fm.state === 'ok') return fm.meta;
+    if (fm.state === 'malformed') {
+      // 统一口径（harness#89）：损坏必须显式上报后跳过，不静默丢条目
+      console.error(`[harness] SDD 索引 frontmatter ${fm.reason}（${fm.detail}），已跳过 ${filePath}`);
     }
+    return null;
   }
 
   private sanitize(s: string): string {

package/src/test-setup/__tests__/project-fixture.test.ts

@@ -0,0 +1,178 @@
+/**
+ * project-fixture 构造 API 测试（架构评审 2026-09-02 候选11 / harness#90）
+ *
+ * 钉死三条契约：
+ * 1) 缺省根 = os.tmpdir()，`config` 槽位逐字节落 `.harness/config.yml`（不做 YAML 往返——
+ *    被检代码大量用例是畸形/脏配置，原样落盘是硬需求）；
+ * 2) 非缺省根必须经 parentDir **显式**声明（cwd 锚定用例的前置约束，不隐式继承默认根）；
+ * 3) 建出的根由 mkdtemp 劫持登记 = 用例结束自动清理，且 name 形状可被超龄兜底清扫识别。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createProjectFixture, writeProjectConfig, writeProjectTraces } from '../project-fixture';
+import { isRegisteredTmpDir } from '../mkdtemp-cleanup';
+import { DEFAULT_TRACE_FILE } from '../../types/trace';
+
+/** mkdtemp-cleanup.ts 的超龄清扫签名（name 不合规的夹具目录漏网后永不被扫） */
+const SWEEP_SIGNATURE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*-[A-Za-z0-9]{6}$/;
+
+describe('createProjectFixture — 根与 config 槽位', () => {
+  it('缺省根在 os.tmpdir()，config 逐字节落 .harness/config.yml', () => {
+    const root = createProjectFixture({ name: 'pfx-default', config: 'preset: standard\n' });
+
+    expect(path.dirname(root)).toBe(os.tmpdir());
+    expect(fs.readFileSync(path.join(root, '.harness', 'config.yml'), 'utf-8')).toBe('preset: standard\n');
+  });
+
+  it('省略 config → 不写 .harness/config.yml（存在性探测类用例依赖此语义）', () => {
+    const root = createProjectFixture({ name: 'pfx-no-config' });
+
+    expect(fs.existsSync(path.join(root, '.harness', 'config.yml'))).toBe(false);
+    expect(fs.existsSync(path.join(root, '.harness'))).toBe(false);
+  });
+
+  it('config 为空字符串仍算声明（falsy 不得退化为“不写”）', () => {
+    const root = createProjectFixture({ name: 'pfx-empty-config', config: '' });
+
+    expect(fs.readFileSync(path.join(root, '.harness', 'config.yml'), 'utf-8')).toBe('');
+  });
+
+  it('files 按相对路径落盘，父目录自动创建', () => {
+    const root = createProjectFixture({
+      name: 'pfx-files',
+      files: {
+        'src/core/foo.ts': 'export const x = 1;',
+        'src/CONTEXT.md': '# src\n',
+        '.harness/custom-constraints.yml': 'custom_constraints: {}\n',
+      },
+    });
+
+    expect(fs.readFileSync(path.join(root, 'src/core/foo.ts'), 'utf-8')).toBe('export const x = 1;');
+    expect(fs.readFileSync(path.join(root, 'src/CONTEXT.md'), 'utf-8')).toBe('# src\n');
+    // 通用槽位不得踩 config 正本路径：两者共存时各写各的
+    expect(fs.readFileSync(path.join(root, '.harness/custom-constraints.yml'), 'utf-8')).toBe(
+      'custom_constraints: {}\n'
+    );
+    expect(fs.existsSync(path.join(root, '.harness/config.yml'))).toBe(false);
+  });
+
+  it('config 与 files 同时声明 → 两侧都落盘', () => {
+    const root = createProjectFixture({
+      name: 'pfx-both',
+      config: 'preset: relaxed\n',
+      files: { 'CAPABILITIES.md': '# Capabilities\n' },
+    });
+
+    expect(fs.readFileSync(path.join(root, '.harness/config.yml'), 'utf-8')).toBe('preset: relaxed\n');
+    expect(fs.readFileSync(path.join(root, 'CAPABILITIES.md'), 'utf-8')).toBe('# Capabilities\n');
+  });
+});
+
+describe('createProjectFixture — 显式 opt-out 根', () => {
+  it('parentDir 声明的根落在该父目录下，而非缺省 tmpdir', () => {
+    const parent = createProjectFixture({ name: 'pfx-parent' });
+    const root = createProjectFixture({ name: 'pfx-child', parentDir: parent });
+
+    expect(path.dirname(root)).toBe(parent);
+    expect(root.startsWith(path.join(parent, 'pfx-child-'))).toBe(true);
+  });
+
+  it('parentDir: process.cwd() → 根落在仓库工作目录（cwd 锚定套件依赖的正是这条语义）', () => {
+    const root = createProjectFixture({ name: 'pfx-cwd-anchor', parentDir: process.cwd() });
+    try {
+      expect(path.dirname(root)).toBe(process.cwd());
+      expect(fs.existsSync(root)).toBe(true);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('opt-out 用例仍被 mkdtemp 劫持登记（自动清理不依赖调用方手动 rm）', () => {
+    const parent = createProjectFixture({ name: 'pfx-optout-parent' });
+    const root = createProjectFixture({ name: 'pfx-optout-child', parentDir: parent });
+
+    expect(isRegisteredTmpDir(root)).toBe(true);
+  });
+
+  it('缺省根同样登记，且目录名符合超龄清扫签名（漏网目录可被兜底扫掉）', () => {
+    const root = createProjectFixture({ name: 'pfx-sweepable' });
+
+    expect(isRegisteredTmpDir(root)).toBe(true);
+    expect(SWEEP_SIGNATURE.test(path.basename(root))).toBe(true);
+  });
+
+  it('name 形状不合规（大写/下划线/空）→ 抛错，不静默产出扫不掉的目录', () => {
+    expect(() => createProjectFixture({ name: 'Pfx-Bad' })).toThrow(/name/);
+    expect(() => createProjectFixture({ name: 'pfx_bad' })).toThrow(/name/);
+    expect(() => createProjectFixture({ name: '' })).toThrow(/name/);
+  });
+});
+
+describe('writeProjectConfig — config 落盘唯一正本', () => {
+  it('根下无 .harness 时自动建目录并写入', () => {
+    const root = createProjectFixture({ name: 'pfx-writer' });
+
+    writeProjectConfig(root, 'gates:\n  order:\n    - security\n');
+
+    expect(fs.readFileSync(path.join(root, '.harness', 'config.yml'), 'utf-8')).toBe(
+      'gates:\n  order:\n    - security\n'
+    );
+  });
+
+  it('已有 config 时覆盖写（用例内后续改配置不叠加旧内容）', () => {
+    const root = createProjectFixture({ name: 'pfx-rewrite', config: 'preset: standard\n' });
+
+    writeProjectConfig(root, 'preset: relaxed\n');
+
+    expect(fs.readFileSync(path.join(root, '.harness', 'config.yml'), 'utf-8')).toBe('preset: relaxed\n');
+  });
+});
+
+describe('traces 槽位 / writeProjectTraces — trace 落盘正本（harness#108）', () => {
+  it('traces 槽位逐条落 DEFAULT_TRACE_FILE，缺省字段补齐（level/timestamp/result）', () => {
+    const root = createProjectFixture({
+      name: 'pfx-traces',
+      traces: [{ constraintId: 'c1', result: 'fail' }],
+    });
+
+    const lines = fs.readFileSync(path.join(root, DEFAULT_TRACE_FILE), 'utf-8').trim().split('\n');
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0])).toEqual({
+      level: 'guideline',
+      timestamp: 1700000000000,
+      result: 'fail',
+      constraintId: 'c1',
+    });
+  });
+
+  it('traces 槽位缺省 → 不写 trace 文件（traceFileExists=false 用例依赖此语义）', () => {
+    const root = createProjectFixture({ name: 'pfx-no-traces' });
+
+    expect(fs.existsSync(path.join(root, DEFAULT_TRACE_FILE))).toBe(false);
+  });
+
+  it('writeProjectTraces 空数组仍落空文件（traceFileExists=true、零记录语义）', () => {
+    const root = createProjectFixture({ name: 'pfx-empty-traces' });
+
+    writeProjectTraces(root, []);
+
+    expect(fs.existsSync(path.join(root, DEFAULT_TRACE_FILE))).toBe(true);
+    expect(fs.readFileSync(path.join(root, DEFAULT_TRACE_FILE), 'utf-8')).toBe('');
+  });
+
+  it('writeProjectTraces 覆盖写：用例内重写不叠加旧记录', () => {
+    const root = createProjectFixture({
+      name: 'pfx-rewrite-traces',
+      traces: [{ constraintId: 'old' }],
+    });
+
+    writeProjectTraces(root, [{ constraintId: 'new' }]);
+
+    const lines = fs.readFileSync(path.join(root, DEFAULT_TRACE_FILE), 'utf-8').trim().split('\n');
+    expect(lines).toHaveLength(1);
+    expect(JSON.parse(lines[0]).constraintId).toBe('new');
+  });
+});

package/src/test-setup/project-fixture.ts

@@ -0,0 +1,87 @@
+/**
+ * 测试项目夹具构造 API（架构评审 2026-09-02 候选11 / harness#90）
+ *
+ * 职责：建一个临时项目根并按声明落 fixture，替掉散在各测试套件的
+ * `mkdtempSync + mkdir('.harness') + writeFileSync('config.yml')` 手写组合。
+ *
+ * 设计口径（triage 裁决）：
+ * - **语义声明**而非文件树声明：`config`/`traces` 是独立槽位（`.harness/config.yml`
+ *   与 `DEFAULT_TRACE_FILE` 的形状正本只有这里知道），其余文件走 `files` 相对路径。
+ *   constraints/knowledge 槽位随后续票补。
+ * - `config` 只收字符串、原样落盘：被检代码大量用例是畸形/脏配置（`governance: [`、
+ *   `required_dirs: [1, null]`、未知 preset 名），YAML 往返会把这些用例抹平。
+ * - 非缺省根必须经 `parentDir` **显式**声明：默认根统一为 tmpdir，
+ *   路径锚定生产代码的用例（cwd 锚定）靠 opt-out 保持原语义，不隐式继承。
+ * - 清理不在本模块做：根经 `fs.mkdtempSync` 创建，由 ./mkdtemp-cleanup 的劫持在
+ *   afterAll 统一回收（setupFilesAfterEnv 已全局装载）。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { DEFAULT_TRACE_FILE, type ExecutionTrace } from '../types/trace';
+import { appendJsonl } from '../utils/jsonl';
+
+/** config.yml 相对项目根的落点（全仓唯一处，测试与生产读取口径在此对齐） */
+const CONFIG_REL = path.join('.harness', 'config.yml');
+
+/** name 只允许小写字母数字与连字符——见 mkdtemp-cleanup 的超龄清扫签名，大写/下划线会让漏网目录永不被扫 */
+const NAME_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+export interface ProjectFixtureDecl {
+  /** 用例标签，进入 mkdtemp 前缀（残留目录可定位到用例）；小写连字符 */
+  name: string;
+  /** `.harness/config.yml` 内容，原样落盘；省略 = 不写该文件（未采用约定语义） */
+  config?: string;
+  /**
+   * trace 槽位（harness#108）：落 `DEFAULT_TRACE_FILE` 的 JSONL 记录；
+   * 省略 = 不写该文件（traceFileExists=false 语义）。缺省字段补齐见 writeProjectTraces
+   */
+  traces?: Partial<ExecutionTrace>[];
+  /** 其余文件：相对路径 → 内容，父目录自动创建 */
+  files?: Record<string, string>;
+  /** 显式 opt-out：临时根的父目录，缺省 `os.tmpdir()`；cwd 锚定用例传 `process.cwd()` */
+  parentDir?: string;
+}
+
+/** 写入（或覆盖）项目根的 `.harness/config.yml`——用例内后续改配置走这里，不再手拼路径 */
+export function writeProjectConfig(projectRoot: string, content: string): void {
+  const target = path.join(projectRoot, CONFIG_REL);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content, 'utf-8');
+}
+
+/**
+ * 写入（或覆盖）项目根的 trace 文件——路径锚定生产正本 DEFAULT_TRACE_FILE，
+ * 序列化走生产写链 appendJsonl（harness#108：测试不再手拼路径与 JSONL 形状，
+ * 生产端改格式时测试随之失真可见而非静默脱节）。
+ *
+ * 缺省字段补齐 level/timestamp/result（与原各套件 writeTraces 的口径一致），
+ * 调用方按需覆盖。覆盖语义：先清空再逐条 append；空数组仍落空文件
+ * （traceFileExists=true、零记录）。
+ */
+export function writeProjectTraces(projectRoot: string, traces: Partial<ExecutionTrace>[]): void {
+  const target = path.join(projectRoot, DEFAULT_TRACE_FILE);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, '', 'utf-8');
+  for (const t of traces) {
+    appendJsonl(target, { level: 'guideline', timestamp: 1700000000000, result: 'pass', ...t });
+  }
+}
+
+/** 建临时项目根并落声明式 fixture，返回根路径 */
+export function createProjectFixture(decl: ProjectFixtureDecl): string {
+  if (!NAME_RE.test(decl.name)) {
+    throw new Error(`project-fixture: name 必须是小写连字符标签（收到 "${decl.name}"），否则残留目录无法被超龄清扫识别`);
+  }
+  const parent = decl.parentDir ?? os.tmpdir();
+  const root = fs.mkdtempSync(path.join(parent, `${decl.name}-`));
+  if (decl.config !== undefined) writeProjectConfig(root, decl.config);
+  if (decl.traces !== undefined) writeProjectTraces(root, decl.traces);
+  for (const [rel, content] of Object.entries(decl.files ?? {})) {
+    const target = path.join(root, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf-8');
+  }
+  return root;
+}

package/src/tools/CONTEXT.md

@@ -13,6 +13,12 @@
 ## 约定
 - 工具定义目录路径由 paths 模块解析
 - `definitions/` 为静态能力目录，构建时复制到 dist
+- **yml 目录是正本、`registry.json` 是派生索引**（#91 裁决）：二者一致性由 `__tests__/registry.test.ts`
+  按 ADR-0009 的 reconcile 形状守（双向集合对照 + 条目 path 指向存在的 yml + `name` 与 yml 内 `name` 一致）。
+  新增能力 = 先落 yml，再补 registry 条目，缺一即测试红。**不做 yml schema 校验**——那等于替 studio 定能力契约。
+  `rollback` 重名 ×2（std/deploy 与 std/governance）是既有事实，进豁免名单；重名是否合法另票裁决。
+- `paths.ts` 单变方**不是**假 seam（#91 裁决）：它是包根公开导出（`src/index.ts`，由 public-exports 测试钉住），
+  实际消费方是 studio 外部仓，本仓内无第二调用方属预期形状，留任
 
 ## 注意事项
 - 旧工具注册表/核心工具/加载器/类型定义已随 H1（#40）删除，仅保留路径管理与能力目录