@kungfu-tech/buildchain 3.0.3-alpha.0 → 3.0.3-alpha.2

package/packages/core/public-surface-audit.js

@@ -1,6 +1,12 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import {
+  commandId,
+  enumerateCliCommandsFromBin,
+} from "./public-surface-cli.js";
+
+export { enumerateCliCommandsFromBin } from "./public-surface-cli.js";
 
 export const BUILDCHAIN_PUBLIC_SURFACE_AUDIT_CONTRACT = "kungfu-buildchain-public-surface-reverse-audit";
 
@@ -40,79 +46,6 @@ function listDirectories(root, dir) {
     .sort();
 }
 
-function commandId(first = "", second = "", third = "") {
-  const head = String(first || "").trim();
-  const sub = String(second || "").trim();
-  const leaf = String(third || "").trim();
-  const normalizedLeaf = leaf === "..." ? "" : leaf;
-  if (!head) return "";
-  if (["-h", "--help", "help"].includes(head)) return "help";
-  if (["-v", "--version", "version"].includes(head)) return "version";
-  if (head === "release" && ["--dry-run", "dry-run", "explain"].includes(sub)) return "release-dry-run";
-  if (head === "release" && sub === "line") return "release-line-open";
-  if (head === "release") return "release-transaction";
-  if (head === "transaction") return "transaction-inspect";
-  if (head === "collect" && sub) return `collect-${sub}`;
-  if (head === "verify" && sub) return `verify-${sub}`;
-  if (head === "explain" && sub) return `explain-${sub}`;
-  if (head === "inspect" && sub) return `inspect-${sub}`;
-  if (head === "npm" && sub) return `npm-${sub}`;
-  if (head === "lifecycle" && sub) return "lifecycle";
-  if (head === "log" && sub) return "logging";
-  if (head === "diagnostics" && sub) return `diagnostics-${sub}`;
-  if (head === "facts" && sub) return "build-facts";
-  if (head === "kfd") {
-    if (!sub || sub === "...") return "kfd";
-    if (sub === "schema") return normalizedLeaf ? `kfd-schema-${normalizedLeaf}` : "kfd-schema";
-    if (sub === "upstream") return normalizedLeaf ? `kfd-upstream-${normalizedLeaf}` : "kfd-upstream";
-    if (/^[1-9][0-9]*$/.test(sub)) return normalizedLeaf ? `kfd-${sub}-${normalizedLeaf}` : `kfd-${sub}`;
-    return `kfd-${sub}`;
-  }
-  if (head === "sample" && sub) return `sample-${sub}`;
-  if (head === "badges" && sub) return `badges-${sub}`;
-  if (head === "homebrew" && sub) return `homebrew-${sub}`;
-  if (head === "release-propagation") return "release-propagation";
-  if (head === "publish-source") return "publish-source";
-  if (head === "publication-artifact" && sub) return `publication-artifact-${sub}`;
-  if (head === "publication-artifact") return "publication-artifact";
-  if (head === "publication" && sub) return `publication-artifact-${sub}`;
-  if (head === "publication") return "publication-artifact";
-  if (head === "build-contract") return "build-contract";
-  if (head === "infra-contract") return "infra-contract";
-  if (head === "web-surface") return "web-surface";
-  return head;
-}
-
-export function enumerateCliCommandsFromBin({ root = process.cwd(), binPath = "bin/buildchain.mjs" } = {}) {
-  const source = readText(root, binPath);
-  const dispatchSource = [
-    source,
-    ...listFiles(root, "bin/internal", (name) => name.endsWith(".mjs"))
-      .map((relPath) => readText(root, relPath)),
-  ].join("\n");
-  const usageMatch = source.match(/return `Usage:\n([\s\S]*?)`;\n}/);
-  const usage = usageMatch?.[1] || "";
-  const usageCommands = [];
-  for (const line of usage.split(/\r?\n/)) {
-    const match = line.trim().match(/^buildchain\s+([^\s]+)(?:\s+([^\s]+))?(?:\s+([^\s]+))?/);
-    if (!match) continue;
-    usageCommands.push({
-      id: commandId(match[1], match[2], match[3]),
-      usage: line.trim().replace(/\s+/g, " "),
-    });
-  }
-  const dispatchCommands = [...dispatchSource.matchAll(/if\s*\(\s*command\s*===\s*"([^"]+)"/g)]
-    .map((match) => commandId(match[1]));
-  return uniqueSorted([
-    ...usageCommands.map((entry) => entry.id),
-    ...dispatchCommands,
-  ]).map((id) => ({
-    id,
-    source: "bin/buildchain.mjs",
-    usage: usageCommands.find((entry) => entry.id === id)?.usage || `buildchain ${id}`,
-  }));
-}
-
 function parseYamlWorkflowCall(text) {
   const lines = text.split(/\r?\n/);
   const result = { reusable: false, inputs: [], secrets: [], outputs: [] };
@@ -330,8 +263,26 @@ export function collectPublicSurfaceReverseAudit({
       mode: "closed-world-enumerable",
       scope: "Buildchain CLI usage/dispatch, reusable workflow inputs, action inputs, site pages, and documentation command references",
       residualRisk: [
-        "Shell commands delegated through helper scripts are only counted when exposed through bin/buildchain.mjs usage or docs.",
-        "YAML parsing is limited to first-class action/workflow inputs, not arbitrary step environment variables.",
+        {
+          id: "public-surface-helper-command-enumeration",
+          definedBy: "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk",
+          riskType: "natural-language-semantic-risk",
+          trustImpact: "downgrade-warning",
+          machineProvability: "not-machine-verifiable",
+          agentAction: "semantic-review-required",
+          owner: "Buildchain maintainers",
+          reason: "Shell commands delegated through helper scripts are counted only when exposed through bin/buildchain.mjs usage or documentation.",
+        },
+        {
+          id: "public-surface-yaml-enumeration",
+          definedBy: "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk",
+          riskType: "natural-language-semantic-risk",
+          trustImpact: "downgrade-warning",
+          machineProvability: "not-machine-verifiable",
+          agentAction: "semantic-review-required",
+          owner: "Buildchain maintainers",
+          reason: "YAML enumeration covers first-class action and workflow inputs, not arbitrary step environment variables.",
+        },
       ],
     },
   };

package/packages/core/public-surface-cli.js

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function readText(root, relPath) {
+  return fs.readFileSync(path.join(root, relPath), "utf8");
+}
+
+function listFiles(root, dir, predicate = () => true) {
+  const base = path.join(root, dir);
+  if (!fs.existsSync(base)) return [];
+  return fs
+    .readdirSync(base, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && predicate(entry.name))
+    .map((entry) => `${dir}/${entry.name}`)
+    .sort();
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function releaseCommandId(sub) {
+  if (["--dry-run", "dry-run", "explain"].includes(sub))
+    return "release-dry-run";
+  if (sub === "line") return "release-line-open";
+  return "release-transaction";
+}
+
+function kfdCommandId(sub, leaf) {
+  if (!sub || sub === "...") return "kfd";
+  if (["schema", "upstream"].includes(sub) || /^[1-9][0-9]*$/.test(sub)) {
+    return leaf ? `kfd-${sub}-${leaf}` : `kfd-${sub}`;
+  }
+  return `kfd-${sub}`;
+}
+
+function paperCommandId(sub, leaf) {
+  if (sub === "bootstrap" && leaf === "npm") return "paper-bootstrap-npm";
+  if (["work", "fleet"].includes(sub) && leaf) return `paper-${sub}-${leaf}`;
+  return sub ? `paper-${sub}` : "paper";
+}
+
+export function commandId(first = "", second = "", third = "") {
+  const head = String(first || "").trim();
+  const sub = String(second || "").trim();
+  const leaf =
+    String(third || "").trim() === "..." ? "" : String(third || "").trim();
+  const paired = new Set([
+    "collect",
+    "verify",
+    "explain",
+    "inspect",
+    "npm",
+    "diagnostics",
+    "sample",
+    "badges",
+    "homebrew",
+  ]);
+  if (!head) return "";
+  if (["-h", "--help", "help"].includes(head)) return "help";
+  if (["-v", "--version", "version"].includes(head)) return "version";
+  if (head === "release") return releaseCommandId(sub);
+  if (head === "transaction") return "transaction-inspect";
+  if (paired.has(head) && sub) return `${head}-${sub}`;
+  if (head === "lifecycle" && sub) return "lifecycle";
+  if (head === "log" && sub) return "logging";
+  if (head === "facts" && sub) return "build-facts";
+  if (head === "kfd") return kfdCommandId(sub, leaf);
+  if (["release-propagation", "publish-source"].includes(head)) return head;
+  if (["publication-artifact", "publication"].includes(head)) {
+    return sub ? `publication-artifact-${sub}` : "publication-artifact";
+  }
+  if (head === "paper") return paperCommandId(sub, leaf);
+  return head;
+}
+
+function usageCommands(source) {
+  const usageMatch = source.match(/`Usage:\n([\s\S]*?)`;/);
+  const rows = [];
+  for (const line of (usageMatch?.[1] || "").split(/\r?\n/)) {
+    const match = line
+      .trim()
+      .match(/^buildchain\s+([^\s]+)(?:\s+([^\s]+))?(?:\s+([^\s]+))?/);
+    if (!match) continue;
+    rows.push({
+      id: commandId(match[1], match[2], match[3]),
+      usage: line.trim().replace(/\s+/g, " "),
+    });
+  }
+  return rows;
+}
+
+export function enumerateCliCommandsFromBin({
+  root = process.cwd(),
+  binPath = "bin/buildchain.mjs",
+} = {}) {
+  const binSource = readText(root, binPath);
+  const helpSource = readText(root, "scripts/buildchain-cli-help.mjs");
+  const dispatchSource = [
+    binSource,
+    ...listFiles(root, "bin/internal", (name) => name.endsWith(".mjs")).map(
+      (relPath) => readText(root, relPath),
+    ),
+  ].join("\n");
+  const usage = usageCommands(helpSource);
+  const dispatch = [
+    ...dispatchSource.matchAll(/if\s*\(\s*command\s*===\s*"([^"]+)"/g),
+  ].map((match) => commandId(match[1]));
+  return uniqueSorted([...usage.map((entry) => entry.id), ...dispatch]).map(
+    (id) => ({
+      id,
+      source: "bin/buildchain.mjs",
+      usage:
+        usage.find((entry) => entry.id === id)?.usage || `buildchain ${id}`,
+    }),
+  );
+}

package/packages/core/publication-artifact.js

@@ -253,7 +253,7 @@ export function createPublicationSourceBundle({
 } = {}) {
   const outputPath = path.resolve(cwd, output);
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-  const paths = sourcePaths.length > 0 ? sourcePaths : ["."];
+  const paths = [...(sourcePaths.length > 0 ? sourcePaths : ["."])].sort();
   execFileSync("git", [
     "archive",
     "--format=tar.gz",
@@ -501,11 +501,6 @@ function mergePublicationRegistryVersions({ registries = [], publicationId }) {
     if (registry.publication?.id !== publicationId) {
       throw new Error(`publication archive registry id mismatch: expected ${publicationId}, got ${registry.publication?.id || "(missing)"}`);
     }
-    if (registry.historyPolicy === "cumulative-authenticated-hydration") {
-      const declaredVersions = new Set(registry.versions.map((record) => String(record?.version || "")));
-      const missingVersions = [...versions.keys()].filter((version) => !declaredVersions.has(version));
-      if (missingVersions.length > 0) throw new Error(`cumulative publication archive registry dropped accepted versions: ${missingVersions.join(", ")}`);
-    }
     for (const record of registry.versions) {
       const version = String(record?.version || "").trim();
       if (!version) throw new Error("publication archive registry record is missing version");

package/packages/core/publication-authority.js

@@ -649,6 +649,7 @@ function validatePublicationEvidence(publicationEvidence, admission) {
     platformMatrix: passport.platformMatrix,
     buildchain: passport.buildchain,
     ...(passport.gateProfileEvidence ? { gateProfileEvidence: passport.gateProfileEvidence } : {}),
+    ...(passport.familyEvidence ? { familyEvidence: passport.familyEvidence } : {}),
     ...(passport.controllerReceipts ? { controllerReceipts: passport.controllerReceipts } : {}),
   });
   if (normalizeDigest(passport.candidateHash, "releaseCandidatePassport.candidateHash") !== candidateHash) {