@zxyycom/vibe-check 0.0.1

package/docs/examples/artifacts/mixed-outcomes/definition.ts

@@ -0,0 +1,195 @@
+import { defineCheck, defineConfig, inherit, jsonValidation } from "@zxyycom/vibe-check";
+
+interface ReleaseInputsData {
+  readonly files: readonly string[];
+  readonly version: 1;
+}
+
+const configuredReleaseInputFiles: readonly string[] = [];
+
+// 一个随包 Check：只验证 project root 的 package.json，并保留其它文件选择默认值。
+const packageManifest = jsonValidation({
+  files: { include: ["package.json"] }
+});
+
+// 一个 typed provider：preflight 用 fallback 准备 invocation-local options。
+const releaseInputs = defineCheck({
+  checkId: "example-release-inputs",
+  displayName: "Example release inputs",
+  options: { files: configuredReleaseInputFiles },
+  parseData(data): ReleaseInputsData {
+    const files = data.files;
+    if (
+      Object.keys(data).length !== 2 ||
+      data.version !== 1 ||
+      !Array.isArray(files) ||
+      !files.every((value): value is string => typeof value === "string")
+    ) {
+      throw new TypeError("Unsupported example release-input data");
+    }
+    return { files: [...files], version: 1 };
+  },
+  preflight(options) {
+    if (options.files.length > 0) {
+      return { status: "success", preparedOptions: options };
+    }
+    return {
+      status: "failure",
+      action: "continue",
+      fallback: { files: ["package.json"] },
+      reason: { code: "default-release-input" },
+      messages: [
+        {
+          level: "warning",
+          code: "default-release-input",
+          message: "未配置发布输入；本次调用改用 package.json。"
+        }
+      ]
+    };
+  },
+  visibility: "attention",
+  execution({ options, signal }) {
+    if (signal.aborted) {
+      return { status: "unavailable", reason: { code: "execution-cancelled" } };
+    }
+    return {
+      status: "passed",
+      data: { files: [...options.files], version: 1 as const }
+    };
+  }
+});
+
+// 一个 downstream policy：读取内置 Check 和 typed provider 的 final data。
+const releasePolicy = defineCheck({
+  checkId: "example-release-policy",
+  displayName: "Example release policy",
+  dependsOn: inherit({ add: [releaseInputs.checkId] }),
+  options: { minimumFileCount: 2 },
+  visibility: "attention",
+  execution({ dependencies, options, records }) {
+    const manifestRead = dependencies.get(packageManifest.checkId);
+    if (!manifestRead.ok) {
+      return {
+        status: "unavailable",
+        reason: { code: "manifest-data-unavailable" },
+        messages: [
+          {
+            level: "error",
+            code: "manifest-data-unavailable",
+            message: "请检查 json-validation 的 terminal outcome，并恢复可解析的 final data。"
+          }
+        ]
+      };
+    }
+    const inputsRead = dependencies.get(releaseInputs.checkId);
+    if (!inputsRead.ok) {
+      return {
+        status: "unavailable",
+        reason: { code: "release-input-data-unavailable" },
+        messages: [
+          {
+            level: "error",
+            code: "release-input-data-unavailable",
+            message: "请检查 release-input provider 的 terminal outcome，并恢复可解析的 final data。"
+          }
+        ]
+      };
+    }
+
+    const manifest = packageManifest.parseData(manifestRead.data);
+    const inputs = releaseInputs.parseData(inputsRead.data);
+    const data = {
+      manifestValid: manifest.invalidFileCount === 0,
+      minimumFileCount: options.minimumFileCount,
+      selectedFileCount: inputs.files.length
+    };
+
+    for (const file of inputs.files) {
+      records.report({ id: `selected:${file}` }, { kind: "release-input", path: file });
+    }
+    if (!data.manifestValid) {
+      records.report(
+        { id: "package-manifest-invalid" },
+        { invalidFileCount: manifest.invalidFileCount, severity: "error" }
+      );
+    }
+    if (data.selectedFileCount < data.minimumFileCount) {
+      records.report(
+        { id: "minimum-file-count" },
+        {
+          actual: data.selectedFileCount,
+          expected: data.minimumFileCount,
+          severity: "error"
+        }
+      );
+    }
+
+    if (data.manifestValid && data.selectedFileCount >= data.minimumFileCount) {
+      return { status: "passed", data };
+    }
+    return {
+      status: "failed",
+      data,
+      messages: [
+        {
+          level: "error",
+          code: "release-policy-failed",
+          message: "请修复 package.json，并补足发布输入。"
+        }
+      ]
+    };
+  }
+});
+
+const optionalDocumentation = defineCheck({
+  checkId: "example-optional-documentation",
+  displayName: "Example optional documentation",
+  options: { enabled: false },
+  execution: ({ options }) =>
+    options.enabled
+      ? { status: "passed", data: { reviewed: true } }
+      : { status: "not-applicable", reason: { code: "documentation-disabled" } }
+});
+
+// block preflight 会在任何 Check execution 开始前把本 Check 结算为 unavailable。
+const externalReview = defineCheck({
+  checkId: "example-external-review",
+  displayName: "Example external review",
+  options: { serviceConfigured: false },
+  preflight(options) {
+    if (options.serviceConfigured) {
+      return { status: "success", preparedOptions: options };
+    }
+    return {
+      status: "failure",
+      action: "block",
+      reason: { code: "review-service-unconfigured" },
+      messages: [
+        {
+          level: "error",
+          code: "review-service-unconfigured",
+          message: "启用此 Check 前请先配置 review service。"
+        }
+      ]
+    };
+  },
+  execution: () => ({ status: "passed", data: { reviewed: true } })
+});
+
+// 组织节点自身不产生 outcome；children 继承 packageManifest dependency 和并行预算。
+const releaseWorkflow = defineCheck({
+  checkId: "example-release-workflow",
+  displayName: "Example release workflow",
+  checks: [releaseInputs, releasePolicy, optionalDocumentation, externalReview],
+  dependsOn: [packageManifest.checkId],
+  maxParallel: 2
+});
+
+export default defineConfig({
+  checks: [packageManifest, releaseWorkflow],
+  outputs: {
+    machinePublication: { directory: "artifacts/vibe-check", enabled: true },
+    progressRendering: { enabled: false }
+  },
+  scheduler: { maxParallel: 3 }
+});

