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

package/scripts/check-internal-architecture.mjs

@@ -42,6 +42,52 @@ function resolveImportTarget(root, sourcePath, specifier) {
   return normalizeRelative(root, absolute);
 }
 
+function resolveGraphTarget(root, sourcePath, specifier, implementationPaths) {
+  const target = resolveImportTarget(root, sourcePath, specifier);
+  return [
+    target,
+    `${target}.js`,
+    `${target}.mjs`,
+    `${target}.cjs`,
+    `${target}/index.js`,
+    `${target}/index.mjs`,
+  ].find((candidate) => implementationPaths.has(candidate));
+}
+
+function dependencyCycles(graph) {
+  const cycles = [];
+  const visited = new Set();
+  const active = new Set();
+  const stack = [];
+  const canonical = new Set();
+  const visit = (node) => {
+    if (active.has(node)) {
+      const start = stack.indexOf(node);
+      const cycle = [...stack.slice(start), node];
+      const members = cycle.slice(0, -1);
+      const rotations = members.map((_, index) => [
+        ...members.slice(index),
+        ...members.slice(0, index),
+      ].join(" -> "));
+      const key = rotations.sort()[0];
+      if (!canonical.has(key)) {
+        canonical.add(key);
+        cycles.push(cycle);
+      }
+      return;
+    }
+    if (visited.has(node)) return;
+    visited.add(node);
+    active.add(node);
+    stack.push(node);
+    for (const target of graph.get(node) || []) visit(target);
+    stack.pop();
+    active.delete(node);
+  };
+  for (const node of [...graph.keys()].sort()) visit(node);
+  return cycles;
+}
+
 function assertIndexShape(index) {
   if (index?.schemaVersion !== 1) {
     throw new Error("internal architecture index schemaVersion must be 1");
@@ -74,6 +120,9 @@ function checkInternalArchitecture({
       continue;
     }
     capabilityIds.add(capability.id);
+    if (!capability.owner || typeof capability.owner !== "string") {
+      issues.push(`${capability.id}: owner is empty`);
+    }
     if (!Array.isArray(capability.implementation) || capability.implementation.length === 0) {
       issues.push(`${capability.id}: implementation mapping is empty`);
     }
@@ -139,6 +188,22 @@ function checkInternalArchitecture({
     }
   }
 
+  const graph = new Map([...expectedImplementation].map((file) => [file, new Set()]));
+  for (const sourcePath of expectedImplementation) {
+    if (![".js", ".mjs", ".cjs"].includes(path.extname(sourcePath))) continue;
+    const source = sourceOverrides.has(sourcePath)
+      ? sourceOverrides.get(sourcePath)
+      : fs.readFileSync(path.resolve(root, sourcePath), "utf8");
+    for (const specifier of relativeImports(source)) {
+      const target = resolveGraphTarget(root, sourcePath, specifier, expectedImplementation);
+      if (target) graph.get(sourcePath).add(target);
+    }
+  }
+  const cycles = dependencyCycles(graph);
+  for (const cycle of cycles) {
+    issues.push(`internal dependency cycle: ${cycle.join(" -> ")}`);
+  }
+
   if (issues.length > 0) {
     throw new Error(
       `internal architecture check failed:\n- ${issues.join("\n- ")}`,
@@ -149,6 +214,7 @@ function checkInternalArchitecture({
     capabilities: index.capabilities.length,
     implementations: expectedImplementation.size,
     dependencyRules: index.dependencyRules.length,
+    dependencyCycles: cycles.length,
   };
 }
 
@@ -160,7 +226,8 @@ if (
     const report = checkInternalArchitecture();
     console.log(
       `internal architecture check passed: ${report.capabilities} capabilities, ` +
-        `${report.implementations} implementations, ${report.dependencyRules} dependency rules`,
+        `${report.implementations} implementations, ${report.dependencyRules} dependency rules, ` +
+        `${report.dependencyCycles} cycles`,
     );
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
@@ -168,4 +235,4 @@ if (
   }
 }
 
-export { checkInternalArchitecture, relativeImports };
+export { checkInternalArchitecture, dependencyCycles, relativeImports };

package/scripts/check-inventory.mjs

@@ -56,6 +56,9 @@ const requiredPaths = [
   "packages/core/anchored-version-material.js",
   "packages/core/build-facts.js",
   "packages/core/publication-package.js",
+  "packages/core/publication-reproducibility.js",
+  "packages/core/publication-sealed-bundle.js",
+  "packages/core/paper.js",
   "packages/core/release-line-bootstrap.js",
   "packages/core/public-surface-audit.js",
   "docs/MAP.md",
@@ -73,10 +76,14 @@ const requiredPaths = [
   "docs/auditable-demo.md",
   "contracts/auditable-demo-media-profiles-v1.json",
   "contracts/evidence/auditable-demo-web-delivery-v1.json",
+  "contracts/evidence/auditable-demo-responsive-web-delivery-v1.json",
   "contracts/buildchain-v2-residuals-v1.json",
   "contracts/fixtures/auditable-demo-web-delivery-v1/complete-transcript.txt",
   "contracts/fixtures/auditable-demo-web-delivery-v1/public-projection.json",
   "contracts/fixtures/auditable-demo-web-delivery-v1/scene.json",
+  "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/complete-transcript.txt",
+  "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/public-projection.json",
+  "contracts/fixtures/auditable-demo-responsive-web-delivery-v1/scene.json",
   "docs/release-propagation.md",
   "docs/site-bundle-contract.md",
   "docs/toolkit-observability.md",
@@ -102,8 +109,10 @@ const requiredPaths = [
   "scripts/anchored-version-material.mjs",
   "scripts/npm-publish-dry-run.mjs",
   "scripts/npm-publish-transaction.mjs",
+  "scripts/paper.mjs",
   "scripts/publication-package.mjs",
   "scripts/publication-commit-evidence.mjs",
+  "scripts/publication-reproducibility.mjs",
   "scripts/release-candidate-resolver.mjs",
   "scripts/buildchain-patrol.mjs",
   "scripts/observed-evidence.mjs",
@@ -114,6 +123,7 @@ const requiredPaths = [
   "docs/observed-evidence-patrol.md",
   "docs/ownership.md",
   "tests/buildchain-inventory.json",
+  "tests/paper.test.mjs",
   ".buildchain/buildchain.toml",
   ".buildchain/contract-lock.json",
   ".buildchain/alpha-contract-lock.json",
@@ -261,12 +271,19 @@ for (const requiredSnippet of [
   `/${promotionShellRouting.stable.workflowPath}@${promotionShellRouting.stable.callRef}`,
   `STABLE_SHELL_REF: v${selfDogfoodMajor}`,
   "promotion-contract-lock-digest:",
-  "promotion runtime override is only allowed for trusted workflow_dispatch runs",
+  "authorize-promotion-runtime-override.cjs",
 ]) {
   if (!channelPromotionWorkflow.includes(requiredSnippet)) {
     throw new Error(`channel promotion workflow missing routing contract: ${requiredSnippet}`);
   }
 }
+const promotionOverrideAuthorization = fs.readFileSync(
+  path.join(root, "scripts/authorize-promotion-runtime-override.cjs"),
+  "utf8",
+);
+if (!promotionOverrideAuthorization.includes("promotion runtime override is only allowed for trusted workflow_dispatch runs")) {
+  throw new Error("promotion runtime override authorization must remain fail closed");
+}
 for (const requiredSnippet of [
   "buildchain-channel:",
   "uses: ./.github/workflows/.build.yml",
@@ -383,6 +400,9 @@ if (rootPackage.exports?.["./buildchain-kfd-claims"] !== "./packages/core/buildc
 if (rootPackage.exports?.["./public-surface-audit"] !== "./packages/core/public-surface-audit.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/public-surface-audit");
 }
+if (rootPackage.exports?.["./paper"] !== "./packages/core/paper.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/paper");
+}
 if (rootPackage.exports?.["./site/buildchain-site.json"] !== "./dist/site/buildchain-site.json") {
   throw new Error("root package must export @kungfu-tech/buildchain/site/buildchain-site.json");
 }
@@ -647,16 +667,60 @@ for (const manual of manualRegistry.manuals || []) {
   }
 }
 const cliRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/cli-registry.json"), "utf8"));
+const requiredPublicLifecycleFields = [
+  "owner",
+  "maturity",
+  "introducedVersion",
+  "compatibilityPromise",
+  "deprecationReplacement",
+  "sunsetCondition",
+  "capabilityGroup",
+  "nonDuplicationRationale",
+];
+function assertPublicLifecycle(entry, label) {
+  for (const field of requiredPublicLifecycleFields) {
+    if (!Object.prototype.hasOwnProperty.call(entry, field) || typeof entry[field] !== "string") {
+      throw new Error(`${label} missing public lifecycle field: ${field}`);
+    }
+  }
+  if (!entry.owner || !entry.maturity || !entry.introducedVersion || !entry.compatibilityPromise || !entry.sunsetCondition || !entry.nonDuplicationRationale) {
+    throw new Error(`${label} has incomplete public lifecycle metadata`);
+  }
+}
 for (const command of cliRegistry.commands || []) {
   if (!command.capabilityGroup || !capabilityGroupIds.has(command.capabilityGroup) || !Array.isArray(command.audience) || !command.maturity || !command.purpose || command.purpose.includes("Add a specific purpose")) {
     throw new Error(`cli-registry.json command missing capability metadata: ${command.id || command.usage}`);
   }
+  assertPublicLifecycle(command, `cli-registry.json command ${command.id || command.usage}`);
 }
 const nodeApiRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/node-api-registry.json"), "utf8"));
 for (const exported of nodeApiRegistry.exports || []) {
   if (!exported.capabilityGroup || !capabilityGroupIds.has(exported.capabilityGroup) || !Array.isArray(exported.audience) || !exported.maturity || !exported.summary) {
     throw new Error(`node-api-registry.json export missing capability metadata: ${exported.export || exported.specifier}`);
   }
+  assertPublicLifecycle(exported, `node-api-registry.json export ${exported.export || exported.specifier}`);
+}
+const workflowRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/workflow-registry.json"), "utf8"));
+for (const workflow of workflowRegistry.workflows || []) {
+  assertPublicLifecycle(workflow, `workflow-registry.json workflow ${workflow.id || workflow.path}`);
+}
+for (const action of workflowRegistry.actions || []) {
+  assertPublicLifecycle(action, `workflow-registry.json action ${action.id || action.path}`);
+}
+const registeredActionIds = (workflowRegistry.actions || []).map((entry) => entry.id).sort();
+const readmeActionIndex = fs.readFileSync(path.join(root, "README.md"), "utf8");
+const mapActionIndex = fs.readFileSync(path.join(root, "docs/MAP.md"), "utf8");
+const retrospectiveActionIndex = fs.readFileSync(path.join(root, ".github/retrospectives/2026-07-10-buildchain-consolidation.md"), "utf8");
+if (registeredActionIds.length !== 6) {
+  throw new Error(`workflow-registry.json must expose the six current action entries, got ${registeredActionIds.length}`);
+}
+for (const actionId of registeredActionIds) {
+  if (!readmeActionIndex.includes(`actions/${actionId}`) || !mapActionIndex.includes(`actions/${actionId}`)) {
+    throw new Error(`README and docs/MAP.md must index registered action: ${actionId}`);
+  }
+}
+if (!retrospectiveActionIndex.includes("snapshot of the four consumer-facing actions")) {
+  throw new Error("the v2 four-action retrospective must remain explicitly classified as historical");
 }
 if (!pageRegistry.pages?.some((page) => page.sourcePath === "actions/promote-buildchain-ref/README.md")) {
   throw new Error("page-registry.json must include action manuals");
@@ -1069,7 +1133,10 @@ if (commonJsSourcePattern.test(npmDryRunScript)) {
 }
 for (const requiredSnippet of [
   "BUILDCHAIN_PUBLISH_EVIDENCE",
-  "\"publish\", \"--access\", access, \"--tag\", distTag",
+  "BUILDCHAIN_SEALED_NPM_TARBALL",
+  "...(pack.tarballPath ? [pack.tarballPath] : [])",
+  "\"--access\"",
+  "\"--tag\"",
   "artifact digest mismatch",
 ]) {
   if (!npmPublishTransactionScript.includes(requiredSnippet)) {

package/scripts/check-javascript-syntax.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+
+const root = process.cwd();
+const files = execFileSync(
+  "git",
+  ["ls-files", "--cached", "--others", "--exclude-standard"],
+  { cwd: root, encoding: "utf8" },
+)
+  .split("\n")
+  .filter((file) => [".js", ".mjs", ".cjs"].includes(path.extname(file)))
+  .filter((file) => !/^actions\/[^/]+\/dist\//u.test(file))
+  .sort();
+
+const failures = [];
+for (const file of files) {
+  const result = spawnSync(process.execPath, ["--check", file], {
+    cwd: root,
+    encoding: "utf8",
+  });
+  if (result.status !== 0) {
+    failures.push(`${file}: ${(result.stderr || result.stdout).trim()}`);
+  }
+}
+
+if (failures.length > 0) {
+  throw new Error(`JavaScript syntax check failed:\n${failures.join("\n")}`);
+}
+console.log(`JavaScript syntax check passed: ${files.length} files`);

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,
+};