@kungfu-tech/buildchain 3.0.4-alpha.4 → 3.0.4-alpha.5

package/scripts/site-reference-registry.mjs

@@ -0,0 +1,174 @@
+import { createNodeApiReference } from "./public-reference.mjs";
+
+export function createSiteNodeApiRegistry({
+  root,
+  packageJson,
+  nodeApiMeta,
+  sha256File,
+  publicSurfaceLifecycle,
+}) {
+  const reference = createNodeApiReference({ root, packageJson });
+  const referenceByExport = new Map(
+    reference.map((entry) => [entry.export, entry]),
+  );
+  const symbolsById = new Map();
+  for (const surface of reference) {
+    const meta = nodeApiMeta(surface.export);
+    for (const symbol of surface.symbols) {
+      const id = `${symbol.source.path}#${symbol.name}`;
+      if (!symbolsById.has(id)) {
+        symbolsById.set(id, {
+          id,
+          ...symbol,
+          maturity: meta.maturity,
+          audience: meta.audience,
+        });
+      }
+    }
+  }
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-node-api-registry",
+    package: packageJson.name,
+    moduleSystem: packageJson.type || "module",
+    symbols: [...symbolsById.values()].sort((left, right) =>
+      left.id.localeCompare(right.id),
+    ),
+    exports: Object.entries(packageJson.exports || {})
+      .filter(
+        ([specifier]) =>
+          !specifier.startsWith("./site/") && specifier !== "./package.json",
+      )
+      .map(([specifier, target]) => {
+        const meta = nodeApiMeta(specifier);
+        const surface = referenceByExport.get(specifier);
+        return {
+          specifier:
+            specifier === "."
+              ? packageJson.name
+              : `${packageJson.name}/${specifier.replace(/^\.\//, "")}`,
+          export: specifier,
+          target,
+          digest:
+            typeof target === "string"
+              ? sha256File(target.replace(/^\.\//, ""))
+              : "",
+          summary: meta.summary,
+          capabilityGroup: meta.capabilityGroup,
+          audience: meta.audience,
+          symbolCount: surface?.symbols.length || 0,
+          symbolIds: (surface?.symbols || []).map(
+            (symbol) => `${symbol.source.path}#${symbol.name}`,
+          ),
+          ...publicSurfaceLifecycle({
+            owner: "buildchain-core",
+            maturity: meta.maturity,
+            nonDuplicationRationale:
+              "Existing package subpath retained as the canonical API boundary for this capability.",
+          }),
+        };
+      }),
+    docs: [
+      ["cli-and-node-package", "docs/cli.md"],
+      ["node-api-reference", "docs/node-api-reference.md"],
+      ["build-facts", "docs/build-facts.md"],
+      ["kfd-support", "docs/kfd-support.md"],
+      ["readme-badges", "docs/readme-badges.md"],
+      ["homebrew", "docs/homebrew.md"],
+      ["site-bundle-contract", "docs/site-bundle-contract.md"],
+    ].map(([id, docPath]) => ({
+      id,
+      path: docPath,
+      digest: sha256File(docPath),
+    })),
+    guidance:
+      "These are the public Node import surfaces and symbols shipped by the npm package. Prefer them over internal file paths.",
+  };
+}
+
+function assertCliReferenceRegistry(cliRegistry) {
+  for (const command of cliRegistry.commands || []) {
+    for (const field of [
+      "paths",
+      "syntaxes",
+      "options",
+      "aliases",
+      "helpCommands",
+    ]) {
+      if (!Array.isArray(command[field])) {
+        throw new Error(
+          `cli-registry.json command missing generated ${field}: ${command.id || command.usage}`,
+        );
+      }
+    }
+    if (
+      command.paths.length === 0 ||
+      command.syntaxes.length === 0 ||
+      command.helpCommands.length === 0
+    ) {
+      throw new Error(
+        `cli-registry.json command has an empty generated reference: ${command.id || command.usage}`,
+      );
+    }
+  }
+}
+
+function assertNodeSymbol(symbol) {
+  const arraysComplete =
+    Array.isArray(symbol.parameters) &&
+    Array.isArray(symbol.errors) &&
+    symbol.errors.length > 0 &&
+    Array.isArray(symbol.sideEffects) &&
+    symbol.sideEffects.length > 0 &&
+    Array.isArray(symbol.audience);
+  const sourceComplete =
+    symbol.source?.path && Number.isInteger(symbol.source?.line);
+  if (
+    !symbol.id ||
+    !symbol.name ||
+    !symbol.kind ||
+    !symbol.signature ||
+    !symbol.returns ||
+    !symbol.maturity ||
+    !symbol.example ||
+    !arraysComplete ||
+    !sourceComplete
+  ) {
+    throw new Error(
+      `node-api-registry.json symbol is incomplete: ${symbol.id || "<unknown>"}`,
+    );
+  }
+}
+
+function assertNodeReferenceRegistry(nodeApiRegistry) {
+  const symbolsById = new Map(
+    (nodeApiRegistry.symbols || []).map((symbol) => [symbol.id, symbol]),
+  );
+  for (const symbol of symbolsById.values()) assertNodeSymbol(symbol);
+  for (const surface of nodeApiRegistry.exports || []) {
+    if (
+      !Number.isInteger(surface.symbolCount) ||
+      surface.symbolCount !== surface.symbolIds?.length ||
+      surface.symbolCount === 0
+    ) {
+      throw new Error(
+        `node-api-registry.json export has incomplete symbol closure: ${surface.export || surface.specifier}`,
+      );
+    }
+    for (const id of surface.symbolIds) {
+      if (!symbolsById.has(id)) {
+        throw new Error(
+          `node-api-registry.json export references an unknown symbol: ${surface.specifier}#${id}`,
+        );
+      }
+    }
+  }
+}
+
+export function assertPublicReferenceRegistry({
+  cliRegistry,
+  nodeApiRegistry,
+}) {
+  assertCliReferenceRegistry(cliRegistry);
+  assertNodeReferenceRegistry(nodeApiRegistry);
+}

package/scripts/verify-golden-path.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function run(command, args, { cwd, json = false } = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      npm_config_audit: "false",
+      npm_config_fund: "false",
+    },
+    timeout: 10 * 60 * 1000,
+  });
+  if (result.error || result.status !== 0) {
+    throw new Error(
+      `${command} ${args.join(" ")} failed (${result.status}): ${result.stderr || result.stdout || result.error?.message}`,
+    );
+  }
+  return json ? JSON.parse(result.stdout) : result.stdout;
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+export function verifyGoldenPath() {
+  const temporary = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-golden-path-"),
+  );
+  const packDir = path.join(temporary, "pack");
+  const consumer = path.join(temporary, "consumer");
+  fs.mkdirSync(packDir);
+  fs.mkdirSync(consumer);
+  try {
+    const packed = run(
+      "npm",
+      ["pack", "--json", "--pack-destination", packDir],
+      { cwd: root, json: true },
+    );
+    const tarball = path.join(packDir, packed[0].filename);
+    fs.writeFileSync(
+      path.join(consumer, "package.json"),
+      `${JSON.stringify(
+        {
+          name: "buildchain-golden-path-consumer",
+          version: "0.1.0",
+          private: true,
+          scripts: { build: 'node -e ""', check: 'node -e ""' },
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    run("npm", ["install", "--ignore-scripts", "--package-lock", tarball], {
+      cwd: consumer,
+    });
+    const buildchain = path.join(
+      consumer,
+      "node_modules",
+      ".bin",
+      process.platform === "win32" ? "buildchain.cmd" : "buildchain",
+    );
+    const version = run(buildchain, ["--version"], { cwd: consumer }).trim();
+    const initialized = run(
+      buildchain,
+      ["init", "--type", "package", "--package-manager", "npm"],
+      { cwd: consumer, json: true },
+    );
+    const validation = run(
+      buildchain,
+      [
+        "validate",
+        "--require-version-state",
+        "--require-lifecycle-stages",
+        "install,build,verify",
+      ],
+      { cwd: consumer, json: true },
+    );
+    const workflow = fs.readFileSync(
+      path.join(consumer, ".github", "workflows", "build.yml"),
+      "utf8",
+    );
+    const releaseDryRun = run(
+      buildchain,
+      ["release", "--dry-run", "--target-ref", "alpha/v3/v3.0", "--json"],
+      { cwd: consumer, json: true },
+    );
+    const passportPath = path.join(
+      consumer,
+      ".buildchain",
+      "golden-path",
+      "buildchain.release.json",
+    );
+    fs.mkdirSync(path.dirname(passportPath), { recursive: true });
+    run(
+      process.execPath,
+      [
+        "--input-type=module",
+        "--eval",
+        `import fs from "node:fs"; import { createReleasePassport } from "@kungfu-tech/buildchain"; const value=createReleasePassport({repository:"example/consumer",tag:"v0.1.0-alpha.0",sourceSha:"a".repeat(40),assets:[{name:"consumer.tgz",sha256:"b".repeat(64)}]}); fs.writeFileSync(${JSON.stringify(passportPath)}, JSON.stringify(value,null,2)+"\\n");`,
+      ],
+      { cwd: consumer },
+    );
+    const inspection = run(
+      buildchain,
+      ["inspect", "release", "--passport", passportPath, "--json"],
+      { cwd: consumer, json: true },
+    );
+
+    assert(
+      initialized.type === "package",
+      "Golden Path init did not retain the package project type",
+    );
+    assert(
+      validation.config?.path === ".buildchain/buildchain.toml",
+      "Golden Path validation did not read the generated config",
+    );
+    assert(
+      ["install", "build", "verify"].every((name) =>
+        (validation.lifecycleStages || []).some((stage) => stage.name === name),
+      ),
+      "Golden Path validation did not retain the required lifecycle stages",
+    );
+    assert(
+      /uses:\s+kungfu-systems\/buildchain\/.github\/workflows\/.build.yml@v3/.test(
+        workflow,
+      ),
+      "Golden Path workflow is not a thin v3 reusable-workflow caller",
+    );
+    assert(
+      /buildchain-ref:/.test(workflow),
+      "Golden Path workflow lacks the bounded runtime override input",
+    );
+    assert(
+      releaseDryRun && typeof releaseDryRun === "object",
+      "Golden Path release dry-run did not return JSON",
+    );
+    assert(
+      inspection && typeof inspection === "object",
+      "Golden Path Release Passport inspection did not return JSON",
+    );
+    return {
+      contract: "kungfu-buildchain-golden-path-verification/v1",
+      ok: true,
+      version,
+      projectType: initialized.type,
+      validationPath: validation.config?.path,
+      reusableWorkflow: ".github/workflows/build.yml",
+      releaseDryRun: true,
+      releasePassportInspection: true,
+    };
+  } finally {
+    fs.rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+try {
+  process.stdout.write(`${JSON.stringify(verifyGoldenPath(), null, 2)}\n`);
+} catch (error) {
+  console.error(`buildchain Golden Path: ${error.message}`);
+  process.exitCode = 1;
+}