@sun-asterisk/sungen 3.2.28 → 3.2.30

package/src/exporters/matrix/wording.ts

@@ -150,6 +150,19 @@ export function renderExpected(raw: string): string {
 
 /** Precondition wording: a state, not an action ("The user is signed out."). */
 export function renderPrecondition(raw: string): string {
+  // A capture step is an INSTRUCTION the tester performs, not a state — the same
+  // reasoning renderSetupInstruction applies to manual `Setup:` lines, and "The
+  // user remember X text as …" was broken grammar besides.
+  // It also carries the ONLY thing that resolves the `as {{v}}` token: on the
+  // trigger path build.ts renders `renderAction(sub(s))`, so substituteDisplayVars
+  // leaves that token for renderAction to quote. The precondition path renders
+  // FIRST and substitutes second, so renderAction was never reached, sub then
+  // declined to touch the token by design, and the raw brace shipped into the
+  // deliverable — Gate D rejected the whole unit over it (#684).
+  // Guarded on the token form exactly as renderExpected does, so a Given that
+  // merely says "remember" in prose keeps its state wording.
+  if (RUNTIME_CAPTURE.test(raw) && /\bas\s+\{\{/.test(raw)) return renderAction(raw);
+
   const s = raw.trim().replace(/^(User|The user)\s+/i, '');
   const m = s.match(/^is on \[([^\]]+)\] page(.*)$/i);
   if (m) return sentence(`The user is on the ${m[1]} page${m[2] ?? ''}`);

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

@@ -0,0 +1,56 @@
+/**
+ * Shared cell primitives for the matrix workbook renderers.
+ *
+ * One place for the palette, the header/data cell styling, and the DRAFT
+ * banner — the testcase, coverage and overview renderers all draw from here so
+ * the four sheets stay visually one document.
+ */
+
+import * as ExcelJS from 'exceljs';
+import { allBordersBlack, ARIAL_FONT, BLACK, LAVENDER } from '../xlsx-report-builder';
+import { MatrixModel } from './types';
+
+export const SOFT_BLUE = { argb: 'FFDCE6F1' };
+export const DRAFT_RED = { argb: 'FFC00000' };
+export const GAP_FILL = { argb: 'FFFCE4EC' };
+/** The five words a variant Result cell may hold — the vocabulary COUNTIF counts. */
+export const RESULT_STATES = 'Passed,Failed,Blocked,Pending,N/A';
+
+export interface DataCellOpts {
+  bold?: boolean;
+  fill?: { argb: string };
+  center?: boolean;
+  color?: { argb: string };
+}
+
+export 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;
+}
+
+export function dataCell(c: ExcelJS.Cell, value: ExcelJS.CellValue, opts?: DataCellOpts): void {
+  // An empty value stays a genuinely blank cell — never an empty shared string,
+  // which some renderers display as its string-table index (review M-03).
+  if (value !== '' && value !== undefined && value !== null) 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 };
+}
+
+/**
+ * Red DRAFT banner on row 5 when the matrix is not approved for official delivery.
+ * Spans A..H — the same width as the masthead above it, on every sheet.
+ */
+export function draftBanner(ws: ExcelJS.Worksheet, model: MatrixModel): void {
+  if (model.manifest.approvalState !== 'draft') return;
+  ws.mergeCells('A5:H5');
+  const c = ws.getCell('A5');
+  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' };
+}

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

@@ -26,7 +26,7 @@ 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';
+import { SENSITIVE_NAME } from './sensitive-key';
 
 /** `${QA_*}` env reference — same shape the runtime resolver allowlists (uppercase, QA_ prefix). */
 const QA_ENV_REF = /\$\{(QA_[A-Z0-9_]+)\}/g;

package/src/exporters/report-path-sanitizer.ts

@@ -0,0 +1,144 @@
+/**
+ * Report path sanitizer — rewrites the operator's machine paths out of a result/report JSON.
+ *
+ * Playwright's JSON reporter (and sungen's own script-check report) record ABSOLUTE paths:
+ * `config.configFile`, `rootDir`, `projects[].testDir/outputDir`, every `error.location.file`,
+ * attachment paths, and the paths quoted inside `stack`/`message`/`snippet` text. Teams commit these
+ * files next to the spec (the delivery reads them), so a username and a machine layout travel into
+ * the repository and the deliverable. Nothing downstream needs them absolute: delivery, dashboard and
+ * merge read titles, statuses and attachment names.
+ *
+ * Rules (pure — no I/O, no mutation of the input):
+ *   - A string that IS an absolute path (POSIX, `C:\…`, `file:///…`) under the report's project root
+ *     becomes the POSIX path relative to that root (the root itself → `.`); outside the root a path that
+ *     names a machine (a home directory, a drive) keeps only its basename; any other absolute string —
+ *     a URL route such as `/products` — is left alone.
+ *   - Inside longer text (stack traces, messages, snippets) every occurrence of the root becomes a
+ *     relative path, and a home directory (`/Users/<name>/`, `/home/<name>/`, `C:\Users\<name>\`) becomes
+ *     `~/` — the text is rewritten, never dropped, so the trace stays readable.
+ *   - URLs are untouched: a `/home/...` inside `https://host/home/...` is not a filesystem path.
+ *   - Idempotent: sanitizing an already-sanitized report rewrites nothing.
+ *
+ * The root is the report's OWN `dirname(config.configFile)` when it carries one (self-describing —
+ * a report produced on another machine relativizes against ITS root, not the reader's cwd); callers
+ * fall back to their cwd otherwise.
+ */
+
+export interface SanitizeOptions {
+  /** Project root the report's paths are made relative to (absolute; POSIX or Windows). */
+  root: string;
+}
+
+export interface SanitizeOutcome<T> {
+  doc: T;
+  /** Number of string values that changed. */
+  rewritten: number;
+}
+
+const ABSOLUTE = /^(?:file:\/\/\/?|[A-Za-z]:[\\/]|\/)/;
+const WINDOWS_DRIVE = /^[A-Za-z]:/;
+/**
+ * A home directory quoted inside text, not embedded in a URL or a longer token: `/Users/<name>/`,
+ * `/home/<name>/`, `C:\Users\<name>\`, each optionally behind a `file://` scheme (Node ESM errors
+ * quote modules as `file:///Users/<name>/…`).
+ */
+const HOME_DIR = /(?<![\w.:/\\-])(?:file:\/\/\/?)?(?:\/(?:Users|home)\/[^/\\\s"'`)\]]+[/\\]|[A-Za-z]:[\\/]Users[\\/][^/\\\s"'`)\]]+[\\/])/g;
+
+/** The project root a report describes itself against, if it says. */
+export function detectReportRoot(doc: unknown): string | undefined {
+  const configFile = (doc as { config?: { configFile?: unknown } } | null)?.config?.configFile;
+  if (typeof configFile !== 'string' || !ABSOLUTE.test(configFile)) return undefined;
+  const p = toPosix(stripFileScheme(configFile));
+  const i = p.lastIndexOf('/');
+  return i > 0 ? p.slice(0, i) : undefined;
+}
+
+export function sanitizeReportPaths<T>(doc: T, opts: SanitizeOptions): SanitizeOutcome<T> {
+  const root = normalizeRoot(opts.root);
+  // A root of `/` (or empty) would make every `/` a "root prefix" and shred the document.
+  if (root.posix.length < 2) return { doc, rewritten: 0 };
+  let rewritten = 0;
+  const rewrite = (value: string): string => {
+    const next = sanitizeString(value, root);
+    if (next !== value) rewritten++;
+    return next;
+  };
+  const walk = (v: unknown): unknown => {
+    if (typeof v === 'string') return rewrite(v);
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === 'object') {
+      const out: Record<string, unknown> = {};
+      for (const [k, x] of Object.entries(v as Record<string, unknown>)) out[k] = walk(x);
+      return out;
+    }
+    return v;
+  };
+  return { doc: walk(doc) as T, rewritten };
+}
+
+interface Root { posix: string; caseInsensitive: boolean; pattern: RegExp }
+
+function normalizeRoot(raw: string): Root {
+  const posix = toPosix(stripFileScheme(raw)).replace(/\/+$/, '');
+  const caseInsensitive = WINDOWS_DRIVE.test(posix);
+  // The root as it may appear inside text: either separator style, optional file:// scheme, and the
+  // separator that follows it (consumed, so what remains starts at the relative path).
+  const body = posix.split('/').map(escapeRegExp).join('[\\\\/]');
+  return { posix, caseInsensitive, pattern: new RegExp(`(?:file:\\/\\/\\/?)?${body}(?:[\\\\/](?![\\\\/])|(?=$|[\\s"'\`):,]))`, caseInsensitive ? 'gi' : 'g') };
+}
+
+function sanitizeString(value: string, root: Root): string {
+  const trimmed = value.trim();
+  if (ABSOLUTE.test(trimmed) && !/\s/.test(trimmed)) {
+    // The whole value is one path.
+    const p = toPosix(stripFileScheme(trimmed)).replace(/\/+$/, '');
+    const rel = relativeToRoot(p, root);
+    if (rel !== undefined) return rel;
+    // Outside the root: only a path that names a MACHINE (a home directory, a drive) is cut to its
+    // basename. Any other absolute string is left alone — `/products` in an audit report is a route.
+    if (isMachinePath(p)) {
+      // Another machine's checkout of THIS project (`…/work/<project>/specs/x.ts`, root `/home/me/<project>`):
+      // the part after the project directory is the honest relative path; only then fall back to the basename.
+      const marker = '/' + root.posix.slice(root.posix.lastIndexOf('/') + 1) + '/';
+      const i = marker.length > 2 ? (root.caseInsensitive ? p.toLowerCase().indexOf(marker.toLowerCase()) : p.indexOf(marker)) : -1;
+      if (i >= 0) return p.slice(i + marker.length);
+      return p.slice(p.lastIndexOf('/') + 1) || p;
+    }
+    return value;
+  }
+  // Paths quoted inside text: root → relative (the root alone → `.`), home → ~/.
+  const out = value.replace(root.pattern, (m: string) => (/[\\/]$/.test(m) ? '' : '.'));
+  return out.replace(HOME_DIR, '~/');
+}
+
+/**
+ * A path that identifies the operator's machine: a drive-letter path, or a home directory with
+ * something UNDER the user's folder (`/Users/<name>/<…>`). Case-sensitive and two segments deep on
+ * purpose — `/users/42/orders` and `/home/dashboard` are routes an audit report lists, not homes.
+ */
+function isMachinePath(posixPath: string): boolean {
+  return WINDOWS_DRIVE.test(posixPath) || /\/(?:Users|home)\/[^/]+\/./.test(posixPath);
+}
+
+function relativeToRoot(p: string, root: Root): string | undefined {
+  const a = root.caseInsensitive ? p.toLowerCase() : p;
+  const b = root.caseInsensitive ? root.posix.toLowerCase() : root.posix;
+  if (a === b) return '.';
+  if (a.startsWith(b + '/')) return p.slice(root.posix.length + 1);
+  return undefined;
+}
+
+function stripFileScheme(p: string): string {
+  if (!p.startsWith('file://')) return p;
+  const rest = p.slice('file://'.length);
+  // file:///C:/x → C:/x ; file:///home/x → /home/x
+  return /^\/[A-Za-z]:/.test(rest) ? rest.slice(1) : rest;
+}
+
+function toPosix(p: string): string {
+  return p.replace(/\\/g, '/');
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/exporters/result-variants.ts

@@ -5,6 +5,7 @@
  */
 import { MergedScenario } from './scenario-merger';
 import { PlaywrightResult } from './types';
+import { maskCredentialValue } from './sensitive-key';
 
 export interface ResultVariant {
   /** Appended to the scenario display name: `''` for a plain scenario, ` — <label>` per
@@ -102,6 +103,6 @@ export function formatVariantRow(variant: ResultVariant, separator: string = '\n
   const useBullet = separator.includes('\n');
   return Object.entries(variant.row)
     .filter(([k]) => !k.startsWith('__'))
-    .map(([k, v]) => `${useBullet ? '• ' : ''}${k}: ${v}`)
+    .map(([k, v]) => `${useBullet ? '• ' : ''}${k}: ${maskCredentialValue(k, String(v))}`)
     .join(separator);
 }

package/src/exporters/sensitive-key.ts

@@ -0,0 +1,48 @@
+/**
+ * Credential-name matching shared by the delivery exporters (key-based masking, value-based
+ * redaction, the qa-env secret denylist). Kept in its own module so the test-data loader can
+ * mask a cell without importing the API formatter.
+ */
+
+/**
+ * Credential name matcher (substring, not anchored) for body-field keys and test-data keys —
+ * catches variants like confirmPassword / new_password / password_confirmation / access_token /
+ * client_secret / otp / passcode.
+ */
+export const SENSITIVE_NAME = /pass(word|code)?|passwd|pwd|secret|token|otp|api[-_]?key|apikey|credential|authorization|signature/i;
+
+/**
+ * The segment of a flattened test-data key that NAMES the value: the last dot-segment, skipping
+ * array indexes. `accounts.0.password` → `password`; `passwords.0` → `passwords`; `tokens.0.label`
+ * → `label`. Matching the whole key would treat every field under a list called `tokens` as a
+ * secret — `tokens.0.label: "New"` is a label, not a token.
+ */
+export function sensitivityKeyName(key: string): string {
+  const segments = key.split('.').filter((seg) => !/^\d+$/.test(seg));
+  return segments[segments.length - 1] ?? key;
+}
+
+/** Key path that walks into an array (`list.0.field`, `tags.0`). */
+const HAS_INDEX_SEGMENT = /(^|\.)\d+(\.|$)/;
+
+/**
+ * Is this test-data key a credential? A non-indexed key is judged as a whole, exactly as before
+ * arrays were flattened per index — `api_key.value` and `token.value` stay credentials. An indexed
+ * key is judged by the segment that names the value, so `tokens.0.label` is not one.
+ */
+export function isSensitiveKey(key: string): boolean {
+  if (SENSITIVE_NAME.test(sensitivityKeyName(key))) return true;
+  return !HAS_INDEX_SEGMENT.test(key) && SENSITIVE_NAME.test(key);
+}
+
+/** A value that still carries a raw `${QA_*}` env placeholder (nothing substituted at export time). */
+const UNRESOLVED_QA_ENV_REF = /\$\{QA_[A-Z0-9_]+\}/;
+
+/**
+ * What a Test Data cell may show for `key`: `***` for a credential-named key, else the value. An
+ * unresolved `${QA_*}` placeholder is not a value but the name of the variable the tester must
+ * set — it stays literal (also inside a composed value like `Bearer ${QA_TOKEN}`) so they can find it.
+ */
+export function maskCredentialValue(key: string, value: string): string {
+  return isSensitiveKey(key) && !UNRESOLVED_QA_ENV_REF.test(value) ? '***' : value;
+}

package/src/exporters/test-data-resolver.ts

@@ -5,6 +5,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
+import { maskCredentialValue } from './sensitive-key';
 
 /**
  * Load test-data.yaml into a flat key→value map.
@@ -12,7 +13,10 @@ import { parse as parseYaml } from 'yaml';
  *   kudos:
  *     recipient: "An"
  * become { "kudos.recipient": "An" }, matching {{kudos.recipient}} refs.
- * Arrays are JSON-stringified. Returns empty map if both files are missing.
+ * An array is kept whole as a JSON string under its own key (the `@cases` dataset
+ * reader parses it back) AND flattened per index, so `{{list.0.field}}` /
+ * `{{tags.0}}` / `{{m.0.1}}` refs resolve exactly as the compile-time resolver
+ * resolves them. Returns empty map if both files are missing.
  *
  * When `SUNGEN_ENV` is set, also merges the matching overlay file alongside
  * the base (e.g. `login.yaml` + `login.vi.yaml`). Shallow root-level merge —
@@ -89,6 +93,10 @@ function flatten(obj: Record<string, unknown>, prefix: string, out: Record<strin
     const path = prefix ? `${prefix}.${key}` : key;
     if (Array.isArray(value)) {
       out[path] = JSON.stringify(value);
+      // Per-index leaves (`list.0.field`, `tags.0`, nested `m.0.1`) — dot form only, matching
+      // the compile-time resolver; a shorter overlay list replaces the whole array, so no
+      // stale `.N` leaves survive from the base.
+      flatten(Object.fromEntries(value.map((el, i) => [String(i), el])), path, out);
     } else if (typeof value === 'object') {
       flatten(value as Record<string, unknown>, path, out);
     } else {
@@ -122,7 +130,9 @@ export function formatTestData(
   for (const key of referencedVars) {
     const value = testData[key];
     if (value === undefined) continue;
-    const line = `${key}: ${truncate(value, maxLen)}`;
+    // A credential-named key shows `***` in this cell, whatever the unit kind (the same rule the
+    // matrix data column and @cases rows apply); unresolved `${QA_*}` placeholders stay literal.
+    const line = `${key}: ${truncate(maskCredentialValue(key, value), maxLen)}`;
     pairs.push(useBullet ? `• ${line}` : line);
   }
   return pairs.join(separator);

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

@@ -239,11 +239,20 @@ export const OVERVIEW_HEADERS = ['#', 'Sheet name', 'Passed', 'Failed', 'Pending
  *
  * `Remain = Total − Passed − N/A` (i.e. Failed + Pending) so the number
  * reconciles with the "Remaining" cell in each detail sheet's summary band.
+ *
+ * Only `sheetName` and `summary` are read, so a caller that has no data rows to
+ * hand over (the matrix exporter renders its own detail sheets) passes just
+ * those two fields rather than inventing an empty `BuilderSheet`.
+ *
+ * `opts.titleLabel` / `opts.formNo` override the masthead; omitted, the title
+ * falls back to `<first sheet's screen> TESTCASE` and the form number to the
+ * builder default — which is what the legacy path has always produced.
  */
 export function addOverviewSheet(
   wb: ExcelJS.Workbook,
-  sheets: BuilderSheet[],
+  sheets: Array<Pick<BuilderSheet, 'sheetName' | 'summary'>>,
   sungenVersion?: string,
+  opts?: { titleLabel?: string; formNo?: string },
 ): void {
   const ws = wb.addWorksheet('Overview');
 
@@ -262,7 +271,12 @@ export function addOverviewSheet(
   ];
 
   const titleScreen = sheets[0]?.summary.screen ?? '';
-  renderReportHeaderBand(wb, ws, `${titleScreen.toUpperCase()} TESTCASE`, sungenVersion);
+  renderReportHeaderBand(
+    wb, ws,
+    opts?.titleLabel ?? `${titleScreen.toUpperCase()} TESTCASE`,
+    sungenVersion,
+    opts?.formNo,
+  );
 
   // Roll-up table: header on row 7, first column B (index 2).
   const HEADER_ROW = 7;

package/src/generators/gherkin-parser/index.ts

@@ -6,6 +6,7 @@ import path from 'path';
 import { SelectorResolver } from '../test-generator/utils/selector-resolver';
 import { maskRefsForMatching } from '../test-generator/utils/mask-refs-for-matching';
 import type { StateClause } from '../test-generator/patterns/types';
+import { extractParentScopeClause } from './parent-scope-clause';
 
 /**
  * Canonical state clauses, longest-first. Order is load-bearing twice over: `sorted ascending` must
@@ -13,7 +14,7 @@ import type { StateClause } from '../test-generator/patterns/types';
  * substring never misclassifies — the same hazard, and the same fix, as `qualifiedState()` in
  * driver-ui's assertion-patterns.
  */
-const STATE_CLAUSES: ReadonlyArray<StateClause> = [
+export const STATE_CLAUSES: ReadonlyArray<StateClause> = [
   'sorted ascending', 'sorted descending',
   'unchecked', 'checked',
   'hidden', 'visible', 'disabled', 'enabled', 'focused', 'empty', 'loading', 'selected',
@@ -71,7 +72,10 @@ export interface ParsedStep {
   nth?: number; // Positional index from "[Element] field 3" → 3 (0 = not specified)
   featurePath?: string; // NEW: Feature path for page type (e.g., "/", "/dashboard")
   parentRef?: string; // Parent scope reference: "in [Parent Name] parentType" → parentRef = "Parent Name"
-  parentType?: string; // Parent scope type: table, list, section, dialog, form
+  parentType?: string; // Parent scope container type — see PARENT_CONTAINER_TYPES
+  parentValueRef?: string; // Parent scoped BY CONTENT: "in [Job Card] card with {{job_title}}" → "job_title"
+  parentValueText?: string; // Same, written as a quoted literal: `… card with "Senior Dev"` → "Senior Dev"
+  unsupportedScopeType?: string; // An `in [X] <word>` clause whose <word> is no container — dropped, reported as SG-W028
   dataTable?: ParsedDataTable; // Inline data table (Cucumber DataTable syntax)
   state?: StateClause; // Trailing canonical state clause, e.g. "hidden" from "… is hidden" (drives SG-E021)
 }
@@ -231,17 +235,21 @@ export class GherkinParser {
   private parseStep(step: Messages.Step): ParsedStep {
     let text = step.text;
 
-    // === Extract parent scoping: "in [Parent Name] parentType" ===
-    // Must be extracted first so the parent [brackets] don't interfere with target selector extraction.
-    // Valid parent types: table, list, section, dialog, form
-    const parentMatch = text.match(/\s+in\s+\[([^\]]+)\]\s+(table|list|section|dialog|form)\b/i);
+    // === Extract parent scoping: "in [Parent Name] containerType [with <value>]" ===
+    // Must be extracted first so the parent [brackets] don't interfere with target selector
+    // extraction. See parent-scope-clause.ts for the container vocabulary and why an unrecognized
+    // clause is reported (SG-W028) rather than left to be absorbed into the target's tokens.
+    const { clause: parentScope, unsupportedType } = extractParentScopeClause(text);
     let parentRef: string | undefined;
     let parentType: string | undefined;
-    if (parentMatch) {
-      parentRef = parentMatch[1];
-      parentType = parentMatch[2].toLowerCase();
-      // Remove parent scoping from text so it doesn't interfere with other parsing
-      text = text.slice(0, parentMatch.index) + text.slice(parentMatch.index! + parentMatch[0].length);
+    let parentValueRef: string | undefined;
+    let parentValueText: string | undefined;
+    if (parentScope) {
+      parentRef = parentScope.ref;
+      parentType = parentScope.type;
+      parentValueRef = parentScope.valueRef;
+      parentValueText = parentScope.valueText;
+      text = parentScope.remainingText;
     }
 
     // Extract selector reference: [Email Address] or [login:email_field] (legacy)
@@ -321,6 +329,9 @@ export class GherkinParser {
       nth,
       parentRef,
       parentType,
+      parentValueRef,
+      parentValueText,
+      unsupportedScopeType: unsupportedType,
       dataTable,
       state: extractStateClause(step.text),
     };

package/src/generators/gherkin-parser/parent-scope-clause.ts

@@ -0,0 +1,130 @@
+/**
+ * The trailing scope clause — `… in [Parent] <containerType>` and its optional `with <value>` tail.
+ *
+ * Lifted out of `parseStep` because the clause failed SILENTLY (#667): the container whitelist held
+ * five types, anything else fell through, and the unmatched words stayed inline in the sentence
+ * where the first-match extractors below simply ignored them. The step compiled clean
+ * and the assertion ran against the WHOLE page instead of the named container — a test that passes
+ * for the wrong reason, findable only by diffing the generated spec against the Gherkin.
+ *
+ * So this module answers two questions, not one:
+ *   - what the clause MEANS when it is recognized (`parentRef` / `parentType` / the value tail), and
+ *   - what was DISCARDED when it is not (`unsupportedType`), so the compiler can say so (SG-W028)
+ *     instead of quietly truncating the sentence.
+ */
+
+/**
+ * Container types a step may scope into. Every one of these is something that HOLDS other elements
+ * on a page; `button`, `field`, `badge` and friends are deliberately absent — a leaf cannot be a
+ * parent, and admitting one would turn a typo into a silently wrong locator rather than a report.
+ *
+ * Ordered longest-first where one type is a prefix of another (`list-item` before `list`), because
+ * the alternation is matched left-to-right: `in [X] list-item` must not resolve as `list` with a
+ * stray `-item` left behind.
+ *
+ * `header` and `footer` are NOT here, though both hold elements. The auto-inferred fallback role
+ * for them would be the page landmarks `banner`/`contentinfo`, and a `<header>` nested inside an
+ * `<article>`/`<section>` — which is exactly how a repeating card is marked up — carries neither.
+ * That fallback would match nothing and fail for a reason unreadable from the Gherkin, so the
+ * clause is refused (SG-W028) and the author is pointed at a container type that resolves.
+ */
+export const PARENT_CONTAINER_TYPES: readonly string[] = [
+  'list-item', 'listitem', 'list',
+  'table', 'section', 'dialog', 'modal', 'drawer', 'overlay', 'form',
+  'card', 'item', 'row', 'group', 'panel', 'region', 'container',
+  'tab', 'menu',
+];
+
+const TYPES_ALT = PARENT_CONTAINER_TYPES.join('|');
+
+/** `in [Parent] <containerType>` — the clause proper, without any value tail. */
+const SCOPE_CLAUSE_BASE = new RegExp(`\\s+in\\s+\\[([^\\]]+)\\]\\s+(${TYPES_ALT})\\b`, 'i');
+
+/** The same, plus the optional `with {{v}}` / `with "text"` tail. */
+const SCOPE_CLAUSE = new RegExp(
+  `${SCOPE_CLAUSE_BASE.source}(?:\\s+with\\s+(\\{\\{[a-z0-9\\-._]+\\}\\}|"[^"]*"))?`,
+  'i',
+);
+
+/** The same shape with ANY word where a container type belongs — used only to report what was lost. */
+const SCOPE_CLAUSE_ANY_TYPE = /\s+in\s+\[([^\]]+)\]\s+([\w-]+)/i;
+
+export interface ParentScopeClause {
+  /** The `[Parent]` reference — a selectors.yaml key, or `{{var}}` naming the container's text. */
+  ref: string;
+  /** The container type, lowercased. */
+  type: string;
+  /** `{{var}}` name when the value tail scopes the parent BY CONTENT. */
+  valueRef?: string;
+  /** Quoted literal when the value tail scopes the parent by content without a variable. */
+  valueText?: string;
+  /** The sentence with the clause removed, so the target extractors never see the parent's tokens. */
+  remainingText: string;
+}
+
+/**
+ * Is the `[…]` at `clauseAt` a CONTAINER, or is it the step's own target?
+ *
+ * A scope clause narrows a target, so the target's bracket must already have appeared. Without this
+ * test, `User select {{country}} in [Country Picker] dropdown` reads its one and only target as a
+ * parent — the bracket is what the step acts ON, and the `in` is English, not grammar.
+ */
+function scopesATarget(text: string, clauseAt: number): boolean {
+  return /\[[^\]]*\]/.test(text.slice(0, clauseAt));
+}
+
+/**
+ * Does the segment before the scope clause already carry its own `with`?
+ *
+ * This is what keeps the value tail backward compatible. The documented grammar
+ * (`see [first] row in [apply list] table with {{job_name}}`) spends its single `with` on the
+ * TARGET, and re-reading that as a parent filter would silently invert the meaning of every such
+ * step already written. A SECOND `with` — `see [Tag] header with {{label}} in [Job Card] card with
+ * {{title}}` — cannot belong to the target, which already has one; only then does the tail bind to
+ * the parent. `[Ref]` contents are blanked first so a bracket like `[Filter With Tags]` is not
+ * mistaken for the keyword.
+ */
+function targetAlreadyHasValue(head: string): boolean {
+  return /\s+with\s+/i.test(head.replace(/\[[^\]]*\]/g, ''));
+}
+
+/**
+ * Extract the scope clause from a step sentence.
+ *
+ * Returns `{ clause }` when a container type was recognized, `{ unsupportedType }` when the
+ * sentence carries an `in [X] <word>` clause whose `<word>` is not a container (it is dropped, and
+ * the caller reports it), or an empty object when there is no scope clause at all.
+ */
+export function extractParentScopeClause(text: string): {
+  clause?: ParentScopeClause;
+  unsupportedType?: string;
+} {
+  const match = text.match(SCOPE_CLAUSE);
+  if (!match) {
+    const loose = text.match(SCOPE_CLAUSE_ANY_TYPE);
+    return loose && scopesATarget(text, loose.index!)
+      ? { unsupportedType: loose[2].toLowerCase() }
+      : {};
+  }
+  if (!scopesATarget(text, match.index!)) return {};
+
+  const head = text.slice(0, match.index);
+  const tail = match[3];
+  const bindsToParent = Boolean(tail) && targetAlreadyHasValue(head);
+  // A value tail the target has already claimed stays in the sentence, exactly where it was, for the
+  // target extractors to pick up — what gets consumed is then only `in [Parent] <type>`.
+  const consumedLength = bindsToParent
+    ? match[0].length
+    : match[0].match(SCOPE_CLAUSE_BASE)![0].length;
+
+  const clause: ParentScopeClause = {
+    ref: match[1],
+    type: match[2].toLowerCase(),
+    remainingText: head + text.slice(match.index! + consumedLength),
+  };
+  if (bindsToParent) {
+    if (tail!.startsWith('{{')) clause.valueRef = tail!.slice(2, -2);
+    else clause.valueText = tail!.slice(1, -1);
+  }
+  return { clause };
+}

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -8,6 +8,27 @@ export interface AuthGroup {
   scenarios: string[];
 }
 
+/**
+ * One statement of a hook block (`@beforeAll` / `@afterEach` / `@afterAll`). `wrap` → the template
+ * guards the statement with try/catch and records a failure under `label` (a JSON string literal,
+ * safe to paste into code); `stopOnFailure` → a failure also ends the hook right there (action
+ * steps: later steps would run on state the failed action never produced). A plain step runs
+ * unwrapped and throws as before.
+ */
+export interface HookStep {
+  comment?: string;
+  code: string;
+  wrap?: boolean;
+  stopOnFailure?: boolean;
+  label?: string;
+}
+
+/** Hook block render input. `collect` → declare the failure list and end with the fail-once guard. */
+export interface HookRenderData {
+  steps: HookStep[];
+  collect?: boolean;
+}
+
 export interface TestFileData {
   imports: string;
   featureName: string;
@@ -79,6 +100,7 @@ export interface RenderImportsOptions {
   needsMock?: boolean;
   urlAssertImports?: string;
   regexEscapeImport?: boolean;
+  checkedStateImports?: string;
 }
 
 export interface TestGeneratorAdapter {
@@ -91,9 +113,9 @@ export interface TestGeneratorAdapter {
   renderScenario(data: ScenarioData): string;
   renderImports(options?: RenderImportsOptions): string;
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
-  renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
-  renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
-  renderAfterAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
+  renderBeforeAll(data: HookRenderData): string;
+  renderAfterEach(data: HookRenderData): string;
+  renderAfterAll(data: HookRenderData): string;
 
   // Step rendering
   renderStep(templateName: string, data: any): string;

package/src/generators/test-generator/adapters/appium/appium-adapter.ts

@@ -1,5 +1,5 @@
 import path from 'path';
-import { TestGeneratorAdapter, TestFileData, ScenarioData, RenderImportsOptions } from '../adapter-interface';
+import { TestGeneratorAdapter, TestFileData, ScenarioData, RenderImportsOptions, HookRenderData } from '../adapter-interface';
 import { TemplateEngine } from '../../template-engine';
 
 /**
@@ -39,15 +39,15 @@ export class AppiumAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderBeforeEach(data);
   }
 
-  renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string {
+  renderBeforeAll(data: HookRenderData): string {
     return this.templateEngine.renderBeforeAll(data);
   }
 
-  renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string {
+  renderAfterEach(data: HookRenderData): string {
     return this.templateEngine.renderAfterEach(data);
   }
 
-  renderAfterAll(data: { steps: Array<{ comment?: string; code: string }> }): string {
+  renderAfterAll(data: HookRenderData): string {
     return this.templateEngine.renderAfterAll(data);
   }