@sun-asterisk/sungen 3.2.18 → 3.2.20

package/src/exporters/feature-parser.ts

@@ -45,18 +45,11 @@ function extractReferencedVars(scenario: ParsedScenario, includeComments = false
 }
 
 /**
- * Classify each step into Given / When / Then bucket based on its preceding
- * explicit keyword. "And" inherits from the previous explicit keyword.
+ * Classify each step into its Given / When / Then bucket based on the
+ * preceding explicit keyword. "And" / "But" inherit the previous bucket.
+ * Chronological order is preserved.
  */
-function classifySteps(scenario: ParsedScenario): {
-  given: string[];
-  when: string[];
-  then: string[];
-  ordered: OrderedStep[];
-} {
-  const given: string[] = [];
-  const when: string[] = [];
-  const then: string[] = [];
+function classifySteps(scenario: ParsedScenario): OrderedStep[] {
   const ordered: OrderedStep[] = [];
   let currentBucket: 'given' | 'when' | 'then' = 'given';
 
@@ -67,14 +60,10 @@ function classifySteps(scenario: ParsedScenario): {
     else if (keyword === 'Then') currentBucket = 'then';
     // And / But → inherit currentBucket
 
-    if (currentBucket === 'given') given.push(step.text);
-    else if (currentBucket === 'when') when.push(step.text);
-    else then.push(step.text);
-
     ordered.push({ text: step.text, bucket: currentBucket });
   }
 
-  return { given, when, then, ordered };
+  return ordered;
 }
 
 /**
@@ -86,35 +75,25 @@ export function parseFeatureMetadata(featureFilePath: string): FeatureMetadata {
 
   // Background block — classify once and surface on FeatureMetadata so the
   // merger can prepend it to each runnable scenario without re-parsing.
-  const bg = parsed.background
+  const backgroundOrderedSteps = parsed.background
     ? classifySteps(parsed.background)
-    : { given: [], when: [], then: [], ordered: [] as OrderedStep[] };
-
-  const scenarios: ScenarioMetadata[] = parsed.scenarios.map((sc) => {
-    const { given, when, then, ordered } = classifySteps(sc);
+    : [];
 
-    return {
-      name: sc.name,
-      tags: [...parsed.tags, ...sc.tags],
-      stepsName: sc.stepsName,
-      extendsName: sc.extendsName,
-      referencedVars: extractReferencedVars(sc, extractTestcaseType([...parsed.tags, ...sc.tags]) === 'Manual'),
-      rawGivenSteps: given,
-      rawWhenSteps:  when,
-      rawThenSteps:  then,
-      orderedSteps:  ordered,
-      comments:      sc.comments,
-    };
-  });
+  const scenarios: ScenarioMetadata[] = parsed.scenarios.map((sc) => ({
+    name: sc.name,
+    tags: [...parsed.tags, ...sc.tags],
+    stepsName: sc.stepsName,
+    extendsName: sc.extendsName,
+    referencedVars: extractReferencedVars(sc, extractTestcaseType([...parsed.tags, ...sc.tags]) === 'Manual'),
+    orderedSteps: classifySteps(sc),
+    comments: sc.comments,
+  }));
 
   return {
     featureName: parsed.name,
     featurePath: parsed.path,
     featureTags: parsed.tags,
-    backgroundGivenSteps:   bg.given,
-    backgroundWhenSteps:    bg.when,
-    backgroundThenSteps:    bg.then,
-    backgroundOrderedSteps: bg.ordered,
+    backgroundOrderedSteps,
     scenarios,
   };
 }

package/src/exporters/json-exporter.ts

@@ -14,7 +14,7 @@ import {
   mapVpToCategory2,
   splitVpAndName,
 } from './feature-parser';
-import { formatPrecondition, keepActor, stripActor } from './step-formatter';
+import { formatPrecondition, groupExpectedByAnchor, keepActor, stripActor } from './step-formatter';
 import { formatTestData, substituteTestDataVars } from './test-data-resolver';
 import { collectSecretValues, formatApiExpected, formatApiRequest, hasApiCalls, redactSecrets } from './api-testcase-formatter';
 import {
@@ -24,6 +24,7 @@ import {
 import { ApiCatalogEntry, EnvironmentInfo, PlaywrightResult } from './types';
 import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
 import { formatVariantRow, resolveResultVariants } from './result-variants';
+import { collectQaEnvSecretDenylist, warnIfRedactionIncomplete } from './qa-env-secret-denylist';
 import {
   ScenarioSnapshot,
   ScreenSnapshot,
@@ -71,24 +72,56 @@ export interface BuildScreenSnapshotInput {
 export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnapshot {
   const scenarios: ScenarioSnapshot[] = [];
   let fallbackIndex = 1;
+  // Runtime failure messages embed RESOLVED ${QA_*} credentials, and `errorMessage`
+  // feeds the dashboard snapshot + its committed history (never deleted by design) —
+  // build the value denylist once per unit so every errorMessage gets scrubbed.
+  const qaEnvSecrets = collectQaEnvSecretDenylist(input.testData);
 
   for (const m of input.merged) {
     const priority = extractPriority(m.feature.tags) as ScenarioSnapshot['priority'];
     const baseType = extractTestcaseType(m.feature.tags);
     const authRole = extractAuthRole(m.feature.tags);
 
-    // Pre-condition is auth-only. Steps section = Background + @extend base
-    // (all of it, including its Then) + own pre-Then. Expected = own's
-    // Then-onwards only. Given → keepActor (state), When/Then → stripActor.
-    const precondition = formatPrecondition(authRole);
-    const localize = (text: string): string =>
-      input.selectorKeyMap
+    // Pre-condition = auth line + feature Background steps (kept out of Steps
+    // so numbering matches the .feature scenario — parity with csv-exporter).
+    // Steps section = @extend base (all of it, including its Then) + own
+    // pre-Then. Expected = own's Then-onwards only. Given → keepActor (state),
+    // When/Then → stripActor.
+    const localize = (text: string): string => {
+      // Same two-step resolution as csv-exporter's localize: 1. resolve [Reference]
+      // selector keys → their label/value; 2. resolve {{var}} test-data placeholders →
+      // concrete values, so the dashboard shows the identical Steps / Expected text as
+      // the delivery sheet. An unknown {{var}} is left literal.
+      const withKeys = input.selectorKeyMap
         ? substituteSelectorKeysInStep(text, input.selectorKeyMap, input.testData)
         : text;
+      return substituteTestDataVars(withKeys, input.testData);
+    };
     const formatStep = (s: { text: string; bucket: 'given' | 'when' | 'then' }) =>
       localize(s.bucket === 'given' ? keepActor(s.text) : stripActor(s.text));
+    const precondition = formatPrecondition(
+      authRole,
+      (m.resolvedBackgroundSteps ?? []).map(formatStep).filter(Boolean)
+    );
     let steps = m.resolvedSteps.map(formatStep).filter(Boolean);
-    let expectedResults = m.resolvedExpected.map(formatStep).filter(Boolean);
+    // Same anchor rule as csv-exporter (shared groupExpectedByAnchor) so the
+    // dashboard shows the identical Expected text as the delivery sheet.
+    const anchorResult = groupExpectedByAnchor(
+      m.resolvedExpected
+        .map((s) => ({ text: formatStep(s), anchorStep: s.anchorStep }))
+        .filter((e) => e.text),
+      m.resolvedAnchorActionCount ?? 0
+    );
+    // Grouped cells carry their own headers + per-group numbering: store as
+    // ONE entry so the dashboard XLSX adapter (formatList: 1 entry → raw)
+    // reproduces the delivery cell verbatim instead of re-numbering lines.
+    let expectedResults = anchorResult.grouped
+      ? [anchorResult.lines.join('\n')]
+      : anchorResult.lines;
+    // Group headers reference Steps numbering; the adapter leaves a
+    // single-entry list unnumbered, so bake the "1. " in when a lone action
+    // is referenced by headers.
+    if (anchorResult.grouped && steps.length === 1) steps = [`1. ${steps[0]}`];
 
     // API test cases: mirror csv-exporter's request/response rendering so the
     // dashboard (UI + XLSX export) shows the same Steps / Expected results as
@@ -97,20 +130,15 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
     // adapter's formatList() (1 entry → raw) reproduces the delivery cell
     // byte-for-byte, and the UI renders the block with pre-wrap.
     if (input.kind === 'api' && input.apiCatalog && hasApiCalls(m.feature.tags)) {
-      // Delivery cells substitute {{var}} test-data refs (csv-exporter's localize);
-      // scope that to the API branch so non-API snapshot behavior is untouched.
-      const localizeApi = (text: string): string => substituteTestDataVars(localize(text), input.testData);
-      const formatStepApi = (s: { text: string; bucket: 'given' | 'when' | 'then' }) =>
-        localizeApi(s.bucket === 'given' ? keepActor(s.text) : stripActor(s.text));
       const joinCell = (lines: string[]): string =>
         lines.length === 0 ? '' :
         lines.length === 1 ? lines[0] :
         lines.map((l, i) => `${i + 1}. ${l}`).join('\n');
-      let stepsCell = joinCell(m.resolvedSteps.map(formatStepApi).filter(Boolean));
-      let expectedCell = joinCell(m.resolvedExpected.map(formatStepApi).filter(Boolean));
-      const apiRequest = formatApiRequest(m.feature.tags, input.apiCatalog, localizeApi);
+      let stepsCell = joinCell(m.resolvedSteps.map(formatStep).filter(Boolean));
+      let expectedCell = joinCell(m.resolvedExpected.map(formatStep).filter(Boolean));
+      const apiRequest = formatApiRequest(m.feature.tags, input.apiCatalog, localize);
       if (apiRequest) stepsCell = stepsCell ? `${stepsCell}\n\n${apiRequest}` : apiRequest;
-      const apiExpected = formatApiExpected(m.resolvedExpected, m.feature.tags, localizeApi);
+      const apiExpected = formatApiExpected(m.resolvedExpected, m.feature.tags, localize);
       if (apiExpected) expectedCell = apiExpected;
       // Same value-based redaction backstop as the CSV path.
       const secrets = collectSecretValues(input.testData);
@@ -121,9 +149,19 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
       steps = stepsCell ? [stepsCell] : [];
       expectedResults = expectedCell ? [expectedCell] : [];
     }
+    // Runtime-secret pass over EVERY kind's content cells (parity with csv-exporter):
+    // value-based only, so demo values / error-message strings / element names stay
+    // readable — only a resolved sensitive ${QA_*} value that reached cell content is erased.
+    if (qaEnvSecrets.values.length > 0) {
+      steps = steps.map((s) => redactSecrets(s, qaEnvSecrets.values));
+      expectedResults = expectedResults.map((s) => redactSecrets(s, qaEnvSecrets.values));
+    }
     // Dashboard modal uses whitespace-pre-wrap — pass '\n' to render one
     // key/value per line instead of the CSV-friendly "; " join.
-    const baseTestDataStr = formatTestData(m.feature.referencedVars, input.testData, Infinity, '\n');
+    const baseTestDataStr = redactSecrets(
+      formatTestData(m.feature.referencedVars, input.testData, Infinity, '\n'),
+      qaEnvSecrets.values,
+    );
 
     // @cases scenarios expand to one snapshot entry per executed dataset row — and manual
     // @cases split per DATASET row (shared with the CSV exporter via resolveResultVariants),
@@ -132,7 +170,8 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
     for (const variant of variants) {
       // Per-line Test Data: shared vars + THIS variant's dataset row (parity with csv-exporter).
       let testDataStr = baseTestDataStr;
-      const variantRow = formatVariantRow(variant, '\n');
+      // A @cases dataset row can carry the same values — redact it like the shared part.
+      const variantRow = redactSecrets(formatVariantRow(variant, '\n'), qaEnvSecrets.values);
       if (variantRow) testDataStr = testDataStr ? `${testDataStr}\n${variantRow}` : variantRow;
       const displayName = `${m.feature.name}${variant.nameSuffix}`;
       const { vpId, category1 } = splitVpAndName(displayName);
@@ -164,11 +203,14 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
           // mid-selector. Drop the stack trace (frames start with "at "), collapse the remaining
           // newlines (incl. the Expected/Received lines) to spaces, and strip a leading "Error:"
           // so consumers (dashboard / CSV `Note`) can prepend their own label.
-          errorMessage = String(result.error)
-            .split(/\n\s*at\s/)[0]
-            .replace(/\s*\n\s*/g, ' ')
-            .trim()
-            .replace(/^Error:\s*/i, '');
+          errorMessage = redactSecrets(
+            String(result.error)
+              .split(/\n\s*at\s/)[0]
+              .replace(/\s*\n\s*/g, ' ')
+              .trim()
+              .replace(/^Error:\s*/i, ''),
+            qaEnvSecrets.values,
+          );
         }
         if (result.tracePath) tracePath = result.tracePath;
         testEnvironment = formatTestEnvironment(input.env.baseURL, input.featurePath, result.projectName || input.env.projectName);
