@dommaker/harness 1.2.3 → 1.4.0

package/dist/utils/jsonl.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * append-only JSONL 日志读写正本（harness#82，架构评审 2026-09-02 候选3）
+ *
+ * 全仓 append-only JSONL（traces.log / failures.log / context-tracker.log /
+ * references.jsonl / sessions/<id>/events.jsonl / 外部 transcript .jsonl）的
+ * exists → read → split → parse → filter 读链与 ensureDir + append 写链
+ * 收口于此，仓内不允许存在第二份副本。
+ *
+ * 坏行策略（harness#82 裁决 1）：读入口 policy 为显式必填参数，类型层面无缺省，
+ * 每个调用点必须逐一声明 'skip' | 'throw'——既不让「静默丢数据」成为框架缺省，
+ * 也不反转既有容错调用点的语义。坏行指非空但 JSON.parse 失败的行
+ * （半写入截断、手工编辑、磁盘满等）。
+ *
+ * tail / head：只解析尾部 / 头部 N 个非空行（文件仍全量读取，parse 才是大头），
+ * 供「只看最近 K 条」的调用点避免全量 parse（check 等热路径）。
+ * countJsonlLines 供纯计数消费方（完全不 parse）。
+ *
+ * 计数去向（harness#100）：本模块是坏行计数的唯一正本，但正本≠终点——凡以 'skip'
+ * 策略读，调用点必须把 skippedLines 带到该消费面的用户可见输出（CLI 走 stderr，
+ * 结构化输出与 API 走字段），或显式记名豁免并写明理由。机器可检面：
+ * `src/utils/__tests__/jsonl-skip-disposition.test.ts`（冻结站点集合 + 要求每个读点
+ * 上方声明 `计数去向：`）。
+ *
+ * 豁免清单与机械核查（期望命中数）：
+ *   grep -rnE "JSON\.parse\((line|trimmed|l)\b" src --include='*.ts' | grep -v __tests__
+ *     → 期望 1 处：本文件 readJsonl（读链正本本体）
+ *   grep -rn "map(JSON.parse" src --include='*.ts' | grep -v __tests__
+ *     → 期望 0 处
+ *   __tests__ 下的坏行 fixture 不在核查范围。
+ * 其余裁决豁免：readIfExists（injection-writer，string|null 形态不同，#82 裁决 3）；
+ * FailureRecorder 轮换链（文件生命周期不变量，裁决 2）；
+ * 单 JSON 文档读取（package.json / .state.json / checkpoint.json / summary 等非 JSONL）。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readJsonl = readJsonl;
+exports.countJsonlLines = countJsonlLines;
+exports.readJsonlEnds = readJsonlEnds;
+exports.appendJsonl = appendJsonl;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** exists → read → split → filter 空行的公共前缀（正本唯一一份） */
+function readNonEmptyLines(filePath) {
+    if (!fs.existsSync(filePath))
+        return [];
+    return fs
+        .readFileSync(filePath, 'utf-8')
+        .split('\n')
+        .filter(line => line.trim().length > 0);
+}
+/**
+ * 读取 JSONL 文件：exists → read → split → parse → filter（正本读链）
+ *
+ * policy 必填无缺省（裁决 1）；缺文件返回空结果，不抛。
+ */
+function readJsonl(filePath, policy, options) {
+    let lines = readNonEmptyLines(filePath);
+    if (options?.head !== undefined) {
+        lines = options.head > 0 ? lines.slice(0, options.head) : [];
+    }
+    if (options?.tail !== undefined) {
+        lines = options.tail > 0 ? lines.slice(-options.tail) : [];
+    }
+    const records = [];
+    let skippedLines = 0;
+    for (const line of lines) {
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch (error) {
+            if (policy === 'throw')
+                throw error;
+            skippedLines++;
+        }
+    }
+    return { records, skippedLines };
+}
+/**
+ * 统计非空行数（含坏行，完全不 parse）
+ *
+ * 供只关心记录条数的调用点（如 check 智能提示）避免全量 parse；
+ * 缺文件返回 0。
+ */
+function countJsonlLines(filePath) {
+    return readNonEmptyLines(filePath).length;
+}
+/**
+ * 只取首尾：首/末条合法记录 + 原始行数，parse 停在两端首个合法行
+ *
+ * 供只要「总数 + 首末记录」的调用点（如 TraceCollector.getStats）避免全量
+ * parse；行文本仍整读（10MB 级文本读廉价，JSON.parse 才是成本）。坏行策略
+ * 同 readJsonl：'skip' 跳过继续找，'throw' 遇坏行上抛。缺文件返回
+ * { totalLines: 0 }。
+ */
+function readJsonlEnds(filePath, policy) {
+    const lines = readNonEmptyLines(filePath);
+    let first;
+    for (let i = 0; i < lines.length; i++) {
+        try {
+            first = JSON.parse(lines[i]);
+            break;
+        }
+        catch (error) {
+            if (policy === 'throw')
+                throw error;
+        }
+    }
+    let last;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            last = JSON.parse(lines[i]);
+            break;
+        }
+        catch (error) {
+            if (policy === 'throw')
+                throw error;
+        }
+    }
+    return { totalLines: lines.length, first, last };
+}
+/**
+ * 追加一条 JSONL 记录：ensureDir + append（正本写链）
+ *
+ * 目录不存在时递归创建；value 序列化为单行 JSON + 换行。
+ */
+function appendJsonl(filePath, value) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.appendFileSync(filePath, JSON.stringify(value) + '\n', 'utf-8');
+}
+//# sourceMappingURL=jsonl.js.map

