@sun-asterisk/sungen 3.2.18 → 3.2.19

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

@@ -20,12 +20,18 @@
  *   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
+ *   SG-W011 — a storage assertion written in `expect … in local/session storage` form:
+ *             `expect` steps only read `{{response}}` refs, so this compiles to a silent
+ *             no-op — the supported grammar is `User see [KEY] in local storage exists/…`
+ *   SG-W012 — a mock-install step AFTER a navigation step in the same block: page.route()
+ *             registered after goto() misses every request fired during page load — move
+ *             the install before the navigation (or into Background)
  *
  * 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' | 'SG-W010';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012';
 
 export interface Diagnostic {
   code: DiagnosticCode;

package/src/generators/test-generator/recipe-expander.ts

@@ -21,7 +21,7 @@
 export interface RecipeExpandContext {
   /** Pre-rendered locator code for the widget element (dialog/frame scoping included). */
   triggerCode: string;
-  /** The step's value — a literal or a __SUNGEN_TD__ runtime marker. */
+  /** The step's value — a literal or a __SUNGEN_TD$…$__ runtime marker. */
   value: string;
 }
 
@@ -53,7 +53,7 @@ function expandPrimitive(prim: unknown, ctx: RecipeExpandContext, itemVar: strin
   const targetExpr = (v: unknown): string =>
     v === '$trigger' ? ctx.triggerCode : `page.locator('${escape(String(v))}')`;
   // Resolve a `$value`/`$item`/literal into a JS value EXPRESSION (quoted unless $item;
-  // a quoted __SUNGEN_TD__ marker is rewritten to testData.get(...) by the runtime transform).
+  // a quoted __SUNGEN_TD$…$__ marker is rewritten to testData.get(...) by the runtime transform).
   const valueExpr = (v: unknown): string => {
     if (v === '$item') {
       if (!itemVar) throw new Error('$item is only valid inside forEach');

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

@@ -43,6 +43,8 @@ export class StepMapper {
   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;
+  /** SG-W012: a navigation already ran in this scenario (mocks installed after it miss page-load requests) */
+  private sawNavigationStep: boolean = false;
   /** Compile-time warning channel (SG-W001/W002); optional — absent means silent legacy behavior */
   private diagnostics?: DiagnosticsCollector;
   /** App profile (qa/app.yaml merged over presets/defaults) — the per-project BEHAVIOR layer */
@@ -91,6 +93,14 @@ export class StepMapper {
     this.featureName = featureName;
     this.featurePath = featurePath;
     this.selectorResolver.setFeatureContext(featureName);
+    // One StepMapper serves every feature in a run, so the step counter that names the
+    // generated temporaries (`__t_<n>`) used to carry over between files: a screen's spec
+    // then depended on how many steps the PRECEDING files happened to contain — i.e. on
+    // readdir order and on whether the run was `--all` or `--screen`. Same input, different
+    // output, which is exactly what a deterministic compiler must not do (and what made a
+    // multi-feature screen report permanent false DRIFT in script-check). The counter only
+    // needs to be unique WITHIN one spec file, so it restarts with each feature.
+    this.stepCounter = 0;
   }
 
   /**
@@ -137,6 +147,7 @@ export class StepMapper {
     this.tableRowScopeSteps = steps.filter((s) => this.isRowScopeEntryStep(s)).length;
     this.tableRowDeclared = false;
     this.sawActionStep = false;
+    this.sawNavigationStep = false;
     this.lastPrimaryKeyword = 'Given';
     this.dataResolver.clearCaptured(); // captured vars are scenario-scoped
     this.templateEngine.resetBaseContext();
@@ -181,6 +192,20 @@ export class StepMapper {
       this.sawActionStep = true;
     }
 
+    // A mock must be routed BEFORE the navigation whose requests it should intercept —
+    // page.route() registered after goto() misses everything fired during page load
+    // (mirror of the late-alert-listener check above). Background installs compile
+    // into beforeEach, before any scenario step, so they never trip this.
+    const isMockInstallStep = /\[[^\]]+\]\s+mock\s+is\s+active\b/i.test(step.text);
+    if (isMockInstallStep && this.sawNavigationStep) {
+      this.diagnostics?.add('SG-W012',
+        'mock installed AFTER a navigation step — requests fired during page load were not intercepted. Move the mock step before the navigation, or declare it in Background',
+        { feature: this.featureName, step: step.text });
+    } else if (!isMockInstallStep && step.elementType === 'page' &&
+      /\b(?:is on|navigates?\s+to|opens?)\b/i.test(step.text)) {
+      this.sawNavigationStep = true;
+    }
+
     // Frame scope directives — intercept before pattern matching
     if (/\bswitch(?:es)?\s+to\b/i.test(step.text) &&
         (step.elementType === 'frame' || step.elementType === 'iframe')) {
@@ -221,7 +246,14 @@ export class StepMapper {
     // Given User is on [...] dialog — set dialog scope (3 cases)
     if (step.text.includes('is on') && step.elementType === 'dialog') {
       this.inDialogScope = true;
-      const contextVars: Record<string, any> = { inDialog: true };
+      // setBaseContext MERGES — clear every root key so a previous dialog scope in the
+      // same scenario cannot leak its root into this one.
+      const contextVars: Record<string, any> = {
+        inDialog: true,
+        dialogRootExpr: undefined,
+        dialogRoleName: undefined,
+        dialogFilterText: undefined,
+      };
 
       if (step.selectorRef && step.dataRef) {
         // Case 3: [panel] dialog with {{value}}
@@ -234,16 +266,18 @@ export class StepMapper {
           filterText = `\${${step.dataRef}}`;
         }
         contextVars.dialogFilterText = filterText;
+        // The declared entry still owns the ROOT the filter applies to — but only when it
+        // is a non-role strategy (locator/testid/css). A role entry keeps the bare
+        // getByRole('dialog') base on purpose here: the name is dynamic, hence the filter.
+        const rootExpr = this.renderDialogRoot(step.selectorRef, { nonRoleOnly: true });
+        if (rootExpr) contextVars.dialogRootExpr = rootExpr;
       } else if (step.selectorRef) {
-        // Case 2: [Title] dialog → named dialog role
-        let roleName = step.selectorRef;
-        try {
-          const resolved = this.selectorResolver.resolveSelector(step.selectorRef, this.featureName, 'dialog', 0);
-          roleName = resolved.name || step.selectorRef;
-        } catch {
-          roleName = step.selectorRef;
-        }
-        contextVars.dialogRoleName = roleName;
+        // Case 2: [Title] dialog → the root the DECLARED selectors.yaml entry asks for
+        // (issue: an explicit `type: locator` / `value: '[role="dialog"]'` was being
+        // discarded in favour of getByRole('dialog', { name: <reference text> })).
+        const rootExpr = this.renderDialogRoot(step.selectorRef);
+        if (rootExpr) contextVars.dialogRootExpr = rootExpr;
+        else contextVars.dialogRoleName = step.selectorRef;
       }
       // Case 1: no selectorRef → plain page.getByRole('dialog')
 
@@ -303,16 +337,69 @@ export class StepMapper {
     }
 
     // No pattern matched - return TODO comment
-    this.diagnostics?.add('SG-W001', 'step matched no pattern — compiled to a no-op // TODO comment', {
-      feature: this.featureName,
-      step: step.text,
-    });
+    if (/\bexpect\b.*\b(?:local|session)\s+storage\b/i.test(step.text)) {
+      // The natural first guess for a storage check — but `expect` steps only read
+      // {{response}} refs, so this shape silently compiles to nothing. Point at the
+      // supported grammar instead of emitting the generic no-pattern warning.
+      this.diagnostics?.add('SG-W011',
+        'storage assertions use `User see [KEY] in local storage exists` (also: does not exist / is not empty / has length {{n}} / key matching "PATTERN") — the `expect …` form compiles to a no-op', {
+        feature: this.featureName,
+        step: step.text,
+      });
+    } else {
+      this.diagnostics?.add('SG-W001', 'step matched no pattern — compiled to a no-op // TODO comment', {
+        feature: this.featureName,
+        step: step.text,
+      });
+    }
     return {
       code: `// TODO: Implement step: ${step.text}`,
       comment: `Unrecognized step pattern: ${step.text}`,
     };
   }
 
+  /** Strategies the `locator` partial renders into a usable ROOT expression. Anything else
+   *  (mobile native strategies) has no meaning as a Playwright dialog root. */
+  private static readonly DIALOG_ROOT_STRATEGIES = ['locator', 'testid', 'role', 'id', 'label', 'text', 'placeholder'];
+
+  /**
+   * Render the Playwright root expression for `Given User is on [X] dialog` from the entry
+   * DECLARED in selectors.yaml, through the same `locator` partial every other step renders
+   * with — so `type: locator`, `type: testid`, a non-`dialog` role, `name: null`, `exact:`
+   * and `nth:` mean here exactly what they mean everywhere else. Before this, the entry was
+   * read for its `name` only and the root was hardcoded to getByRole('dialog', { name }),
+   * silently discarding an explicit `type: locator` / `value: '[role="dialog"]'`.
+   *
+   * Returns undefined when the reference does not resolve to a usable root — the caller then
+   * falls back to the legacy named-dialog root, so behavior is unchanged for those entries.
+   */
+  private renderDialogRoot(selectorRef: string, opts: { nonRoleOnly?: boolean } = {}): string | undefined {
+    let resolved: any;
+    try {
+      resolved = this.selectorResolver.resolveSelector(selectorRef, this.featureName, 'dialog', 0);
+    } catch {
+      return undefined;
+    }
+    if (!resolved) return undefined;
+
+    // `type: role` + a `locator:` field collapses to strategy 'css', which the locator partial
+    // has no case for — normalize it to the raw-locator strategy it actually means.
+    if (resolved.strategy === 'css' && resolved.locator) {
+      resolved = { ...resolved, strategy: 'locator', value: resolved.locator };
+    }
+    if (!StepMapper.DIALOG_ROOT_STRATEGIES.includes(resolved.strategy)) return undefined;
+    if (opts.nonRoleOnly && resolved.strategy === 'role') return undefined;
+
+    // Render the root PAGE-rooted: leaving inDialog set (or `scope: dialog` on the entry
+    // itself) would send the partial back through dialog-root and nest the dialog in itself.
+    const expr = this.templateEngine.renderStep('locator', {
+      ...resolved,
+      scope: resolved.scope === 'dialog' ? undefined : resolved.scope,
+      inDialog: false,
+    }).trim();
+    return expr || undefined;
+  }
+
   /**
    * SG-W002 — a step carried a parsed {{dataRef}} but the matched pattern's generated
    * code never uses it (neither the runtime marker, the ${ref} fallback, nor the
@@ -323,7 +410,11 @@ export class StepMapper {
   private checkDataRefConsumed(step: ParsedStep, mapped: MappedStep): void {
     if (!step.dataRef || !this.diagnostics) return;
     const code = mapped.code || '';
-    if (code.includes(DataResolver.encodeMarker(step.dataRef))) return; // runtime marker
+    // Runtime marker — in both spellings: templates that embed the value into a regex
+    // literal run it through the escapeRegex helper, which escapes the marker's `$`
+    // delimiters, so the code may carry `__SUNGEN_TD\$key\$__` instead of the plain form.
+    const marker = DataResolver.encodeMarker(step.dataRef);
+    if (code.includes(marker) || code.includes(marker.replace(/\$/g, '\\$'))) return;
     if (code.includes(`\${${step.dataRef}}`)) return;                    // unresolved fallback
     if (code.includes(step.dataRef)) return;                             // testData.set('ref'), comments
     try {

package/src/generators/test-generator/template-engine.ts

@@ -277,8 +277,8 @@ export class TemplateEngine {
     this.baseContext = { ...this.persistentContext };
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi });
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string {
+    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi, needsMock: options?.needsMock });
   }
 
   renderTestFile(data: {

package/src/generators/test-generator/utils/data-resolver.ts

@@ -112,12 +112,15 @@ export class DataResolver {
     return { fileName: parts[0], valuePath: parts.slice(1) };
   }
 
+  /**
+   * Encode a test-data ref as an opaque wire marker: `__SUNGEN_TD$<key>$__`,
+   * dots escaped to `_D_`. `$` delimiters keep the key boundary unambiguous
+   * when the surrounding text continues with underscores (`{{code}}_SUFFIX`)
+   * while the marker stays a single JS-identifier-safe token. This is the ONLY
+   * producer; the only decoder lives in runtime-data-transformer.ts.
+   */
   static encodeMarker(ref: string): string {
-    return `__SUNGEN_TD_${ref.replace(/\./g, '_D_')}__`;
-  }
-
-  static decodeMarker(encoded: string): string {
-    return encoded.replace(/^__SUNGEN_TD_/, '').replace(/__$/, '').replace(/_D_/g, '.');
+    return `__SUNGEN_TD$${ref.replace(/\./g, '_D_')}$__`;
   }
 
   /**

package/src/generators/test-generator/utils/runtime-data-transformer.ts

@@ -1,8 +1,54 @@
-const MARKER_PATTERN = /__SUNGEN_TD_([A-Za-z0-9_]+)__/;
+/**
+ * Wire format of a runtime test-data marker: `__SUNGEN_TD$<key>$__`.
+ *
+ * `$` delimits the encoded key on both sides. The key alphabet is [A-Za-z0-9_]
+ * (dots in refs are escaped to `_D_` by DataResolver.encodeMarker), so a `$`
+ * can never occur INSIDE a key — the `$__` terminator stays unambiguous even
+ * when the surrounding literal continues with underscore text. The previous
+ * `__SUNGEN_TD_<key>__` format could not tell its `__` terminator apart from a
+ * `_`-leading suffix: in `'{{code}}_ACCESS_TOKEN'` the greedy key class
+ * swallowed one `_` of the `___` run and decoding produced `get('code_')` plus
+ * a detached `ACCESS_TOKEN`. `$` is also identifier-safe — the whole marker
+ * still parses as ONE bare JS token, so it survives the bare-identifier
+ * (numeric) positions Pass 3 handles.
+ *
+ * Single source of truth: every pass and every whole-literal probe below is
+ * built from these constants. Invariant: every marker producer goes through
+ * DataResolver.encodeMarker and every consumer through this module — a
+ * drifting hand-copied char class is what let the suffix bug hide.
+ */
+const MARKER_KEY = '[A-Za-z0-9_]+';
+// Templates that embed a value into a regex literal run it through the escapeRegex
+// Handlebars helper first (template-engine.ts), which escapes `$` — so a marker can
+// arrive here spelled `__SUNGEN_TD\$key\$__`. `\\\\?` accepts that optional backslash
+// before each delimiter; the replacement consumes it, so no escape leaks to output.
+const DELIM = '\\\\?\\$';
+/** Marker with no capture group — for "contains a marker" positions inside bigger regexes. */
+const MARKER = `__SUNGEN_TD${DELIM}${MARKER_KEY}${DELIM}__`;
+/** Marker capturing the encoded key. */
+const MARKER_CAP = `__SUNGEN_TD${DELIM}(${MARKER_KEY})${DELIM}__`;
+
+const MARKER_PATTERN = new RegExp(MARKER);
+// Pass 0: full-line // comments carrying a marker (anchored — see pass comment).
+const RE_COMMENT_LINE = new RegExp(`^(\\s*)\\/\\/(.*)${MARKER_CAP}(.*)$`, 'gm');
+// Pass 1: a quoted string literal containing at least one marker. Covers ', " and
+// backtick containers; `\\.` lets an ESCAPED quote (`'it\'s {{x}}'`) sit inside the
+// body instead of terminating the literal early. The single-char branch excludes `\`
+// so every backslash is consumed by exactly ONE branch — an ambiguous `(?!\1).`
+// alternative enumerates 2^n segmentations when a marker-less escape-heavy literal
+// (escapeQuotes output: multi-line Flutter content-desc) fails to match, hanging
+// the generate run. `\n` exclusion just makes the dot's no-newline behavior explicit.
+const RE_STRING_LITERAL = new RegExp('([\'"`])((?:\\\\.|(?!\\1)[^\\\\\\n])*?' + MARKER + '(?:\\\\.|(?!\\1)[^\\\\\\n])*)\\1', 'g');
+// Pass 2: a single-line regex literal containing at least one marker.
+const RE_REGEX_LITERAL = new RegExp(`\\/((?:[^/\\\\\\n]|\\\\.)*?${MARKER}(?:[^/\\\\\\n]|\\\\.)*)\\/([gimsuy]*)`, 'g');
+// Whole-literal probe: the body is EXACTLY one marker (bare accessor call, no template).
+const RE_WHOLE_MARKER = new RegExp(`^${MARKER_CAP}$`);
+// Every marker occurrence, capturing the key (Pass 3 + interpolation).
+const RE_MARKER_G = new RegExp(MARKER_CAP, 'g');
 
 /**
- * Replace __SUNGEN_TD_ markers with testData.get() calls in generated code.
- * Three passes: comments, string literals, then regex literals.
+ * Replace __SUNGEN_TD$…$__ markers with testData.get() calls in generated code.
+ * Four passes: comments, string literals, regex literals, then bare identifiers.
  */
 export function transformToRuntimeData(code: string, accessor: string = 'testData'): string {
   // Pass 0: Comments — replace markers in // comments with decoded key name.
@@ -14,7 +60,7 @@ export function transformToRuntimeData(code: string, accessor: string = 'testDat
   // testData.get() (silent: `toHaveAttribute('href', 'official_site_url')`). Generated
   // comments are always full-line, so anchoring loses nothing.
   code = code.replace(
-    /^(\s*)\/\/(.*)__SUNGEN_TD_([A-Za-z0-9_]+)__(.*)$/gm,
+    RE_COMMENT_LINE,
     (_, indent, before, enc, after) => `${indent}//${before}${decodeKey(enc)}${after}`
   );
 
@@ -30,22 +76,22 @@ export function transformToRuntimeData(code: string, accessor: string = 'testDat
   // 'marker'          → testData.get('key')
   // 'a__m1__b__m2__c' → `a${testData.get('k1')}b${testData.get('k2')}c`
   code = code.replace(
-    /(['"])((?:(?!\1).)*?__SUNGEN_TD_[A-Za-z0-9_]+__(?:(?!\1).)*)\1/g,
+    RE_STRING_LITERAL,
     (_, _quote, body) => {
-      const whole = /^__SUNGEN_TD_([A-Za-z0-9_]+)__$/.exec(body);
+      const whole = RE_WHOLE_MARKER.exec(body);
       if (whole) return `${accessor}.get('${decodeKey(whole[1])}')`;
       return `\`${interpolateMarkers(body, accessor)}\``;
     }
   );
 
-  // Pass 2: Regex literal context — /…__marker__…/ → new RegExp(`…`). Same
+  // Pass 2: Regex literal context — /…$marker$…/ → new RegExp(`…`). Same
   // several-markers-per-literal rule as Pass 1 (/{{min}}-{{max}} items/).
   // Only matches within a single line (no newlines in the body).
   code = code.replace(
-    /\/((?:[^/\\\n]|\\.)*?__SUNGEN_TD_[A-Za-z0-9_]+__(?:[^/\\\n]|\\.)*)\/([gimsuy]*)/g,
+    RE_REGEX_LITERAL,
     (_, body, flags) => {
       const flagStr = flags ? `, '${flags}'` : '';
-      const whole = /^__SUNGEN_TD_([A-Za-z0-9_]+)__$/.exec(body);
+      const whole = RE_WHOLE_MARKER.exec(body);
       if (whole) return `new RegExp(${accessor}.get('${decodeKey(whole[1])}')${flagStr})`;
       return `new RegExp(\`${interpolateMarkers(body, accessor)}\`${flagStr})`;
     }
@@ -55,7 +101,7 @@ export function transformToRuntimeData(code: string, accessor: string = 'testDat
   // sits as a bare token in a numeric position (e.g. `toHaveCount(__marker__)` from the
   // table/list count templates). testData.get() returns a string, so coerce with Number().
   code = code.replace(
-    /__SUNGEN_TD_([A-Za-z0-9_]+)__/g,
+    RE_MARKER_G,
     (_, enc) => `Number(${accessor}.get('${decodeKey(enc)}'))`
   );
 
@@ -72,5 +118,5 @@ function decodeKey(encoded: string): string {
 
 /** Replace every marker in a literal's body with a `${accessor.get('key')}` interpolation. */
 function interpolateMarkers(body: string, accessor: string): string {
-  return body.replace(/__SUNGEN_TD_([A-Za-z0-9_]+)__/g, (_, enc) => `\${${accessor}.get('${decodeKey(enc)}')}`);
+  return body.replace(RE_MARKER_G, (_, enc) => `\${${accessor}.get('${decodeKey(enc)}')}`);
 }

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -56,6 +56,23 @@ interface SelectorEntry {
   };
 }
 
+/**
+ * Roles whose accessible name comes from their own CONTENT, not from a label — so a name the
+ * compiler invented from the `[Reference]` text can never match a real element.
+ *
+ * The `name:` key is defaulted to the Gherkin reference when an entry omits it, which is right for
+ * label-named roles (button/link/textbox) and wrong for these. Left unchecked it compiles to
+ * `getByRole('option', { name: 'Shop Item' })` — zero elements — and `toBeHidden()` PASSES on an
+ * empty locator, so the scenario goes green without ever testing anything.
+ *
+ * The rule lives HERE, at the point the name is invented, rather than in each consumer: it used to
+ * be enforced in exactly one of the branches that read `resolved.name`, and every other branch
+ * (`is hidden`, `is disabled`) silently kept the bogus filter.
+ *
+ * An EXPLICIT `name:` in selectors.yaml is always honoured — the user knows their DOM.
+ */
+export const LIST_MEMBER_ROLES = new Set(['listitem', 'option', 'cell']);
+
 // New selector file structure: flat key-value pairs
 type SelectorFile = Record<string, SelectorEntry>;
 
@@ -275,7 +292,9 @@ export class SelectorResolver {
       'list': () => ({ strategy: 'role', role: 'list', name: label, value: 'list' }),
       'listitem': () => ({ strategy: 'role', role: 'listitem', value: 'listitem' }),
       'searchbox': () => ({ strategy: 'role', role: 'searchbox', name: label, value: 'searchbox' }),
-      'option': () => ({ strategy: 'role', role: 'option', name: label, value: 'option' }),
+      // no `name` — a list-member role names itself from its content (see LIST_MEMBER_ROLES);
+      // `listitem` already omitted it, `option`/`cell` used to disagree.
+      'option': () => ({ strategy: 'role', role: 'option', value: 'option' }),
       'slider': () => ({ strategy: 'role', role: 'slider', name: label, value: 'slider' }),
       'switch': () => ({ strategy: 'role', role: 'switch', name: label, value: 'switch' }),
       'tab': () => ({ strategy: 'role', role: 'tab', name: label, value: 'tab' }),
@@ -286,7 +305,7 @@ export class SelectorResolver {
       'progressbar': () => ({ strategy: 'role', role: 'progressbar', name: label, value: 'progressbar' }),
       'region': () => ({ strategy: 'role', role: 'region', name: label, value: 'region' }),
       'article': () => ({ strategy: 'role', role: 'article', name: label, value: 'article' }),
-      'cell': () => ({ strategy: 'role', role: 'cell', name: label, value: 'cell' }),
+      'cell': () => ({ strategy: 'role', role: 'cell', value: 'cell' }),
       'status': () => ({ strategy: 'role', role: 'status', name: label, value: 'status' }),
       'navigation': () => ({ strategy: 'role', role: 'navigation', name: label, value: 'navigation' }),
     };
@@ -491,8 +510,8 @@ export class SelectorResolver {
    * Replace {{variable}} references in selector values with runtime data markers.
    * This enables i18n: selectors can reference locale-dependent text from test-data.
    *
-   * "{{lbl_submit}}" → "__SUNGEN_TD_lbl_submit__"
-   * "Hello {{name}}" → "Hello __SUNGEN_TD_name__"
+   * "{{lbl_submit}}" → "__SUNGEN_TD$lbl_submit$__"
+   * "Hello {{name}}" → "Hello __SUNGEN_TD$name$__"
    * "No variables"   → "No variables" (unchanged)
    */
   private static resolveTemplateVars(value: string): string {
@@ -517,7 +536,12 @@ export class SelectorResolver {
     // Explicit `name: null` in YAML is a deliberate opt-out (e.g. a role selector that must NOT
     // filter by accessible name); it must not be conflated with "unset". The role template omits
     // `{ name }` when this resolves to a falsy value.
-    const rawName = entry.name === undefined ? originalLabel : (entry.name ?? '');
+    // A list-member role gets NO defaulted name — see LIST_MEMBER_ROLES. `type` is the entry's
+    // declared kind and `rawValue` the role, so the check reads the entry, not a resolved shape.
+    const defaultsNameFromLabel = !(type === 'role' && LIST_MEMBER_ROLES.has(String(rawValue)));
+    const rawName = entry.name === undefined
+      ? (defaultsNameFromLabel ? originalLabel : '')
+      : (entry.name ?? '');
     const value = SelectorResolver.resolveTemplateVars(rawValue);
     const name = SelectorResolver.resolveTemplateVars(rawName);
     const nth = entry.nth !== undefined && entry.nth !== null ? entry.nth : undefined;

package/src/harness/audit.ts

@@ -8,9 +8,9 @@
  */
 import * as path from 'path';
 import * as fs from 'fs';
-import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
+import { loadUnitScenarios, readUnitFeatureText, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import { checkViewpointBaseline, ViewpointBaseline } from './viewpoint-baseline';
-import { featureBasename } from './unit-paths';
+import { featureFilesFor } from './unit-paths';
 import {
   loadCatalog, viewpointGate, assertionDepth, dataThemesFor, depthThresholdFor, coverageBalance, duplicateClusters, traceability, claimProof, taxonomyLint,
   automatableManual, flowCoveredThemes, flowRegressionDepth, oracleStrength,
@@ -117,9 +117,10 @@ export function seniorBandedOverall(
 }
 
 export function runAudit(screenDir: string, screenName: string): AuditReport {
-  // The feature filename is the unit's LAST segment — an api flow (`flows/<flow>`) lives at
-  // `<dir>/features/<flow>.feature`, not `features/flows/<flow>.feature` (which found 0 scenarios).
-  const featurePath = path.join(screenDir, 'features', `${featureBasename(screenName)}.feature`);
+  // A unit is a DIRECTORY of features — `add --feature` puts sub-features beside the canonical
+  // one, and they all count. `featureFiles[0]` is that canonical `<basename>.feature` (an api
+  // flow `flows/<flow>` lives at `<dir>/features/<flow>.feature`, not `features/flows/…`).
+  const featureFiles = featureFilesFor(screenDir, screenName);
   const viewpointPath = path.join(screenDir, 'requirements', 'test-viewpoint.md');
   // Catalog-resolution id (for the @api/@query gate sensors): the unit's path relative to qa/ —
   // `flows/<flow>`, `api/<area>`, `api/flows/<flow>`, else the bare screen. A bare screen matches
@@ -127,9 +128,9 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   const catalogScreenName = catalogIdFromScreenDir(screenDir);
 
   const specPath = path.join(screenDir, 'requirements', 'spec.md');
-  const featureText = fs.existsSync(featurePath) ? readTextFile(featurePath) : '';
+  const featureText = readUnitFeatureText(screenDir, screenName);
 
-  const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
+  const scenarios: ScenarioInfo[] = loadUnitScenarios(screenDir, screenName);
   const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
   // AO-1 — capability-routed scoring: the viewpoint catalog + score-bearing gate are owned by the
   // unit's capability, resolved from the unit id (`api/<area>` → `api`; screen/flow → the default
@@ -390,14 +391,14 @@ export function runAudit(screenDir: string, screenName: string): AuditReport {
   }
   // TQ-9 — manual reason-code mismatch: an explicit @manual:Mx that disagrees with the reason
   // text makes the capability planner recommend the wrong driver. Surface it so the code is fixed.
-  for (const mm of manualReasonMismatches(featurePath).slice(0, 8)) {
+  for (const mm of featureFiles.flatMap(manualReasonMismatches).slice(0, 8)) {
     const label = MANUAL_REASONS[mm.inferred]?.label ?? (mm.inferred === 'XS' ? 'Cross-screen (→ flow)' : mm.inferred);
     findings.push(`MANUAL-REASON-MISMATCH: "${mm.scenario}" is tagged @manual:${mm.explicit} but its reason reads as ${mm.inferred} (${label}) → fix the code so \`sungen capability plan\` recommends the right driver to automate it.`);
   }
   // TQ-10 — surface the Capability Planner recommendation (recommend-only; never installs). Silenced
   // by `capability_suggestions: off` in qa/context.md. Reuses the planner (trustworthy after TQ-9).
   if (intent.capabilitySuggestions) {
-    const plan = buildPlan(screenDir, featureBasename(screenName));
+    const plan = buildPlan(screenDir, screenName);
     if (plan.recommendations.length) {
       const recs = plan.recommendations.map((r) => `\`sungen capability add ${r.driver}\` (automates ${r.count})`).join(' · ');
       findings.push(`CAPABILITY-SUGGESTION: ${plan.capabilityManual} @manual scenario(s) are capability-manual (a driver could automate them) — ${recs}. Recommend-only: nothing is installed automatically; the ${plan.judgmentManual} judgment-manual (M6/M8/M9) correctly stay manual.`);

package/src/harness/capability-plan.ts

@@ -10,6 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { loadDriverCatalog } from './capability';
 import { readTextFile } from './read-text';
+import { featureFilesFor } from './unit-paths';
 
 export type ReasonClass = 'capability' | 'keep' | 'flow';
 export interface ReasonDef { code: string; label: string; cls: ReasonClass; drivers: string[] }
@@ -193,8 +194,7 @@ export interface CapabilityPlan {
 }
 
 export function buildPlan(screenDir: string, screenName: string): CapabilityPlan {
-  const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
-  const scenarios = parseScenarios(featurePath);
+  const scenarios = featureFilesFor(screenDir, screenName).flatMap(parseScenarios);
   const catalog = loadDriverCatalog();
 
   const modes: Record<string, number> = {};

package/src/harness/catalog/drivers.yaml

@@ -58,7 +58,7 @@ drivers:
   mock:
     kind: capability
     package: "@sungen/driver-mock"
-    status: planned
+    status: shipped
     capabilities: ["@mock", "@network"]
     unblocks: [M3]
   mail-file:

package/src/harness/challenge.ts

@@ -18,7 +18,7 @@
  * The AI agent layer adds the semantic + novelty judgement on top of this spine.
  */
 import * as path from 'path';
-import { loadScenarios, ScenarioInfo } from './parse';
+import { loadUnitScenarios, ScenarioInfo } from './parse';
 import { runAudit } from './audit';
 
 export interface ChallengeFinding {
@@ -63,8 +63,7 @@ const NOVELTY_LENSES = [
 ];
 
 export function buildChallenge(screenDir: string, screenName: string): ChallengeReport {
-  const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
-  const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
+  const scenarios: ScenarioInfo[] = loadUnitScenarios(screenDir, screenName);
   const audit = runAudit(screenDir, screenName);
 
   // 1. Coverage critic — over-covered buckets (secondary >> business-core) + shallow themes.

package/src/harness/data-driven-lint.ts

@@ -8,6 +8,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { featureFilesFor } from './unit-paths';
 import { parse as parseYaml } from 'yaml';
 import { GherkinParser, ParsedScenario } from '../generators/gherkin-parser';
 import { resolveQuery, lintCatalog } from './query-catalog';
@@ -44,15 +45,18 @@ export function lintDataDriven(screenDir: string, cwd: string = process.cwd()):
   const base = path.basename(screenDir);
   const isFlow = path.basename(path.dirname(screenDir)) === 'flows';
   const screenName = isFlow ? `flows/${base}` : base;
-  const featurePath = path.join(screenDir, 'features', `${base}.feature`);
-  if (!fs.existsSync(featurePath)) return [];
-
-  let scenarios: ParsedScenario[];
-  try {
-    scenarios = new GherkinParser().parseFeatureFile(featurePath).scenarios || [];
-  } catch {
-    return [];
-  }
+  // Every `.feature` of the unit — `add --feature` sub-features lint too. A file that
+  // fails to parse contributes nothing rather than voiding the whole unit's lint.
+  const scenarios: ParsedScenario[] = featureFilesFor(screenDir, base)
+    .filter((p) => fs.existsSync(p))
+    .flatMap((p) => {
+      try {
+        return new GherkinParser().parseFeatureFile(p).scenarios || [];
+      } catch {
+        return [];
+      }
+    });
+  if (scenarios.length === 0) return [];
 
   const tdPath = path.join(screenDir, 'test-data', `${base}.yaml`);
   const td: Record<string, any> = tdPath && fs.existsSync(tdPath) ? parseYaml(fs.readFileSync(tdPath, 'utf8')) || {} : {};

package/src/harness/depth-lint.ts

@@ -13,7 +13,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { loadScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
+import { loadUnitScenarios, parseViewpointOverview, ScenarioInfo, ViewpointEntry } from './parse';
 import { loadCatalog, viewpointGate, assertionDepth, dataThemesFor, CatalogTheme } from './sensors';
 
 export type DepthAction = 'deepen' | 'defer';
@@ -50,11 +50,9 @@ function matchTheme(s: ScenarioInfo, dataThemes: CatalogTheme[]): CatalogTheme |
 }
 
 export function runDepthLint(screenDir: string, screenName: string, focus = 'functional'): DepthLintReport {
-  const last = screenName.split('/').pop() || screenName;
-  const featurePath = path.join(screenDir, 'features', `${last}.feature`);
   const viewpointPath = path.join(screenDir, 'requirements', 'test-viewpoint.md');
 
-  const scenarios: ScenarioInfo[] = loadScenarios(featurePath);
+  const scenarios: ScenarioInfo[] = loadUnitScenarios(screenDir, screenName);
   const viewpoints: ViewpointEntry[] = parseViewpointOverview(viewpointPath);
   const catalog = loadCatalog();
   const gate = viewpointGate(scenarios, viewpoints, catalog);