@@ -208,6 +250,11 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
     }
   }
 
+  // A sensitive ${QA_*} ref that resolved to nothing here can still appear RESOLVED in
+  // failure text (the run may have happened in another shell, e.g. CI artifacts exported
+  // locally) — never export silently unredacted.
+  warnIfRedactionIncomplete(qaEnvSecrets, scenarios.some((s) => s.status === 'Failed'), input.screen);
+
   return {
     name: input.screen,
     isFlow: input.isFlow,

package/src/exporters/matrix/build.ts

@@ -6,6 +6,7 @@
  */
 
 import { FeatureMetadata, PlaywrightResult } from '../types';
+import { bucketTexts } from './step-buckets';
 import { MergedScenario } from '../scenario-merger';
 import {
   extractAuthRole,
@@ -14,6 +15,7 @@ import {
   splitVpAndName,
 } from '../feature-parser';
 import { getCasesDatasetRows, resolveResultVariants } from '../result-variants';
+import { renderDynamicTokens } from '../test-data-resolver';
 import { classifyManualComments, renderAction, renderExpected, renderPrecondition, renderSetupInstruction, runtimeVarsOf } from './wording';
 import { scenarioFingerprint, combinedFingerprint, mapContentFingerprint } from './fingerprint';
 import {
@@ -126,9 +128,9 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       : null;
 
     // Raw (pre-wording) step texts — these feed shapes + Gate C, never the cells.
-    const rawTrigger = manual ? manual.actions : m.feature.rawWhenSteps;
+    const rawTrigger = manual ? manual.actions : bucketTexts(m.feature.orderedSteps, 'when');
     const rawOracle = manual
-      ? (manual.expected.length > 0 ? manual.expected : m.feature.rawThenSteps)
+      ? (manual.expected.length > 0 ? manual.expected : bucketTexts(m.feature.orderedSteps, 'then'))
       : m.resolvedExpected.filter((s) => s.bucket === 'then').map((s) => s.text);
 
     // Values the scenario itself produces during the run — captured from the page
@@ -142,7 +144,7 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
     const preconditionProfile = [
       authRole ?? '-',
       m.feature.extendsName ?? '-',
-      ...m.feature.rawGivenSteps.map(normalizeShape),
+      ...bucketTexts(m.feature.orderedSteps, 'given').map(normalizeShape),
       ...(manual?.preconditions ?? []).map(normalizeShape),
     ].join(' | ');
     // Display precondition = auth state + Background Given (shared start state) +
@@ -150,8 +152,8 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
     // scenario often repeats the Background navigation as its own Given).
     const precondition = Array.from(new Set([
       ...(authRole ? [authRole === 'no-auth' ? 'The user is signed out.' : `The user is signed in as ${authRole}.`] : []),
-      ...inputs.feature.backgroundGivenSteps.map(renderPrecondition),
-      ...m.feature.rawGivenSteps.map(renderPrecondition),
+      ...bucketTexts(inputs.feature.backgroundOrderedSteps, 'given').map(renderPrecondition),
+      ...bucketTexts(m.feature.orderedSteps, 'given').map(renderPrecondition),
       ...(manual?.preconditions ?? []).map((t) => renderSetupInstruction(t)),
     ]));
 
@@ -264,7 +266,7 @@ function substituteDisplayVars(
   // `remember … as {{v}}` DECLARES v — leave that token for renderAction, which
   // turns it into a quoted name ("note it as …"), not a value to look up.
   const isCapture = /\bremember\b/i.test(text);
-  return text.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (m, key: string, offset: number) => {
+  const out = text.replace(/\{\{\s*([^}\s]+)\s*\}\}/g, (m, key: string, offset: number) => {
     if (isCapture && /\bas\s+$/i.test(text.slice(0, offset))) return m;
     // A value the test produces at run time has no static form — name it so the
     // tester knows to compare against what the earlier step captured.
@@ -272,6 +274,9 @@ function substituteDisplayVars(
     if (!(key in vars)) return m; // unknown stays literal → Gate D flags it
     return displayValue(vars[key]);
   });
+  // A dynamic token written straight into a step (`{{$uuid}}`) never reaches
+  // displayValue — name it here so the same wording covers both routes.
+  return renderDynamicTokens(out);
 }
 
 /**
@@ -280,6 +285,10 @@ function substituteDisplayVars(
  * The canonical value is never changed — only its presentation.
  */
 export function displayValue(v: string): string {
+  // Runtime-generated tokens nested in a value ("Summary intro {{$timestamp}}")
+  // are presentation, not canon — name them before the fidelity checks below,
+  // which judge the value's real whitespace.
+  v = renderDynamicTokens(v);
   if (v === '') return '(empty)';
   if (/^\s+$/.test(v)) return `(${v.length} space${v.length > 1 ? 's' : ''})`;
   if (v !== v.trim()) return `"${v}"`;

package/src/exporters/matrix/gates.ts

@@ -13,6 +13,7 @@
 
 import { splitVpAndName, extractTestcaseType } from '../feature-parser';
 import { mapContentFingerprint } from './fingerprint';
+import { bucketTexts } from './step-buckets';
 import { CoverageVariant, MatrixFinding, MAX_VARIANTS_PER_ITEM } from './types';
 import { expandMapRef, BuildInputs } from './build';
 
@@ -73,7 +74,7 @@ function gateKCategory(ctx: GateContext, findings: MatrixFinding[]): void {
 function gateASource(ctx: GateContext, findings: MatrixFinding[]): void {
   const { feature, merged } = ctx.inputs;
 
-  if (feature.backgroundWhenSteps.length > 0 || feature.backgroundThenSteps.length > 0) {
+  if (bucketTexts(feature.backgroundOrderedSteps, 'when').length > 0 || bucketTexts(feature.backgroundOrderedSteps, 'then').length > 0) {
     findings.push({
       gate: 'A', severity: 'error',
       message: 'Background contains When/Then steps — setup only; move the action/oracle into scenarios',
@@ -247,7 +248,7 @@ function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
   for (const g of map.groups) {
     const vs = g.variants.flatMap((ref) => expandMapRef(ref, variantsByVp));
     for (const v of vs) {
-      const hasPrecondition = v.precondition.length > 0 || feature.backgroundGivenSteps.length > 0;
+      const hasPrecondition = v.precondition.length > 0 || bucketTexts(feature.backgroundOrderedSteps, 'given').length > 0;
       if (!hasPrecondition) {
         findings.push({
           gate: 'D', severity: 'error', ref: v.ref,

package/src/exporters/matrix/step-buckets.ts

@@ -0,0 +1,15 @@
+/**
+ * Per-bucket raw step texts, derived from `orderedSteps`.
+ *
+ * The parser's `rawGiven/When/ThenSteps` and `backgroundGiven/When/ThenSteps`
+ * arrays were removed as dead code (0c3f4ca7 — they duplicated what
+ * `orderedSteps` already carries) while the matrix module, merged in parallel,
+ * still consumed them: main stopped compiling. classifySteps used to build
+ * those arrays as exactly this filter+map over the same buckets, so this view
+ * is 1:1 with the removed fields.
+ */
+import { OrderedStep } from '../types';
+
+export function bucketTexts(steps: OrderedStep[], bucket: OrderedStep['bucket']): string[] {
+  return steps.filter((s) => s.bucket === bucket).map((s) => s.text);
+}

package/src/exporters/qa-env-secret-denylist.ts

@@ -0,0 +1,118 @@
+/**
+ * Denylist of RESOLVED `${QA_*}` secret values, for redacting runtime failure text
+ * (the CSV/XLSX `Note` column and the dashboard snapshot's `errorMessage`).
+ *
+ * A failed assertion's message carries the credential the runtime already substituted
+ * (`Expected: "<real password>"`), and delivery lifts that message into files that get
+ * committed permanently (qa/deliverables/*.csv, qa/dashboard/history/*.json). Key-based
+ * masking can't help there — the secret appears as a free-standing VALUE — so we build a
+ * value denylist and erase every occurrence.
+ *
+ * Selection = env-var names referenced as `${QA_*}` in the unit's test data, INTERSECTED
+ * with a sensitive-name signal on the ENV VAR NAME: QA_ADMIN_PASSWORD / QA_ACCESS_TOKEN
+ * are denylisted, QA_BASE_URL / QA_ADMIN_EMAIL are not — non-secret values must stay
+ * readable so the deliverable keeps its reproduction value.
+ *
+ * Values resolve like the runtime does (specs-test-data loadEnvQa precedence):
+ * shell/CI env highest > .env.qa.<SUNGEN_ENV> > .env.qa. Reading process.env is
+ * deliberate — on CI (where deliverables are actually committed) the .env.qa file is
+ * gitignored and usually absent; secrets arrive via env, and a parse-file-only denylist
+ * would be empty exactly where it matters. `.env.qa.example` (committed placeholders) is
+ * never read. This module only BUILDS the denylist — values are erased from output,
+ * never rendered into it.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+// Sensitive-name signal shared with the API exporter's key/body-field classifier —
+// here it is applied to the ENV VAR NAME (QA_ACCESS_TOKEN), not the yaml key.
+import { SENSITIVE_NAME } from './api-testcase-formatter';
+
+/** `${QA_*}` env reference — same shape the runtime resolver allowlists (uppercase, QA_ prefix). */
+const QA_ENV_REF = /\$\{(QA_[A-Z0-9_]+)\}/g;
+
+export interface QaEnvSecretDenylist {
+  /** Resolved secret values to erase, deduped, longest-first (so a longer secret wins over its substring). */
+  values: string[];
+  /** Sensitive `${QA_*}` names referenced by the unit that resolved to no usable value. */
+  unresolved: string[];
+}
+
+/**
+ * Build the denylist for one unit from its LOADED test-data map (values still carry the
+ * literal `${QA_*}` refs — delivery never resolves them into cells). `cwd` is the project
+ * root the delivery CLI runs from, where .env.qa files live.
+ */
+export function collectQaEnvSecretDenylist(
+  testData: Record<string, string>,
+  cwd: string = process.cwd(),
+): QaEnvSecretDenylist {
+  const referenced = new Set<string>();
+  for (const v of Object.values(testData)) {
+    if (typeof v !== 'string') continue;
+    for (const m of v.matchAll(QA_ENV_REF)) referenced.add(m[1]);
+  }
+  const sensitive = [...referenced].filter((n) => SENSITIVE_NAME.test(n));
+  if (sensitive.length === 0) return { values: [], unresolved: [] };
+
+  const fileEnv = readEnvQaFiles(cwd);
+  const values: string[] = [];
+  const unresolved: string[] = [];
+  for (const name of sensitive) {
+    const v = process.env[name] !== undefined ? process.env[name] : fileEnv[name];
+    // Values shorter than 3 chars are unusable as a denylist entry (they'd mask
+    // coincidental text); treat them as unresolved so coverage gaps stay visible.
+    if (typeof v === 'string' && v.length >= 3) values.push(v);
+    else unresolved.push(name);
+  }
+  return {
+    values: [...new Set(values)].sort((a, b) => b.length - a.length),
+    unresolved,
+  };
+}
+
+/**
+ * Read .env.qa files into a local map (never mutating process.env), with the runtime's
+ * precedence: first file that sets a key wins, and `.env.qa.<SUNGEN_ENV>` is read before
+ * the base `.env.qa`. Callers give process.env priority over everything here.
+ */
+function readEnvQaFiles(cwd: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const env = process.env.SUNGEN_ENV;
+  for (const name of [env ? `.env.qa.${env}` : '', '.env.qa']) {
+    // .env.qa.example is a committed placeholder file, never a source of real values.
+    if (!name || name === '.env.qa.example') continue;
+    const p = path.join(cwd, name);
+    if (!fs.existsSync(p)) continue;
+    for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+      const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+      if (m && out[m[1]] === undefined) out[m[1]] = m[2].replace(/^["']|["']$/g, '');
+    }
+  }
+  return out;
+}
+
+/** Keys already warned about, so per-variant exporter loops don't repeat themselves. */
+const warnedUnits = new Set<string>();
+
+/**
+ * Fail-loud seam: a unit references sensitive `${QA_*}` vars whose values can't be
+ * resolved here, AND the run has failures whose messages may embed those very values
+ * (resolved by the runtime in a different shell, e.g. CI artifacts exported locally).
+ * Silence would mean exporting unredacted secrets without a trace — warn instead.
+ */
+export function warnIfRedactionIncomplete(
+  denylist: QaEnvSecretDenylist,
+  hasFailures: boolean,
+  unitLabel: string,
+): void {
+  if (!hasFailures || denylist.unresolved.length === 0) return;
+  const key = `${unitLabel}:${denylist.unresolved.join(',')}`;
+  if (warnedUnits.has(key)) return;
+  warnedUnits.add(key);
+  console.warn(
+    `⚠ [${unitLabel}] redaction coverage incomplete: ${denylist.unresolved.join(', ')} ` +
+    'referenced in test-data but not resolvable here — failure notes in the deliverable ' +
+    'may contain unredacted secret values. Set the variable(s) in the shell/CI env or .env.qa before exporting.',
+  );
+}