@devcxl/opencode-cabbage 0.2.0 → 0.3.0

package/dist/flowrun/ci.js

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+// ─── checkRequiredChecks ───
+/**
+ * 验证 PR 的状态检查是否满足 RepositoryQualityPolicy 中定义的 required checks。
+ *
+ * 规则：
+ * - mode 为 "off" 时不校验，直接返回 allPassed: true
+ * - mode 为 "required" 时：
+ *   1. 每个 requiredChecks 中的 context 必须在 PR checks 中存在
+ *   2. 状态必须为 SUCCESS
+ *   3. 发布该 check 的 GitHub App ID 必须与配置的 appId 匹配
+ *      （appId 为 0 时不校验来源）
+ */
+export function checkRequiredChecks(policy, prChecks) {
+    // mode off — 不增加额外约束
+    if (policy.mode === "off") {
+        return {
+            allPassed: true,
+            missingContexts: [],
+            failedContexts: [],
+            pendingContexts: [],
+            untrustedSources: [],
+        };
+    }
+    // mode required — 逐项验证
+    const prCheckMap = new Map();
+    for (const c of prChecks) {
+        prCheckMap.set(c.context, c);
+    }
+    const missingContexts = [];
+    const failedContexts = [];
+    const pendingContexts = [];
+    const untrustedSources = [];
+    for (const required of policy.requiredChecks) {
+        const prCheck = prCheckMap.get(required.context);
+        // 1. context 缺失
+        if (!prCheck) {
+            missingContexts.push(required.context);
+            continue;
+        }
+        // 2. 状态检查
+        if (prCheck.state === "SUCCESS") {
+            // 通过 — 继续检查来源
+        }
+        else if (prCheck.state === "PENDING" || prCheck.state === "EXPECTED") {
+            pendingContexts.push(required.context);
+            continue;
+        }
+        else {
+            // FAILURE, ERROR
+            failedContexts.push(required.context);
+            continue;
+        }
+        // 3. 来源验证（appId 为 0 时不校验）
+        if (required.appId !== 0) {
+            if (!prCheck.app || prCheck.app.id !== required.appId) {
+                untrustedSources.push({
+                    context: required.context,
+                    expectedAppId: required.appId,
+                    actualAppId: prCheck.app?.id ?? null,
+                });
+            }
+        }
+    }
+    const allPassed = missingContexts.length === 0 &&
+        failedContexts.length === 0 &&
+        pendingContexts.length === 0 &&
+        untrustedSources.length === 0;
+    return {
+        allPassed,
+        missingContexts,
+        failedContexts,
+        pendingContexts,
+        untrustedSources,
+    };
+}
+// ─── validateRequiredWorkflow ───
+/**
+ * 验证 RepositoryQualityPolicy 的 requiredChecks 配置有效性。
+ *
+ * 规则：
+ * - mode 为 "off" 时跳过所有校验
+ * - mode 为 "required" 时：
+ *   1. requiredChecks 不能为空
+ *   2. 每个 entry 必须有 workflowPath、workflowRef
+ *   3. 不允许重复的 context
+ */
+export function validateRequiredWorkflow(policy) {
+    // mode off — 无需校验
+    if (policy.mode === "off") {
+        return { valid: true, errors: [] };
+    }
+    const errors = [];
+    // 1. requiredChecks 不能为空
+    if (policy.requiredChecks.length === 0) {
+        errors.push("requiredChecks must not be empty when mode is 'required'");
+        return { valid: false, errors };
+    }
+    // 2. 校验每个 entry
+    const seenContexts = new Set();
+    for (let i = 0; i < policy.requiredChecks.length; i++) {
+        const entry = policy.requiredChecks[i];
+        const prefix = `requiredChecks[${i}]`;
+        // 检查 context 重复
+        if (seenContexts.has(entry.context)) {
+            errors.push(`${prefix}: duplicate context "${entry.context}"`);
+        }
+        seenContexts.add(entry.context);
+        // 检查 workflowPath
+        if (!entry.workflowPath) {
+            errors.push(`${prefix}: workflowPath must not be empty`);
+        }
+        // 检查 workflowRef
+        if (!entry.workflowRef) {
+            errors.push(`${prefix}: workflowRef must not be empty`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+// ─── checkBranchProtection ───
+/**
+ * checkBranchProtection 委托给 merge.ts 中已有的实现。
+ * 这里作为 re-export wrapper，保持 CI 模块的 API 统一性。
+ */
+export { checkBranchProtection } from "./merge.js";
+// ─── computeQualityContractDigest ───
+/**
+ * JCS (JSON Canonicalization Scheme) 序列化：
+ * - 对象的 key 按 UTF-8 字节序排序
+ * - 无多余空白
+ * - 数字保留原始精度
+ */
+function jcsStringify(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (Number.isFinite(value)) {
+            // 使用标准数字序列化
+            return String(value);
+        }
+        return "null";
+    }
+    if (typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        const items = value.map(jcsStringify);
+        return `[${items.join(",")}]`;
+    }
+    if (typeof value === "object") {
+        // 按 key 排序
+        const keys = Object.keys(value).sort((a, b) => {
+            const bufA = Buffer.from(a, "utf-8");
+            const bufB = Buffer.from(b, "utf-8");
+            return Buffer.compare(bufA, bufB);
+        });
+        const pairs = keys.map(k => {
+            const v = value[k];
+            return `${JSON.stringify(k)}:${jcsStringify(v)}`;
+        });
+        return `{${pairs.join(",")}}`;
+    }
+    return "null";
+}
+/**
+ * 计算质量契约摘要（Quality Contract Digest）。
+ *
+ * 绑定 testCommands + verifyCommands + coveragePolicy，
+ * 使用 JCS (JSON Canonicalization Scheme) + SHA-256 生成确定性摘要。
+ *
+ * 用于在 PR checkpoint 中记录期望的契约版本，确保 CI 执行时契约未被修改。
+ */
+export function computeQualityContractDigest(testCommands, verifyCommands, coveragePolicy) {
+    const contract = {
+        testCommands,
+        verifyCommands,
+        coveragePolicy,
+    };
+    const json = jcsStringify(contract);
+    return createHash("sha256").update(json, "utf-8").digest("hex");
+}
+//# sourceMappingURL=ci.js.map

package/dist/flowrun/ci.js.map

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

package/dist/flowrun/coverage.d.ts

@@ -0,0 +1,70 @@
+import type { CoverageEvidence } from "./types.js";
+/**
+ * 检验 coverage report 路径的安全性。
+ *
+ * 规则：
+ * - 拒绝空路径
+ * - 拒绝绝对路径
+ * - 拒绝包含 null 字节等危险字符的路径
+ * - 拒绝包含 `..` 路径遍历的路径
+ *
+ * 注意：此函数仅检查路径结构，不处理 symlink。symlink 检查由 resolveCoveragePath 通过 realpath 完成。
+ */
+export declare function validateCoveragePath(reportPath: string, sandboxRoot: string): void;
+/**
+ * 在 sandbox 内安全地解析 coverage report 路径。
+ *
+ * 1. 先执行 validateCoveragePath 结构检查
+ * 2. join sandbox + reportPath
+ * 3. resolve 后确保不逃逸 sandbox
+ * 4. （调用方负责）通过 realpath 检查 symlink 逃逸
+ *
+ * 返回解析后的绝对路径。
+ */
+export declare function resolveCoveragePath(reportPath: string, sandboxRoot: string): string;
+export interface ParsedCoverageData {
+    actual: number;
+    metric: "lines";
+}
+/**
+ * 解析 istanbul-json-summary 格式的 coverage 报告。
+ *
+ * 抽取 `total.lines.pct`，执行严格的数值校验：
+ * - 拒绝缺少 `total.lines` 字段
+ * - 拒绝 `pct` 为 non-number、NaN、`"Unknown"` 等非数值
+ * - 拒绝 `pct` 超出 [0, 100] 范围
+ *
+ * 返回 ParsedCoverageData 或 null（解析失败/数据无效）。
+ */
+export declare function parseCoverageReport(reportPath: string, metric: "lines"): Promise<ParsedCoverageData | null>;
+export interface BuildCoverageEvidenceInput {
+    actual: number | null;
+    threshold: number;
+    metric: "lines";
+    headSha: string;
+    reportDigest: string | null;
+}
+/**
+ * 构建 CoverageEvidence。
+ *
+ * - actual >= threshold → pass
+ * - actual < threshold → fail
+ * - actual 为 null → pending（报告解析失败或不存在）
+ */
+export declare function buildCoverageEvidence(input: BuildCoverageEvidenceInput): CoverageEvidence;
+/**
+ * 简单的阈值校验（纯数字比较）。
+ */
+export declare function checkCoverageThreshold(actual: number, threshold: number): boolean;
+/**
+ * 对 coverage report 文件计算 digest。
+ * 用于绑定 report 内容与 evidence。
+ */
+export declare function computeReportDigest(reportPath: string): Promise<string | null>;
+/**
+ * 检查 symlink 是否逃逸 sandbox。
+ * 在 resolveCoveragePath 之后调用，对已解析路径做 realpath 检查。
+ *
+ * 返回 safe absolute path，或抛出错误。
+ */
+export declare function verifySymlinkSafe(resolvedPath: string, sandboxRoot: string): Promise<string>;

package/dist/flowrun/coverage.js

@@ -0,0 +1,207 @@
+import { readFile, lstat, realpath } from "node:fs/promises";
+import { resolve, isAbsolute, join, normalize } from "node:path";
+import { createHash } from "node:crypto";
+// ─── 常量 ───
+const DANGEROUS_PATH = /[\x00-\x1f\x7f]/;
+// ─── 路径安全校验 ───
+/**
+ * 检验 coverage report 路径的安全性。
+ *
+ * 规则：
+ * - 拒绝空路径
+ * - 拒绝绝对路径
+ * - 拒绝包含 null 字节等危险字符的路径
+ * - 拒绝包含 `..` 路径遍历的路径
+ *
+ * 注意：此函数仅检查路径结构，不处理 symlink。symlink 检查由 resolveCoveragePath 通过 realpath 完成。
+ */
+export function validateCoveragePath(reportPath, sandboxRoot) {
+    if (!reportPath || reportPath.trim() === "") {
+        throw new Error("Coverage report path is empty");
+    }
+    if (DANGEROUS_PATH.test(reportPath)) {
+        throw new Error(`Coverage report path contains dangerous characters: ${reportPath}`);
+    }
+    const normalized = normalize(reportPath);
+    if (isAbsolute(normalized)) {
+        throw new Error("Coverage report path must be relative, got absolute path");
+    }
+    // 拒绝路径穿越：以 .. 开头或包含 /../
+    const segments = normalized.split("/");
+    if (segments.includes("..") || segments.includes("..\\")) {
+        throw new Error(`Coverage report path escapes sandbox: ${reportPath}`);
+    }
+    // 拒绝 Windows 风格的路径穿越
+    const winSegments = normalized.split("\\");
+    if (winSegments.includes("..")) {
+        throw new Error(`Coverage report path escapes sandbox: ${reportPath}`);
+    }
+}
+/**
+ * 在 sandbox 内安全地解析 coverage report 路径。
+ *
+ * 1. 先执行 validateCoveragePath 结构检查
+ * 2. join sandbox + reportPath
+ * 3. resolve 后确保不逃逸 sandbox
+ * 4. （调用方负责）通过 realpath 检查 symlink 逃逸
+ *
+ * 返回解析后的绝对路径。
+ */
+export function resolveCoveragePath(reportPath, sandboxRoot) {
+    // 步骤 1: 结构检查
+    validateCoveragePath(reportPath, sandboxRoot);
+    // 步骤 2: 拼接并解析
+    const sandboxNorm = resolve(sandboxRoot);
+    const resolved = resolve(join(sandboxNorm, reportPath));
+    // 步骤 3: 确保未逃逸 sandbox
+    if (!resolved.startsWith(sandboxNorm + "/") && resolved !== sandboxNorm) {
+        throw new Error(`Coverage report path resolves outside sandbox: ${reportPath} → ${resolved}`);
+    }
+    return resolved;
+}
+/**
+ * 解析 istanbul-json-summary 格式的 coverage 报告。
+ *
+ * 抽取 `total.lines.pct`，执行严格的数值校验：
+ * - 拒绝缺少 `total.lines` 字段
+ * - 拒绝 `pct` 为 non-number、NaN、`"Unknown"` 等非数值
+ * - 拒绝 `pct` 超出 [0, 100] 范围
+ *
+ * 返回 ParsedCoverageData 或 null（解析失败/数据无效）。
+ */
+export async function parseCoverageReport(reportPath, metric) {
+    let raw;
+    try {
+        raw = await readFile(reportPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const report = parsed;
+    // 检查 total 对象
+    const total = report.total;
+    if (!total || typeof total !== "object") {
+        return null;
+    }
+    // 检查 lines 对象
+    const lines = total.lines;
+    if (!lines || typeof lines !== "object") {
+        return null;
+    }
+    // 提取并校验 pct
+    const pct = lines.pct;
+    // 拒绝 "Unknown" 字符串值
+    if (typeof pct === "string") {
+        return null;
+    }
+    // 拒绝非 number 类型
+    if (typeof pct !== "number") {
+        return null;
+    }
+    // 拒绝 NaN
+    if (isNaN(pct)) {
+        return null;
+    }
+    // 拒绝无穷大
+    if (!isFinite(pct)) {
+        return null;
+    }
+    // 拒绝范围外数值
+    if (pct < 0 || pct > 100) {
+        return null;
+    }
+    return {
+        actual: pct,
+        metric,
+    };
+}
+/**
+ * 构建 CoverageEvidence。
+ *
+ * - actual >= threshold → pass
+ * - actual < threshold → fail
+ * - actual 为 null → pending（报告解析失败或不存在）
+ */
+export function buildCoverageEvidence(input) {
+    let status;
+    let summary;
+    if (input.actual === null) {
+        status = "pending";
+        summary = `Coverage report not available or could not be parsed for head ${input.headSha.slice(0, 7)}`;
+    }
+    else if (input.actual >= input.threshold) {
+        status = "pass";
+        summary = `Coverage ${input.actual}% meets threshold ${input.threshold}% (${input.metric}) at head ${input.headSha.slice(0, 7)}`;
+    }
+    else {
+        status = "fail";
+        summary = `Coverage ${input.actual}% below threshold ${input.threshold}% (${input.metric}) at head ${input.headSha.slice(0, 7)}`;
+    }
+    return {
+        status,
+        headSha: input.headSha,
+        actual: input.actual,
+        threshold: input.threshold,
+        metric: input.metric,
+        reportDigest: input.reportDigest,
+        summary,
+    };
+}
+/**
+ * 简单的阈值校验（纯数字比较）。
+ */
+export function checkCoverageThreshold(actual, threshold) {
+    return actual >= threshold;
+}
+/**
+ * 对 coverage report 文件计算 digest。
+ * 用于绑定 report 内容与 evidence。
+ */
+export async function computeReportDigest(reportPath) {
+    try {
+        const content = await readFile(reportPath);
+        const hash = createHash("sha256");
+        hash.update(content);
+        return hash.digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 检查 symlink 是否逃逸 sandbox。
+ * 在 resolveCoveragePath 之后调用，对已解析路径做 realpath 检查。
+ *
+ * 返回 safe absolute path，或抛出错误。
+ */
+export async function verifySymlinkSafe(resolvedPath, sandboxRoot) {
+    const sandboxNorm = resolve(sandboxRoot);
+    let lstatResult;
+    try {
+        lstatResult = await lstat(resolvedPath);
+    }
+    catch {
+        // 文件不存在，由调用方处理
+        return resolvedPath;
+    }
+    if (lstatResult.isSymbolicLink()) {
+        const real = await realpath(resolvedPath);
+        const realNorm = resolve(real);
+        if (!realNorm.startsWith(sandboxNorm + "/") && realNorm !== sandboxNorm) {
+            throw new Error(`Symlink escapes sandbox: ${resolvedPath} → ${realNorm}`);
+        }
+        return realNorm;
+    }
+    return resolvedPath;
+}
+//# sourceMappingURL=coverage.js.map

package/dist/flowrun/coverage.js.map

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

package/dist/flowrun/digest.d.ts

@@ -0,0 +1,17 @@
+import type { VersionedDigest } from "./types.js";
+export interface DigestOptions {
+    testFilePatterns: string[];
+    implementationFilePatterns: string[];
+    generatedArtifactPatterns: string[];
+}
+/**
+ * 计算 worktree 的 Canonical Content Digest。
+ *
+ * 规则：
+ * 1. repo-relative paths，按 UTF-8 字节序排序
+ * 2. 纳入文件类型（含可执行位）、原始字节、删除标记
+ * 3. 拒绝逃逸 worktree 的 symlink
+ * 4. 忽略 .git/、node_modules/、coverage/、dist/、policy 声明的 generated artifacts
+ * 5. tracked + policy 范围内 untracked 文件均纳入
+ */
+export declare function computeWorkspaceDigest(root: string, options: DigestOptions): Promise<VersionedDigest>;