@kungfu-tech/buildchain 4.0.9 → 4.1.0-alpha.0

package/packages/core/contracts/runtime-contract-action.js

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  inspectRuntimeContract,
+  assertRuntimeContractAccepted,
+} from "./runtime-contract-inspection.js";
+import { resolveBuildchainContractLockPath } from "./buildchain-layout.js";
+
+export function runtimeContractAction(core, env) {
+  const workspace = env.GITHUB_WORKSPACE;
+  if (!path.isAbsolute(workspace || ""))
+    throw new Error("Runtime contract check requires the runner workspace");
+  const input = JSON.parse(core.getInput("request-json", { required: true }));
+  const runtimeRoot = path.join(workspace, ".buildchain/runtime");
+  const result = inspectRuntimeContract({
+    lockPath: path.resolve(
+      workspace,
+      input["buildchain-contract-lock-path"] ||
+        resolveBuildchainContractLockPath(workspace),
+    ),
+    currentContractPath: path.join(
+      runtimeRoot,
+      "dist/site/buildchain-contract.json",
+    ),
+    runtimeRoot,
+    runtimeRef: core.getInput("runtime-ref"),
+    runtimeSha: core.getInput("runtime-sha"),
+    runtimeClass: core.getInput("runtime-class"),
+    workflowShellRef: core.getInput("workflow-ref"),
+    allowOpaqueRuntime: core.getBooleanInput("runtime-override"),
+    compatibilityPolicy: input["buildchain-contract-compatibility-policy"],
+    expectedChannel: input["buildchain-contract-expected-channel"],
+    expectedMajor: input["buildchain-contract-expected-major"],
+    issueMode: input["buildchain-contract-drift-issue-mode"],
+    issueBodyPath: path.join(
+      workspace,
+      ".buildchain/contract-drift/issue-body.md",
+    ),
+    repository: env.GITHUB_REPOSITORY,
+    workflow: env.GITHUB_WORKFLOW,
+    runUrl: `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}`,
+  });
+  if (env.GITHUB_STEP_SUMMARY)
+    fs.appendFileSync(env.GITHUB_STEP_SUMMARY, result.summary + "\n\n");
+  for (const [key, value] of Object.entries(result.outputs))
+    core.setOutput(key, value);
+  assertRuntimeContractAccepted(result);
+}

