refactor: dedupe coverage-tag rewrite + document E2E_NIGHTLY_COVERAGE

Review follow-ups on the nightly coverage swap:

- Extract toCoverageImageRef() so the `:(tag)__coverage` rewrite (and the
  greedy-up-to-! regex) lives in one documented place instead of being
  duplicated across PR mode and nightly resolution.
- Hoist the workspace-root resolution to a single workspaceRoot const
  (was computed twice).
- Document the new behavior per the repo convention: a changelog entry,
  an E2E_NIGHTLY_COVERAGE row in the environment-variables reference, and
  a coverage-swap section in plugin-metadata-resolution.

No behavior change; full suite still passes (yarn check + tests green).

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

Author: gustavolira

docs/changelog.md

@@ -7,6 +7,7 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - **E2E coverage collection auto-fixture**: New `_coverageCollector` automatic fixture collects Istanbul coverage (`window.__coverage__`) from the browser after each test and writes per-test JSON files to `<outputDir>/coverage/`. Enabled via `E2E_COLLECT_COVERAGE=true`. Zero overhead when disabled — no `page.evaluate` call or fs operations. Designed for use with instrumented dynamic plugin builds (nyc instrument).
+- **Nightly coverage image swap** (`E2E_NIGHTLY_COVERAGE`): In nightly plugin resolution, an explicit opt-in swaps a rolled-out frontend plugin (workspace with a `coverage-anchors/` directory) from its released OCI image to the instrumented `__coverage` variant, so a coverage-dedicated nightly run can collect browser coverage. Gated separately from the ambient `E2E_COLLECT_COVERAGE` so the functional nightly's resolution is unchanged; `{{inherit}}` (DPDY) plugins are never swapped.
 
 ### Fixed
 

docs/guide/configuration/environment-variables.md

@@ -48,6 +48,7 @@ These control automatic plugin configuration injection from metadata files.
 | ------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `GIT_PR_NUMBER`                       | PR number (set by OpenShift CI)                         | Enables OCI URL generation for PR builds                                                                                                                                                 |
 | `E2E_NIGHTLY_MODE`                    | When `"true"`, activates nightly mode                   | Plugins in `default.packages.yaml` with OCI metadata use `{{inherit}}` (RHDH resolves both OCI tag and config from DPDY); other OCI plugins use full metadata refs with config injection |
+| `E2E_NIGHTLY_COVERAGE`                | When `"true"`, opt into the nightly coverage image swap | In nightly resolution, a rolled-out frontend plugin (workspace has `coverage-anchors/`) gets its released OCI tag swapped to the instrumented `__coverage` variant so the run can collect browser coverage. Off by default — the functional nightly is unaffected; `{{inherit}}` plugins are never swapped |
 | `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | When `"true"`, disables metadata injection              | Local-only opt-out (ignored when `CI=true`)                                                                                                                                              |
 | `RELEASE_BRANCH_NAME`                 | Release branch (set by OpenShift CI step registry)      | Used to fetch `default.packages.yaml` for DPDY resolution in nightly mode. Required in CI, defaults to `main` locally                                                                    |
 | `NIGHTLY_DPDY_OCI_REGISTRY`           | OCI registry for `{{inherit}}` refs                     | Overrides default `registry.access.redhat.com/rhdh` for all plugins using `{{inherit}}` in nightly mode                                                                                  |

docs/overlay/reference/plugin-metadata-resolution.md

@@ -113,10 +113,20 @@ For each plugin, the resolver checks in order:
 
 4. Use metadata's dynamicArtifact as-is
    (OCI ref → OCI ref, wrapper path → wrapper path)
+   In a dedicated coverage run (E2E_NIGHTLY_COVERAGE=true), a frontend plugin
+   whose workspace is rolled out (has a coverage-anchors/ directory) gets its
+   OCI tag swapped to the instrumented __coverage variant:
+     oci://ghcr.io/.../plugin:bs_X__Y!alias → ...:bs_X__Y__coverage!alias
 ```
 
 Metadata is the source of truth for the package reference, except for plugins in `default.packages.yaml` with OCI metadata in nightly mode — these use `{{inherit}}` so RHDH resolves both the OCI tag and config from its built-in DPDY, testing the exact versions and configuration shipped in the RC.
 
