feat: swap to instrumented __coverage image in dedicated nightly coverage runs

A nightly run can only collect browser coverage if RHDH deploys the
instrumented __coverage plugin image. Today the image swap only happens
in PR mode (when a PR OCI URL is present); nightly runs deploy the plain
released image, so window.__coverage__ is never created.

Add the swap to the nightly OCI-direct resolution branch (plugins not in
default.packages.yaml): for a frontend plugin, replace the image tag with
its __coverage variant.

Gating is deliberately conservative so the FUNCTIONAL nightly cannot
break:
- E2E_NIGHTLY_COVERAGE (explicit opt-in), NOT the ambient
  E2E_COLLECT_COVERAGE. run-e2e.sh defaults E2E_COLLECT_COVERAGE=true, so
  gating on it would make every functional nightly deploy __coverage
  images — and since those are built non-fatally by the overlay release
  publish, a missing one would break the deployment. Requiring the
  explicit opt-in keeps the functional nightly's resolution byte-identical
  to today (the env check short-circuits before any fs access).
- coverage-anchors/ presence (the same rolled-out signal the overlay
  release publish uses to build the __coverage variant), so a plugin
  without one is never pointed at a tag that does not exist.
- frontend-plugin role only.

The {{inherit}} branch (DPDY plugins) is untouched — those resolve to the
RHDH catalog image, which we cannot instrument.

Adds tests for: opted-in swap, no swap in the functional nightly even
with E2E_COLLECT_COVERAGE on, no swap when not rolled out, no swap for
non-frontend roles.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gustavolira

src/utils/plugin-metadata.ts

@@ -475,6 +475,24 @@ async function resolvePluginPackages(
     prOciUrls = await getOCIUrlsForPR(workspacePath, prNumber);
   }
 
+  // A dedicated coverage run swaps rolled-out frontend plugins to their
+  // instrumented __coverage image so the browser exposes window.__coverage__.
+  //
+  // This is gated on E2E_NIGHTLY_COVERAGE (an explicit opt-in), NOT on the
+  // ambient E2E_COLLECT_COVERAGE: the functional nightly runs with coverage
+  // collection on by default but deploys RELEASED images, and the __coverage
+  // variant is built non-fatally by the overlay release publish — so swapping
+  // there could point at a tag that doesn't exist and break the deployment.
+  // Requiring the explicit opt-in keeps the functional nightly's resolution
+  // identical to today; only a coverage-dedicated run (which ensures the
+  // images exist) sets the flag. The coverage-anchors/ check further restricts
+  // the swap to rolled-out workspaces.
+  const coverageSwap =
+    process.env.E2E_NIGHTLY_COVERAGE === "true" &&
+    fs.existsSync(
+      path.join(path.resolve(metadataPath, ".."), "coverage-anchors"),
+    );
+
   return plugins.map((plugin) => {
     const pkg = plugin.package;
     const pluginName = extractPluginName(pkg);
@@ -514,9 +532,15 @@ async function resolvePluginPackages(
       }
 
       // OCI: use metadata's dynamicArtifact directly (not in default.packages.yaml, or not nightly).
+      // For a rolled-out frontend plugin in a coverage run, swap to the
+      // instrumented __coverage image so the nightly can collect coverage.
       if (metadata.packagePath.startsWith("oci://")) {
-        console.log(`[PluginMetadata] ${pkg} → ${metadata.packagePath}`);
-        return { ...plugin, package: metadata.packagePath };
+        const resolved =
+          coverageSwap && metadata.role === "frontend-plugin"
+            ? metadata.packagePath.replace(/(:[^!]+)/, "$1__coverage")
+            : metadata.packagePath;
+        console.log(`[PluginMetadata] ${pkg} → ${resolved}`);
+        return { ...plugin, package: resolved };
       }
 
       // Wrapper (local path): metadata is the source of truth.

src/utils/tests/plugin-metadata.nightly.test.ts

@@ -5,6 +5,9 @@
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert";
 import fs from "fs-extra";
+import path from "path";
+import os from "os";
+import yaml from "js-yaml";
 import {
   isNightlyJob,
   processPluginsForDeployment,
@@ -951,3 +954,125 @@ describe("getDpdyRegistry", () => {
     );
   });
 });
