@kungfu-tech/buildchain 3.0.4-alpha.2 → 3.0.4-alpha.3

package/scripts/check-internal-architecture.mjs

@@ -2,6 +2,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 
 const implementationExtensions = new Set([".js", ".mjs", ".cjs", ".sh"]);
@@ -9,7 +10,10 @@ const importPattern =
   /(?:\bimport\s*(?:\([^)]*?\)|[^"'\n]*?\s+from\s+)?|\bexport\s+[^"'\n]*?\s+from\s+)(["'])([^"'\n]+)\1/g;
 
 function normalizeRelative(root, value) {
-  return path.relative(root, path.resolve(root, value)).split(path.sep).join("/");
+  return path
+    .relative(root, path.resolve(root, value))
+    .split(path.sep)
+    .join("/");
 }
 
 function isInside(relativePath, prefix) {
@@ -22,11 +26,15 @@ function collectImplementationFiles(root, entry) {
     throw new Error(`internal architecture path is missing: ${entry}`);
   }
   if (fs.statSync(absolute).isFile()) {
-    return implementationExtensions.has(path.extname(absolute)) ? [absolute] : [];
+    return implementationExtensions.has(path.extname(absolute))
+      ? [absolute]
+      : [];
   }
-  return fs.readdirSync(absolute, { withFileTypes: true }).flatMap((item) =>
-    collectImplementationFiles(root, path.join(entry, item.name))
-  );
+  return fs
+    .readdirSync(absolute, { withFileTypes: true })
+    .flatMap((item) =>
+      collectImplementationFiles(root, path.join(entry, item.name)),
+    );
 }
 
 function relativeImports(source) {
@@ -38,7 +46,10 @@ function relativeImports(source) {
 }
 
 function resolveImportTarget(root, sourcePath, specifier) {
-  const absolute = path.resolve(path.dirname(path.resolve(root, sourcePath)), specifier);
+  const absolute = path.resolve(
+    path.dirname(path.resolve(root, sourcePath)),
+    specifier,
+  );
   return normalizeRelative(root, absolute);
 }
 
@@ -65,10 +76,9 @@ function dependencyCycles(graph) {
       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 rotations = members.map((_, index) =>
+        [...members.slice(index), ...members.slice(0, index)].join(" -> "),
+      );
       const key = rotations.sort()[0];
       if (!canonical.has(key)) {
         canonical.add(key);
@@ -92,38 +102,106 @@ function assertIndexShape(index) {
   if (index?.schemaVersion !== 1) {
     throw new Error("internal architecture index schemaVersion must be 1");
   }
-  for (const field of ["coverageRoots", "dependencyRules", "capabilities"]) {
+  for (const field of [
+    "coverageRoots",
+    "dependencyRules",
+    "ownershipRules",
+    "capabilities",
+  ]) {
     if (!Array.isArray(index[field]) || index[field].length === 0) {
-      throw new Error(`internal architecture index requires non-empty ${field}`);
+      throw new Error(
+        `internal architecture index requires non-empty ${field}`,
+      );
     }
   }
 }
 
-function checkInternalArchitecture({
-  root = process.cwd(),
-  index = JSON.parse(
-    fs.readFileSync(
-      path.join(root, "architecture", "internal-capabilities.json"),
-      "utf8",
-    ),
-  ),
-  sourceOverrides = new Map(),
-} = {}) {
-  assertIndexShape(index);
+function repositoryJavaScriptFiles(root) {
+  return execFileSync(
+    "git",
+    ["ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+    {
+      cwd: root,
+      encoding: "utf8",
+    },
+  )
+    .split("\0")
+    .filter(Boolean)
+    .filter((file) => fs.existsSync(path.resolve(root, file)))
+    .filter((file) => [".js", ".mjs", ".cjs"].includes(path.extname(file)))
+    .filter((file) => !file.startsWith("tests/"))
+    .filter((file) => !/(?:^|\/)tests?\//u.test(file))
+    .filter((file) => !/^actions\/[^/]+\/dist\//u.test(file))
+    .sort();
+}
+
+function ownershipFor(index, sourcePath) {
+  return index.ownershipRules.filter((rule) =>
+    (rule.paths || []).some((prefix) => isInside(sourcePath, prefix)),
+  );
+}
+
+function evaluateSourceOwnership(index, repositorySources) {
+  const issues = [];
+  const exclusions = new Map(
+    (index.ownershipExclusions || []).map((entry) => [entry.path, entry]),
+  );
+  let ownedSources = 0;
+  let excludedSources = 0;
+  for (const sourcePath of repositorySources) {
+    const owners = ownershipFor(index, sourcePath);
+    const exclusion = exclusions.get(sourcePath);
+    if (owners.length === 1 && !exclusion) {
+      if (!String(owners[0].owner || "").trim()) {
+        issues.push(`${owners[0].id}: ownership rule owner is empty`);
+      } else {
+        ownedSources += 1;
+      }
+    } else if (owners.length === 0 && exclusion) {
+      if (!String(exclusion.rationale || "").trim()) {
+        issues.push(`${sourcePath}: ownership exclusion requires a rationale`);
+      } else {
+        excludedSources += 1;
+      }
+    } else if (owners.length === 0) {
+      issues.push(`repository source has no owner: ${sourcePath}`);
+    } else if (owners.length > 1) {
+      issues.push(
+        `repository source has multiple owners: ${sourcePath} (${owners.map((entry) => entry.id).join(", ")})`,
+      );
+    } else {
+      issues.push(
+        `repository source is both owned and excluded: ${sourcePath}`,
+      );
+    }
+  }
+  for (const [sourcePath] of exclusions) {
+    if (!repositorySources.includes(sourcePath)) {
+      issues.push(`ownership exclusion is stale: ${sourcePath}`);
+    }
+  }
+  return { issues, ownedSources, excludedSources };
+}
+
+function evaluateCapabilities(root, index) {
   const issues = [];
   const capabilityIds = new Set();
   const coveredImplementation = new Map();
-
   for (const capability of index.capabilities) {
     if (!capability?.id || capabilityIds.has(capability.id)) {
-      issues.push(`capability id must be present and unique: ${capability?.id || "<empty>"}`);
+      issues.push(
+        `capability id must be present and unique: ${capability?.id || "<empty>"}`,
+      );
       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) {
+    if (
+      !Array.isArray(capability.implementation) ||
+      capability.implementation.length === 0
+    ) {
       issues.push(`${capability.id}: implementation mapping is empty`);
     }
     if (!Array.isArray(capability.tests) || capability.tests.length === 0) {
@@ -131,47 +209,58 @@ function checkInternalArchitecture({
     }
     for (const field of ["implementation", "tests", "contracts"]) {
       for (const relativePath of capability[field] || []) {
-        const absolutePath = path.resolve(root, relativePath);
-        if (!fs.existsSync(absolutePath)) {
-          issues.push(`${capability.id}: ${field} path is missing: ${relativePath}`);
+        if (!fs.existsSync(path.resolve(root, relativePath))) {
+          issues.push(
+            `${capability.id}: ${field} path is missing: ${relativePath}`,
+          );
         }
-        if (field === "implementation") {
-          const owner = coveredImplementation.get(relativePath);
-          if (owner) {
-            issues.push(
-              `${relativePath}: implementation is mapped by both ${owner} and ${capability.id}`,
-            );
-          } else {
-            coveredImplementation.set(relativePath, capability.id);
-          }
+        if (field !== "implementation") continue;
+        const owner = coveredImplementation.get(relativePath);
+        if (owner) {
+          issues.push(
+            `${relativePath}: implementation is mapped by both ${owner} and ${capability.id}`,
+          );
+        } else {
+          coveredImplementation.set(relativePath, capability.id);
         }
       }
     }
   }
-
   const expectedImplementation = new Set(
     index.coverageRoots.flatMap((entry) =>
       collectImplementationFiles(root, entry).map((absolutePath) =>
-        normalizeRelative(root, absolutePath)
-      )
+        normalizeRelative(root, absolutePath),
+      ),
     ),
   );
   for (const relativePath of expectedImplementation) {
     if (!coveredImplementation.has(relativePath)) {
-      issues.push(`capability-to-test mapping is missing implementation: ${relativePath}`);
+      issues.push(
+        `capability-to-test mapping is missing implementation: ${relativePath}`,
+      );
     }
   }
   for (const relativePath of coveredImplementation.keys()) {
     if (!expectedImplementation.has(relativePath)) {
-      issues.push(`capability implementation is outside coverageRoots: ${relativePath}`);
+      issues.push(
+        `capability implementation is outside coverageRoots: ${relativePath}`,
+      );
     }
   }
+  return { issues, expectedImplementation };
+}
 
+function evaluateDependencyDirections(root, index, sourceOverrides) {
+  const issues = [];
   for (const rule of index.dependencyRules) {
     const allowed = rule.allowedRelativeTargets || [];
     for (const sourceEntry of rule.sources || []) {
-      for (const absoluteSource of collectImplementationFiles(root, sourceEntry)) {
-        if (![".js", ".mjs", ".cjs"].includes(path.extname(absoluteSource))) continue;
+      for (const absoluteSource of collectImplementationFiles(
+        root,
+        sourceEntry,
+      )) {
+        if (![".js", ".mjs", ".cjs"].includes(path.extname(absoluteSource)))
+          continue;
         const sourcePath = normalizeRelative(root, absoluteSource);
         const source = sourceOverrides.has(sourcePath)
           ? sourceOverrides.get(sourcePath)
@@ -187,18 +276,42 @@ function checkInternalArchitecture({
       }
     }
   }
+  return issues;
+}
 
-  const graph = new Map([...expectedImplementation].map((file) => [file, new Set()]));
-  for (const sourcePath of expectedImplementation) {
-    if (![".js", ".mjs", ".cjs"].includes(path.extname(sourcePath))) continue;
+function buildRepositoryGraph(root, repositorySources, sourceOverrides) {
+  const sourceSet = new Set(repositorySources);
+  const graph = new Map(repositorySources.map((file) => [file, new Set()]));
+  for (const sourcePath of repositorySources) {
     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);
+      const target = resolveGraphTarget(root, sourcePath, specifier, sourceSet);
       if (target) graph.get(sourcePath).add(target);
     }
   }
+  return graph;
+}
+
+function checkInternalArchitecture({
+  root = process.cwd(),
+  index = JSON.parse(
+    fs.readFileSync(
+      path.join(root, "architecture", "internal-capabilities.json"),
+      "utf8",
+    ),
+  ),
+  sourceOverrides = new Map(),
+} = {}) {
+  assertIndexShape(index);
+  const issues = [];
+  const repositorySources = repositoryJavaScriptFiles(root);
+  const ownership = evaluateSourceOwnership(index, repositorySources);
+  const capabilities = evaluateCapabilities(root, index);
+  issues.push(...ownership.issues, ...capabilities.issues);
+  issues.push(...evaluateDependencyDirections(root, index, sourceOverrides));
+  const graph = buildRepositoryGraph(root, repositorySources, sourceOverrides);
   const cycles = dependencyCycles(graph);
   for (const cycle of cycles) {
     issues.push(`internal dependency cycle: ${cycle.join(" -> ")}`);
@@ -212,7 +325,14 @@ function checkInternalArchitecture({
   return {
     schemaVersion: index.schemaVersion,
     capabilities: index.capabilities.length,
-    implementations: expectedImplementation.size,
+    implementations: capabilities.expectedImplementation.size,
+    repositorySources: repositorySources.length,
+    ownedSources: ownership.ownedSources,
+    excludedSources: ownership.excludedSources,
+    dependencyEdges: [...graph.values()].reduce(
+      (total, targets) => total + targets.size,
+      0,
+    ),
     dependencyRules: index.dependencyRules.length,
     dependencyCycles: cycles.length,
   };
@@ -226,7 +346,8 @@ if (
     const report = checkInternalArchitecture();
     console.log(
       `internal architecture check passed: ${report.capabilities} capabilities, ` +
-        `${report.implementations} implementations, ${report.dependencyRules} dependency rules, ` +
+        `${report.implementations} capability implementations, ${report.ownedSources}/${report.repositorySources} owned sources, ` +
+        `${report.dependencyEdges} dependency edges, ${report.dependencyRules} dependency rules, ` +
         `${report.dependencyCycles} cycles`,
     );
   } catch (error) {
@@ -235,4 +356,9 @@ if (
   }
 }
 
-export { checkInternalArchitecture, dependencyCycles, relativeImports };
+export {
+  checkInternalArchitecture,
+  dependencyCycles,
+  relativeImports,
+  repositoryJavaScriptFiles,
+};

package/scripts/check-maintainability.mjs

@@ -166,14 +166,23 @@ function evaluatePublicSurface({ root, revision, policy }) {
         );
       }
       const previous = baselineByKey.get(entry[definition.key]);
+      const currentContract = publicSurfaceContract(entry, definition.kind);
       if (
         previous &&
-        JSON.stringify(publicSurfaceContract(entry, definition.kind)) !==
+        JSON.stringify(currentContract) !==
           JSON.stringify(publicSurfaceContract(previous, definition.kind))
       ) {
-        issues.push(
-          `${label}: existing public contract drifted from ${revision}`,
-        );
+        const approval = policy.approvedPublicSurfaceTransitions?.[label];
+        const approved =
+          approval?.fromRevision === revision &&
+          String(approval?.rationale || "").trim() &&
+          JSON.stringify(approval?.contract) ===
+            JSON.stringify(currentContract);
+        if (!approved) {
+          issues.push(
+            `${label}: existing public contract drifted from ${revision}`,
+          );
+        }
       }
       if (!previous && !entry.nonDuplicationRationale) {
         issues.push(
@@ -193,16 +202,19 @@ function evaluateAddedFunctionBudgets({
   budgets,
 }) {
   const issues = [];
-  const baselineFunctionNames = new Set(
-    (baseline.functions || [])
-      .map((entry) => entry.name)
-      .filter((name) => !name.startsWith("<anonymous@")),
-  );
+  const identity = (entry) =>
+    entry.name.startsWith("<anonymous@") ? "<anonymous>" : entry.name;
+  const baselineFunctionCounts = new Map();
+  for (const entry of baseline.functions || []) {
+    const key = identity(entry);
+    baselineFunctionCounts.set(key, (baselineFunctionCounts.get(key) || 0) + 1);
+  }
+  const currentFunctionCounts = new Map();
   for (const entry of metrics.functions) {
-    if (
-      entry.name.startsWith("<anonymous@") ||
-      baselineFunctionNames.has(entry.name)
-    ) {
+    const identityKey = identity(entry);
+    const occurrence = (currentFunctionCounts.get(identityKey) || 0) + 1;
+    currentFunctionCounts.set(identityKey, occurrence);
+    if (occurrence <= (baselineFunctionCounts.get(identityKey) || 0)) {
       continue;
     }
     const key = `${file}#${entry.name}`;
@@ -227,6 +239,43 @@ function evaluateAddedFunctionBudgets({
   return issues;
 }
 
+function evaluateRepositoryBudgets({ current, policy }) {
+  const issues = [];
+  const budgets = policy.repositoryBudgets;
+  if (!budgets) return issues;
+  if (!String(budgets.rationale || "").trim()) {
+    issues.push("repository growth budget requires a rationale");
+  }
+  const checks = [
+    [
+      "handMaintainedSourceFiles",
+      "maxHandMaintainedSourceFiles",
+      "source files",
+    ],
+    [
+      "handMaintainedSourceLines",
+      "maxHandMaintainedSourceLines",
+      "source lines",
+    ],
+    ["workflowFiles", "maxWorkflowFiles", "workflow files"],
+    ["workflowLines", "maxWorkflowLines", "workflow lines"],
+  ];
+  for (const [metric, ceiling, label] of checks) {
+    if (!Number.isInteger(budgets[ceiling]) || budgets[ceiling] < 0) {
+      issues.push(
+        `repository growth budget ${ceiling} must be a non-negative integer`,
+      );
+      continue;
+    }
+    if (current.repository[metric] > budgets[ceiling]) {
+      issues.push(
+        `repository ${label} are ${current.repository[metric]}; approved ceiling is ${budgets[ceiling]}`,
+      );
+    }
+  }
+  return issues;
+}
+
 function evaluateMaintainability({ current, baselineFiles, policy }) {
   const issues = [];
   const budgets = policy.sourceBudgets;
@@ -239,14 +288,22 @@ function evaluateMaintainability({ current, baselineFiles, policy }) {
         );
       }
       for (const entry of metrics.functions) {
-        if (entry.lines > budgets.newFunctionLines) {
+        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 ${budgets.newFunctionLines}`,
+            `${file}:${entry.start} ${entry.name} has ${entry.lines} lines; new-function budget is ${allowedLines}`,
           );
         }
-        if (entry.complexity > budgets.newFunctionComplexity) {
+        if (entry.complexity > allowedComplexity) {
           issues.push(
-            `${file}:${entry.start} ${entry.name} has complexity ${entry.complexity}; new-function budget is ${budgets.newFunctionComplexity}`,
+            `${file}:${entry.start} ${entry.name} has complexity ${entry.complexity}; new-function budget is ${allowedComplexity}`,
           );
         }
       }
@@ -326,6 +383,7 @@ function checkMaintainability({ root = process.cwd() } = {}) {
   const current = collectMaintainabilityMetrics({ root });
   const baselineFiles = sourceMetricsAtRevision(root, enforcementRevision);
   const issues = evaluateMaintainability({ current, baselineFiles, policy });
+  issues.push(...evaluateRepositoryBudgets({ current, policy }));
   issues.push(
     ...evaluatePublicSurface({ root, revision: enforcementRevision, policy }),
   );
@@ -366,6 +424,7 @@ export {
   ensureMaintainabilityRevisionsAvailable,
   ensureRevisionAvailable,
   evaluateMaintainability,
+  evaluateRepositoryBudgets,
   evaluatePublicSurface,
   sourceMetricsAtRevision,
 };

package/scripts/generate-site-bundle.mjs

@@ -621,6 +621,21 @@ function createPublicationReleaseRegistry({ packageJson, timestampPolicy }) {
   };
 }
 
+const RELEASE_PROPAGATION_MODEL = {
+  graphContract: "kungfu-buildchain-release-propagation-graph",
+  planContract: "kungfu-buildchain-release-propagation-plan",
+  lockContract: "kungfu-buildchain-release-propagation-lock",
+  workContract: "kungfu-buildchain-release-propagation-work",
+  stageReceiptContract: "kungfu-buildchain-release-propagation-stage-receipt",
+  workControlBindings: [
+    "kungfu.assignment-graph.work-ref/v1",
+    "kungfu.work-control.initiative-family-state/v2",
+  ],
+  completionBoundary: "production-online-readback-plus-accepted-work-control-decision",
+  defaultChannelPolicy: "preserve",
+  defaultChannelMap: { alpha: "alpha", release: "release" },
+};
+
 function buildSiteBundle() {
   const packageJson = readJson("package.json");
   const inventory = readJson("tests/buildchain-inventory.json");
@@ -857,13 +872,7 @@ function buildSiteBundle() {
       schema: "schemas/release-passport-v1.schema.json",
       checkManifest: "release-passport-check-manifest.json",
     },
-    releasePropagation: {
-      graphContract: "kungfu-buildchain-release-propagation-graph",
-      planContract: "kungfu-buildchain-release-propagation-plan",
-      lockContract: "kungfu-buildchain-release-propagation-lock",
-      defaultChannelPolicy: "preserve",
-      defaultChannelMap: { alpha: "alpha", release: "release" },
-    },
+    releasePropagation: RELEASE_PROPAGATION_MODEL,
     npm: {
       package: packageJson.name,
       command: packageJson.bin?.buildchain || "",

package/scripts/maintainability-metrics.mjs

@@ -174,10 +174,12 @@ function architectureSummary(root, revision = "") {
   const implementationPaths = new Set(
     index.capabilities.flatMap((entry) => entry.implementation || []),
   );
-  const graph = new Map(
-    [...implementationPaths].map((file) => [file, new Set()]),
+  const repositorySources = trackedFiles(root, revision).filter(
+    isHandMaintainedSource,
   );
-  for (const file of implementationPaths) {
+  const repositorySourceSet = new Set(repositorySources);
+  const graph = new Map(repositorySources.map((file) => [file, new Set()]));
+  for (const file of repositorySources) {
     if (!JS_EXTENSIONS.has(path.extname(file))) continue;
     for (const specifier of relativeImports(
       readTrackedFile(root, file, revision),
@@ -192,10 +194,20 @@ function architectureSummary(root, revision = "") {
         `${base}.cjs`,
         `${base}/index.js`,
         `${base}/index.mjs`,
-      ].find((candidate) => implementationPaths.has(candidate));
+      ].find((candidate) => repositorySourceSet.has(candidate));
       if (target) graph.get(file).add(target);
     }
   }
+  const exclusions = new Set(
+    (index.ownershipExclusions || []).map((entry) => entry.path),
+  );
+  const ownedSources = repositorySources.filter((file) =>
+    index.ownershipRules?.some((rule) =>
+      (rule.paths || []).some(
+        (prefix) => file === prefix || file.startsWith(`${prefix}/`),
+      ),
+    ),
+  ).length;
   return {
     capabilities: index.capabilities.length,
     implementationMappings: index.capabilities.reduce(
@@ -207,6 +219,14 @@ function architectureSummary(root, revision = "") {
       0,
     ),
     dependencyRules: index.dependencyRules.length,
+    repositorySources: repositorySources.length,
+    ownedSources,
+    excludedSources: repositorySources.filter((file) => exclusions.has(file))
+      .length,
+    dependencyEdges: [...graph.values()].reduce(
+      (total, targets) => total + targets.size,
+      0,
+    ),
     dependencyCycles: dependencyCycles(graph).length,
   };
 }