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

package/scripts/check-maintainability.mjs

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import {
+  analyzeJavaScript,
+  collectMaintainabilityMetrics,
+  isHandMaintainedSource,
+} from "./maintainability-metrics.mjs";
+
+function readJson(root, file) {
+  return JSON.parse(fs.readFileSync(path.join(root, file), "utf8"));
+}
+
+function gitOutput(root, args) {
+  return execFileSync("git", args, { cwd: root, encoding: "utf8" });
+}
+
+function revisionAvailable(root, revision) {
+  try {
+    execFileSync("git", ["cat-file", "-e", `${revision}^{commit}`], {
+      cwd: root,
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ensureRevisionAvailable(root, revision) {
+  if (revisionAvailable(root, revision)) return false;
+  try {
+    gitOutput(root, ["fetch", "--no-tags", "--depth=1", "origin", revision]);
+  } catch (error) {
+    const detail = String(error?.stderr || error?.message || error).trim();
+    throw new Error(
+      `maintainability revision ${revision} is unavailable and could not be fetched from origin${detail ? `: ${detail}` : ""}`,
+    );
+  }
+  if (!revisionAvailable(root, revision)) {
+    throw new Error(
+      `maintainability revision ${revision} is unavailable after a successful origin fetch`,
+    );
+  }
+  return true;
+}
+
+function ensureMaintainabilityRevisionsAvailable(
+  root,
+  { baselineRevision, enforcementRevision },
+) {
+  return Object.fromEntries(
+    [...new Set([baselineRevision, enforcementRevision])].map((revision) => [
+      revision,
+      ensureRevisionAvailable(root, revision),
+    ]),
+  );
+}
+
+function sourceMetricsAtRevision(root, revision) {
+  const files = gitOutput(root, ["ls-tree", "-r", "--name-only", revision])
+    .split("\n")
+    .filter(isHandMaintainedSource)
+    .sort();
+  return Object.fromEntries(
+    files.map((file) => [
+      file,
+      analyzeJavaScript(file, gitOutput(root, ["show", `${revision}:${file}`])),
+    ]),
+  );
+}
+
+function maximumFunction(metrics, field) {
+  return Math.max(
+    0,
+    ...(metrics?.functions || []).map((entry) => entry[field]),
+  );
+}
+
+function selectedFunction(metrics, file, name) {
+  return metrics.files[file]?.functions.find((entry) => entry.name === name);
+}
+
+function readJsonAtRevision(root, revision, file) {
+  return JSON.parse(gitOutput(root, ["show", `${revision}:${file}`]));
+}
+
+function publicSurfaceContract(entry, kind) {
+  if (kind === "cli") return { id: entry.id, usage: entry.usage };
+  if (kind === "node")
+    return {
+      export: entry.export,
+      specifier: entry.specifier,
+      target: entry.target,
+    };
+  return {
+    id: entry.id,
+    path: entry.path,
+    reusable: entry.reusable,
+    inputs: entry.inputs || [],
+    secrets: entry.secrets || [],
+    outputs: entry.outputs || [],
+  };
+}
+
+function evaluatePublicSurface({ root, revision, policy }) {
+  const issues = [];
+  const lifecycleFields = policy.publicSurfacePolicy.requiredLifecycleFields;
+  const capabilityGroups = new Set(
+    readJson(root, "dist/site/capability-registry.json").groups.map(
+      (entry) => entry.id,
+    ),
+  );
+  const definitions = [
+    {
+      file: "dist/site/cli-registry.json",
+      collection: "commands",
+      kind: "cli",
+      key: "id",
+    },
+    {
+      file: "dist/site/node-api-registry.json",
+      collection: "exports",
+      kind: "node",
+      key: "export",
+    },
+    {
+      file: "dist/site/workflow-registry.json",
+      collection: "workflows",
+      kind: "workflow",
+      key: "id",
+    },
+    {
+      file: "dist/site/workflow-registry.json",
+      collection: "actions",
+      kind: "action",
+      key: "id",
+    },
+  ];
+  for (const definition of definitions) {
+    const current =
+      readJson(root, definition.file)[definition.collection] || [];
+    const baseline =
+      readJsonAtRevision(root, revision, definition.file)[
+        definition.collection
+      ] || [];
+    const baselineByKey = new Map(
+      baseline.map((entry) => [entry[definition.key], entry]),
+    );
+    for (const entry of current) {
+      const label = `${definition.kind}:${entry[definition.key]}`;
+      for (const field of lifecycleFields) {
+        if (
+          !Object.prototype.hasOwnProperty.call(entry, field) ||
+          typeof entry[field] !== "string"
+        ) {
+          issues.push(`${label}: lifecycle field ${field} is missing`);
+        }
+      }
+      if (!capabilityGroups.has(entry.capabilityGroup)) {
+        issues.push(
+          `${label}: capability group ${entry.capabilityGroup || "<empty>"} is not registered`,
+        );
+      }
+      const previous = baselineByKey.get(entry[definition.key]);
+      if (
+        previous &&
+        JSON.stringify(publicSurfaceContract(entry, definition.kind)) !==
+          JSON.stringify(publicSurfaceContract(previous, definition.kind))
+      ) {
+        issues.push(
+          `${label}: existing public contract drifted from ${revision}`,
+        );
+      }
+      if (!previous && !entry.nonDuplicationRationale) {
+        issues.push(
+          `${label}: new public surface requires a non-duplication rationale`,
+        );
+      }
+    }
+  }
+  return issues;
+}
+
+function evaluateAddedFunctionBudgets({
+  file,
+  metrics,
+  baseline,
+  policy,
+  budgets,
+}) {
+  const issues = [];
+  const baselineFunctionNames = new Set(
+    (baseline.functions || [])
+      .map((entry) => entry.name)
+      .filter((name) => !name.startsWith("<anonymous@")),
+  );
+  for (const entry of metrics.functions) {
+    if (
+      entry.name.startsWith("<anonymous@") ||
+      baselineFunctionNames.has(entry.name)
+    ) {
+      continue;
+    }
+    const key = `${file}#${entry.name}`;
+    const approval = policy.approvedExtractedDebt?.[key];
+    if (approval && !String(approval.rationale || "").trim()) {
+      issues.push(`${key}: approved extracted debt requires a rationale`);
+    }
+    const allowedLines = approval?.maxLines ?? budgets.newFunctionLines;
+    const allowedComplexity =
+      approval?.maxComplexity ?? budgets.newFunctionComplexity;
+    if (entry.lines > allowedLines) {
+      issues.push(
+        `${file}:${entry.start} ${entry.name} has ${entry.lines} lines; new-function budget is ${allowedLines}`,
+      );
+    }
+    if (entry.complexity > allowedComplexity) {
+      issues.push(
+        `${file}:${entry.start} ${entry.name} has complexity ${entry.complexity}; new-function budget is ${allowedComplexity}`,
+      );
+    }
+  }
+  return issues;
+}
+
+function evaluateMaintainability({ current, baselineFiles, policy }) {
+  const issues = [];
+  const budgets = policy.sourceBudgets;
+  for (const [file, metrics] of Object.entries(current.files)) {
+    const baseline = baselineFiles[file];
+    if (!baseline) {
+      if (metrics.lines > budgets.newFileLines) {
+        issues.push(
+          `${file}: new file has ${metrics.lines} lines; budget is ${budgets.newFileLines}`,
+        );
+      }
+      for (const entry of metrics.functions) {
+        if (entry.lines > budgets.newFunctionLines) {
+          issues.push(
+            `${file}:${entry.start} ${entry.name} has ${entry.lines} lines; new-function budget is ${budgets.newFunctionLines}`,
+          );
+        }
+        if (entry.complexity > budgets.newFunctionComplexity) {
+          issues.push(
+            `${file}:${entry.start} ${entry.name} has complexity ${entry.complexity}; new-function budget is ${budgets.newFunctionComplexity}`,
+          );
+        }
+      }
+      continue;
+    }
+    const transition = policy.approvedExistingDebtTransitions?.[file];
+    if (transition && !String(transition.rationale || "").trim()) {
+      issues.push(`${file}: approved debt transition requires a rationale`);
+    }
+    const allowedLines =
+      transition?.maxLines ?? Math.max(baseline.lines, budgets.newFileLines);
+    const allowedFunctionLines =
+      transition?.maxFunctionLines ??
+      Math.max(maximumFunction(baseline, "lines"), budgets.newFunctionLines);
+    const allowedFunctionComplexity =
+      transition?.maxFunctionComplexity ??
+      Math.max(
+        maximumFunction(baseline, "complexity"),
+        budgets.newFunctionComplexity,
+      );
+    if (metrics.lines > allowedLines) {
+      issues.push(
+        `${file}: file debt widened from ${baseline.lines} to ${metrics.lines} lines`,
+      );
+    }
+    const maxLines = maximumFunction(metrics, "lines");
+    if (maxLines > allowedFunctionLines) {
+      issues.push(
+        `${file}: maximum function length widened beyond ${allowedFunctionLines} to ${maxLines}`,
+      );
+    }
+    const maxComplexity = maximumFunction(metrics, "complexity");
+    if (maxComplexity > allowedFunctionComplexity) {
+      issues.push(
+        `${file}: maximum function complexity widened beyond ${allowedFunctionComplexity} to ${maxComplexity}`,
+      );
+    }
+    issues.push(
+      ...evaluateAddedFunctionBudgets({
+        file,
+        metrics,
+        baseline,
+        policy,
+        budgets,
+      }),
+    );
+  }
+
+  for (const [name, budget] of Object.entries(policy.selectedFunctionBudgets)) {
+    const entry = selectedFunction(current, budget.file, name);
+    if (!entry) {
+      issues.push(`${budget.file}: selected function ${name} is missing`);
+      continue;
+    }
+    if (entry.lines > budget.lines) {
+      issues.push(
+        `${budget.file}: ${name} has ${entry.lines} lines; terminal budget is ${budget.lines}`,
+      );
+    }
+    if (entry.complexity > budget.complexity) {
+      issues.push(
+        `${budget.file}: ${name} has complexity ${entry.complexity}; terminal budget is ${budget.complexity}`,
+      );
+    }
+  }
+  return issues;
+}
+
+function checkMaintainability({ root = process.cwd() } = {}) {
+  const policy = readJson(root, "architecture/maintainability-policy.json");
+  const baseline = readJson(root, policy.baseline);
+  const enforcementRevision = policy.enforcementRevision || baseline.revision;
+  const hydratedRevisions = ensureMaintainabilityRevisionsAvailable(root, {
+    baselineRevision: baseline.revision,
+    enforcementRevision,
+  });
+  const current = collectMaintainabilityMetrics({ root });
+  const baselineFiles = sourceMetricsAtRevision(root, enforcementRevision);
+  const issues = evaluateMaintainability({ current, baselineFiles, policy });
+  issues.push(
+    ...evaluatePublicSurface({ root, revision: enforcementRevision, policy }),
+  );
+  if (issues.length > 0) {
+    throw new Error(`maintainability check failed:\n- ${issues.join("\n- ")}`);
+  }
+  return {
+    schemaVersion: 1,
+    baselineRevision: baseline.revision,
+    enforcementRevision,
+    hydratedBaselineRevision: hydratedRevisions[baseline.revision],
+    hydratedEnforcementRevision: hydratedRevisions[enforcementRevision],
+    trackedFiles: current.repository.trackedFiles,
+    sourceFiles: current.repository.handMaintainedSourceFiles,
+    publicSurface: current.publicSurface,
+    hotspots: current.hotspots,
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  try {
+    const report = checkMaintainability();
+    console.log(
+      `maintainability check passed: ${report.sourceFiles} source files against ${report.enforcementRevision} ` +
+        `(audit baseline ${report.baselineRevision})`,
+    );
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+
+export {
+  checkMaintainability,
+  ensureMaintainabilityRevisionsAvailable,
+  ensureRevisionAvailable,
+  evaluateMaintainability,
+  evaluatePublicSurface,
+  sourceMetricsAtRevision,
+};

package/scripts/compiler-cache-evidence.mjs

@@ -0,0 +1,221 @@
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const BUILDCHAIN_COMPILER_CACHE_PREPARATION_CONTRACT =
+  "kungfu-buildchain-compiler-cache-preparation";
+
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, stableValue(value[key])]),
+    );
+  }
+  return value;
+}
+
+function digest(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(JSON.stringify(stableValue(value)))
+    .digest("hex")}`;
+}
+
+function cleanText(value) {
+  return String(value || "").trim();
+}
+
+function optionalDigest(value, label) {
+  const candidate = cleanText(value);
+  if (!candidate) return "";
+  if (!DIGEST_RE.test(candidate)) {
+    throw new Error(`${label} must be a sha256 digest`);
+  }
+  return candidate;
+}
+
+function defaultRunCommand(command, args, options = {}) {
+  return spawnSync(command, args, {
+    cwd: options.cwd,
+    env: options.env,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+}
+
+function assertCommandSucceeded(result, label) {
+  if (result?.error) {
+    throw new Error(`${label} failed: ${result.error.code || result.error.message}`);
+  }
+  if (result?.status !== 0) {
+    const detail = cleanText(result?.stderr || result?.stdout);
+    throw new Error(`${label} exited ${result?.status ?? "without status"}${detail ? `: ${detail}` : ""}`);
+  }
+}
+
+function appendGithubEnv(filePath, values) {
+  if (!filePath) return;
+  for (const [name, value] of Object.entries(values)) {
+    if (/[\r\n\0]/.test(String(value))) {
+      throw new Error(`${name} contains control characters`);
+    }
+  }
+  fs.appendFileSync(
+    filePath,
+    `${Object.entries(values)
+      .map(([name, value]) => `${name}=${value}`)
+      .join("\n")}\n`,
+  );
+}
+
+function readToolEvidence({ cwd, env, expectedRoot }) {
+  const configured = cleanText(
+    env.BUILDCHAIN_COMPILER_CACHE_TOOL_EVIDENCE_PATH,
+  );
+  if (!configured) return undefined;
+  const filePath = path.resolve(cwd, configured);
+  const relative = path.relative(path.resolve(cwd), filePath);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(
+      "BUILDCHAIN_COMPILER_CACHE_TOOL_EVIDENCE_PATH must remain inside the workflow workspace",
+    );
+  }
+  const evidence = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  if (!DIGEST_RE.test(evidence?.root || "")) {
+    throw new Error("compiler-cache tool evidence root is invalid");
+  }
+  if (expectedRoot && evidence.root !== expectedRoot) {
+    throw new Error(
+      "compiler-cache tool evidence does not match BUILDCHAIN_COMPILER_CACHE_TOOL_ROOT",
+    );
+  }
+  return evidence;
+}
+
+export function prepareCompilerCacheEvidence({
+  cwd = process.cwd(),
+  env = process.env,
+  runCommand = defaultRunCommand,
+  now = () => new Date(),
+} = {}) {
+  const provider = cleanText(env.BUILDCHAIN_COMPILER_CACHE_PROVIDER || "none").toLowerCase();
+  const required = cleanText(env.BUILDCHAIN_COMPILER_CACHE_REQUIRED).toLowerCase() === "true";
+  if (provider !== "sccache") {
+    if (required) {
+      throw new Error(`required compiler cache provider must be sccache, received ${provider || "empty"}`);
+    }
+    return undefined;
+  }
+
+  const outputPath = path.resolve(
+    cwd,
+    cleanText(env.BUILDCHAIN_COMPILER_CACHE_PREPARATION_PATH) ||
+      ".buildchain/diagnostics/compiler-cache-preparation.json",
+  );
+  const versionResult = runCommand("sccache", ["--version"], { cwd, env });
+  assertCommandSucceeded(versionResult, "sccache version probe");
+  const version = cleanText(versionResult.stdout).split(/\r?\n/, 1)[0];
+  if (!version) {
+    throw new Error("sccache version probe returned empty output");
+  }
+
+  const resetResult = runCommand("sccache", ["--zero-stats"], { cwd, env });
+  assertCommandSucceeded(resetResult, "sccache current-run stats reset");
+
+  const compilerCacheToolRoot = optionalDigest(
+    env.BUILDCHAIN_COMPILER_CACHE_TOOL_ROOT,
+    "BUILDCHAIN_COMPILER_CACHE_TOOL_ROOT",
+  );
+  const toolEvidence = readToolEvidence({
+    cwd,
+    env,
+    expectedRoot: compilerCacheToolRoot,
+  });
+  const bindings = Object.fromEntries(
+    [
+      ["sourceCommit", cleanText(env.BUILDCHAIN_SOURCE_SHA || env.GITHUB_SHA)],
+      ["sourceTree", cleanText(env.BUILDCHAIN_SOURCE_TREE_SHA)],
+      ["runtimeCommit", cleanText(env.BUILDCHAIN_RUNTIME_SHA)],
+      ["dependencyLockRoot", cleanText(env.BUILDCHAIN_DEPENDENCY_LOCK_ROOT)],
+      ["toolchainRoot", cleanText(env.BUILDCHAIN_TOOLCHAIN_ROOT)],
+      ["policyRoot", cleanText(env.BUILDCHAIN_CACHE_POLICY_ROOT)],
+      ["cacheProfileRoot", optionalDigest(env.SHIFU_CACHE_PROFILE_DIGEST, "SHIFU_CACHE_PROFILE_DIGEST")],
+      ["compilerCacheToolRoot", compilerCacheToolRoot],
+    ].filter(([, value]) => value),
+  );
+  if (!bindings.sourceCommit) {
+    throw new Error("BUILDCHAIN_SOURCE_SHA is required for compiler-cache preparation evidence");
+  }
+
+  const body = {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_COMPILER_CACHE_PREPARATION_CONTRACT,
+    generatedAt: now().toISOString(),
+    provider,
+    required,
+    status: "prepared",
+    platform: {
+      id: cleanText(env.BUILDCHAIN_PLATFORM_ID) || "unknown",
+      os: cleanText(env.RUNNER_OS) || process.platform,
+      arch: cleanText(env.RUNNER_ARCH) || process.arch,
+    },
+    tool: {
+      command: "sccache",
+      version,
+      ...(bindings.compilerCacheToolRoot
+        ? { evidenceRoot: bindings.compilerCacheToolRoot }
+        : {}),
+      ...(toolEvidence ? { evidence: toolEvidence } : {}),
+    },
+    action: {
+      statsReset: true,
+      command: ["sccache", "--zero-stats"],
+    },
+    bindings,
+  };
+  const receipt = {
+    ...body,
+    root: digest(body),
+  };
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(receipt, null, 2)}\n`);
+  appendGithubEnv(env.GITHUB_ENV, {
+    BUILDCHAIN_COMPILER_CACHE_ACTIVE_PROVIDER: provider,
+    BUILDCHAIN_COMPILER_CACHE_PREPARATION_PATH: outputPath,
+    BUILDCHAIN_COMPILER_CACHE_PREPARATION_ROOT: receipt.root,
+  });
+  return receipt;
+}
+
+function main() {
+  const command = process.argv[2] || "";
+  if (command !== "prepare") {
+    throw new Error("usage: node scripts/compiler-cache-evidence.mjs prepare");
+  }
+  const receipt = prepareCompilerCacheEvidence();
+  if (receipt) {
+    console.log(`compiler_cache_provider=${receipt.provider}`);
+    console.log(`compiler_cache_preparation_root=${receipt.root}`);
+  } else {
+    console.log("compiler_cache_provider=none");
+  }
+}
+
+const isMain = process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}