package/docs/examples/artifacts/mixed-outcomes/records.ndjson

@@ -0,0 +1,2 @@
+{"checkId":"example-release-policy","data":{"actual":1,"expected":2,"severity":"error"},"id":"minimum-file-count","schemaVersion":"vibe-check.record.v4"}
+{"checkId":"example-release-policy","data":{"kind":"release-input","path":"package.json"},"id":"selected:package.json","schemaVersion":"vibe-check.record.v4"}

package/docs/examples/artifacts/mixed-outcomes/run.json

@@ -0,0 +1,70 @@
+{
+  "checks": [
+    {
+      "checkId": "example-external-review",
+      "displayName": "Example external review",
+      "outcome": {
+        "status": "unavailable",
+        "reason": {
+          "code": "review-service-unconfigured"
+        }
+      }
+    },
+    {
+      "checkId": "example-optional-documentation",
+      "displayName": "Example optional documentation",
+      "outcome": {
+        "status": "not-applicable",
+        "reason": {
+          "code": "documentation-disabled"
+        }
+      }
+    },
+    {
+      "checkId": "example-release-inputs",
+      "displayName": "Example release inputs",
+      "outcome": {
+        "status": "passed",
+        "data": {
+          "files": [
+            "package.json"
+          ],
+          "version": 1
+        }
+      }
+    },
+    {
+      "checkId": "example-release-policy",
+      "displayName": "Example release policy",
+      "outcome": {
+        "status": "failed",
+        "data": {
+          "manifestValid": true,
+          "minimumFileCount": 2,
+          "selectedFileCount": 1
+        }
+      }
+    },
+    {
+      "checkId": "json-validation",
+      "displayName": "JSON validation",
+      "outcome": {
+        "status": "passed",
+        "data": {
+          "invalidFileCount": 0,
+          "issueCount": 0,
+          "rejectedInputCount": 0,
+          "scannedFileCount": 1,
+          "validFileCount": 1
+        }
+      }
+    }
+  ],
+  "invocation": {
+    "invocationId": "invocation/v1:docs-mixed-outcomes",
+    "projectRoot": ".",
+    "timestamp": "2026-08-12T00:00:00.000Z"
+  },
+  "recordsFingerprint": "check-record/v2/records/sha256:d35ff68c8a089bc03df035ede9f114f5e23478eab61c33243e13feaad6b9a393",
+  "schemaVersion": "vibe-check.run.v4"
+}