package/dist/utils/jsonl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.js","sourceRoot":"","sources":["../../src/utils/jsonl.ts"],"names":[],"mappings":"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"}

package/dist/utils/package-version.d.ts

@@ -0,0 +1,16 @@
+/**
+ * harness 包版本读取正本（#102，架构评审 A3）
+ *
+ * 「harness 包版本」此前散在四处五种写法（constraints.ts 带 cwd 兜底、init.ts
+ * require 与内联各一份、injection-drift.ts / constraints-retire.ts __dirname
+ * 相对路径）。其中 cwd 兜底在 harness 装进消费者 node_modules 且相对路径失败时
+ * 会读到**消费者自己的版本号**——这是本模块要消灭的 bug。语义在此一处定义：
+ *
+ * - 只读本模块自身的 package.json（__dirname 相对；src 与 dist 目录深度一致，
+ *   两种加载方式命中同一份清单）；
+ * - 无 cwd 兜底——cwd 的 package.json 是消费者项目的，不是 harness 的；
+ * - 清单缺失/损坏/无 version 字段 → 'unknown'（沿用收口前各处一致语义）。
+ */
+/** 读取 harness 包版本；读不到（缺失/损坏/无 version 字段）返回 'unknown' */
+export declare function getHarnessPackageVersion(): string;
+//# sourceMappingURL=package-version.d.ts.map

package/dist/utils/package-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../../src/utils/package-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,yDAAyD;AACzD,wBAAgB,wBAAwB,IAAI,MAAM,CAQjD"}