package/packages/core/contracts/runtime-contract-inspection.js

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  createBuildchainContractWorld,
+  evaluateBuildchainContractLock,
+  readBuildchainContractLock,
+  readBuildchainContractWorld,
+  renderBuildchainContractDriftIssueBody,
+} from "./buildchain-contract.js";
+
+function readCurrentContract(contractPath, runtimeRoot) {
+  if (contractPath && fs.existsSync(contractPath)) {
+    return readBuildchainContractWorld(contractPath);
+  }
+  return createBuildchainContractWorld({ root: runtimeRoot || process.cwd() });
+}
+
+function issueModeAllows(mode, evaluation) {
+  if (!evaluation.issueRecommended) {
+    return false;
+  }
+  if (mode === "off") {
+    return false;
+  }
+  if (mode === "breaking-only") {
+    return evaluation.status === "breaking-drift";
+  }
+  return mode === "compatible-and-breaking";
+}
+
+export function inspectRuntimeContract({
+  lockPath,
+  currentContractPath,
+  runtimeRoot,
+  runtimeRef,
+  runtimeSha,
+  runtimeClass,
+  compatibilityPolicy,
+  workflowShellRef,
+  expectedChannel,
+  expectedMajor,
+  allowOpaqueRuntime,
+  issueMode = "compatible-and-breaking",
+  issueBodyPath,
+  repository,
+  workflow,
+  runUrl,
+}) {
+  const current = readCurrentContract(currentContractPath, runtimeRoot);
+  const lock = readBuildchainContractLock(lockPath);
+  const evaluation = evaluateBuildchainContractLock({
+    lock,
+    current,
+    runtimeRef,
+    runtimeSha,
+    runtimeClass,
+    compatibilityPolicy,
+    workflowShellRef,
+    expectedChannel,
+    expectedMajor,
+    allowOpaqueRuntime,
+  });
+  const shouldIssue = issueModeAllows(issueMode, evaluation);
+  if (shouldIssue) {
+    const body = renderBuildchainContractDriftIssueBody({
+      repository,
+      workflow,
+      runUrl,
+      lockPath,
+      evaluation,
+    });
+    fs.mkdirSync(path.dirname(issueBodyPath), { recursive: true });
+    fs.writeFileSync(issueBodyPath, `${body}\n`);
+  }
+  const summary = [
+    "## Buildchain contract lock",
+    "",
+    `- Status: \`${evaluation.status}\``,
+    `- Compatible: \`${evaluation.compatible ? "true" : "false"}\``,
+    `- Runtime ref: \`${runtimeRef || "(unknown)"}\``,
+    `- Runtime SHA: \`${runtimeSha || "(unknown)"}\``,
+    `- Workflow shell ref: \`${workflowShellRef || "(unknown)"}\``,
+    evaluation.channelBinding
+      ? `- Bound channel: \`${evaluation.channelBinding.channel || "(unknown)"}\``
+      : "",
+    `- Contract digest: \`${current.contractDigest}\``,
+    `- Compatibility digest: \`${current.compatibilityDigest}\``,
+    evaluation.reasons?.length
+      ? `- Reasons: ${evaluation.reasons.join("; ")}`
+      : "",
+    shouldIssue ? `- Drift issue body: \`${issueBodyPath}\`` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+  const outputs = {
+    "contract-lock-status": evaluation.status,
+    "contract-lock-compatible": String(evaluation.compatible === true),
+    "contract-lock-drift": String(evaluation.drift === true),
+    "contract-lock-issue-needed": String(shouldIssue),
+    "contract-lock-issue-body-file": shouldIssue ? issueBodyPath : "",
+    "contract-digest": current.contractDigest,
+    "contract-compatibility-digest": current.compatibilityDigest,
+    "accepted-contract-digest": evaluation.accepted?.contractDigest || "",
+    "accepted-buildchain-sha": evaluation.accepted?.resolvedSha || "",
+    "current-buildchain-sha": runtimeSha || "",
+  };
+  return { evaluation, current, shouldIssue, summary, outputs };
+}
+
+export function assertRuntimeContractAccepted(result) {
+  if (!result.evaluation.ok)
+    throw new Error(
+      `Buildchain contract lock rejected: ${(result.evaluation.reasons || []).join("; ")}`,
+    );
+}

package/packages/core/contracts/structured-values.js

@@ -0,0 +1,29 @@
+export function parseJsonObject(value, label) {
+  try {
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`${label} must be a JSON object`);
+    }
+    return parsed;
+  } catch (error) {
+    if (error.message.includes(label)) {
+      throw error;
+    }
+    throw new Error(`${label} must be valid JSON: ${error.message}`);
+  }
+}
+
+export function parseJsonArray(value, label) {
+  try {
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed)) {
+      throw new Error(`${label} must be a JSON array`);
+    }
+    return parsed;
+  } catch (error) {
+    if (error.message.includes(label)) {
+      throw error;
+    }
+    throw new Error(`${label} must be valid JSON: ${error.message}`);
+  }
+}

package/packages/core/contracts/workflow-yaml-contract.js

