feat(showcase): add build-outputs parser for structured build-matrix results

Author: jpr5

showcase/scripts/lib/__tests__/build-outputs.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import {
+    parseBuildOutputs,
+    successSet,
+    type BuildOutcome,
+    type ServiceBuildResult,
+} from "../build-outputs";
+
+const sample: ServiceBuildResult[] = [
+    { service: "showcase-mastra", status: "success" },
+    { service: "showcase-ag2", status: "failure" },
+    { service: "shell-docs", status: "skipped" },
+    { service: "showcase-aimock", status: "success" },
+];
+
+describe("build-outputs", () => {
+    it("parses a JSON array of {service,status} entries", () => {
+        const json = JSON.stringify(sample);
+        expect(parseBuildOutputs(json)).toEqual(sample);
+    });
+
+    it("throws on malformed JSON", () => {
+        expect(() => parseBuildOutputs("not json")).toThrow(/parse/i);
+    });
+
+    it("throws on entries missing fields", () => {
+        expect(() => parseBuildOutputs(JSON.stringify([{ service: "x" }]))).toThrow(
+            /status/i,
+        );
+    });
+
+    it("throws on an unknown status value", () => {
+        const bad = JSON.stringify([{ service: "x", status: "weird" }]);
+        expect(() => parseBuildOutputs(bad)).toThrow(/status/i);
+    });
+
+    it("successSet returns only services with status === 'success'", () => {
+        expect(successSet(sample).sort()).toEqual(
+            ["showcase-aimock", "showcase-mastra"].sort(),
+        );
+    });
+
+    it("successSet returns empty when no services succeeded", () => {
+        const allFailed: ServiceBuildResult[] = [
+            { service: "a", status: "failure" },
+            { service: "b", status: "failure" },
+        ];
+        expect(successSet(allFailed)).toEqual([]);
+    });
+
+    it("type BuildOutcome enumerates success|failure|skipped", () => {
+        const outcomes: BuildOutcome[] = ["success", "failure", "skipped"];
+        expect(outcomes).toHaveLength(3);
+    });
+});

showcase/scripts/lib/build-outputs.ts

@@ -0,0 +1,68 @@
+/**
+ * build-outputs.ts — Parse + merge the structured per-slot build results
+ * emitted by `showcase_build.yml`. Each matrix slot in the build job
+ * uploads a per-slot artifact named `build-result-<dispatch_name>`
+ * containing a single `result.json` payload of the shape
+ * `{service: "<dispatch_name>", status: "success"|"failure"|"skipped"}`.
+ * The aggregate-build-results job downloads every `build-result-*`
+ * artifact and merges the payloads via `mergeBuildResultFiles` below;
+ * the resulting array is uploaded as the canonical `build-results`
+ * artifact for cross-workflow consumption. The deploy workflow (and the
+ * redeploy guard) read this list instead of parsing job names.
+ */
+
+export type BuildOutcome = "success" | "failure" | "skipped";
+
+export interface ServiceBuildResult {
+    service: string;
+    status: BuildOutcome;
+}
+
+const VALID_STATUSES: ReadonlySet<BuildOutcome> = new Set([
+    "success",
+    "failure",
+    "skipped",
+]);
+
+export function parseBuildOutputs(raw: string): ServiceBuildResult[] {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (e) {
+        throw new Error(
+            `Failed to parse build outputs JSON: ${
+                e instanceof Error ? e.message : String(e)
+            }`,
+        );
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error("Build outputs must be a JSON array");
+    }
+    const results: ServiceBuildResult[] = [];
+    for (const entry of parsed) {
+        if (
+            typeof entry !== "object" ||
+            entry === null ||
+            typeof (entry as { service?: unknown }).service !== "string"
+        ) {
+            throw new Error(
+                `Build outputs entry missing required string field "service": ${JSON.stringify(entry)}`,
+            );
+        }
+        const status = (entry as { status?: unknown }).status;
+        if (typeof status !== "string" || !VALID_STATUSES.has(status as BuildOutcome)) {
+            throw new Error(
+                `Build outputs entry has invalid "status" (must be success|failure|skipped): ${JSON.stringify(entry)}`,
+            );
+        }
+        results.push({
+            service: (entry as { service: string }).service,
+            status: status as BuildOutcome,
+        });
+    }
+    return results;
+}
+
+export function successSet(results: ServiceBuildResult[]): string[] {
+    return results.filter((r) => r.status === "success").map((r) => r.service);
+}