@sun-asterisk/sungen 3.1.0 → 3.1.2

package/src/cli/commands/generate.ts

@@ -4,6 +4,7 @@ import * as fs from 'fs';
 import { CodeGenerator } from '../../generators/test-generator/code-generator';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 import { scanTestDataSecrets } from '../../harness/secret-scan';
+import { lintDataDriven } from '../../harness/data-driven-lint';
 import { readCapabilities, writeCapabilities, driverMeta, loadDriverCatalog } from '../../harness/capability';
 
 /**
@@ -182,6 +183,13 @@ export function registerGenerateCommand(program: Command): void {
           console.log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.`);
         }
 
+        // Data-driven lint (@cases / @query) — advisory, never blocks generation.
+        const ddWarnings = scanDirs.flatMap((d) => lintDataDriven(d, cwd));
+        if (ddWarnings.length) {
+          console.log(`\n⚠️  Data-driven lint (@cases / @query) — review:`);
+          for (const w of ddWarnings.slice(0, 20)) console.log(`   ${w.scenario ? w.scenario + ': ' : ''}${w.message}`);
+        }
+
         console.log(`Next step: npx playwright test --ui\n`);
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);

package/src/exporters/csv-exporter.ts

@@ -53,7 +53,25 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
   let fallbackIndex = 1;
 
   for (const m of input.merged) {
-    const { vpId, category1 } = splitVpAndName(m.feature.name);
+    // Data-driven (@cases): one scenario ran once per input row — emit one CSV row per
+    // executed input. The Playwright results are titled "<scenario> — <label>"; expand
+    // by matching that prefix. With no results yet, fall back to a single (Pending) row.
+    const isCases = m.feature.tags.some((t) => t.startsWith('@cases:'));
+    let variants: Array<{ nameSuffix: string; result?: PlaywrightResult }> = [{ nameSuffix: '' }];
+    if (isCases && input.results) {
+      // Result titles are "<describe> > <scenario> — <label>"; match the scenario+label marker.
+      const marker = `${m.feature.name} — `;
+      const rowResults = [...input.results.entries()].filter(([t]) => t.includes(marker));
+      if (rowResults.length) {
+        variants = rowResults.map(([t, r]) => ({ nameSuffix: ` — ${t.slice(t.indexOf(marker) + marker.length)}`, result: r }));
+      }
+    } else if (input.results && m.spec) {
+      variants = [{ nameSuffix: '', result: input.results.get(m.spec.testTitle) }];
+    }
+
+   for (const variant of variants) {
+    const displayName = `${m.feature.name}${variant.nameSuffix}`;
+    const { vpId, category1 } = splitVpAndName(displayName);
     const tcId = generateTcId(input.screen, vpId, fallbackIndex);
     if (!vpId) fallbackIndex++;
 
@@ -87,11 +105,8 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
     // automatically) and render natively as multi-line in XLSX.
     const testData = formatTestData(m.feature.referencedVars, input.testData, Infinity, '\n');
 
-    // Match Playwright result by test title (from .spec.ts) OR by scenarioName
-    let result: PlaywrightResult | undefined;
-    if (input.results && m.spec) {
-      result = input.results.get(m.spec.testTitle);
-    }
+    // Status for this (possibly per-input) row — resolved into `variant` above.
+    const result: PlaywrightResult | undefined = variant.result;
 
     // Determine Test Result
     let testResult: string;
@@ -141,6 +156,7 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
       testEnvironment: environment,
       note,
     });
+   }
   }
 
   return rows;

package/src/exporters/spec-parser.ts

@@ -20,7 +20,12 @@ function extractTestBlock(content: string, startIdx: number): {
   //   test('title', { tag: [...] }, async ({ page }) => {
   // Backreference \1 lets the inner title contain the opposite quote type
   // (e.g. test('Footer "X" link', ...) — common when scenarios cite UI labels).
-  const testRegex = /test\s*\(\s*(['"])((?:(?!\1).)+)\1\s*,\s*(?:\{[^}]*\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
+  // Quote char may be ' " or ` — the backtick form is a data-driven (@cases) title
+  // like `VP-… — ${__row.__label}`.
+  // The options object uses `\{.*?\}` (non-greedy, not `[^}]*`) so a tag value containing a
+  // `}` — e.g. `@query:q(p={{var}})` — doesn't truncate the match (issue #271). The header is
+  // single-line, so `.*?` anchored on `}, async` is safe.
+  const testRegex = /test\s*\(\s*(['"`])((?:(?!\1).)+)\1\s*,\s*(?:\{.*?\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
   testRegex.lastIndex = startIdx;
   const match = testRegex.exec(content);
   if (!match) return null;

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

@@ -36,6 +36,7 @@ export interface ScenarioData {
   authRole?: string; // Auth role for storage state
   isParallel?: boolean; // @parallel: use fresh page from fixture
   tags?: string; // Pass-through tags for Playwright { tag: [...] }, e.g. "'@smoke', '@high'"
+  casesDataset?: string; // @cases:<dataset> — emit one test() per row of the runtime dataset
 }
 
 export interface StepTemplateData {

package/src/generators/test-generator/adapters/playwright/templates/scenario.hbs

@@ -1,3 +1,20 @@
+{{#if casesDataset}}
+  for (const __row of testData.cases('{{casesDataset}}')) {
+{{#if tags}}
+  test(`{{scenarioName}} — ${__row.__label}`, { tag: [{{{tags}}}] }, async ({{#if isParallel}}{ page }{{/if}}) => {
+{{else}}
+  test(`{{scenarioName}} — ${__row.__label}`, async ({{#if isParallel}}{ page }{{/if}}) => {
+{{/if}}
+    const rowData = testData.withRow(__row);
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });
+  }
+{{else}}
 {{#if isParallel}}
 {{#if tags}}
   test('{{scenarioName}}', { tag: [{{{tags}}}] }, async ({ page }) => {
@@ -24,4 +41,5 @@
 {{code}}
 {{/each}}
   });
-{{/if}}
+{{/if}}
+{{/if}}

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

@@ -5,6 +5,7 @@ import { StepMapper } from './step-mapper';
 import { TestGeneratorAdapter, adapterRegistry } from './adapters';
 import { transformToRuntimeData } from './utils/runtime-data-transformer';
 import { isDbStep } from './patterns/database-patterns';
+import { resolveQuery, compileQuery } from '../../harness/query-catalog';
 
 /**
  * Filter base scenario steps for @extend: only keep Given→When steps.
@@ -74,7 +75,7 @@ function extractCleanupFlags(tags: string[]): { overlay?: boolean; forms?: boole
 const FUNCTIONAL_TAG_PREFIXES = [
   '@parallel', '@cleanup:', '@auth:', '@manual', '@no-auth',
   '@steps:', '@extend:', '@screenshot:', '@beforeAll', '@afterEach', '@afterAll',
-  '@flow',
+  '@flow', '@cases:',
 ];
 
 function extractPassThroughTags(scenarioTags: string[], featureTags: string[]): string | undefined {
@@ -170,6 +171,8 @@ export class CodeGenerator {
   private adapter: TestGeneratorAdapter;
   private screenName?: string;
   private options: any;
+  // Screen/flow name for the CURRENT feature, in catalog-resolution form (`flows/<x>` for flows).
+  private queryScreenName: string = '';
   // Steps registry built per feature during generateTestCode(); used by countSteps()
   private stepsRegistry = new Map<string, ParsedScenario>();
 
@@ -302,62 +305,90 @@ export class CodeGenerator {
     const steps: ParsedStep[] = [];
     if (feature.background?.steps) steps.push(...feature.background.steps);
     for (const sc of feature.scenarios || []) if (sc.steps) steps.push(...sc.steps);
-    return steps.some((s) => s && typeof s.text === 'string' && isDbStep(s.text));
+    if (steps.some((s) => s && typeof s.text === 'string' && isDbStep(s.text))) return true;
+    // A scenario may carry only a @query:<name> post-condition tag (no DB step in its body).
+    return (feature.scenarios || []).some((sc) => (sc.tags || []).some((t) => t.startsWith('@query:')));
   }
 
-  /** Copy the Data Driver runtime helper into specs/db.ts (idempotent). */
-  ensureDbFile(outputDir: string): void {
-    const templatesRoot = path.join(__dirname, '..', '..', 'orchestrator', 'templates');
-    const dbPath = path.join(outputDir, 'db.ts');
-    if (!fs.existsSync(dbPath)) {
-      const templatePath = path.join(templatesRoot, 'specs-db.ts');
-      if (fs.existsSync(templatePath)) {
-        if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
-        fs.copyFileSync(templatePath, dbPath);
-        console.log('✓ Created: specs/db.ts');
-      }
+  /**
+   * Build the precondition bind steps for a scenario's `@query:<name>[(p={{v}},…)]` tags.
+   * Each runs the catalog query and binds the result array to a `{{name}}` variable.
+   */
+  private buildQueryBinds(scenario: ParsedScenario): Array<{ comment?: string; code: string }> {
+    const out: Array<{ comment?: string; code: string }> = [];
+    const TAG = /^@query:([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
+    for (const tag of scenario.tags || []) {
+      const m = tag.match(TAG);
+      if (!m) continue;
+      const name = m[1];
+      const overrides = this.parseQueryOverrides(m[2]);
+      const entry = resolveQuery(name, this.queryScreenName); // throws (fail-fast) if missing/ambiguous
+      const { sql, paramNames } = compileQuery(entry);
+      const paramExprs = paramNames.map((p) =>
+        p in overrides ? overrides[p] : `testData.get(${JSON.stringify(p)})`,
+      );
+      const label = JSON.stringify(entry.description ? `query "${name}" — ${entry.description}` : `query "${name}"`);
+      const ds = entry.datasource ? JSON.stringify(entry.datasource) : 'undefined';
+      out.push({
+        comment: `@query:${name} → bind {{${name}}} from ${entry.datasource || 'default datasource'}`,
+        code: this.indentCode(
+          `testData.bind(${JSON.stringify(name)}, await db.fetchQuery(${label}, ${JSON.stringify(sql)}, [${paramExprs.join(', ')}], ${ds}));`,
+          4,
+        ),
+      });
     }
+    return out;
   }
 
-  ensureBaseFile(outputDir: string): void {
-    const templatesRoot = path.join(__dirname, '..', '..', 'orchestrator', 'templates');
-
-    const basePath = path.join(outputDir, 'base.ts');
-    if (!fs.existsSync(basePath)) {
-      const templatePath = path.join(templatesRoot, 'specs-base.ts');
-      if (fs.existsSync(templatePath)) {
-        const baseDir = path.dirname(basePath);
-        if (!fs.existsSync(baseDir)) {
-          fs.mkdirSync(baseDir, { recursive: true });
-        }
-        fs.copyFileSync(templatePath, basePath);
-        console.log('✓ Created: specs/base.ts');
-      }
-    }
+  /** Parse `@query:name(a={{x}},b="lit",c=3)` overrides → { a: "testData.get('x')", … } JS exprs. */
+  private parseQueryOverrides(raw?: string): Record<string, string> {
+    const out: Record<string, string> = {};
+    if (!raw) return out;
+    for (const part of raw.split(',')) {
+      const eq = part.indexOf('=');
+      if (eq < 0) continue;
+      const key = part.slice(0, eq).trim();
+      const val = part.slice(eq + 1).trim();
+      if (!key) continue;
+      const v = val.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
+      const q = val.match(/^["'](.*)["']$/);
+      if (v) out[key] = `testData.get(${JSON.stringify(v[1])})`;
+      else if (q) out[key] = JSON.stringify(q[1]);
+      else if (/^-?\d+(?:\.\d+)?$/.test(val)) out[key] = val;
+      else out[key] = JSON.stringify(val);
+    }
+    return out;
+  }
 
-    // base.ts now depends on locale-fixture.ts — keep them paired.
-    const localeFixturePath = path.join(outputDir, 'locale-fixture.ts');
-    if (!fs.existsSync(localeFixturePath)) {
-      const templatePath = path.join(templatesRoot, 'specs-locale-fixture.ts');
-      if (fs.existsSync(templatePath)) {
-        const baseDir = path.dirname(localeFixturePath);
-        if (!fs.existsSync(baseDir)) {
-          fs.mkdirSync(baseDir, { recursive: true });
-        }
-        fs.copyFileSync(templatePath, localeFixturePath);
-        console.log('✓ Created: specs/locale-fixture.ts');
-      }
-    }
+  /**
+   * Copy an auto-generated runtime helper into specs/, **refreshing it when the template changed**.
+   * These files carry a `DO NOT EDIT — regenerated` header, so a stale copy left by an older sungen
+   * (e.g. a `specs/db.ts` from before a feature was added) is replaced instead of kept (issue #270).
+   * No-ops when the on-disk content already matches the template, so it stays quiet + idempotent.
+   */
+  private syncGeneratedHelper(outputDir: string, fileName: string, templateName: string): void {
+    const templatePath = path.join(__dirname, '..', '..', 'orchestrator', 'templates', templateName);
+    if (!fs.existsSync(templatePath)) return;
+    const targetPath = path.join(outputDir, fileName);
+    const next = fs.readFileSync(templatePath, 'utf8');
+    const exists = fs.existsSync(targetPath);
+    if (exists && fs.readFileSync(targetPath, 'utf8') === next) return; // already current
+    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(targetPath, next);
+    console.log(`✓ ${exists ? 'Updated' : 'Created'}: specs/${fileName}`);
+  }
+
+  /** Ensure specs/db.ts is present and current (Data Driver runtime helper). */
+  ensureDbFile(outputDir: string): void {
+    this.syncGeneratedHelper(outputDir, 'db.ts', 'specs-db.ts');
+  }
 
+  ensureBaseFile(outputDir: string): void {
+    this.syncGeneratedHelper(outputDir, 'base.ts', 'specs-base.ts');
+    // base.ts depends on locale-fixture.ts — keep them paired.
+    this.syncGeneratedHelper(outputDir, 'locale-fixture.ts', 'specs-locale-fixture.ts');
     if (this.options.runtimeData) {
-      const testDataPath = path.join(outputDir, 'test-data.ts');
-      if (!fs.existsSync(testDataPath)) {
-        const templatePath = path.join(templatesRoot, 'specs-test-data.ts');
-        if (fs.existsSync(templatePath)) {
-          fs.copyFileSync(templatePath, testDataPath);
-          console.log('✓ Created: specs/test-data.ts');
-        }
-      }
+      this.syncGeneratedHelper(outputDir, 'test-data.ts', 'specs-test-data.ts');
     }
   }
 
@@ -391,6 +422,8 @@ export class CodeGenerator {
       }
       this.stepMapper.setScreenContext(effectiveScreenName);
     }
+    // Catalog-resolution screen name for @query binds (flows are prefixed `flows/`).
+    this.queryScreenName = isFlowFeature ? `flows/${effectiveScreenName}` : (effectiveScreenName || '');
 
     // Reset flow mode per feature to prevent state leak in --all mode
     this.stepMapper.setFlowMode(isFlowFeature);
@@ -637,6 +670,35 @@ export class CodeGenerator {
     // Set scenario context for path variable resolution (full merged list)
     this.stepMapper.setScenarioContext(stepsToMap);
 
+    // Data-driven (@cases): the scenario's {{col}} refs are dataset *row columns* that
+    // exist only at runtime — register them as captured so they resolve to a runtime
+    // get() (→ rowData.get) instead of compile-time YAML lookup.
+    const casesTag = scenario.tags.find((t) => t.startsWith('@cases:'));
+    const casesDataset = casesTag ? casesTag.slice('@cases:'.length).trim() : undefined;
+    if (casesDataset) {
+      const refs = new Set<string>();
+      for (const st of stepsToMap) {
+        for (const m of (st.text || '').matchAll(/\{\{\s*([\w.]+)\s*\}\}/g)) refs.add(m[1]);
+      }
+      for (const r of refs) this.stepMapper.registerCaptured(r);
+    }
+
+    // @query-bound vars: `{{name.col}}` / `{{name[2].col}}` / `{{name.count}}` exist only at
+    // runtime (the bind fetches them) — register as captured so they resolve to a runtime get()
+    // instead of a compile-time YAML lookup that would fail.
+    const queryNames = (scenario.tags || [])
+      .map((t) => t.match(/^@query:([A-Za-z_][A-Za-z0-9_]*)/))
+      .filter((m): m is RegExpMatchArray => !!m)
+      .map((m) => m[1]);
+    if (queryNames.length) {
+      for (const st of stepsToMap) {
+        for (const mt of (st.text || '').matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) {
+          const head = mt[1].split(/[.[]/)[0];
+          if (queryNames.includes(head)) this.stepMapper.registerCaptured(mt[1]);
+        }
+      }
+    }
+
     const steps: Array<{ comment?: string; code: string }> = [];
 
     if (scenario.extendsName && this.stepsRegistry.has(scenario.extendsName)) {
@@ -666,17 +728,33 @@ export class CodeGenerator {
       }
     }
 
+    // @query:<name>[(p={{v}},…)] tags → run the catalog query as a PRECONDITION and bind its
+    // result to a `{{name}}` variable (scenario asserts on it with `expect …` + path access).
+    // Prepended so the binds run before the scenario's own steps.
+    const queryBinds = this.buildQueryBinds(scenario);
+    if (queryBinds.length) steps.unshift(...queryBinds);
+
     // Extract pass-through tags (feature + scenario, excluding functional tags)
     const tags = extractPassThroughTags(scenario.tags, featureTags);
 
     // Use adapter to render scenario
-    return this.adapter.renderScenario({
+    const rendered = this.adapter.renderScenario({
       scenarioName: scenario.name,
       steps,
       authRole,
       isParallel,
       tags,
+      casesDataset,
     });
+
+    // Data-driven (@cases): the per-row test() binds a row-scoped view (`rowData`).
+    // Pre-transform THIS scenario's runtime-data markers to read from `rowData`, so the
+    // global `testData` transform that runs next on the rest of the file leaves it alone.
+    // The loop header's `testData.cases()/withRow()` are literal code (no markers) → untouched.
+    if (casesDataset && this.options.runtimeData) {
+      return transformToRuntimeData(rendered, 'rowData');
+    }
+    return rendered;
   }
 
   /**

package/src/generators/test-generator/patterns/database-patterns.ts

@@ -21,7 +21,8 @@ const reRow = new RegExp(`see\\s+${TABLE}\\s+row\\s+where\\b`, 'i');
 const reNoRow = new RegExp(`see\\s+${TABLE}\\s+no\\s+row\\s+where\\b`, 'i');
 const reCount = new RegExp(`see\\s+${TABLE}.*\\bcount\\s+is\\b`, 'i');
 
-/** True when a step is a DB-verification step (used to wire the `db` import). */
+/** True when a step is a declarative DB-verification step (used to wire the `db` import).
+ *  Named queries are invoked via the `@query:` annotation, not a step — see code-generator. */
 export function isDbStep(text: string): boolean {
   return reNoRow.test(text) || reRow.test(text) || reCount.test(text);
 }

package/src/generators/test-generator/patterns/expect-patterns.ts

@@ -0,0 +1,49 @@
+import { ParsedStep } from '../../gherkin-parser';
+import { StepPattern, PatternContext } from './types';
+import { MappedStep } from '../step-mapper';
+
+/**
+ * Data-vs-data assertions — compare two runtime values directly (no UI element).
+ * The primary use is asserting on an `@query`-bound result via path access, e.g.
+ *
+ *   Then expect {{products.count}} is {{expected}}
+ *   Then expect {{products.count}} is at least {{one}}
+ *   Then expect {{active_user.status}} is "active"
+ *   Then expect {{order.total}} is not {{zero}}
+ *
+ * Both sides are `{{var|path}}` | "literal" | 'literal' | number. Generic — works for any
+ * test-data values, not only DB results.
+ */
+const VALUE = String.raw`\{\{[^}]+\}\}|"[^"]*"|'[^']*'|-?\d+(?:\.\d+)?`;
+const reExpect = new RegExp(`^\\s*(?:User\\s+)?expect\\s+(${VALUE})\\s+is\\s+(not\\s+|at\\s+least\\s+|at\\s+most\\s+)?(${VALUE})\\s*$`, 'i');
+
+/** Render a value token (`{{var}}` | "literal" | 'literal' | number) as a JS expression. */
+function valueExpr(token: string): string {
+  const t = token.trim();
+  const v = t.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
+  if (v) return `testData.get(${JSON.stringify(v[1])})`;
+  const q = t.match(/^["'](.*)["']$/);
+  if (q) return JSON.stringify(q[1]);
+  if (/^-?\d+(?:\.\d+)?$/.test(t)) return t;
+  return JSON.stringify(t);
+}
+
+export const expectPatterns: StepPattern[] = [
+  {
+    name: 'expect-data',
+    priority: 62, // above generic see-assertions; sibling of the DB assertions
+    matcher: (step: ParsedStep) => reExpect.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      const m = step.text.match(reExpect)!;
+      const a = valueExpr(m[1]);
+      const op = (m[2] || '').trim().toLowerCase();
+      const b = valueExpr(m[3]);
+      let code: string;
+      if (op === 'at least') code = `expect(Number(${a})).toBeGreaterThanOrEqual(Number(${b}));`;
+      else if (op === 'at most') code = `expect(Number(${a})).toBeLessThanOrEqual(Number(${b}));`;
+      else if (op === 'not') code = `expect(String(${a})).not.toBe(String(${b}));`;
+      else code = `expect(String(${a})).toBe(String(${b}));`;
+      return { code, comment: `Expect ${m[1]} ${op ? op + ' ' : 'is '}${m[3]}` };
+    },
+  },
+];

package/src/generators/test-generator/patterns/index.ts

@@ -12,6 +12,7 @@ import { scopePatterns } from './scope-patterns';
 import { tablePatterns } from './table-patterns';
 import { capturePatterns } from './capture-patterns';
 import { databasePatterns } from './database-patterns';
+import { expectPatterns } from './expect-patterns';
 
 /**
  * Pattern Registry - manages all step patterns
@@ -38,6 +39,7 @@ export class PatternRegistry {
     this.patterns.push(...tablePatterns);
     this.patterns.push(...capturePatterns);
     this.patterns.push(...databasePatterns);
+    this.patterns.push(...expectPatterns);
 
     // Sort by priority (higher first)
     this.patterns.sort((a, b) => (b.priority || 0) - (a.priority || 0));

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

@@ -94,6 +94,15 @@ export class StepMapper {
     this.templateEngine.resetBaseContext();
   }
 
+  /**
+   * Register a runtime data variable so `{{name}}` resolves to `testData.get('name')`
+   * (skipping compile-time YAML validation). Used for @cases row columns, which exist
+   * only at runtime in the dataset rows. Scenario-scoped (cleared by setScenarioContext).
+   */
+  registerCaptured(name: string): void {
+    this.dataResolver.registerCaptured(name);
+  }
+
   /**
    * Map a Gherkin step to Playwright code
    * Uses pattern registry first, falls back to AI if enabled

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

@@ -284,6 +284,9 @@ export class TemplateEngine {
     scenarioName: string;
     steps: Array<{ comment?: string; code: string }>;
     authRole?: string;
+    isParallel?: boolean;
+    tags?: string;
+    casesDataset?: string;
   }): string {
     return this.render('scenario', data);
   }

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

@@ -4,7 +4,7 @@ const MARKER_PATTERN = /__SUNGEN_TD_([A-Za-z0-9_]+)__/;
  * Replace __SUNGEN_TD_ markers with testData.get() calls in generated code.
  * Three passes: comments, string literals, then regex literals.
  */
-export function transformToRuntimeData(code: string): string {
+export function transformToRuntimeData(code: string, accessor: string = 'testData'): string {
   // Pass 0: Comments — replace markers in // comments with decoded key name
   // Prevents Pass 2 from misinterpreting // comment markers as regex delimiters
   code = code.replace(
@@ -20,9 +20,9 @@ export function transformToRuntimeData(code: string): string {
     (_, _quote, prefix, enc, suffix) => {
       const key = decodeKey(enc);
       if (!prefix && !suffix) {
-        return `testData.get('${key}')`;
+        return `${accessor}.get('${key}')`;
       }
-      return `\`${prefix}\${testData.get('${key}')}${suffix}\``;
+      return `\`${prefix}\${${accessor}.get('${key}')}${suffix}\``;
     }
   );
 
@@ -32,7 +32,7 @@ export function transformToRuntimeData(code: string): string {
     /\/((?:[^/\\\n]|\\.)*?)__SUNGEN_TD_([A-Za-z0-9_]+)__((?:[^/\\\n]|\\.)*?)\/([gimsuy]*)/g,
     (_, prefix, enc, suffix, flags) => {
       const key = decodeKey(enc);
-      const ref = `testData.get('${key}')`;
+      const ref = `${accessor}.get('${key}')`;
       const flagStr = flags ? `, '${flags}'` : '';
       if (!prefix && !suffix) return `new RegExp(${ref}${flagStr})`;
       return `new RegExp(\`${prefix}\${${ref}}${suffix}\`${flagStr})`;
@@ -44,7 +44,7 @@ export function transformToRuntimeData(code: string): string {
   // table/list count templates). testData.get() returns a string, so coerce with Number().
   code = code.replace(
     /__SUNGEN_TD_([A-Za-z0-9_]+)__/g,
-    (_, enc) => `Number(testData.get('${decodeKey(enc)}'))`
+    (_, enc) => `Number(${accessor}.get('${decodeKey(enc)}'))`
   );
 
   return code;

package/src/harness/challenge.ts

@@ -34,6 +34,8 @@ export interface ChallengeReport {
   shallowThemes: string[];
   // Depth critic
   collectionClaimSingular: ChallengeFinding[];
+  // Data-driven critic — @cases-worthy gaps (spec-independent)
+  dataDriven: ChallengeFinding[];
   // Novelty critic (deterministic prompts → AI agent fills candidates)
   noveltyPrompts: string[];
   // Roll-up
@@ -47,6 +49,10 @@ const PLURAL_NOUN = /\b(cards|items|products|rows|results|prices|entries|records
 const QUANTIFIER = /\b(all|every|each)\b/i;
 const DISPLAY_VERB = /\b(displays?|shows?|lists?|grid|contains?)\b/i;
 
+// Title lexicon implying a CLASS of inputs (→ a data-driven @cases candidate). Used by
+// Detector A. Spec-independent — reads the title, not the spec.
+const INPUT_CLASS_LEXICON = /\b(invalid|formats?|boundary|range|min|max|too (?:long|short)|special char|each|various|classes)\b/i;
+
 /** Risk lenses the Novelty critic prompts the AI to explore (beyond the catalog). */
 const NOVELTY_LENSES = [
   'double-submit / rapid repeat of the primary action (duplicate side-effects?)',
@@ -88,17 +94,49 @@ export function buildChallenge(screenDir: string, screenName: string): Challenge
     }
   }
 
-  // 3. Novelty critic — deterministic prompts; the AI agent expands these into candidates.
+  // 3. Data-driven critic — surface @cases-worthy gaps (spec-independent).
+  const dataDriven: ChallengeFinding[] = [];
+  const clustered = new Set<string>();
+  // Detector B (high precision): ≥2 non-@cases scenarios sharing the SAME step skeleton
+  // (stepSkeleton normalizes {{vars}}/quoted values) → they differ only by data → collapse.
+  const bySkeleton = new Map<string, ScenarioInfo[]>();
+  for (const s of scenarios) {
+    if (s.manual || s.casesDataset || !s.stepSkeleton) continue;
+    (bySkeleton.get(s.stepSkeleton) ?? bySkeleton.set(s.stepSkeleton, []).get(s.stepSkeleton)!).push(s);
+  }
+  for (const group of bySkeleton.values()) {
+    if (group.length < 2) continue;
+    group.forEach((s) => clustered.add(s.name));
+    dataDriven.push({
+      scenario: group.map((s) => s.name).join(' | '),
+      issue: `${group.length} scenarios share the same steps and differ only by input value (data-variants).`,
+      suggestion: `Collapse into ONE \`@cases:<dataset>\` — ${group.length} rows in test-data, each \`{{col}}\` a column. See Gherkin → Advanced → Data-driven.`,
+    });
+  }
+  // Detector A (advisory): a lone scenario whose title implies a class of inputs → suggest @cases.
+  for (const s of scenarios) {
+    if (s.manual || s.casesDataset || clustered.has(s.name)) continue;
+    if (INPUT_CLASS_LEXICON.test(s.name)) {
+      dataDriven.push({
+        scenario: s.name,
+        issue: 'Title reads like a CLASS of inputs (validation/boundary/error) but tests a single value.',
+        suggestion: 'Consider `@cases` to cover the EP/boundary classes (one row per valid/invalid class), not just one value.',
+      });
+    }
+  }
+
+  // 4. Novelty critic — deterministic prompts; the AI agent expands these into candidates.
   const noveltyPrompts = NOVELTY_LENSES.map((l) => `Find 1 non-obvious, valuable scenario via: ${l}`);
 
   // Roll-up — exploration readiness signals (not a fake score).
   const explorationReadiness: string[] = [];
+  if (dataDriven.length) explorationReadiness.push(`${dataDriven.length} data-driven gap(s) — scenarios that should be one \`@cases\` (collapse data-variants / cover EP-boundary classes).`);
   if (collectionClaimSingular.length) explorationReadiness.push(`${collectionClaimSingular.length} title↔assertion gap(s) — deterministic depth critic flagged these; an AI Business-Depth critic should confirm + fix.`);
   if (overCovered.length) explorationReadiness.push(`${overCovered.length} possibly over-covered area(s) — rebalance toward correctness.`);
   if (shallowThemes.length) explorationReadiness.push(`Shallow themes: ${shallowThemes.join(', ')}.`);
   explorationReadiness.push('Novelty candidates are NOT generated deterministically — run the `sungen-challenge` agent (Claude) or its inline criteria (Copilot) to propose them, then QA accept/reject (≤20% of official, no auto-merge).');
 
-  return { screen: screenName, overCovered, shallowThemes, collectionClaimSingular, noveltyPrompts, explorationReadiness };
+  return { screen: screenName, overCovered, shallowThemes, collectionClaimSingular, dataDriven, noveltyPrompts, explorationReadiness };
 }
 
 /** Render the Challenge Report as Markdown (advisory — not part of the official suite). */
@@ -114,6 +152,13 @@ export function renderChallengeMarkdown(r: ChallengeReport): string {
   } else lines.push('_none_');
   lines.push('');
 
+  lines.push('## Data-driven — scenarios that should be `@cases` (one test case, many inputs)');
+  if (r.dataDriven.length) {
+    lines.push('| Scenario(s) | Issue | Suggested |', '|---|---|---|');
+    for (const f of r.dataDriven) lines.push(`| ${f.scenario} | ${f.issue} | ${f.suggestion} |`);
+  } else lines.push('_none_');
+  lines.push('');
+
   lines.push('## Coverage — possibly over-covered / shallow');
   if (r.overCovered.length) for (const o of r.overCovered) lines.push(`- **${o.bucket}** — ${o.note}`);
   if (r.shallowThemes.length) lines.push(`- Shallow themes: ${r.shallowThemes.join(', ')}`);