+### Coverage image swap (`E2E_NIGHTLY_COVERAGE`)
+
+A nightly run can only collect browser coverage if RHDH deploys the **instrumented** `__coverage` plugin image (built by the overlay release publish). When `E2E_NIGHTLY_COVERAGE=true`, step 4 above swaps a rolled-out frontend plugin's released OCI tag to its `__coverage` variant.
+
+This is a separate flag from the ambient `E2E_COLLECT_COVERAGE` (which only toggles the collector fixture) on purpose: the functional nightly runs with `E2E_COLLECT_COVERAGE=true` by default, and the `__coverage` variant is built non-fatally, so swapping there could point at a tag that doesn't exist and break the deployment. The explicit `E2E_NIGHTLY_COVERAGE` opt-in keeps the functional nightly's resolution unchanged; only a coverage-dedicated run (which ensures the images exist) sets it. Plugins resolved via `{{inherit}}` are never swapped — those are RHDH's catalog images, which can't be instrumented.
+
 ## Resolution Scenarios
 
 The tables below show what happens to each plugin type in PR check and nightly modes. Local dev behaves the same as PR check (metadata refs + full config injection).

src/utils/plugin-metadata.ts

@@ -206,6 +206,13 @@ function toDisplayName(packageName: string): string {
   return packageName.replace(/^@/, "").replace(/\//g, "-");
 }
 
+// Append the __coverage suffix to an OCI image tag, before the optional
+// !<extractPath>. The instrumented variant the overlay builds. The regex is
+// greedy up to the first `!`, so the suffix always lands at the end of the tag.
+function toCoverageImageRef(ref: string): string {
+  return ref.replace(/(:[^!]+)/, "$1__coverage");
+}
+
 // ── Metadata Loading ──────────────────────────────────────────────────────────
 
 export const DEFAULT_METADATA_PATH = "../metadata";
@@ -464,15 +471,16 @@ async function resolvePluginPackages(
   metadataPath: string,
   dpdyPackages: Set<string> | null = null,
 ): Promise<PluginEntry[]> {
+  const workspaceRoot = path.resolve(metadataPath, "..");
+
   // Build PR OCI URLs if applicable
   const prNumber = process.env.GIT_PR_NUMBER;
   let prOciUrls: Map<string, string> | null = null;
   if (prNumber) {
     console.log(
       `[PluginMetadata] PR build detected (PR #${prNumber}), fetching OCI URLs...`,
     );
-    const workspacePath = path.resolve(metadataPath, "..");
-    prOciUrls = await getOCIUrlsForPR(workspacePath, prNumber);
+    prOciUrls = await getOCIUrlsForPR(workspaceRoot, prNumber);
   }
 
   // A dedicated coverage run swaps rolled-out frontend plugins to their
@@ -489,9 +497,7 @@ async function resolvePluginPackages(
   // the swap to rolled-out workspaces.
   const coverageSwap =
     process.env.E2E_NIGHTLY_COVERAGE === "true" &&
-    fs.existsSync(
-      path.join(path.resolve(metadataPath, ".."), "coverage-anchors"),
-    );
+    fs.existsSync(path.join(workspaceRoot, "coverage-anchors"));
 
   return plugins.map((plugin) => {
     const pkg = plugin.package;
@@ -509,9 +515,7 @@ async function resolvePluginPackages(
           const usesCoverage =
             process.env.E2E_COLLECT_COVERAGE === "true" &&
             metadata.role === "frontend-plugin";
-          const resolved = usesCoverage
-            ? prUrl.replace(/(:[^!]+)/, "$1__coverage")
-            : prUrl;
+          const resolved = usesCoverage ? toCoverageImageRef(prUrl) : prUrl;
           console.log(`[PluginMetadata] PR: ${pkg} → ${resolved}`);
           return { ...plugin, package: resolved };
         }
@@ -537,7 +541,7 @@ async function resolvePluginPackages(
       if (metadata.packagePath.startsWith("oci://")) {
         const resolved =
           coverageSwap && metadata.role === "frontend-plugin"
-            ? metadata.packagePath.replace(/(:[^!]+)/, "$1__coverage")
+            ? toCoverageImageRef(metadata.packagePath)
             : metadata.packagePath;
         console.log(`[PluginMetadata] ${pkg} → ${resolved}`);
         return { ...plugin, package: resolved };