package/dist/utils/package-version.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * harness 包版本读取正本（#102，架构评审 A3）
+ *
+ * 「harness 包版本」此前散在四处五种写法（constraints.ts 带 cwd 兜底、init.ts
+ * require 与内联各一份、injection-drift.ts / constraints-retire.ts __dirname
+ * 相对路径）。其中 cwd 兜底在 harness 装进消费者 node_modules 且相对路径失败时
+ * 会读到**消费者自己的版本号**——这是本模块要消灭的 bug。语义在此一处定义：
+ *
+ * - 只读本模块自身的 package.json（__dirname 相对；src 与 dist 目录深度一致，
+ *   两种加载方式命中同一份清单）；
+ * - 无 cwd 兜底——cwd 的 package.json 是消费者项目的，不是 harness 的；
+ * - 清单缺失/损坏/无 version 字段 → 'unknown'（沿用收口前各处一致语义）。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHarnessPackageVersion = getHarnessPackageVersion;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** 读取 harness 包版本；读不到（缺失/损坏/无 version 字段）返回 'unknown' */
+function getHarnessPackageVersion() {
+    try {
+        const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return typeof pkg.version === 'string' && pkg.version ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+//# sourceMappingURL=package-version.js.map

package/dist/utils/package-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.js","sourceRoot":"","sources":["../../src/utils/package-version.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMH,4DAQC;AAZD,uCAAyB;AACzB,2CAA6B;AAE7B,yDAAyD;AACzD,SAAgB,wBAAwB;IACtC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1D,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAClF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dommaker/harness",
-  "version": "1.2.3",
+  "version": "1.4.0",
   "description": "通用工程约束框架 - 铁律系统、检查点验证、测试门控",
   "keywords": [
     "harness",

package/src/CONTEXT.md

@@ -19,7 +19,8 @@
 | failure/ | 错误分类、失败记录 |
 | context/ | 会话管理、token 预算、压缩、知识注入 |
 | spec/ | （空目录）@spec 注释检查已删（ADR-0003）；spec 故事见 core/spec/validator + SpecAcceptanceGate |
-| cli/commands/ | 24 个 CLI 子命令 |
+| cli/commands/ | 23 个 CLI 子命令 |
+| test-setup/ | 测试夹具层：`project-fixture` 构造临时项目根（config/traces/files 声明式落盘，非缺省根显式 opt-out）、`mkdtemp-cleanup` 统一回收 |
 | tools/ | 工具定义 |
 
 ## 依赖关系
@@ -38,8 +39,12 @@
 | GateDecision | 三态决策 `deny \| abstain \| ask`；deny 单调（下游不可改回 allow）、ask 枚举预留 fail-closed = deny |
 | GateResult | 报告结构（gate/passed/message/details/timestamp/duration），保留为报告层，不作决策 |
 | 守卫 guard | 仅 dsh 借鉴语境（工具管线单调守卫），不进入 harness 命名 |
-| 回滚 | 分工：版本化回退（单段——yml 数据文件 git 版本化，删段恢复）+ 提案回滚（多段 inverse，挂 #82 D6） |
+| 回滚 | 分工：版本化回退（单段——yml 数据文件 git 版本化，删段恢复）+ 提案回滚（多段 inverse，挂 studio#82 D6） |
 | 文件驱动 CLI | yml 状态真值 + 一次性进程、无常驻生命周期；故不引 dispose 链（止步档 1） |
+| 对照（reconcile） | CAPABILITIES.md 声明与源码实况的双向一致性判定（代码→文档查漏登，文档→代码查幽灵）；唯一实现 `core/constraints/capabilities-reconcile.ts`，capability_sync / docs_freshness / sync-docs 共消费（ADR-0009） |
+| 测试产物解读（test-output） | 从测试运行器 stdout 读出「过了没 / 哪些失败 / 覆盖率」的判定；唯一实现 `core/validators/test-output.ts`（包内，不进导出面），passes-gate / acceptance 共消费（ADR-0012）。两门禁判定依据不一致待 #93 裁决，覆盖率取数归属待 #94 裁决 |
+| 飞轮指标（flywheel） | 知识条目的引用与消费度量（refCoverage / avgRefs / consumptionHitRate）；唯一实现 `knowledge/flywheel-metrics.ts`（包内，不进导出面），canonical 分子为过滤 synthetic 后的 genuine refs，audit D6 / knowledge stats / knowledge health 共消费（ADR-0013，#81） |
+| 测试夹具（project fixture） | 临时项目根 + 落盘声明；唯一实现 `test-setup/project-fixture.ts`（测试层，不进导出面）——`config` 槽是 `.harness/config.yml` 落点唯一正本（字符串原样落盘，畸形/脏配置用例依赖此口径），`traces` 槽/`writeProjectTraces` 是 trace 落盘唯一正本（路径锚定 `DEFAULT_TRACE_FILE`、序列化走 `appendJsonl` 生产写链，harness#108），其余文件走 `files` 相对路径；非缺省根必须经 `parentDir` **显式** opt-out（cwd 锚定用例语义），回收经 `mkdtemp-cleanup` 劫持（harness#90） |
 
 ## 注意事项
 - 公共包，禁止硬编码业务路径

package/src/__tests__/acceptance-gate.test.ts

@@ -3,7 +3,9 @@
  */
 
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
-import { SpecAcceptanceGate, createSpecAcceptanceGate } from '../gates/acceptance';
+import { SpecAcceptanceGate } from '../gates/acceptance';
+// 工厂与公共面同一 seam：gates/index 是唯一出口（harness#101）
+import { createSpecAcceptanceGate } from '../gates/index';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';