@dommaker/harness 1.2.3 → 1.4.0

package/src/release/CONTEXT.md

@@ -0,0 +1,24 @@
+# release/
+
+## 职责
+发布物完整性自检：harness 自己声明并校验自己发布了什么。关键发布物清单的单一来源，替代外部（studio publishPackage）与本仓 release 命令各自的 dist 文件硬编码（harness#77，#75 N4 收编）。
+
+## 核心导出
+下列符号都由 `integrity.ts` 就地导出；`index.ts` barrel 只再导出标「公开 API」的那一组，其余属模块内部 seam——仓内消费方直接 `from './integrity'`，导出面由 `__tests__/barrel.test.ts` 守卫（harness#92）。
+- `deriveCriticalArtifacts(manifest)`（`integrity.ts`）——从包声明面（package.json `main`/`exports`/`bin`）推导脚本入口清单（.js/.cjs/.mjs/.d.ts，去 `./` 前缀、剔除非脚本叶子、去重排序）；纯函数
+- `EXTRA_CRITICAL_ARTIFACTS`——声明面推导之外的运行时关键发布物（bin/harness.js 引导期 require 的命令/门禁定义表、`dist/tools/definitions` 数据目录）；与其描述的文件同仓同评审，删改须同步
+- `resolvePackageRoot(fromDir?)`——从模块位置向上按包名解析本包根（源码仓与 node_modules 安装态均可达）
+- `getCriticalArtifacts(pkgRoot?)` / `verifyReleaseArtifacts(pkgRoot?)`——公开 API；pkgRoot 缺省自动解析，外部消费者零参数即自检已安装的 harness
+
+## 依赖关系
+- 无内部依赖（只依赖 node fs/path）
+
+## 约定
+- 清单维护模型：声明面推导为主（目录重构动到 package.json 时清单自动跟随）+ extras 随源码维护；**不新增第三处硬编码清单**
+- 覆盖口径（有意裁决，#77）：深度内部文件（tsc 产出的 dist/knowledge/*、core/constraints/checker.js 等）**不在清单**——非公开契约，存在性由 tsc 构建成功保证；历史上外部硬编码它们正是重构误判（studio 6cf3c329）的根因。旧 studio 清单 checker.js/doctor.js、旧 release 清单 13 项均被本清单取代，覆盖收窄是裁决而非遗漏
+- `__tests__/integrity.test.ts` 的「真实包根清单同步闸门」是重构同步闸门：动 exports/main/bin 或 extras 时该测试强制同步
+- bin 新增引导期 require 的 dist 文件 → extras 加一条 + 测试同步
+
+## 注意事项
+- 挂载点：`harness release` 命令第 4 步（tsc 后校验 dist）；studio publishPackage dist 校验改调本能力（studio#425 配套切换）
+- 公开面只收 `getCriticalArtifacts` / `verifyReleaseArtifacts` + `ArtifactIntegrityResult`（ADR-0003）；derive/resolve 属内部 seam

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/__tests__/integrity.test.ts

