@sun-asterisk/sungen 3.2.14 → 3.2.16-beta.1

package/src/exporters/matrix/render-xlsx.ts

@@ -0,0 +1,289 @@
+/**
+ * Render the Test Case & Coverage Matrix workbook.
+ *
+ * Sheets:
+ *   1. Testcases — one parent row per delivery item, variant sub-rows grouped with
+ *      Excel outline (expanded for execution; the level-1 outline button collapses
+ *      to the customer/review view — same sheet, one model, two views).
+ *   2. Coverage — target × category grid (items + variants, `—` marks the gaps),
+ *      dispositions, and the generation manifest.
+ *
+ * Every sheet keeps the company ISO masthead (renderReportHeaderBand). A draft
+ * matrix (unapproved groups / review findings) carries a red DRAFT banner.
+ */
+
+import * as ExcelJS from 'exceljs';
+import {
+  renderReportHeaderBand,
+  allBordersBlack,
+  ARIAL_FONT,
+  BLACK,
+  LAVENDER,
+} from '../xlsx-report-builder';
+import { statusToTestResult, formatExecutedDate } from '../playwright-report-parser';
+import { CoverageVariant, DeliveryItem, ItemResult, MatrixModel, MapCategory } from './types';
+
+const CATEGORY_ORDER: MapCategory[] = ['normal', 'abnormal', 'security', 'nfr'];
+const SOFT_BLUE = { argb: 'FFDCE6F1' };
+const DRAFT_RED = { argb: 'FFC00000' };
+const GAP_FILL = { argb: 'FFFCE4EC' };
+
+function headerCell(c: ExcelJS.Cell, label: string): void {
+  c.value = label;
+  c.font = { bold: true, size: 10, color: BLACK, name: ARIAL_FONT };
+  c.fill = { type: 'pattern', pattern: 'solid', fgColor: LAVENDER };
+  c.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
+  c.border = allBordersBlack;
+}
+
+function dataCell(c: ExcelJS.Cell, value: ExcelJS.CellValue, opts?: { bold?: boolean; fill?: { argb: string }; center?: boolean; color?: { argb: string } }): void {
+  c.value = value;
+  c.font = { bold: opts?.bold ?? false, size: 10, name: ARIAL_FONT, ...(opts?.color ? { color: opts.color } : {}) };
+  c.alignment = { horizontal: opts?.center ? 'center' : 'left', vertical: 'top', wrapText: true };
+  c.border = allBordersBlack;
+  if (opts?.fill) c.fill = { type: 'pattern', pattern: 'solid', fgColor: opts.fill };
+}
+
+function itemResultLabel(item: DeliveryItem): string {
+  const { passed, failed, blocked, notRun } = item.resultCounts;
+  const total = item.variants.length;
+  const map: Record<ItemResult, string> = {
+    passed: `${passed}/${total} Passed`,
+    failed: `${passed}/${total} Passed · ${failed} Failed`,
+    blocked: `${blocked} Blocked`,
+    partial: `${passed}/${total} Passed · ${notRun} not run`,
+    not_run: 'Pending',
+  };
+  return map[item.result];
+}
+
+function variantResultLabel(v: CoverageVariant): string {
+  if (!v.result) return 'Pending';
+  return statusToTestResult(v.result.status);
+}
+
+function numbered(lines: string[]): string {
+  if (lines.length === 0) return '';
+  if (lines.length === 1) return lines[0];
+  return lines.map((l, i) => `${i + 1}. ${l}`).join('\n');
+}
+
+/** Red DRAFT banner on row 5 when the matrix is not approved for official delivery. */
+function draftBanner(ws: ExcelJS.Worksheet, model: MatrixModel): void {
+  if (model.manifest.approvalState !== 'draft') return;
+  ws.mergeCells('B5:H5');
+  const c = ws.getCell('B5');
+  c.value = 'DRAFT — NOT APPROVED FOR OFFICIAL DELIVERY (review-required findings or proposed groups remain)';
+  c.font = { bold: true, size: 11, name: ARIAL_FONT, color: { argb: 'FFFFFFFF' } };
+  c.fill = { type: 'pattern', pattern: 'solid', fgColor: DRAFT_RED };
+  c.alignment = { horizontal: 'center', vertical: 'middle' };
+}
+
+// ---------------------------------------------------------------------------
+// Sheet 1 — Testcases (the matrix)
+// ---------------------------------------------------------------------------
+
+const MATRIX_HEADERS = [
+  'ID', 'Target', 'Test Intent / Condition', 'Category', 'Priority', 'Precondition',
+  'Coverage / Test Data', 'Action / Trigger', 'Expected (Oracle)', 'Mode', 'Trace',
+  'Result', 'Executed Date', 'Executor', 'Note\n(Evidence, DefectID)',
+];
+
+function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?: string): void {
+  const ws = wb.addWorksheet('Testcases');
+  ws.properties.outlineLevelRow = 1;
+
+  ws.columns = [
+    { width: 3 },  // A margin
+    { width: 20 }, // B ID
+    { width: 18 }, // C Target
+    { width: 42 }, // D Intent / Condition
+    { width: 11 }, // E Category
+    { width: 9 },  // F Priority
+    { width: 26 }, // G Precondition
+    { width: 34 }, // H Coverage / Data
+    { width: 34 }, // I Trigger
+    { width: 42 }, // J Expected
+    { width: 11 }, // K Mode
+    { width: 13 }, // L Trace
+    { width: 17 }, // M Result
+    { width: 13 }, // N Executed
+    { width: 13 }, // O Executor
+    { width: 24 }, // P Note
+  ];
+
+  renderReportHeaderBand(wb, ws, `${model.unit.toUpperCase()} TEST CASE & COVERAGE MATRIX`, sungenVersion, model.formNo);
+  draftBanner(ws, model);
+
+  // Summary band (row 6) — items vs variants stay separate metrics by design (I8):
+  // the ITEM count is reviewer workload, the VARIANT count is execution workload.
+  const passed = model.items.reduce((a, i) => a + i.resultCounts.passed, 0);
+  const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
+  const notRun = model.items.reduce((a, i) => a + i.resultCounts.notRun + i.resultCounts.blocked, 0);
+  const band = ws.getRow(6);
+  [
+    `Delivery items: ${model.manifest.itemCount}`,
+    `Coverage variants: ${model.manifest.variantCount}`,
+    `Passed: ${passed}`, `Failed: ${failed}`, `Pending: ${notRun}`,
+  ].forEach((label, i) => {
+    const c = band.getCell(2 + i);
+    dataCell(c, label, { bold: true, fill: SOFT_BLUE, center: true });
+  });
+
+  const HEADER_ROW = 8;
+  const hr = ws.getRow(HEADER_ROW);
+  hr.height = 28;
+  MATRIX_HEADERS.forEach((label, i) => headerCell(hr.getCell(2 + i), label));
+
+  let rowIdx = HEADER_ROW + 1;
+  for (const item of model.items) {
+    // Parent row — the delivery item (the review unit).
+    const pr = ws.getRow(rowIdx++);
+    const single = item.variants.length === 1;
+    const only = single ? item.variants[0] : undefined;
+    const coverage = single
+      ? numbered(only!.data)
+      : `${item.variants.length} variants: ${item.variants.map((v) => v.condition).join(' · ')}`;
+    const values: ExcelJS.CellValue[] = [
+      item.id,
+      item.target,
+      item.intent,
+      item.category,
+      item.priority,
+      numbered(item.precondition),
+      coverage,
+      numbered(item.trigger),
+      item.oracle,
+      item.mode === 'manual' ? `Manual${only?.manualReason ? ` (${only.manualReason})` : ''}` : 'Auto',
+      item.traces.join(', '),
+      itemResultLabel(item),
+      single ? formatExecutedDate(only!.result?.startTime) : '',
+      '',
+      item.review === 'proposed' ? 'REVIEW REQUIRED' : '',
+    ];
+    values.forEach((v, i) => dataCell(pr.getCell(2 + i), v, {
+      bold: true,
+      fill: SOFT_BLUE,
+      center: i === 3 || i === 4 || i === 9,
+      ...(String(values[14]).startsWith('REVIEW') && i === 14 ? { color: DRAFT_RED } : {}),
+    }));
+
+    // Variant sub-rows — the execution units (outline level 1; collapse for review).
+    if (!single) {
+      for (const v of item.variants) {
+        const vr = ws.getRow(rowIdx++);
+        vr.outlineLevel = 1;
+        const vValues: ExcelJS.CellValue[] = [
+          v.ref,
+          '',
+          v.condition,
+          '', '', '',
+          numbered(v.data),
+          numbered(v.trigger),
+          numbered(v.oracle),
+          v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
+          v.traces.join(', '),
+          variantResultLabel(v),
+          formatExecutedDate(v.result?.startTime),
+          '',
+          v.result?.error ? String(v.result.error).slice(0, 200) : '',
+        ];
+        vValues.forEach((val, i) => dataCell(vr.getCell(2 + i), val, { center: i === 9 }));
+      }
+    }
+  }
+
+  ws.autoFilter = { from: { row: HEADER_ROW, column: 2 }, to: { row: rowIdx - 1, column: 16 } };
+  ws.views = [{ state: 'frozen', ySplit: HEADER_ROW }];
+}
+
+// ---------------------------------------------------------------------------
+// Sheet 2 — Coverage (overview grid + dispositions + manifest)
+// ---------------------------------------------------------------------------
+
+function addCoverageSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?: string): void {
+  const ws = wb.addWorksheet('Coverage');
+  ws.columns = [
+    { width: 3 }, { width: 30 }, { width: 16 }, { width: 16 }, { width: 16 }, { width: 16 },
+    { width: 16 }, { width: 40 },
+  ];
+  renderReportHeaderBand(wb, ws, `${model.unit.toUpperCase()} COVERAGE OVERVIEW`, sungenVersion, model.formNo);
+  draftBanner(ws, model);
+
+  // --- Target × category grid ---
+  let rowIdx = 7;
+  dataCell(ws.getRow(rowIdx).getCell(2), 'Coverage matrix — delivery items (coverage variants) per target × category', { bold: true });
+  rowIdx += 1;
+  const gridHeader = ws.getRow(rowIdx++);
+  headerCell(gridHeader.getCell(2), 'Target');
+  CATEGORY_ORDER.forEach((cat, i) => headerCell(gridHeader.getCell(3 + i), cat));
+  headerCell(gridHeader.getCell(3 + CATEGORY_ORDER.length), 'Total');
+
+  const targets = Array.from(new Set(model.items.map((i) => i.target)));
+  for (const target of targets) {
+    const row = ws.getRow(rowIdx++);
+    dataCell(row.getCell(2), target, { bold: true });
+    let totalItems = 0;
+    let totalVariants = 0;
+    CATEGORY_ORDER.forEach((cat, i) => {
+      const cell = row.getCell(3 + i);
+      const items = model.items.filter((it) => it.target === target && it.category === cat);
+      const variants = items.reduce((a, it) => a + it.variants.length, 0);
+      totalItems += items.length;
+      totalVariants += variants;
+      // `—` is an explicit statement: this target × category cell has NO coverage.
+      dataCell(cell, items.length === 0 ? '—' : `${items.length} (${variants})`, {
+        center: true,
+        ...(items.length === 0 ? { fill: GAP_FILL } : {}),
+      });
+    });
+    dataCell(row.getCell(3 + CATEGORY_ORDER.length), `${totalItems} (${totalVariants})`, { center: true, bold: true });
+  }
+
+  // --- Dispositions ---
+  if (model.dispositions.length > 0) {
+    rowIdx += 1;
+    dataCell(ws.getRow(rowIdx).getCell(2), 'Not in the matrix (explicit dispositions)', { bold: true });
+    rowIdx += 1;
+    const dh = ws.getRow(rowIdx++);
+    ['Source', 'Disposition', 'Reason', 'Title'].forEach((l, i) => headerCell(dh.getCell(2 + i), l));
+    for (const d of model.dispositions) {
+      const row = ws.getRow(rowIdx++);
+      dataCell(row.getCell(2), d.vpId);
+      dataCell(row.getCell(3), d.as, { center: true });
+      dataCell(row.getCell(4), d.reason);
+      dataCell(row.getCell(5), d.title);
+    }
+  }
+
+  // --- Manifest ---
+  rowIdx += 1;
+  dataCell(ws.getRow(rowIdx).getCell(2), 'Generation manifest', { bold: true });
+  rowIdx += 1;
+  const m = model.manifest;
+  const manifestRows: Array<[string, string]> = [
+    ['Unit', m.unit],
+    ['Approval state', m.approvalState],
+    ['Delivery items', String(m.itemCount)],
+    ['Coverage variants', String(m.variantCount)],
+    ['Source fingerprint', m.sourceFingerprint],
+    ['Map fingerprint', m.mapFingerprint],
+    ['Transformer version', m.transformerVersion],
+    ['Max variants / item (warn)', String(m.thresholds.maxVariantsPerItem)],
+  ];
+  for (const [k, v] of manifestRows) {
+    const row = ws.getRow(rowIdx++);
+    dataCell(row.getCell(2), k, { bold: true, fill: SOFT_BLUE });
+    ws.mergeCells(rowIdx - 1, 3, rowIdx - 1, 7);
+    dataCell(row.getCell(3), v);
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+export function renderMatrixXlsx(model: MatrixModel, sungenVersion?: string): ExcelJS.Workbook {
+  const wb = new ExcelJS.Workbook();
+  addMatrixSheet(wb, model, sungenVersion);
+  addCoverageSheet(wb, model, sungenVersion);
+  return wb;
+}

package/src/exporters/matrix/types.ts

@@ -0,0 +1,176 @@
+/**
+ * Delivery v2 — Test Case & Coverage Matrix model (docs/spec/delivery-coverage-matrix-spec.md).
+ *
+ * Gherkin stays the source of test meaning; the matrix is a derived presentation:
+ * one delivery item = one target + one intent + one oracle family, containing one or
+ * more atomic coverage variants (scenario / @cases row). Grouping semantics live in the
+ * committed Delivery Map (`qa/<kind>/<unit>/delivery/<unit>.map.yaml`) — AI-proposed,
+ * gate-validated, QA-approved.
+ */
+
+import { PlaywrightResult } from '../types';
+
+// ---------------------------------------------------------------------------
+// Delivery Map (the committed grouping artifact)
+// ---------------------------------------------------------------------------
+
+export type MapCategory = 'normal' | 'abnormal' | 'security' | 'nfr';
+export type ReviewState = 'proposed' | 'approved';
+export type DispositionKind = 'excluded' | 'blocked' | 'covered_elsewhere' | 'accepted_risk';
+
+export interface MapGroup {
+  /** Stable delivery id, unique per unit, order-independent (e.g. DI-EMAIL-FORMAT). */
+  id: string;
+  /** ONE primary target: field/component dot-path, function/flow phrase, or `METHOD /path`. */
+  target: string;
+  /** One coherent test intent (the primary behavior/rule verified). */
+  intent: string;
+  /** Oracle family in words — the shared Pass/Fail observation. */
+  oracle: string;
+  category: MapCategory;
+  review: ReviewState;
+  /** Variant refs: `VP-ID` (all @cases rows when the scenario has a dataset) or `VP-ID#label`. */
+  variants: string[];
+}
+
+export interface MapDisposition {
+  as: DispositionKind;
+  reason?: string;
+}
+
+export interface DeliveryMap {
+  version: number;
+  unit: string;
+  /** ISO form number rendered in the workbook masthead (default BM-2-901-13). */
+  formNo?: string;
+  groups: MapGroup[];
+  /** VP-id → intentionally-not-grouped disposition. */
+  dispositions: Record<string, MapDisposition>;
+  /** VP-id → scenario fingerprint stamped at approval time (drift detector input). */
+  fingerprints: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Derived model (deterministic, computed from the .feature at build time)
+// ---------------------------------------------------------------------------
+
+/** Execution layers a variant verifies on — cross-checked with the verification scope. */
+export type MatrixLayer = 'ui' | 'api' | 'db';
+
+/**
+ * One atomic coverage variant — the unit of execution, result, and traceability.
+ * Backed by one scenario, or one `@cases` dataset row of a scenario.
+ */
+export interface CoverageVariant {
+  /** `VP-ID` or `VP-ID#label` for a dataset row. */
+  ref: string;
+  vpId: string;
+  /** Dataset-row label when this variant is one `@cases` row. */
+  caseLabel?: string;
+  /** Human title (scenario name without the VP prefix; row label appended for @cases). */
+  title: string;
+  /** Viewpoint category from the VP prefix (LOGIC/VAL/UI/SEC/…). */
+  vpCategory: string;
+  priority: string;                        // High | Normal | Low
+  /** 'auto' | 'manual'; manual keeps its @manual:Mx reason. */
+  mode: 'auto' | 'manual';
+  manualReason?: string;
+  layers: MatrixLayer[];
+  /** @spec:* requirement traces. */
+  traces: string[];
+  /** Condition summary: differentiating dimension shown on the sub-row. */
+  condition: string;
+  /** Resolved data pairs (test-data values / dataset-row columns), `key: value` lines. */
+  data: string[];
+  /** Normalized trigger shape (When steps, `{{var}}` collapsed) — signature input. */
+  triggerShape: string[];
+  /** Trigger for display (When steps, vars resolved). */
+  trigger: string[];
+  /** Normalized oracle shape (Then steps / manual Observable+Oracle) — signature input. */
+  oracleShape: string[];
+  /** Oracle for display. */
+  oracle: string[];
+  /** Precondition profile: auth role + scenario-level Given shapes — signature input. */
+  preconditionProfile: string;
+  /** Human preconditions (auth + own Given steps). */
+  precondition: string[];
+  /** 'simple' (G*W*T*) | 'sequence' (mid-flow Given / multi round-trip) | 'manual'. */
+  procedureProfile: 'simple' | 'sequence' | 'manual';
+  /** Canonical scenario fingerprint (drift detection). */
+  fingerprint: string;
+  /** Execution result, when the run report has one for this variant. */
+  result?: PlaywrightResult;
+}
+
+export type ItemResult = 'passed' | 'failed' | 'blocked' | 'partial' | 'not_run';
+
+/** One summarized row in the matrix — a group of variants sharing the signature. */
+export interface DeliveryItem {
+  id: string;
+  target: string;
+  intent: string;
+  oracle: string;
+  category: MapCategory;
+  review: ReviewState;
+  priority: string;
+  mode: 'auto' | 'manual';
+  layers: MatrixLayer[];
+  /** Union of variant traces (exact per-variant traces stay on the variants). */
+  traces: string[];
+  precondition: string[];
+  /** Common trigger when all variants share one shape, else '(per variant)'. */
+  trigger: string[];
+  variants: CoverageVariant[];
+  /** Derived roll-up — never entered independently (Gate F). */
+  result: ItemResult;
+  resultCounts: { passed: number; failed: number; blocked: number; notRun: number };
+}
+
+export interface MatrixDisposition {
+  vpId: string;
+  title: string;
+  as: DispositionKind;
+  reason: string;
+}
+
+// ---------------------------------------------------------------------------
+// Gate findings
+// ---------------------------------------------------------------------------
+
+export type GateId = 'A' | 'B' | 'C' | 'D' | 'E' | 'G';
+export type FindingSeverity = 'error' | 'review' | 'warning';
+
+export interface MatrixFinding {
+  gate: GateId;
+  severity: FindingSeverity;
+  /** Delivery item / VP-id the finding anchors to, when applicable. */
+  ref?: string;
+  message: string;
+}
+
+// ---------------------------------------------------------------------------
+// The assembled matrix
+// ---------------------------------------------------------------------------
+
+export interface MatrixManifest {
+  unit: string;
+  transformerVersion: string;
+  sourceFingerprint: string;     // canonical hash over all scenario fingerprints
+  mapFingerprint: string;        // canonical hash of the map content
+  approvalState: 'approved' | 'draft';
+  itemCount: number;
+  variantCount: number;
+  thresholds: { maxVariantsPerItem: number };
+}
+
+export interface MatrixModel {
+  unit: string;
+  formNo: string;
+  items: DeliveryItem[];
+  dispositions: MatrixDisposition[];
+  findings: MatrixFinding[];
+  manifest: MatrixManifest;
+}
+
+/** Complexity warning threshold (rules draft Gate I) — echoed in the manifest. */
+export const MAX_VARIANTS_PER_ITEM = 12;

package/src/exporters/scenario-merger.ts

@@ -162,7 +162,7 @@ function findMatchingSpecTest(scenario: ScenarioMetadata, tests: SpecTest[]): Sp
   if (exact) return exact;
 
   // Fallback: match by VP-ID prefix (ignore trailing text differences)
-  const vpMatch = scenario.name.match(/^(VP-[A-Z][A-Z0-9]*-\d+[a-zA-Z]?)/);
+  const vpMatch = scenario.name.match(/^(VP-[A-Z][A-Z0-9]*-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?)/);
   if (vpMatch) {
     const vpId = vpMatch[1];
     const byVp = tests.find((t) => t.vpId === vpId);

package/src/exporters/spec-parser.ts

@@ -165,7 +165,7 @@ function classifyBlock(block: CodeBlock): 'precondition' | 'step' | 'expectation
  * Try to extract VP ID (e.g., VP-UI-001) from the start of a scenario title.
  */
 function extractVpId(title: string): string | undefined {
-  const match = title.match(/^(VP-[A-Z][A-Z0-9]*-\d+[a-zA-Z]?)\b/);
+  const match = title.match(/^(VP-[A-Z][A-Z0-9]*-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?)\b/);
   return match ? match[1] : undefined;
 }
 

package/src/exporters/xlsx-report-builder.ts

@@ -143,6 +143,7 @@ export function renderReportHeaderBand(
   ws: ExcelJS.Worksheet,
   titleLabel: string,
   sungenVersion?: string,
+  formNo: string = 'BM-2-901-13',
 ): void {
   const issueDate = (() => {
     const d = new Date();
@@ -187,9 +188,9 @@ export function renderReportHeaderBand(
   d1.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
   d1.border = allBordersBlack;
 
-  // G1 — No: BM-2-901-13
+  // G1 — No: <form number> (the company ISO form id; configurable via the delivery map)
   const g1 = ws.getCell('G1');
-  g1.value = 'No: BM-2-901-13';
+  g1.value = `No: ${formNo}`;
   g1.font = { size: 12, name: TIMES };
   g1.alignment = { vertical: 'middle' };
   g1.border = { top: thinBlack, left: thinBlack, right: thinBlack };

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;
   }

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

@@ -17,12 +17,15 @@
  *             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' | 'SG-W009';
+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;

package/src/generators/test-generator/step-mapper.ts

@@ -37,6 +37,10 @@ export class StepMapper {
   /** Row scope: when active, column assertions are scoped to this row */
   private inRowScope: boolean = false;
   private rowScopeTable: string = '';
+  /** Count of row-scope-entering steps in the current scenario + whether the shared
+   *  `tableRow` binding has been emitted (let-once + reassign when there are ≥2). */
+  private tableRowScopeSteps: number = 0;
+  private tableRowDeclared: boolean = false;
   /** SG-W007: an action step already ran in this scenario (alert handlers registered after it are too late) */
   private sawActionStep: boolean = false;
   /** Compile-time warning channel (SG-W001/W002); optional — absent means silent legacy behavior */
@@ -109,6 +113,12 @@ export class StepMapper {
   /**
    * Set scenario context for path variable resolution
    */
+  /** A `see [Ref] row in [Table] table with {{v}}` step — declares `tableRow` and enters row scope. */
+  private isRowScopeEntryStep(step: ParsedStep): boolean {
+    return step.elementType === 'row' && /\bin\b.*\btable\b/i.test(step.text) &&
+      /\bwith\b/i.test(step.text) && !/\bis\s+hidden\b/i.test(step.text);
+  }
+
   setScenarioContext(steps: ParsedStep[]): void {
     this.currentScenarioSteps = steps;
     // Reset dialog and frame scope at the start of each new scenario
@@ -116,6 +126,16 @@ export class StepMapper {
     this.inFrameScope = false;
     this.inRowScope = false;
     this.rowScopeTable = '';
+    // Row-scope steps declare `const tableRow` at FUNCTION scope on purpose — the
+    // following `[Col] column with {{v}}` steps reference it, so the declaration
+    // can't be block-wrapped like the self-contained row ACTIONS are. But two or
+    // more row steps in one scenario then redeclare the same const → the whole
+    // spec fails to parse ("Identifier 'tableRow' has already been declared").
+    // Count them up front: with ≥2 the first becomes `let` and the rest plain
+    // reassignments (which also correctly REBINDS the row scope); a single
+    // occurrence keeps `const` so existing single-row specs stay byte-identical.
+    this.tableRowScopeSteps = steps.filter((s) => this.isRowScopeEntryStep(s)).length;
+    this.tableRowDeclared = false;
     this.sawActionStep = false;
     this.lastPrimaryKeyword = 'Given';
     this.dataResolver.clearCaptured(); // captured vars are scenario-scoped
@@ -245,13 +265,34 @@ export class StepMapper {
 
     if (mappedStep) {
       // Enter row scope when a row-in-table step is matched
-      if (step.elementType === 'row' && /\bin\b.*\btable\b/i.test(step.text) &&
-          /\bwith\b/i.test(step.text) && !/\bis\s+hidden\b/i.test(step.text)) {
+      if (this.isRowScopeEntryStep(step)) {
         const brackets = step.text.match(/\[([^\]]+)\]/g) || [];
         this.inRowScope = true;
         this.rowScopeTable = brackets.length >= 2
           ? brackets[1].replace(/[\[\]]/g, '')
           : '';
+        // ≥2 row steps in this scenario: turn the duplicate `const tableRow`
+        // declarations into one `let` + reassignments (see setScenarioContext).
+        if (this.tableRowScopeSteps > 1 && mappedStep.code && mappedStep.code.includes('const tableRow')) {
+          if (this.tableRowDeclared) {
+            mappedStep.code = mappedStep.code.replace('const tableRow', 'tableRow');
+          } else {
+            mappedStep.code = mappedStep.code.replace('const tableRow', 'let tableRow');
+            this.tableRowDeclared = true;
+          }
+        }
+        // SG-W010 — a POSITIONAL-looking row label ([First X Row], [Last …]) without a
+        // selectors.yaml entry is display-only: the step degrades to an anywhere-in-the-
+        // table existence check and an ordering rule silently never fails. A resolved
+        // entry compiles to a positioned toContainText — its absence is detectable here.
+        const rowLabel = (brackets[0] || '').replace(/[\[\]]/g, '');
+        if (this.diagnostics && rowLabel &&
+            /\b(first|last|top|bottom|nth|\d+(st|nd|rd|th)?)\b/i.test(rowLabel) &&
+            mappedStep.code && !mappedStep.code.includes('toContainText')) {
+          this.diagnostics.add('SG-W010',
+            `row label "[${rowLabel}]" looks positional but has no selectors.yaml entry — it is a display label only, so this step checks existence ANYWHERE in the table (an ordering rule would pass even when the row moved). Declare it to position the row, e.g. "${rowLabel.toLowerCase()}:\\n  type: locator\\n  value: 'tbody tr:first-child'"`,
+            { feature: this.featureName, step: step.text });
+        }
       }
 
       if (this.verbose) {