@dommaker/harness 1.2.3 → 1.3.0

package/src/release/CONTEXT.md

@@ -0,0 +1,23 @@
+# release/
+
+## 职责
+发布物完整性自检：harness 自己声明并校验自己发布了什么。关键发布物清单的单一来源，替代外部（studio publishPackage）与本仓 release 命令各自的 dist 文件硬编码（harness#77，#75 N4 收编）。
+
+## 核心导出
+- `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__/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,13 @@
+export {
+  HARNESS_PACKAGE_NAME,
+  EXTRA_CRITICAL_ARTIFACTS,
+  deriveCriticalArtifacts,
+  resolvePackageRoot,
+  getCriticalArtifacts,
+  verifyReleaseArtifacts,
+} from './integrity';
+export type {
+  PackagePublishManifest,
+  PackageExports,
+  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/types/failure.ts

@@ -5,6 +5,14 @@
  * 不包含业务逻辑，只定义数据结构
  */
 
+/**
+ * 默认 failure 日志路径（相对项目根目录）
+ *
+ * 读写双方必须统一引用此常量（DEFAULT_TRACE_FILE 同款先例）；
+ * 自定义路径时向 FailureRecorder 传入自定 logFile
+ */
+export const DEFAULT_FAILURE_LOG_FILE = '.harness/logs/failures.log';
+
 /**
  * 错误类型枚举
  */