@@ -0,0 +1,157 @@
+/**
+ * 发布物完整性自检测试（harness#77，#75 N4 收编）
+ *
+ * 覆盖：声明面推导（main/exports/bin）、extras 清单守卫、包根向上解析、
+ * 存在性校验、真实包根清单同步闸门。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  HARNESS_PACKAGE_NAME,
+  EXTRA_CRITICAL_ARTIFACTS,
+  deriveCriticalArtifacts,
+  resolvePackageRoot,
+  getCriticalArtifacts,
+  verifyReleaseArtifacts,
+} from '../integrity';
+import type { PackagePublishManifest } from '../integrity';
+
+/** 建临时 fixture 包根：写 package.json + 按清单造文件/目录 */
+function makeFixture(manifest: PackagePublishManifest, artifacts: string[]): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-release-integrity-'));
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify(manifest));
+  for (const artifact of artifacts) {
+    const abs = path.join(root, artifact);
+    if (/\.[cm]?js$|\.d\.ts$/.test(artifact)) {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, '');
+    } else {
+      fs.mkdirSync(abs, { recursive: true });
+    }
+  }
+  return root;
+}
+
+describe('deriveCriticalArtifacts', () => {
+  it('收集 main/exports/bin 声明的脚本入口，去 ./ 前缀、去重、排序，非脚本叶子剔除', () => {
+    const manifest: PackagePublishManifest = {
+      name: HARNESS_PACKAGE_NAME,
+      main: './dist/index.js',
+      bin: { harness: './bin/harness.js' },
+      exports: {
+        '.': {
+          types: './dist/index.d.ts',
+          require: './dist/index.js',
+          import: './dist/index.js',
+        },
+        './core': './dist/core/index.js',
+        './package.json': './package.json',
+      },
+    };
+    expect(deriveCriticalArtifacts(manifest)).toEqual([
+      'bin/harness.js',
+      'dist/core/index.js',
+      'dist/index.d.ts',
+      'dist/index.js',
+    ]);
+  });
+
+  it('exports 为字符串、bin 为字符串、null 条目（兜底禁用）安全', () => {
+    const manifest: PackagePublishManifest = {
+      name: HARNESS_PACKAGE_NAME,
+      main: 'dist/index.js',
+      bin: 'bin/harness.js',
+      exports: { '.': './dist/index.js', './forbidden': null },
+    };
+    expect(deriveCriticalArtifacts(manifest)).toEqual(['bin/harness.js', 'dist/index.js']);
+  });
+
+  it('无声明字段返回空清单', () => {
+    expect(deriveCriticalArtifacts({ name: HARNESS_PACKAGE_NAME })).toEqual([]);
+  });
+});
+
+describe('EXTRA_CRITICAL_ARTIFACTS', () => {
+  it('覆盖 bin 引导定义表与 tools 运行时数据目录（随源码维护，删改须同评审）', () => {
+    expect(EXTRA_CRITICAL_ARTIFACTS).toEqual([
+      'dist/cli/commands/definitions.js',
+      'dist/gates/definitions.js',
+      'dist/tools/definitions',
+    ]);
+  });
+});
+
+describe('resolvePackageRoot', () => {
+  it('从源码位置向上解析到本仓包根', () => {
+    const root = resolvePackageRoot(__dirname);
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
+    expect(pkg.name).toBe(HARNESS_PACKAGE_NAME);
+  });
+
+  it('无匹配包根时抛错并提示显式传入 pkgRoot', () => {
+    const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-no-pkg-root-'));
+    const nested = path.join(bare, 'deep', 'nested');
+    fs.mkdirSync(nested, { recursive: true });
+    expect(() => resolvePackageRoot(nested)).toThrow(/pkgRoot/);
+  });
+});
+
+describe('getCriticalArtifacts / verifyReleaseArtifacts（fixture 包根）', () => {
+  const FIXTURE_MANIFEST: PackagePublishManifest = {
+    name: HARNESS_PACKAGE_NAME,
+    main: './dist/index.js',
+    bin: './bin/harness.js',
+    exports: { '.': './dist/index.js' },
+  };
+  const FIXTURE_ARTIFACTS = [
+    'dist/index.js',
+    'bin/harness.js',
+    ...EXTRA_CRITICAL_ARTIFACTS,
+  ];
+
+  it('清单 = 声明面推导 + extras', () => {
+    const root = makeFixture(FIXTURE_MANIFEST, FIXTURE_ARTIFACTS);
+    expect(getCriticalArtifacts(root)).toEqual([
+      'bin/harness.js',
+      'dist/cli/commands/definitions.js',
+      'dist/gates/definitions.js',
+      'dist/index.js',
+      'dist/tools/definitions',
+    ]);
+  });
+
+  it('全部就位 → ok:true', () => {
+    const root = makeFixture(FIXTURE_MANIFEST, FIXTURE_ARTIFACTS);
+    const result = verifyReleaseArtifacts(root);
+    expect(result).toMatchObject({ ok: true, pkgRoot: root, missing: [] });
+  });
+
+  it('缺文件 → ok:false 且 missing 指名', () => {
+    const root = makeFixture(FIXTURE_MANIFEST, FIXTURE_ARTIFACTS);
+    fs.rmSync(path.join(root, 'dist', 'tools', 'definitions'), { recursive: true, force: true });
+    const result = verifyReleaseArtifacts(root);
+    expect(result.ok).toBe(false);
+    expect(result.missing).toEqual(['dist/tools/definitions']);
+  });
+});
+
+describe('真实包根清单同步闸门', () => {
+  it('真实 package.json 推导覆盖全部声明入口 + extras（重构动声明面时本测试强制同步）', () => {
+    const root = resolvePackageRoot(__dirname);
+    const artifacts = getCriticalArtifacts(root);
+    for (const required of [
+      'dist/index.js',
+      'dist/core/index.js',
+      'dist/presets/index.js',
+      'dist/context/index.js',
+      'dist/gates/index.js',
+      'bin/harness.js',
+      ...EXTRA_CRITICAL_ARTIFACTS,
+    ]) {
+      expect(artifacts).toContain(required);
+    }
+  });
+});

