@sun-asterisk/sungen 3.2.13 → 3.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.13",
+  "version": "3.2.15",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,7 +12,7 @@
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && mkdir -p dist/generators/test-generator/adapters/appium/templates/steps && cp -r src/generators/test-generator/adapters/appium/templates/*.hbs dist/generators/test-generator/adapters/appium/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/appium/templates/steps dist/generators/test-generator/adapters/appium/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
-    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/exporter/overview-sheet.run.ts && tsx tests/exporter/delivery-divider-tcid.run.ts && tsx tests/exporter/note-expected-actual.run.ts && tsx tests/exporter/test-data-vars.run.ts && tsx tests/exporter/mobile-app-id.run.ts && tsx tests/exporter/api-testcase-cells.run.ts && tsx tests/exporter/delivery-cases-result.run.ts && tsx tests/exporter/precondition-auth-role.run.ts && tsx tests/exporter/report-builder-parity.run.ts && tsx tests/exporter/delivery-preflight-testdata.run.ts && tsx tests/exporter/delivery-preflight-selectors.run.ts && tsx tests/exporter/delivery-prerun-overview.run.ts && tsx tests/exporter/manual-testcase-testdata.run.ts && tsx tests/dashboard/api-flows-discovery.run.ts && tsx tests/dashboard/status-results-fallback.run.ts && tsx tests/codegen/verb-ref-masking.run.ts && tsx tests/codegen/table-aria-hidden-locators.run.ts && tsx tests/codegen/steps-base-not-compiled.run.ts && tsx tests/codegen/manual-oracle-gate.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/api-runtime/file-upload-multipart.run.ts && tsx tests/api-runtime/schema-assertion.run.ts && tsx tests/runtime/test-data-cross-ref.run.ts && tsx tests/runtime/test-data-array-projection.run.ts &&tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/api-field-coverage/run.ts && tsx tests/packaging/run.ts && tsx tests/generate-hint/run.ts && tsx tests/template-assertion/run.ts && tsx tests/journey/run.ts && tsx tests/harness/serial-cascade.run.ts && tsx tests/ai-skills/cross-assistant-orphan.run.ts && tsx tests/init/codex-mcp-config.run.ts && tsx src/orchestrator/ai-skills/golden-skills.test.ts && tsx tests/db-runtime/sql-placeholder-rewrite.run.ts && tsx tests/db-runtime/fallback-flow-codified.run.ts && tsx tests/db-runtime/cosmos-engine.run.ts && tsx tests/db-runtime/mongodb-engine.run.ts && tsx tests/db-runtime/dynamodb-engine.run.ts && tsx tests/db-runtime/mysql-integration.opt-in.run.ts && tsx tests/db-runtime/mongodb-integration.opt-in.run.ts && tsx tests/db-runtime/dynamodb-integration.opt-in.run.ts",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/exporter/overview-sheet.run.ts && tsx tests/exporter/delivery-divider-tcid.run.ts && tsx tests/exporter/note-expected-actual.run.ts && tsx tests/exporter/test-data-vars.run.ts && tsx tests/exporter/mobile-app-id.run.ts && tsx tests/exporter/api-testcase-cells.run.ts && tsx tests/exporter/delivery-cases-result.run.ts && tsx tests/exporter/precondition-auth-role.run.ts && tsx tests/exporter/report-builder-parity.run.ts && tsx tests/exporter/delivery-preflight-testdata.run.ts && tsx tests/exporter/delivery-preflight-selectors.run.ts && tsx tests/exporter/delivery-prerun-overview.run.ts && tsx tests/exporter/delivery-locale-env-discovery.run.ts && tsx tests/exporter/manual-testcase-testdata.run.ts && tsx tests/dashboard/api-flows-discovery.run.ts && tsx tests/dashboard/status-results-fallback.run.ts && tsx tests/codegen/verb-ref-masking.run.ts && tsx tests/codegen/table-aria-hidden-locators.run.ts && tsx tests/codegen/steps-base-not-compiled.run.ts && tsx tests/codegen/manual-oracle-gate.run.ts && tsx tests/codegen/locator-value-qualified-assertions.run.ts && tsx tests/codegen/table-match-data-column-mapping.run.ts && tsx tests/codegen/param-binding-native-type.run.ts && tsx tests/codegen/table-row-scope-redeclaration.run.ts && tsx tests/codegen/table-row-label-resolution.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/api-runtime/file-upload-multipart.run.ts && tsx tests/api-runtime/schema-assertion.run.ts && tsx tests/runtime/test-data-cross-ref.run.ts && tsx tests/runtime/test-data-array-projection.run.ts && tsx tests/runtime/env-secret-interpolation.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/api-field-coverage/run.ts && tsx tests/packaging/run.ts && tsx tests/generate-hint/run.ts && tsx tests/template-assertion/run.ts && tsx tests/journey/run.ts && tsx tests/harness/serial-cascade.run.ts && tsx tests/ai-skills/cross-assistant-orphan.run.ts && tsx tests/init/codex-mcp-config.run.ts && tsx src/orchestrator/ai-skills/golden-skills.test.ts && tsx tests/db-runtime/sql-placeholder-rewrite.run.ts && tsx tests/db-runtime/fallback-flow-codified.run.ts && tsx tests/db-runtime/cosmos-engine.run.ts && tsx tests/db-runtime/mongodb-engine.run.ts && tsx tests/db-runtime/dynamodb-engine.run.ts && tsx tests/db-runtime/mysql-integration.opt-in.run.ts && tsx tests/db-runtime/mongodb-integration.opt-in.run.ts && tsx tests/db-runtime/dynamodb-integration.opt-in.run.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
@@ -39,8 +39,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.2.13",
-    "@sungen/driver-ui": "3.2.13",
+    "@sungen/driver-data-factory": "3.2.15",
+    "@sungen/driver-ui": "3.2.15",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/delivery.ts

@@ -13,6 +13,7 @@ import { parseSpecFile } from '../../exporters/spec-parser';
 import { loadTestData } from '../../exporters/test-data-resolver';
 import { loadSelectorKeyMap } from '../../exporters/selector-key-resolver';
 import { loadPlaywrightReport, resolveResultsPath as resolveResultsPathShared } from '../../exporters/playwright-report-parser';
+import { discoverLocaleVariants } from '../../exporters/locale-variants';
 import { mergeFeatureAndSpec } from '../../exporters/scenario-merger';
 import {
   buildTestCaseRows,
@@ -167,70 +168,11 @@ function resolveResultsPath(cwd: string, target: DeliveryTarget): string | null
   return resolveResultsPathShared(cwd, generatedDir(cwd, target), target.featureBaseName);
 }
 
-/**
- * A single locale variant of a delivery target.
- *
- * `locale === ''` denotes the base locale (file `<name>-test-result.json`,
- * test-data without overlay). Non-empty values come from
- * `<name>-test-result.<locale>.json` files found in the generated directory.
- *
- * `displayCode` is what we show in sheet names — `BASE_LOCALE.toUpperCase()`
- * for base, the locale code uppercased otherwise (e.g. `EN`, `JA`, `EN-US`).
- */
-interface LocaleVariant {
-  locale: string;          // '' for base, 'en' / 'ja' / 'staging-ja' for variants
-  displayCode: string;     // 'VI' / 'EN' / 'JA' — used in sheet name
-  resultsPath: string | null;
-}
-
-/**
- * Base locale assumed when no `SUNGEN_ENV` and no explicit override.
- * Configurable later via `qa/.sungen-config.yaml` or similar — currently
- * hardcoded since every existing sungen project uses Vietnamese as the
- * source-of-truth `test-data/<feature>.yaml`.
- */
-const DEFAULT_BASE_LOCALE = 'vi';
-
-/**
- * Discover every locale variant available for a feature by scanning the
- * generated directory for `<featureBaseName>-test-result*.json` files.
- *
- * Result always includes the base (locale = '') as the first entry — even if
- * `<name>-test-result.json` doesn't exist, callers still need somewhere to
- * fall back to (Pending status). Variants follow alphabetically by locale
- * code, so the sheet order is deterministic across runs.
- */
-function discoverLocaleVariants(cwd: string, target: DeliveryTarget): LocaleVariant[] {
-  const genDir = generatedDir(cwd, target);
-  const prefix = `${target.featureBaseName}-test-result`;
-  const variants: LocaleVariant[] = [];
-
-  // Base variant: per-target result file if present, else fall back to the global
-  // test-results/results.json (what playwright.config writes by default) via resolveResultsPath.
-  variants.push({
-    locale: '',
-    displayCode: DEFAULT_BASE_LOCALE.toUpperCase(),
-    resultsPath: resolveResultsPath(cwd, target),
-  });
-
-  if (fs.existsSync(genDir)) {
-    const localeFiles = fs.readdirSync(genDir)
-      .filter((f) => f.startsWith(`${prefix}.`) && f.endsWith('.json') && f !== `${prefix}.json`)
-      .sort();
-    for (const f of localeFiles) {
-      // Strip prefix + '.' on the left, '.json' on the right → locale code.
-      const locale = f.slice(prefix.length + 1, -'.json'.length);
-      if (!locale) continue;
-      variants.push({
-        locale,
-        displayCode: locale.toUpperCase(),
-        resultsPath: path.join(genDir, f),
-      });
-    }
-  }
-
-  return variants;
-}
+// Locale/env variant discovery is SHARED with the dashboard snapshot builder —
+// see exporters/locale-variants.ts for the classification rules (declared
+// locales via qa/capabilities.yaml, env pairing, mobile OS exemption). The two
+// surfaces previously hand-mirrored this logic and drifted into the
+// fake-locale bug (any env-suffixed result file became a "locale" sheet).
 
 function resolveTestDataPathForTarget(cwd: string, target: DeliveryTarget): string {
   return path.join(qaDir(cwd, target), 'test-data', `${target.featureBaseName}.yaml`);
@@ -522,7 +464,17 @@ async function exportTarget(
       return buildSummary(label, rows, path.relative(cwd, csvPath));
     }
 
-    const variants = discoverLocaleVariants(cwd, target);
+    const { variants, ignored } = discoverLocaleVariants(
+      cwd, generatedDir(cwd, target), target.featureBaseName,
+      () => resolveResultsPath(cwd, target),
+    );
+    if (ignored.length > 0) {
+      const env = process.env.SUNGEN_ENV;
+      log(`  ${COLOR.gray}Ignored result file(s) from other environments: ${ignored.join(', ')}${COLOR.reset}`);
+      for (const suffix of ignored) {
+        log(`  ${COLOR.cyan}→ sungen delivery ${target.screen} --env ${suffix}${COLOR.reset}${env ? '' : ` ${COLOR.gray}(this run uses the base results only)${COLOR.reset}`}`);
+      }
+    }
 
     // Mobile: emit ONE deliverable per OS (csv + xlsx), each from its own
     // `<feature>-test-result.<os>.json`. Android/iOS are SEPARATE platform runs,
@@ -542,7 +494,11 @@ async function exportTarget(
             featureName: feature.featureName,
             featurePath: resolvePlatformAppId(featurePath, variant.locale), // OS-precise app id
             merged,
-            testData: loadTestData(testDataFile, variant.locale || null),
+            // Overlay = the after-OS tail (what SUNGEN_ENV was during that run):
+            // `android.ja` merged <name>.ja.yaml at runtime — the old code passed the
+            // full `android.ja` suffix, looked up a nonexistent overlay, and silently
+            // showed base-language values in the Test Data column.
+            testData: loadTestData(testDataFile, variant.overlay ?? null),
             results: variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null,
             env,
             selectorKeyMap,
@@ -579,9 +535,11 @@ async function exportTarget(
     const multiLocale = variants.length > 1;
 
     for (const variant of variants) {
-      // For the base variant the overlay merge is skipped (`locale: null`);
-      // for locale variants the matching `<feature>.<locale>.yaml` is merged.
-      const variantTestData = loadTestData(testDataFile, variant.locale || null);
+      // Overlay parity with the RUNTIME: merge exactly what TestDataLoader merged
+      // during that run (the run's SUNGEN_ENV) — the base variant under --env dev
+      // merges <feature>.dev.yaml, a ja variant merges <feature>.ja.yaml, plain
+      // base merges nothing.
+      const variantTestData = loadTestData(testDataFile, variant.overlay ?? null);
       const variantResults = variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null;
       const variantRows = buildTestCaseRows({
         screen: label,
@@ -713,8 +671,12 @@ export function registerDeliveryCommand(program: Command): void {
     .argument('[names...]', 'Specific screen or flow names. Omit to process all.')
     .option('--skip-preflight', 'Skip pre-flight checks (not recommended)')
     .option('--continue-on-missing', 'Skip targets with blocking misses instead of aborting')
-    .action(async (names: string[], options: { skipPreflight?: boolean; continueOnMissing?: boolean }) => {
+    .option('--env <env>', 'Environment/locale of the run to deliver (sets SUNGEN_ENV; e.g. dev, staging, ja, dev-ja)')
+    .action(async (names: string[], options: { skipPreflight?: boolean; continueOnMissing?: boolean; env?: string }) => {
       try {
+        // Same effect as running with SUNGEN_ENV=<env> — result-file resolution,
+        // locale pairing, and test-data overlays all key off this one string.
+        if (options.env) process.env.SUNGEN_ENV = options.env;
         const cwd = process.cwd();
 
         // 1. Scope detection — each positional name expands into one target

package/src/dashboard/snapshot-builder.ts

@@ -25,6 +25,7 @@ import { buildScreenSnapshot } from '../exporters/json-exporter';
 import { loadApiCatalog } from '../exporters/api-catalog-loader';
 import { buildApiDetailRows } from '../exporters/xlsx-exporter';
 import { resolvePlatformAppId } from '../exporters/mobile-app-id';
+import { discoverLocaleVariants, LocaleVariant } from '../exporters/locale-variants';
 import { getPackageVersion } from '../exporters/package-info';
 import { ApiCatalogEntry, EnvironmentInfo } from '../exporters/types';
 import {
@@ -38,11 +39,10 @@ import {
   SNAPSHOT_VERSION,
 } from './types';
 
-/**
- * Locale code displayed when a screen has no overlay variants — the base
- * test-data file alone. Matches the delivery CLI's `DEFAULT_BASE_LOCALE`.
- */
-const DEFAULT_BASE_LOCALE = 'vi';
+// Locale/env variant discovery is SHARED with the delivery CLI — see
+// exporters/locale-variants.ts (declared locales, env pairing, mobile OS
+// exemption). Previously a hand-mirrored copy that drifted into the
+// fake-locale bug.
 
 export interface DashboardTarget {
   name: string;
@@ -217,13 +217,16 @@ function buildOneFeature(
   // Discover locale variants by scanning <feature>-test-result*.json files.
   // Always includes base ('') as the first entry, even if its results file
   // is missing — UI still needs to render the feature.
-  const variants = discoverLocaleVariants(cwd, genBase, featureBaseName);
+  const { variants } = discoverLocaleVariants(
+    cwd, genBase, featureBaseName,
+    () => resolveResultsPath(cwd, genBase, featureBaseName),
+  );
 
   // Build one per-variant ScreenSnapshot (test-data overlay + results + OS-precise
   // env column). Reused by both the web/i18n (locale-axis) and mobile (platform-axis) paths.
-  const buildVariant = (variant: FeatureLocaleVariant) => {
+  const buildVariant = (variant: LocaleVariant) => {
     const testData = fs.existsSync(testDataFile)
-      ? loadTestData(testDataFile, variant.locale || null)
+      ? loadTestData(testDataFile, variant.overlay ?? null)
       : {};
     const results = variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null;
     return buildScreenSnapshot({
@@ -341,59 +344,6 @@ function buildOneFeature(
   }];
 }
 
-/**
- * A single locale variant of a feature.
- * `locale === ''` denotes the base (file `<name>-test-result.json`,
- * test-data without overlay merge). Variants come from
- * `<name>-test-result.<locale>.json` filenames.
- */
-interface FeatureLocaleVariant {
-  locale: string;
-  displayCode: string;
-  resultsPath: string | null;
-}
-
-/**
- * Scan the generated directory for `<basename>-test-result*.json` files
- * and infer locale codes. The base entry is always returned first; locale
- * variants follow alphabetically so sheet/tab order stays deterministic.
- *
- * Mirrors `discoverLocaleVariants` in `src/cli/commands/delivery.ts` so the
- * dashboard and the CSV/XLSX delivery agree on what locales exist for a
- * given feature.
- */
-function discoverLocaleVariants(cwd: string, genDir: string, featureBaseName: string): FeatureLocaleVariant[] {
-  const prefix = `${featureBaseName}-test-result`;
-  const variants: FeatureLocaleVariant[] = [];
-
-  // Base variant resolves through the SHARED candidate chain (per-feature file
-  // first, then the global test-results/results.json playwright writes by
-  // default) — the same resolution delivery.ts uses. Without the fallback the
-  // dashboard showed every scenario Pending on projects that only have the
-  // global results file, while delivery correctly reported Passed.
-  variants.push({
-    locale: '',
-    displayCode: DEFAULT_BASE_LOCALE.toUpperCase(),
-    resultsPath: resolveResultsPath(cwd, genDir, featureBaseName),
-  });
-
-  if (fs.existsSync(genDir)) {
-    const localeFiles = fs.readdirSync(genDir)
-      .filter((f) => f.startsWith(`${prefix}.`) && f.endsWith('.json') && f !== `${prefix}.json`)
-      .sort();
-    for (const f of localeFiles) {
-      const locale = f.slice(prefix.length + 1, -'.json'.length);
-      if (!locale) continue;
-      variants.push({
-        locale,
-        displayCode: locale.toUpperCase(),
-        resultsPath: path.join(genDir, f),
-      });
-    }
-  }
-
-  return variants;
-}
 
 /**
  * Combine per-feature summaries into a single screen-level rollup.

package/src/exporters/locale-variants.ts

@@ -0,0 +1,157 @@
+/**
+ * Locale/env classification for `<feature>-test-result.<suffix>.json` files —
+ * SHARED by the delivery CLI and the dashboard snapshot builder (previously two
+ * hand-mirrored copies that had already drifted into the fake-locale bug).
+ *
+ * Field report (3.2.14): every result-file suffix was treated as a LOCALE. A
+ * team running `SUNGEN_ENV=dev npx playwright test` (the standard .env.qa.dev
+ * convention) then `sungen delivery` without an env got a fabricated two-locale
+ * deliverable: a "VI Auto" sheet (hardcoded base label, all Pending, pointing
+ * at a result file that doesn't exist) next to a "DEV Auto" sheet.
+ *
+ * The file mechanism cannot distinguish an env overlay (`login.dev.yaml`,
+ * per-env credentials) from a locale overlay (`login.ja.yaml`, translated
+ * text) — they are deliberately the same mechanism keyed by SUNGEN_ENV. So
+ * locales are DECLARED, not guessed:
+ *
+ *   # qa/capabilities.yaml
+ *   locales: [ja, en]      # non-base locales (written by /sungen:locale)
+ *   base_locale: en        # language of the base test-data (default: en)
+ *
+ * Suffix classification (first match wins), with E = the delivery env
+ * (SUNGEN_ENV / --env, possibly empty):
+ *   1. ^(android|ios)(.|$)          → OS run (mobile per-OS branch consumes)
+ *   2. suffix === E                 → the base variant's own file (not a variant)
+ *   3. E === '' && suffix ∈ locales → locale variant on the base env
+ *   4. E !== '' && suffix === `${E}-<L>`, L ∈ locales → locale variant on env E
+ *   5. anything else                → env run — EXCLUDED from variants and
+ *      reported in `ignored` so the CLI can hint "run with --env <suffix>".
+ *
+ * Env pairing (rules 2–4) means a delivery only ever mixes results from ONE
+ * environment. Running with `--env ja` (an env named exactly like a declared
+ * locale) is interpreted as "deliver that locale's run" — the documented
+ * SUNGEN_ENV=<locale> convention, not a collision.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+
+export interface LocaleVariant {
+  /** Result-file suffix as found on disk ('' = base). */
+  locale: string;
+  /** Sheet-name label (used only in multi-locale mode). */
+  displayCode: string;
+  resultsPath: string | null;
+  /**
+   * Test-data overlay code to merge for this variant's Test Data column —
+   * mirrors what the RUNTIME merged (TestDataLoader uses SUNGEN_ENV): the full
+   * suffix on web, the after-OS tail on mobile (`android.ja` ran with
+   * SUNGEN_ENV=ja). `null` = base data only. loadTestData no-ops on a missing
+   * overlay file, so passing an env code whose overlay doesn't exist is safe.
+   */
+  overlay: string | null;
+}
+
+export interface LocaleDiscovery {
+  variants: LocaleVariant[];
+  /** Env-run suffixes with result files, excluded from this delivery (hint material). */
+  ignored: string[];
+}
+
+export interface LocaleConfig {
+  baseLocale: string;
+  locales: string[];
+}
+
+export const DEFAULT_BASE_LOCALE = 'en';
+
+/** Read the i18n declaration from qa/capabilities.yaml (absent → no locales, base 'en'). */
+export function readLocaleConfig(cwd: string): LocaleConfig {
+  try {
+    const p = path.join(cwd, 'qa', 'capabilities.yaml');
+    if (fs.existsSync(p)) {
+      const parsed = parseYaml(fs.readFileSync(p, 'utf-8')) as
+        { locales?: unknown; base_locale?: unknown } | null;
+      const locales = Array.isArray(parsed?.locales)
+        ? parsed!.locales!.filter((l): l is string => typeof l === 'string' && l.length > 0)
+        : [];
+      const baseLocale = typeof parsed?.base_locale === 'string' && parsed.base_locale
+        ? parsed.base_locale
+        : DEFAULT_BASE_LOCALE;
+      return { baseLocale, locales };
+    }
+  } catch { /* malformed yaml → behave as undeclared */ }
+  return { baseLocale: DEFAULT_BASE_LOCALE, locales: [] };
+}
+
+const OS_SUFFIX = /^(android|ios)(\.|$)/;
+
+/** The after-OS tail of a mobile suffix: 'android.ja' → 'ja', 'ios' → ''. */
+export function osSuffixTail(suffix: string): string {
+  return suffix.replace(OS_SUFFIX, '');
+}
+
+/**
+ * Discover the variants of a feature for ONE delivery run.
+ *
+ * `resolveBaseResultsPath` supplies the base variant's results (delivery and
+ * the dashboard share the same env-aware candidate chain via
+ * playwright-report-parser.resolveResultsPath — passed in to avoid a cycle).
+ */
+export function discoverLocaleVariants(
+  cwd: string,
+  genDir: string,
+  featureBaseName: string,
+  resolveBaseResultsPath: () => string | null,
+): LocaleDiscovery {
+  const cfg = readLocaleConfig(cwd);
+  const env = process.env.SUNGEN_ENV || '';
+  const prefix = `${featureBaseName}-test-result`;
+
+  const variants: LocaleVariant[] = [{
+    locale: '',
+    // With --env <locale> (the SUNGEN_ENV=<locale> convention) the base IS that
+    // locale's run; otherwise the base carries the declared base language.
+    displayCode: (cfg.locales.includes(env) ? env : cfg.baseLocale).toUpperCase(),
+    resultsPath: resolveBaseResultsPath(),
+    overlay: env || null,
+  }];
+  const ignored: string[] = [];
+
+  if (fs.existsSync(genDir)) {
+    const suffixes = fs.readdirSync(genDir)
+      .filter((f) => f.startsWith(`${prefix}.`) && f.endsWith('.json') && f !== `${prefix}.json`)
+      .map((f) => f.slice(prefix.length + 1, -'.json'.length))
+      .filter((s) => s.length > 0)
+      .sort();
+    for (const suffix of suffixes) {
+      if (OS_SUFFIX.test(suffix)) {
+        // Mobile per-OS run — kept unconditionally; the mobile branch consumes these.
+        // Overlay = the tail (what SUNGEN_ENV was during that run), never the OS itself.
+        variants.push({
+          locale: suffix,
+          displayCode: suffix.toUpperCase(),
+          resultsPath: path.join(genDir, `${prefix}.${suffix}.json`),
+          overlay: osSuffixTail(suffix) || null,
+        });
+        continue;
+      }
+      if (suffix === env) continue; // the base variant's own file
+      const isLocaleOfThisEnv = env === ''
+        ? cfg.locales.includes(suffix)
+        : suffix.startsWith(`${env}-`) && cfg.locales.includes(suffix.slice(env.length + 1));
+      if (isLocaleOfThisEnv) {
+        variants.push({
+          locale: suffix,
+          displayCode: suffix.toUpperCase(),
+          resultsPath: path.join(genDir, `${prefix}.${suffix}.json`),
+          overlay: suffix,
+        });
+      } else {
+        ignored.push(suffix);
+      }
+    }
+  }
+
+  return { variants, ignored };
+}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/state-with-filter-assertion.hbs

@@ -0,0 +1,11 @@
+{{#if selectedProbe}}
+{ const el = {{> locator-base}}.filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}};
+if ((await el.getAttribute('aria-selected')) !== null) {
+await expect(el).toHaveAttribute('aria-selected', 'true');
+} else {
+await expect(el).toBeChecked();
+}
+}
+{{else}}
+await expect({{> locator-base}}.filter({ hasText: /^{{escapeRegex dataValue}}$/ }){{> locator-nth}}).{{{stateAssertion}}};
+{{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-match-data.hbs

@@ -1,15 +1,7 @@
-{{~#if isGiven~}}
 {
-  const rows = {{> locator}}.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true });
+  const table = {{> locator}};
+  const rows = table.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true });
 {{#each assertions}}
-  {{this}}
+  {{{this}}}
 {{/each~}}
 }
-{{~else~}}
-{
-  const rows = {{> locator}}.locator('tbody').getByRole('row', { includeHidden: true }).filter({ visible: true });
-{{#each assertions}}
-  {{this}}
-{{/each~}}
-}
-{{~/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-exists.hbs

@@ -1,7 +1,17 @@
+{{~#if rowSelector}}
+{{~#if isGiven}}
+const tableRow = {{> locator}}.locator('{{rowSelector}}');
+await tableRow.filter({ hasText: '{{escapeQuotes filterValue}}' }).waitFor();
+{{~else}}
+const tableRow = {{> locator}}.locator('{{rowSelector}}');
+await expect(tableRow).toContainText('{{escapeQuotes filterValue}}');
+{{~/if}}
+{{~else}}
 {{~#if isGiven}}
 const tableRow = {{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true });
 await tableRow.waitFor();
 {{~else}}
 const tableRow = {{> locator}}.getByRole('row', { includeHidden: true }).filter({ hasText: '{{escapeQuotes filterValue}}' }).filter({ visible: true });
 await expect(tableRow).toBeVisible();
-{{~/if}}
+{{~/if}}
+{{~/if}}

package/src/generators/test-generator/code-generator.ts

@@ -908,7 +908,7 @@ export class CodeGenerator {
       // them. Rewrite those to the per-row `rowData` view — each row then fires its own `@api` call
       // with that row's input and asserts that row's expected status/body (the success/failure matrix).
       // `testData.cases()/withRow()` (the global loader, no `.get/.bind/.set`) is intentionally left alone.
-      return transformToRuntimeData(rendered, 'rowData').replace(/\btestData\.(get|bind|set)\(/g, 'rowData.$1(');
+      return transformToRuntimeData(rendered, 'rowData').replace(/\btestData\.(get|bind|set|raw)\(/g, 'rowData.$1(');
     }
     return rendered;
   }
@@ -937,6 +937,40 @@ export class CodeGenerator {
   /**
    * Generate tests for all features in a directory
    */
+  /**
+   * SG-W009 — every `${QA_*}` secret reference in the unit's test-data yaml must be
+   * DECLARED: as a real value in .env.qa (or an overlay .env.qa.<env>), or at least as
+   * a name in the committed .env.qa.example. An undeclared ref means the test throws
+   * "environment variable not set" the moment the key is used — surface it at compile
+   * time instead. Only the `${QA_*}` shape is checked: any other `${...}` text is
+   * ordinary literal data by design (never resolved, never warned about).
+   */
+  private reportedEnvRefs = new Set<string>();
+  private checkEnvSecretRefs(featureFile: string): void {
+    const testDataDir = path.join(path.dirname(featureFile), '..', 'test-data');
+    if (!fs.existsSync(testDataDir)) return;
+    const referenced = new Set<string>();
+    for (const f of fs.readdirSync(testDataDir).filter((x) => x.endsWith('.yaml') || x.endsWith('.yml'))) {
+      const text = fs.readFileSync(path.join(testDataDir, f), 'utf-8');
+      for (const m of text.matchAll(/\$\{(QA_[A-Z0-9_]+)\}/g)) referenced.add(m[1]);
+    }
+    if (!referenced.size) return;
+    const declared = new Set<string>();
+    for (const f of fs.readdirSync(process.cwd()).filter((x) => x === '.env.qa' || x.startsWith('.env.qa.'))) {
+      for (const line of fs.readFileSync(path.join(process.cwd(), f), 'utf-8').split('\n')) {
+        const m = line.match(/^\s*#?\s*(QA_[A-Z0-9_]+)\s*=/);
+        if (m) declared.add(m[1]);
+      }
+    }
+    for (const name of referenced) {
+      if (declared.has(name) || this.reportedEnvRefs.has(name)) continue;
+      this.reportedEnvRefs.add(name);
+      this.diagnostics.add('SG-W009',
+        `test-data references \${${name}} but ${name} is declared in neither .env.qa nor .env.qa.example — the test will throw "environment variable not set" when the key is used. Add ${name}=<value> to .env.qa (gitignored), and list the name in .env.qa.example`,
+        { feature: path.basename(featureFile, '.feature'), step: name });
+    }
+  }
+
   async generateAllTests(
     featuresDir: string,
     outputDir: string,
@@ -956,6 +990,7 @@ export class CodeGenerator {
       try {
         const feature = parser.parseFeatureFile(featureFile);
         features.push(feature);
+        this.checkEnvSecretRefs(featureFile);
       } catch (error) {
         console.error(`✗ Failed to parse ${featureFile}:`, error);
         parseErrors.push({ file: featureFile, error });

package/src/generators/test-generator/diagnostics.ts

@@ -15,12 +15,17 @@
  *             Then (invalid Gherkin; comments cannot substitute), or a documentation-style
  *             manual (no steps) whose comments lack the extractable procedure — ≥1 numbered
  *             action line + ≥1 labeled Observable:/Oracle:/Expected: line
+ *   SG-W009 — test-data references a `${QA_*}` secret that is declared in neither .env.qa
+ *             nor .env.qa.example — the test will throw "not set" the moment the key is used
+ *   SG-W010 — a row step's [Ref] looks POSITIONAL (First/Last/Top/…) but has no selectors.yaml
+ *             entry: the label is display-only, so the step checks existence anywhere in the
+ *             table — an ordering rule would pass even when the row moved
  *
  * Diagnostics never block generation by themselves; `sungen generate --strict`
  * turns any collected diagnostic into a non-zero exit.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010';
 
 export interface Diagnostic {
   code: DiagnosticCode;