+
+// ── Nightly coverage image swap ──────────────────────────────────────────────
+
+describe("processPluginsForDeployment — nightly coverage swap", () => {
+  const env = withCleanEnv();
+  beforeEach(() => {
+    env.save();
+    delete process.env.GIT_PR_NUMBER;
+    process.env.E2E_NIGHTLY_MODE = "true";
+  });
+  afterEach(() => env.restore());
+
+  const OCI_REF =
+    "oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-theme:bs_1.49.4__0.14.5!red-hat-developer-hub-backstage-plugin-theme";
+
+  // Builds a workspace layout (<ws>/metadata + optional <ws>/coverage-anchors)
+  // and returns the metadata dir to pass as metadataPath. The resolver derives
+  // the workspace root as the parent of the metadata dir.
+  async function createCoverageWorkspace(opts: {
+    rolledOut: boolean;
+    role?: string;
+  }): Promise<string> {
+    const ws = await fs.mkdtemp(path.join(os.tmpdir(), "cov-ws-"));
+    const metadataDir = path.join(ws, "metadata");
+    await fs.ensureDir(metadataDir);
+    if (opts.rolledOut) {
+      await fs.ensureDir(path.join(ws, "coverage-anchors"));
+    }
+    await fs.writeFile(
+      path.join(metadataDir, "theme.yaml"),
+      yaml.dump({
+        apiVersion: "extensions.backstage.io/v1alpha1",
+        kind: "Package",
+        metadata: { name: "theme" },
+        spec: {
+          packageName: "@red-hat-developer-hub/backstage-plugin-theme",
+          dynamicArtifact: OCI_REF,
+          ...(opts.role ? { backstage: { role: opts.role } } : {}),
+        },
+      }),
+    );
+    return metadataDir;
+  }
+
+  const config: DynamicPluginsConfig = {
+    plugins: [{ package: OCI_REF, disabled: false }],
+  };
+
+  async function resolveWith(metadataDir: string): Promise<string> {
+    const result = await processPluginsForDeployment(
+      config,
+      metadataDir,
+      new Set(), // empty DPDY → OCI-direct branch, not {{inherit}}
+    );
+    return result.plugins![0].package;
+  }
+
+  it("swaps to the __coverage image for a rolled-out frontend plugin when opted in", async () => {
+    process.env.E2E_NIGHTLY_COVERAGE = "true";
+    const metadataDir = await createCoverageWorkspace({
+      rolledOut: true,
+      role: "frontend-plugin",
+    });
+    try {
+      const pkg = await resolveWith(metadataDir);
+      assert.strictEqual(
+        pkg,
+        "oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-theme:bs_1.49.4__0.14.5__coverage!red-hat-developer-hub-backstage-plugin-theme",
+        "tag must get the __coverage suffix, the !path must be preserved",
+      );
+    } finally {
+      await fs.remove(path.resolve(metadataDir, ".."));
+    }
+  });
+
+  it("does NOT swap in the functional nightly (E2E_NIGHTLY_COVERAGE unset), even with E2E_COLLECT_COVERAGE on", async () => {
+    // The functional nightly runs with E2E_COLLECT_COVERAGE=true by default but
+    // must keep deploying the released image — swapping there could point at a
+    // __coverage tag that doesn't exist and break the deployment.
+    process.env.E2E_COLLECT_COVERAGE = "true";
+    delete process.env.E2E_NIGHTLY_COVERAGE;
+    const metadataDir = await createCoverageWorkspace({
+      rolledOut: true,
+      role: "frontend-plugin",
+    });
+    try {
+      assert.strictEqual(
+        await resolveWith(metadataDir),
+        OCI_REF,
+        "functional nightly resolution must be unchanged (no swap)",
+      );
+    } finally {
+      await fs.remove(path.resolve(metadataDir, ".."));
+    }
+  });
+
+  it("does not swap when the workspace has no coverage-anchors (not rolled out)", async () => {
+    process.env.E2E_NIGHTLY_COVERAGE = "true";
+    const metadataDir = await createCoverageWorkspace({
+      rolledOut: false,
+      role: "frontend-plugin",
+    });
+    try {
+      assert.strictEqual(await resolveWith(metadataDir), OCI_REF);
+    } finally {
+      await fs.remove(path.resolve(metadataDir, ".."));
+    }
+  });
+
+  it("does not swap a non-frontend plugin even when rolled out and opted in", async () => {
+    process.env.E2E_NIGHTLY_COVERAGE = "true";
+    const metadataDir = await createCoverageWorkspace({
+      rolledOut: true,
+      role: "backend-plugin",
+    });
+    try {
+      assert.strictEqual(await resolveWith(metadataDir), OCI_REF);
+    } finally {
+      await fs.remove(path.resolve(metadataDir, ".."));
+    }
+  });
+});