@@ -0,0 +1,373 @@
+function indentation(line) {
+  return line.match(/^(\s*)/)?.[1].length || 0;
+}
+
+function stripComment(value) {
+  let quote = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if ((char === '"' || char === "'") && value[index - 1] !== "\\") {
+      quote = quote === char ? "" : quote || char;
+    }
+    if (
+      char === "#" &&
+      !quote &&
+      (index === 0 || /\s/.test(value[index - 1]))
+    ) {
+      return value.slice(0, index).trimEnd();
+    }
+  }
+  return value.trimEnd();
+}
+
+function unquote(value) {
+  const trimmed = stripComment(String(value || "").trim());
+  if (
+    trimmed.length >= 2 &&
+    trimmed[0] === trimmed.at(-1) &&
+    ['"', "'"].includes(trimmed[0])
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function blockValue(lines, entry) {
+  if (!/^[>|][+-]?$/.test(entry.value)) return entry.value;
+  const values = [];
+  for (let index = entry.line + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (line.trim() && indentation(line) <= entry.indent) break;
+    values.push(line);
+  }
+  const content = values.filter((line) => line.trim());
+  const contentIndent = content.length
+    ? Math.min(...content.map(indentation))
+    : entry.indent + 2;
+  return values
+    .map((line) => line.slice(Math.min(contentIndent, line.length)))
+    .join("\n")
+    .trimEnd();
+}
+
+function directEntries(lines, parentLine) {
+  const parentIndent = indentation(lines[parentLine]);
+  let childIndent = null;
+  for (let index = parentLine + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const indent = indentation(line);
+    if (indent <= parentIndent) break;
+    childIndent = childIndent === null ? indent : Math.min(childIndent, indent);
+  }
+  if (childIndent === null) return [];
+  const entries = [];
+  for (let index = parentLine + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    const trimmed = line.trim();
+    const indent = indentation(line);
+    if (trimmed && indent <= parentIndent) break;
+    if (!trimmed || trimmed.startsWith("#") || indent !== childIndent) continue;
+    const match = line.match(/^\s*([A-Za-z0-9_.-]+):(?:\s*(.*))?$/);
+    if (match) {
+      entries.push({
+        key: match[1],
+        value: stripComment(match[2] || ""),
+        line: index,
+        indent,
+      });
+    }
+  }
+  return entries;
+}
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function topLevelEntry(lines, key) {
+  const pattern = new RegExp(
+    `^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:(?:\\s*(.*))?$`,
+  );
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(pattern);
+    if (match)
+      return {
+        key,
+        value: stripComment(match[1] || ""),
+        line: index,
+        indent: 0,
+      };
+  }
+  return null;
+}
+
+function childEntry(lines, parent, key) {
+  return (
+    directEntries(lines, parent.line).find((entry) => entry.key === key) || null
+  );
+}
+
+function scalar(value) {
+  const raw = stripComment(String(value || "").trim());
+  if (raw.length >= 2 && raw[0] === raw.at(-1) && ['"', "'"].includes(raw[0])) {
+    return { kind: "string", value: raw.slice(1, -1) };
+  }
+  const text = unquote(raw);
+  if (/^\$\{\{[\s\S]*\}\}$/.test(text))
+    return { kind: "expression", value: text };
+  if (/^(true|false)$/i.test(text))
+    return { kind: "boolean", value: text.toLowerCase() === "true" };
+  if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(text))
+    return { kind: "number", value: Number(text) };
+  if (/^(null|~)$/i.test(text)) return { kind: "null", value: null };
+  return { kind: "string", value: text };
+}
+
+function parsePermissions(lines, entry) {
+  if (!entry) return {};
+  if (entry.value) return { "*": unquote(entry.value) };
+  return Object.fromEntries(
+    directEntries(lines, entry.line).map((item) => [
+      item.key,
+      unquote(item.value),
+    ]),
+  );
+}
+
+function parseTriggers(lines) {
+  const on = topLevelEntry(lines, "on");
+  if (!on) return [];
+  if (on.value) {
+    const inline = unquote(on.value);
+    if (inline.startsWith("[") && inline.endsWith("]")) {
+      return inline
+        .slice(1, -1)
+        .split(",")
+        .map((value) => unquote(value.trim()))
+        .filter(Boolean)
+        .sort();
+    }
+    return inline ? [inline] : [];
+  }
+  const events = [];
+  for (const event of directEntries(lines, on.line)) {
+    const types = childEntry(lines, event, "types");
+    const rawTypes = types ? unquote(types.value) : "";
+    if (rawTypes.startsWith("[") && rawTypes.endsWith("]")) {
+      for (const type of rawTypes
+        .slice(1, -1)
+        .split(",")
+        .map((value) => unquote(value.trim()))
+        .filter(Boolean)) {
+        events.push(`${event.key}:${type}`);
+      }
+    } else {
+      events.push(event.key);
+    }
+  }
+  return [...new Set(events)].sort();
+}
+
+function definition(lines, entry) {
+  const properties = Object.fromEntries(
+    directEntries(lines, entry.line).map((item) => [
+      item.key,
+      blockValue(lines, item),
+    ]),
+  );
+  return {
+    name: entry.key,
+    type: unquote(properties.type || "string"),
+    required: scalar(properties.required || "false").value === true,
+    default:
+      properties.default === undefined ? null : scalar(properties.default),
+  };
+}
+
+export function parseReusableWorkflowInterface(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  const on = topLevelEntry(lines, "on");
+  const workflowCall = on && childEntry(lines, on, "workflow_call");
+  if (!workflowCall) {
+    return {
+      reusable: false,
+      inputs: [],
+      secrets: [],
+      outputs: [],
+      permissions: parsePermissions(lines, topLevelEntry(lines, "permissions")),
+    };
+  }
+  const inputs = childEntry(lines, workflowCall, "inputs");
+  const secrets = childEntry(lines, workflowCall, "secrets");
+  const outputs = childEntry(lines, workflowCall, "outputs");
+  return {
+    reusable: true,
+    inputs: inputs
+      ? directEntries(lines, inputs.line)
+          .map((entry) => definition(lines, entry))
+          .sort((a, b) => compareCodeUnits(a.name, b.name))
+      : [],
+    secrets: secrets
+      ? directEntries(lines, secrets.line)
+          .map((entry) => definition(lines, entry))
+          .sort((a, b) => compareCodeUnits(a.name, b.name))
+      : [],
+    outputs: outputs
+      ? directEntries(lines, outputs.line)
+          .map((entry) => entry.key)
+          .sort()
+      : [],
+    permissions: parsePermissions(lines, topLevelEntry(lines, "permissions")),
+  };
+}
+
+function parseJobMap(lines, entry) {
+  if (!entry) return {};
+  return Object.fromEntries(
+    directEntries(lines, entry.line).map((item) => [
+      item.key,
+      scalar(blockValue(lines, item)),
+    ]),
+  );
+}
+
+export function parseWorkflowCallJobs(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  const jobs = topLevelEntry(lines, "jobs");
+  if (!jobs) return [];
+  const topPermissions = parsePermissions(
+    lines,
+    topLevelEntry(lines, "permissions"),
+  );
+  return directEntries(lines, jobs.line)
+    .map((job) => {
+      const properties = directEntries(lines, job.line);
+      const property = (name) =>
+        properties.find((entry) => entry.key === name) || null;
+      const secrets = property("secrets");
+      return {
+        id: job.key,
+        uses: unquote(property("uses")?.value || ""),
+        with: parseJobMap(lines, property("with")),
+        secrets:
+          secrets?.value === "inherit"
+            ? "inherit"
+            : parseJobMap(lines, secrets),
+        permissions: property("permissions")
+          ? parsePermissions(lines, property("permissions"))
+          : topPermissions,
+      };
+    })
+    .filter((job) => job.uses);
+}
+
+export function parseWorkflowJobs(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  const jobs = topLevelEntry(lines, "jobs");
+  if (!jobs) return [];
+  return directEntries(lines, jobs.line)
+    .map((job) => {
+      const properties = directEntries(lines, job.line);
+      const property = (name) =>
+        properties.find((entry) => entry.key === name) || null;
+      return {
+        id: job.key,
+        name: unquote(property("name")?.value || job.key),
+        uses: unquote(property("uses")?.value || ""),
+        runsOn: unquote(property("runs-on")?.value || ""),
+        timeoutMinutes: property("timeout-minutes")
+          ? scalar(property("timeout-minutes").value)
+          : null,
+      };
+    })
+    .sort((left, right) => compareCodeUnits(left.id, right.id));
+}
+
+function blockScalarIndent(lines, lineIndex, parentIndent) {
+  for (let index = lineIndex + 1; index < lines.length; index += 1) {
+    if (!lines[index].trim()) continue;
+    const indent = indentation(lines[index]);
+    return indent > parentIndent ? indent : null;
+  }
+  return null;
+}
+
+export function parseYamlJsonInputs(text) {
+  const lines = String(text || "").split(/\r?\n/u);
+  const inputs = [];
+  let block = null;
+  for (const [index, line] of lines.entries()) {
+    const indent = indentation(line);
+    if (block) {
+      if (!line.trim() || indent >= block.contentIndent) continue;
+      block = null;
+    }
+    const mapping = line.match(
+      /^(\s*)(?:-\s+)?(?:"([A-Za-z0-9_.-]+)"|'([A-Za-z0-9_.-]+)'|([A-Za-z0-9_.-]+)):(?:\s*(.*))?$/u,
+    );
+    if (!mapping) continue;
+    const key = mapping[2] || mapping[3] || mapping[4];
+    const value = stripComment(mapping[5] || "");
+    if (key.endsWith("-json")) {
+      inputs.push({
+        key,
+        line: index + 1,
+        value: unquote(blockValue(lines, { value, line: index, indent })),
+      });
+    }
+    if (/^[>|][+-]?$/u.test(value)) {
+      const contentIndent = blockScalarIndent(lines, index, indent);
+      if (contentIndent !== null) block = { contentIndent };
+    }
+  }
+  return inputs;
+}
+
+/**
+ * Enumerate semantic `uses` mapping nodes without mistaking shell/heredoc text
+ * inside YAML block scalars for workflow syntax. The returned scalar retains
+ * expression-vs-literal classification used by the reusable-call contract.
+ */
+export function parseYamlUses(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  const uses = [];
+  let block = null;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const indent = indentation(line);
+    if (block) {
+      if (!line.trim()) continue;
+      if (indent >= block.contentIndent) continue;
+      block = null;
+    }
+    const mapping = line.match(
+      /^(\s*)(?:-\s+)?([A-Za-z0-9_.-]+):(?:\s*(.*))?$/,
+    );
+    if (!mapping) continue;
+    const value = stripComment(mapping[3] || "");
+    if (/^[>|][+-]?$/.test(value)) {
+      const contentIndent = blockScalarIndent(lines, index, indent);
+      if (contentIndent !== null) block = { contentIndent };
+      continue;
+    }
+    if (mapping[2] !== "uses") continue;
+    uses.push({
+      line: index + 1,
+      column: mapping[1].length + 1,
+      raw: value,
+      scalar: scalar(value),
+      value: unquote(value),
+    });
+  }
+  return uses;
+}
+
+export function parseWorkflowDocument(text) {
+  return {
+    triggers: parseTriggers(String(text || "").split(/\r?\n/)),
+    interface: parseReusableWorkflowInterface(text),
+    jobs: parseWorkflowJobs(text),
+    callJobs: parseWorkflowCallJobs(text),
+  };
+}