package/docs/output.md

@@ -0,0 +1,97 @@
+# 机器输出契约
+
+本文定义 package consumer 读取 Vibe Check v4 machine publication 的方式。一次 publication 由同一目录中的
+`run.json` 与 `records.ndjson` 共同组成；任何单文件都不能证明完整结果。精确字段由随包发布的
+[run schema](schemas/vibe-check-run.schema.json) 与
+[Record schema](schemas/vibe-check-record.schema.json) 定义。
+
+## 读取与验证顺序
+
+1. 同时读取同一 output directory 的两份原始 bytes；缺少任一文件或混用不同 Run 的文件时拒绝整组。
+2. 按 framing 解析：`run.json` 是一个 UTF-8 JSON value；非空 `records.ndjson` 每行一个 JSON value 并以 LF
+   结束，空 Record set 恰好是零字节文件。
+3. 分别按 current v4 schema 验证 `run.json` 和每个 Record row。
+4. 验证 Check 与 Record 的排序、`{ checkId, id }` 唯一性和 Record ownership，再重算
+   `recordsFingerprint`。任一步失败都拒绝整组，不保留“已验证前缀”。
+5. 只从 `passed` / `failed` Check row 读取 `outcome.data`。随包 Check 的 final-data parser 可以继续验证该
+   Check 的业务 shape，但不能替代前四步。
+
+Artifact reader 由 consumer 实现或选择；读取实现先用 schema 与完整集合不变量把原始 bytes 收窄为可信数据，再进入
+Check-local parser。
+
+## 字段与完整集合验证
+
+| 文件 | 内容与 schema identity |
+| --- | --- |
+| `run.json` | invocation、完整 Record-set fingerprint 与按 `checkId` 排序的 terminal Check rows；`urn:vibe-check:schema:run:v4` |
+| `records.ndjson` | 按 `{ checkId, id }` 排序的 supplemental Record rows；`urn:vibe-check:schema:record:v4` |
+
+`run.json` 只发布 `schemaVersion`、`invocation`、`recordsFingerprint` 和 `checks`。启用 machine publication 时，
+`invocation.timestamp` 是 Run 创建阶段一次捕获的 UTC instant，不是 machine publication 完成的时间；若 diagnostic logging
+也启用，二者共享该 instant。两项 output 都禁用时，Run 不读取或序列化 wall clock。每个 Check row 包含
+`checkId`、`displayName` 和一种 terminal outcome：`passed` / `failed` 带 object-shaped final `data`；
+`not-applicable` / `unavailable` 带受控 reason，前者可以省略 reason。Aggregation、所有 Run output status 与
+diagnostic logging file、duration、terminal messages、visibility 和 progress presentation 不属于 machine fields。
+
+每个 `records.ndjson` row 的结构是：
+
+```json
+{
+  "schemaVersion": "vibe-check.record.v4",
+  "checkId": "api-health",
+  "id": "sample:health",
+  "data": { "latencyMs": 820, "statusCode": 503 }
+}
+```
+
+Record `id` 只在 owning Check 内唯一；Record presence、count 和 data 不决定 terminal status。final data 是主要事实，
+Records 是补充事实；producing Check 拥有二者的业务字段与安全投影，generic publication 只保存已经通过 settlement 的
+数据。随包 Check 的安全字段与排除边界见对应 [Check 指南](../README.md#随包提供的-check)。
+
+`recordsFingerprint` 绑定完整、排序后的 Record row array。重算时把每个 object 的 properties 递归按名称词法排序，array
+保持 index order，再对所得 UTF-8 canonical JSON text 计算 SHA-256；结果是
+`check-record/v2/records/sha256:<lowercase-hex>`，空 array 也有稳定摘要。它不是 `records.ndjson` bytes 的 hash，JavaScript
+own-key enumeration 与序列化时的 key 排列也不是 public contract。
+
+## 发布与并发读取边界
+
+Publisher 在修改 canonical paths 前先形成并完整验证两份文件。写入或首次 canonical rename 失败时保留 prior set；一次
+canonical replacement 已发生后的 handled failure 会清理可能混合的 canonical files。pre-work configuration failure
+不进行 output I/O。diagnostic logging 是独立的人读 Run output，不进入 v4 directory、schema、example 或 publication set；
+machine consumer 不发现或解析它。其 configuration 与 `RunResult` readback 见
+[深入 API 机制](api-mechanics.md#outputs-与-runresult-边界)。
+
+两个 canonical files 是独立 filesystem paths，rename 不提供跨路径原子可见性。并发 reader 可能观察到 mixed
+generation，因此必须按完整集合执行 fingerprint validation；需要 generation pointer、reader lock 或跨路径 atomic
+visibility 的系统，应在 Vibe Check 契约之外建立自己的读取协议。
+
+## 随包材料与版本
+
+随包机器契约材料包含本文、开头链接的两份 current v4 schemas，以及一组以 TypeScript Definition 为输入的
+`mixed-outcomes` example。该示例由以下三份文件组成：
+
+| 文件 | 用途 |
+| --- | --- |
+| [`definition.ts`](examples/artifacts/mixed-outcomes/definition.ts) | 可直接交给 `run` 的 TypeScript Project Definition；混合一个 `jsonValidation` 内置 Check 与一条递归自定义 workflow。 |
+| [`run.json`](examples/artifacts/mixed-outcomes/run.json) | 与该 Definition 的五个可执行 Check 对应，集中展示 package-provided/custom `passed`、`failed`、`not-applicable` 与 `unavailable` facts。 |
+| [`records.ndjson`](examples/artifacts/mixed-outcomes/records.ndjson) | failed policy 发布的两条 supplemental Records，用于核对多行 framing、ownership、排序和 fingerprint。 |
+
+这三份材料按以下关系阅读：
+
+1. `jsonValidation({ files: { include: ["package.json"] } })` 使用随包 constructor，显式选择 `package.json` 并保留默认
+   source / exclude policy；示例输入中的有效 manifest 使 `json-validation` 形成 `passed` final data。
+2. `example-release-inputs` 的 preflight 在 authored files 为空时以 `failure / continue` 准备 fallback，再由
+   `parseData` 声明 typed provider contract；对应 Check 形成 `passed`。
+3. 递归 `example-release-workflow` 把 manifest dependency 传给 children；`example-release-policy` 用 `inherit` 追加 provider
+   dependency，读取并解析两份 upstream final data，随后形成 `failed` final data 和两条 Records。组织节点自身不产生 Check row。
+4. optional Check 直接形成 `not-applicable`；external review 的 `failure / block` preflight 在任何 execution 开始前形成
+   `unavailable`。两条 preflight message 与 failed policy message 保留在 `RunResult.checkMessages`，不进入 machine fields。
+
+仓库生成器通过完整 public `run` 执行同一份 Definition，并使用只含有效 `package.json` 的隔离 project root 得到以上
+Check/Record facts；随后只把 invocation ID 与 timestamp 固定为文档值，使 checked-in bytes 可重复生成。示例 Definition
+启用了 `artifacts/vibe-check` machine publication；直接运行会在本次 project root 下更新该目录中的两份 canonical files。
+示例 facts 与固定 metadata 只用于核对 Definition/output 对应关系；consumer 在自己的 project root 调用
+`run(definition)` 时，会按实际 `package.json` 形成结果和本次 Run 的 invocation metadata。
+
+随包机器契约的当前版本是 v4，validation boundary 对其它 schema identity fail closed。本示例使用非空 Record set；零
+Record 集合按读取规则表示为零字节 `records.ndjson`。

package/docs/schemas/vibe-check-record.schema.json

@@ -0,0 +1,33 @@
+{
+  "type": "object",
+  "required": [
+    "checkId",
+    "data",
+    "id",
+    "schemaVersion"
+  ],
+  "properties": {
+    "checkId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "data": {
+      "type": "object",
+      "patternProperties": {
+        "^.*$": {}
+      }
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "schemaVersion": {
+      "type": "string",
+      "const": "vibe-check.record.v4"
+    }
+  },
+  "$id": "urn:vibe-check:schema:record:v4",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "title": "Vibe Check machine record v4"
+}

package/docs/schemas/vibe-check-run.schema.json

@@ -0,0 +1,173 @@
+{
+  "type": "object",
+  "required": [
+    "checks",
+    "invocation",
+    "recordsFingerprint",
+    "schemaVersion"
+  ],
+  "properties": {
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "checkId",
+          "displayName",
+          "outcome"
+        ],
+        "properties": {
+          "checkId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "displayName": {
+            "type": "string",
+            "minLength": 1
+          },
+          "outcome": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "data",
+                  "status"
+                ],
+                "properties": {
+                  "data": {
+                    "type": "object",
+                    "patternProperties": {
+                      "^.*$": {}
+                    }
+                  },
+                  "status": {
+                    "type": "string",
+                    "const": "passed"
+                  }
+                },
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "required": [
+                  "data",
+                  "status"
+                ],
+                "properties": {
+                  "data": {
+                    "type": "object",
+                    "patternProperties": {
+                      "^.*$": {}
+                    }
+                  },
+                  "status": {
+                    "type": "string",
+                    "const": "failed"
+                  }
+                },
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "required": [
+                  "status"
+                ],
+                "properties": {
+                  "reason": {
+                    "type": "object",
+                    "required": [
+                      "code"
+                    ],
+                    "properties": {
+                      "code": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    },
+                    "additionalProperties": false
+                  },
+                  "status": {
+                    "type": "string",
+                    "const": "not-applicable"
+                  }
+                },
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "required": [
+                  "reason",
+                  "status"
+                ],
+                "properties": {
+                  "reason": {
+                    "type": "object",
+                    "required": [
+                      "code"
+                    ],
+                    "properties": {
+                      "checkIds": {
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        "minItems": 1
+                      },
+                      "code": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    },
+                    "additionalProperties": false
+                  },
+                  "status": {
+                    "type": "string",
+                    "const": "unavailable"
+                  }
+                },
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "invocation": {
+      "type": "object",
+      "required": [
+        "invocationId",
+        "projectRoot",
+        "timestamp"
+      ],
+      "properties": {
+        "invocationId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "projectRoot": {
+          "type": "string",
+          "const": "."
+        },
+        "timestamp": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$"
+        }
+      },
+      "additionalProperties": false
+    },
+    "recordsFingerprint": {
+      "type": "string",
+      "pattern": "^check-record/v2/records/sha256:[a-f0-9]{64}$"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "const": "vibe-check.run.v4"
+    }
+  },
+  "$id": "urn:vibe-check:schema:run:v4",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "title": "Vibe Check machine run v4"
+}

package/index.mjs

@@ -0,0 +1 @@
+export * from "./dist/esm/index.mjs";

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@zxyycom/vibe-check",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zxyycom/vibe-check.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./index.mjs"
+    }
+  },
+  "files": [
+    "index.mjs",
+    "LICENSE",
+    "README.md",
+    "docs",
+    "dist",
+    "types",
+    "src",
+    "third-party-licenses"
+  ],
+  "dependencies": {
+    "@humanwhocodes/momoa": "3.3.12",
+    "ajv": "8.20.0",
+    "csv-parse": "7.0.1",
+    "execa": "9.6.1",
+    "github-slugger": "2.0.0",
+    "jscpd": "^5.0.11",
+    "mdast-util-from-markdown": "2.0.3",
+    "mdast-util-frontmatter": "2.0.1",
+    "mdast-util-gfm": "3.1.0",
+    "micromark-extension-frontmatter": "2.0.0",
+    "micromark-extension-gfm": "3.0.0",
+    "minimatch": "10.2.5",
+    "neverthrow": "8.2.0",
+    "typebox": "1.3.9"
+  }
+}