@istuen/pt 0.1.0

package/src/verify/index.ts

@@ -0,0 +1,57 @@
+// src/verify/index.ts — verify 注册表 + runVerify 入口
+//
+// P1：observe 字段的实现库。纯函数 (cwd, params) => ProbeOutcome，不依赖 OXN 的 kernel/verdict 链。
+// 加新 probe = 注册表加一行 + 实现文件一个。
+
+import type { ProbeOutcome } from "../schema.js";
+import { fsContentMatch } from "./fs-content-match.js";
+import { fsExists } from "./fs-exists.js";
+import { fsNotExists } from "./fs-not-exists.js";
+import { lintCheck } from "./lint-check.js";
+import { tsCompiles } from "./ts-compiles.js";
+import { testPass } from "./test-pass.js";
+import { gitStatusClean } from "./git-status-clean.js";
+import { fileHash } from "./file-hash.js";
+
+/** verify 函数签名：纯函数，接收 cwd + 参数，返回 ProbeOutcome。 */
+export type VerifyFunction = (cwd: string, params: Record<string, string>) => Promise<ProbeOutcome>;
+
+/** 注册表：probe 名 → verify 函数。 */
+const registry: Record<string, VerifyFunction> = {
+  "fs-content-match": fsContentMatch,
+  "fs-exists": fsExists,
+  "fs-not-exists": fsNotExists,
+  "lint-check": lintCheck,
+  "ts-compiles": tsCompiles,
+  "test-pass": testPass,
+  "git-status-clean": gitStatusClean,
+  "file-hash": fileHash,
+};
+
+/** 列出所有已注册的 probe 名（pt_verify tool 的错误提示用）。 */
+export function listProbes(): string[] {
+  return Object.keys(registry);
+}
+
+/** 按名执行 verify。未注册的 probe 名返回 INCONCLUSIVE。 */
+export async function runVerify(
+  cwd: string,
+  name: string,
+  params: Record<string, string>
+): Promise<ProbeOutcome> {
+  const fn = registry[name];
+  if (!fn) {
+    return {
+      outcome: "INCONCLUSIVE",
+      message: `未知 probe: ${name}（可用: ${listProbes().join(", ")}）`,
+    };
+  }
+  try {
+    return await fn(cwd, params);
+  } catch (e) {
+    return {
+      outcome: "INCONCLUSIVE",
+      message: `probe ${name} 执行异常: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}

package/src/verify/lint-check.ts

@@ -0,0 +1,21 @@
+// src/verify/lint-check.ts — 验证 lint 通过
+import { execSync } from "node:child_process";
+import type { ProbeOutcome } from "../schema.js";
+import { readStderr } from "./read-stderr.js";
+
+export async function lintCheck(
+  cwd: string,
+  params: Record<string, string>
+): Promise<ProbeOutcome> {
+  const cmd = params.cmd ?? "npx biome check";
+  try {
+    execSync(cmd, { cwd, stdio: "pipe", timeout: 30000 });
+    return { outcome: "COMPLETED", message: `lint 通过: ${cmd}` };
+  } catch (e) {
+    return {
+      outcome: "DEVIATED",
+      message: `lint 失败: ${cmd}`,
+      actual: readStderr(e).slice(0, 500),
+    };
+  }
+}

package/src/verify/read-stderr.ts

@@ -0,0 +1,24 @@
+// src/verify/read-stderr.ts — execSync 异常 stderr 提取公共辅助（P3.5 抽出）
+//
+// execSync 抛异常时 stderr 是 Uint8Array，需要 Buffer.from 转换。
+// lint-check.ts + test-pass.ts 都需要此逻辑——抽到此处避免重复。
+
+/** execSync 抛出的异常可能包含的 stderr 字段（Node 内部行为）。 */
+type ExecError = Error & { stderr?: Uint8Array | string };
+
+/** 从 execSync 抛出的异常中提取 stderr 字符串。
+ *  - e 非 Error 或无 stderr 字段 → 返 ""
+ *  - stderr 为 Uint8Array → Buffer 转字符串
+ *  - 其他类型 → String() 兜底 */
+export function readStderr(e: unknown): string {
+  if (e instanceof Error && "stderr" in e) {
+    const stderr = (e as ExecError).stderr;
+    if (stderr instanceof Uint8Array) {
+      return Buffer.from(stderr).toString();
+    }
+    if (typeof stderr === "string") {
+      return stderr;
+    }
+  }
+  return "";
+}

package/src/verify/ref-check.ts

@@ -0,0 +1,118 @@
+// src/verify/ref-check.ts — Profile→Blueprint→Domain 引用完整性校验
+//
+// pt 引用图是三层星型（非 OXN Domain→Domain 网状），无环风险。
+// 校验重点是完整性：悬空引用检测。
+// 不校验 Blueprint.groups[].modules（H2 段名是模块类型声明，非 Domain 引用）。
+//
+// v11.x：Profile 全局 domains 覆盖是主用例——"未实例化"警告在该模式下静默
+// （未实例化 = 走全局分发，无 warning；只有 Profile 完全空 + 聚合组全空时才报 warning）。
+
+import type { Blueprint, Domain, Profile } from "../schema.js";
+
+export interface RefCheckResult {
+  ok: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/** 校验单个 Profile 的引用完整性。
+ *  传入该 Profile 引用的 Blueprint（若存在）+ 全集 Domains。 */
+export function checkProfileRefs(
+  profile: Profile,
+  blueprints: Blueprint[],
+  domains: Domain[]
+): RefCheckResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const domainNames = new Set(domains.map((d) => d.name));
+  const _blueprintNames = new Set(blueprints.map((b) => b.name));
+
+  // 1. Profile → Blueprint 存在性
+  const bp = blueprints.find((b) => b.name === profile.blueprint);
+  if (!bp) {
+    errors.push(`Profile "${profile.name}" 引用的 Blueprint "${profile.blueprint}" 不存在`);
+  }
+
+  // 2. Profile → Domain（全局 domains）
+  for (const dn of profile.domains) {
+    if (!domainNames.has(dn)) {
+      errors.push(`Profile "${profile.name}" 的 domains 引用悬空 Domain "${dn}"`);
+    }
+  }
+
+  // 3. Profile.groups → Domain + 聚合组名匹配
+  for (const group of profile.groups) {
+    // 3a. 聚合组名应在 Blueprint 里有对应
+    if (bp) {
+      const bpGroup = bp.groups.find((bg) => bg.name === group.name);
+      if (!bpGroup) {
+        errors.push(
+          `Profile "${profile.name}" 的聚合组 "${group.name}" 在 Blueprint "${bp.name}" 里无对应`
+        );
+      }
+    }
+
+    // 3b. 聚合组引用的 Domain 存在
+    for (const dn of group.domains) {
+      if (!domainNames.has(dn)) {
+        errors.push(`Profile "${profile.name}" 聚合组 "${group.name}" 引用悬空 Domain "${dn}"`);
+      }
+    }
+  }
+
+  // 4. 警告：Blueprint 声明了聚合组但 Profile 未实例化（非错误——Profile 可只实例化部分聚合组）
+  //    v11.x：Profile 有全局 domains 时，聚合组未 H2 实例化是合法用法（全局分发到所有聚合组），
+  //    静默不报。只有 Profile 全空（无全局 domains + 无 H2 实例化）时才报"未实例化" warning。
+  if (bp && profile.domains.length === 0) {
+    for (const bpGroup of bp.groups) {
+      const hasProfileGroup = profile.groups.some((pg) => pg.name === bpGroup.name);
+      if (!hasProfileGroup) {
+        warnings.push(
+          `Blueprint "${bp.name}" 的聚合组 "${bpGroup.name}" 在 Profile "${profile.name}" 里未实例化`
+        );
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+/** 校验所有 Profile 的引用完整性（批量入口）。 */
+export function checkAllRefs(
+  profiles: Profile[],
+  blueprints: Blueprint[],
+  domains: Domain[]
+): RefCheckResult {
+  const allErrors: string[] = [];
+  const allWarnings: string[] = [];
+
+  for (const profile of profiles) {
+    const r = checkProfileRefs(profile, blueprints, domains);
+    allErrors.push(...r.errors);
+    allWarnings.push(...r.warnings);
+  }
+
+  return { ok: allErrors.length === 0, errors: allErrors, warnings: allWarnings };
+}
+
+/** 把 RefCheckResult 格式化为人类可读文本（pt_check_refs tool 输出用）。 */
+export function formatRefCheckResult(r: RefCheckResult): string {
+  const lines: string[] = [];
+  if (r.ok && r.warnings.length === 0) {
+    lines.push("✓ 引用完整性检查通过，无悬空引用");
+    return lines.join("\n");
+  }
+  if (r.errors.length > 0) {
+    lines.push(`✗ ${r.errors.length} 个悬空引用：`);
+    for (const e of r.errors) lines.push(`  - ${e}`);
+  }
+  if (r.warnings.length > 0) {
+    lines.push(`⚠ ${r.warnings.length} 个警告：`);
+    for (const w of r.warnings) lines.push(`  - ${w}`);
+  }
+  if (r.ok && r.warnings.length > 0) {
+    lines.unshift("✓ 引用完整性检查通过（有警告）");
+  }
+  return lines.join("\n");
+}

package/src/verify/test-pass.ts

@@ -0,0 +1,18 @@
+// src/verify/test-pass.ts — 验证测试通过
+import { execSync } from "node:child_process";
+import type { ProbeOutcome } from "../schema.js";
+import { readStderr } from "./read-stderr.js";
+
+export async function testPass(cwd: string, params: Record<string, string>): Promise<ProbeOutcome> {
+  const cmd = params.cmd ?? "npx vitest run tests/verify/";
+  try {
+    execSync(cmd, { cwd, stdio: "pipe", timeout: 120000 });
+    return { outcome: "COMPLETED", message: `测试通过: ${cmd}` };
+  } catch (e) {
+    return {
+      outcome: "DEVIATED",
+      message: `测试失败: ${cmd}`,
+      actual: readStderr(e).slice(0, 500),
+    };
+  }
+}

package/src/verify/ts-compiles.ts

@@ -0,0 +1,21 @@
+// src/verify/ts-compiles.ts — 验证 TS 编译通过
+import { execSync } from "node:child_process";
+import type { ProbeOutcome } from "../schema.js";
+import { readStderr } from "./read-stderr.js";
+
+export async function tsCompiles(
+  cwd: string,
+  params: Record<string, string>
+): Promise<ProbeOutcome> {
+  const cmd = params.cmd ?? "npx tsc --noEmit";
+  try {
+    execSync(cmd, { cwd, stdio: "pipe", timeout: 60000 });
+    return { outcome: "COMPLETED", message: `TS 编译通过: ${cmd}` };
+  } catch (e) {
+    return {
+      outcome: "DEVIATED",
+      message: `TS 编译失败: ${cmd}`,
+      actual: readStderr(e).slice(0, 500),
+    };
+  }
+}