package/src/release/index.ts

@@ -0,0 +1,2 @@
+export { getCriticalArtifacts, verifyReleaseArtifacts } from './integrity';
+export type { ArtifactIntegrityResult } from './integrity';

package/src/release/integrity.ts

@@ -0,0 +1,141 @@
+/**
+ * 发布物完整性自检（harness#77，#75 N4 收编）
+ *
+ * harness 自己最知道自己发了什么：关键发布物清单不再由外部（studio publishPackage）
+ * 或本仓 release 命令各自硬编码 dist 内部文件，而是从包声明面（package.json
+ * main/exports/bin）运行时推导 + 少量运行时 extras 随源码维护——目录重构动到
+ * 声明面时清单自动跟随，extras 与其描述的文件同仓同评审。
+ *
+ * 公开面（barrel）：getCriticalArtifacts / verifyReleaseArtifacts。
+ * studio publishPackage 的 dist 校验改调本能力，替换硬编码清单（studio#425 配套切换）。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/** 本包名（包根向上解析的身份锚点，同 bin 名同源） */
+export const HARNESS_PACKAGE_NAME = '@dommaker/harness';
+
+/** package.json 发布面形状（只关心与发布物定位相关字段） */
+export interface PackagePublishManifest {
+  name?: string;
+  main?: string;
+  bin?: string | Record<string, string>;
+  exports?: PackageExports;
+}
+
+/** exports 字段形状：字符串叶子 / null（兜底禁用）/ 条件对象递归 */
+export type PackageExports = string | null | { [key: string]: PackageExports };
+
+/**
+ * 推导之外、随源码维护的运行时关键发布物。
+ * 声明面推导只覆盖入口文件；以下入口的运行时依赖由本清单兜底。
+ */
+export const EXTRA_CRITICAL_ARTIFACTS: readonly string[] = [
+  // bin/harness.js 引导期 require 的命令/门禁定义表
+  'dist/cli/commands/definitions.js',
+  'dist/gates/definitions.js',
+  // getToolsDir/getRegistryPath 运行时数据目录（build 脚本 cp -r，tsc 不产出）
+  'dist/tools/definitions',
+];
+
+const CRITICAL_SUFFIXES = ['.js', '.cjs', '.mjs', '.d.ts'];
+
+function collectExportsLeaves(exportsField: PackageExports | undefined, out: string[]): void {
+  if (typeof exportsField === 'string') {
+    out.push(exportsField);
+    return;
+  }
+  if (!exportsField || typeof exportsField !== 'object') return;
+  for (const value of Object.values(exportsField)) {
+    collectExportsLeaves(value, out);
+  }
+}
+
+/**
+ * 从包声明面推导关键发布物清单：main + bin + exports 全部脚本入口。
+ * 去 ./ 前缀，剔除非脚本叶子（如 ./package.json 自导出），去重排序。
+ */
+export function deriveCriticalArtifacts(manifest: PackagePublishManifest): string[] {
+  const collected: string[] = [];
+  if (manifest.main) collected.push(manifest.main);
+  if (typeof manifest.bin === 'string') collected.push(manifest.bin);
+  else if (manifest.bin && typeof manifest.bin === 'object') {
+    collected.push(...Object.values(manifest.bin));
+  }
+  collectExportsLeaves(manifest.exports, collected);
+  return [...new Set(
+    collected
+      .map(p => p.replace(/^\.\//, ''))
+      .filter(p => CRITICAL_SUFFIXES.some(suffix => p.endsWith(suffix)))
+  )].sort();
+}
+
+function isHarnessPackageRoot(dir: string): boolean {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+    return pkg?.name === HARNESS_PACKAGE_NAME;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 从 fromDir（缺省本模块编译位置）向上解析本包根。
+ * 源码仓（src/release → 仓根）与发布包（node_modules/@dommaker/harness/dist/release
+ * → 包根）均可达；到文件系统根仍无匹配则抛错。
+ */
+export function resolvePackageRoot(fromDir: string = __dirname): string {
+  let dir = path.resolve(fromDir);
+  for (;;) {
+    if (isHarnessPackageRoot(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `[harness] 无法从 ${fromDir} 向上定位 ${HARNESS_PACKAGE_NAME} 包根；请显式传入 pkgRoot。`
+  );
+}
+
+function resolveRoot(pkgRoot?: string): string {
+  return pkgRoot ? path.resolve(pkgRoot) : resolvePackageRoot();
+}
+
+/**
+ * 关键发布物清单（相对包根路径，排序去重）。
+ * pkgRoot 缺省时自动解析本包根——外部消费者（studio）零参数即自检已安装的 harness。
+ */
+export function getCriticalArtifacts(pkgRoot?: string): string[] {
+  const root = resolveRoot(pkgRoot);
+  const manifest: PackagePublishManifest = JSON.parse(
+    fs.readFileSync(path.join(root, 'package.json'), 'utf-8')
+  );
+  return [...new Set([...deriveCriticalArtifacts(manifest), ...EXTRA_CRITICAL_ARTIFACTS])].sort();
+}
+
+export interface ArtifactIntegrityResult {
+  ok: boolean;
+  pkgRoot: string;
+  /** 清单全量（相对包根路径） */
+  checked: string[];
+  /** 缺失项（相对包根路径） */
+  missing: string[];
+}
+
+/**
+ * 发布物完整性自检：逐项存在性校验（目录/文件均可）。
+ *
+ * 覆盖口径（有意裁决，#77）：清单只锚定声明面及其运行时依赖；深度内部文件
+ * （tsc 产出的 dist/knowledge/*、core/constraints/checker.js 等）不在清单——
+ * 它们非公开契约，存在性由 tsc 构建成功保证，历史上外部硬编码它们正是
+ * 重构误判（6cf3c329）的根因。
+ *
+ * 挂载点：harness release 命令第 4 步；studio publishPackage dist 校验（配套切换 studio#425）。
+ */
+export function verifyReleaseArtifacts(pkgRoot?: string): ArtifactIntegrityResult {
+  const root = resolveRoot(pkgRoot);
+  const checked = getCriticalArtifacts(root);
+  const missing = checked.filter(f => !fs.existsSync(path.join(root, f)));
+  return { ok: missing.length === 0, pkgRoot: root, checked, missing };
+}

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 {