package/packages/core/dev-delivery/admission/gh-cli-client.js

@@ -0,0 +1,110 @@
+import { spawnSync } from "node:child_process";
+import { GitHubClient } from "./github-client.js";
+export function ghEnvironment() {
+  const environment = { ...process.env };
+  delete environment.GITHUB_TOKEN;
+  delete environment.GH_TOKEN;
+  return environment;
+}
+export function ghAuthToken() {
+  const result = spawnSync("gh", ["auth", "token"], {
+    encoding: "utf8",
+    env: ghEnvironment(),
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0 || !result.stdout.trim())
+    throw new Error((result.stderr || "gh auth token failed").trim());
+  return result.stdout.trim();
+}
+export function ghJson(args, { input } = {}) {
+  const result = spawnSync("gh", args, {
+    encoding: "utf8",
+    input,
+    env: ghEnvironment(),
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const error = new Error(
+      (result.stderr || result.stdout || "gh command failed").trim(),
+    );
+    error.status = result.status;
+    throw error;
+  }
+  return result.stdout.trim() ? JSON.parse(result.stdout) : null;
+}
+export class GhCliClient extends GitHubClient {
+  constructor({ repository, token = "", fetchImpl = globalThis.fetch } = {}) {
+    super({ token: token || ghAuthToken(), repository, fetchImpl });
+  }
+  async request(method, requestPath, { body } = {}) {
+    const endpoint = requestPath.replace(/^https:\/\/api\.github\.com/, "");
+    const args = ["api", "--method", method, endpoint];
+    if (body !== undefined) args.push("--input", "-");
+    return {
+      data: ghJson(args, {
+        input: body === undefined ? undefined : `${JSON.stringify(body)}\n`,
+      }),
+      response: { headers: { get: () => "" } },
+    };
+  }
+  async paginate(requestPath) {
+    return ghJson(["api", "--paginate", requestPath, "--slurp"]).flatMap(
+      (page) => page,
+    );
+  }
+  async getMergeQueueState(branch) {
+    const query = `query($owner:String!,$repo:String!,$branch:String!){repository(owner:$owner,name:$repo){mergeQueue(branch:$branch){id entries(first:100){nodes{id position state baseCommit{oid} headCommit{oid} pullRequest{number headRefOid}}}}}}`;
+    const data = ghJson([
+      "api",
+      "graphql",
+      "-f",
+      `query=${query}`,
+      "-f",
+      `owner=${this.repository.owner}`,
+      "-f",
+      `repo=${this.repository.repo}`,
+      "-f",
+      `branch=${branch}`,
+    ]).data;
+    const queue = data?.repository?.mergeQueue || null;
+    return {
+      enabled: Boolean(queue),
+      id: queue?.id || "",
+      entries: (queue?.entries?.nodes || []).map((entry) => ({
+        id: entry.id || "",
+        position: entry.position,
+        state: entry.state || "",
+        pullRequestNumber: entry.pullRequest?.number || null,
+        pullRequestHeadSha: entry.pullRequest?.headRefOid || "",
+        baseSha: entry.baseCommit?.oid || "",
+        headSha: entry.headCommit?.oid || "",
+      })),
+    };
+  }
+
+  async enqueuePullRequest({ pullRequestId, expectedHeadOid }) {
+    const query = `mutation($id:ID!,$head:GitObjectID!){enqueuePullRequest(input:{pullRequestId:$id,expectedHeadOid:$head}){mergeQueueEntry{id position state baseCommit{oid} headCommit{oid} pullRequest{number headRefOid}}}}`;
+    const data = ghJson([
+      "api",
+      "graphql",
+      "-f",
+      `query=${query}`,
+      "-f",
+      `id=${pullRequestId}`,
+      "-f",
+      `head=${expectedHeadOid}`,
+    ]).data;
+    const entry = data?.enqueuePullRequest?.mergeQueueEntry;
+    if (!entry?.id)
+      throw new Error("GitHub did not return a merge queue entry");
+    return {
+      id: entry.id,
+      position: entry.position,
+      state: entry.state || "",
+      pullRequestNumber: entry.pullRequest?.number || null,
+      pullRequestHeadSha: entry.pullRequest?.headRefOid || "",
+      baseSha: entry.baseCommit?.oid || "",
+      headSha: entry.headCommit?.oid || "",
+    };
+  }
+}