@sun-asterisk/sungen 3.1.0 → 3.1.1

package/src/exporters/spec-parser.ts

@@ -20,7 +20,9 @@ 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}`.
+  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,7 +305,59 @@ 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:')));
+  }
+
+  /**
+   * 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;
+  }
+
+  /** 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;
   }
 
   /** Copy the Data Driver runtime helper into specs/db.ts (idempotent). */
@@ -391,6 +446,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 +694,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 +752,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(', ')}`);

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

@@ -0,0 +1,119 @@
+/**
+ * Deterministic lint for the data-driven features (`@cases` + `@query`).
+ *
+ * Advisory (warn, never block) — surfaced after `sungen generate`. Catches the silent
+ * footguns: a `{{var}}` in a @cases scenario that is neither a row column nor a top-level
+ * key, a name collision that shadows a top-level value, inconsistent dataset rows, and a
+ * @query whose param has no value / whose name doesn't resolve.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { GherkinParser, ParsedScenario } from '../generators/gherkin-parser';
+import { resolveQuery, lintCatalog } from './query-catalog';
+
+export interface DataDrivenWarning {
+  scenario?: string;
+  message: string;
+}
+
+const ROW_META = new Set(['case', 'name', 'label', '__label']);
+
+/** Collect the inner text of every `{{…}}` reference in a scenario's steps. */
+function collectRefs(sc: ParsedScenario): string[] {
+  const refs = new Set<string>();
+  for (const st of sc.steps || []) {
+    for (const m of (st.text || '').matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) refs.add(m[1]);
+  }
+  return [...refs];
+}
+
+/** Keys overridden in a `@query:name(a=…,b=…)` annotation. */
+function overrideKeys(raw?: string): Set<string> {
+  const out = new Set<string>();
+  if (!raw) return out;
+  for (const part of raw.split(',')) {
+    const eq = part.indexOf('=');
+    if (eq > 0) out.add(part.slice(0, eq).trim());
+  }
+  return out;
+}
+
+/** Lint the @cases/@query usage of one screen/flow directory. Returns advisory warnings. */
+export function lintDataDriven(screenDir: string, cwd: string = process.cwd()): DataDrivenWarning[] {
+  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 [];
+  }
+
+  const tdPath = path.join(screenDir, 'test-data', `${base}.yaml`);
+  const td: Record<string, any> = tdPath && fs.existsSync(tdPath) ? parseYaml(fs.readFileSync(tdPath, 'utf8')) || {} : {};
+  const topKeys = new Set(Object.keys(td));
+  const warns: DataDrivenWarning[] = [];
+
+  for (const sc of scenarios) {
+    const tags: string[] = sc.tags || [];
+    const refs = collectRefs(sc);
+
+    // --- @cases -----------------------------------------------------------
+    const casesTag = tags.find((t) => t.startsWith('@cases:'));
+    if (casesTag) {
+      const ds = casesTag.slice('@cases:'.length).trim();
+      const rows = td[ds];
+      if (!Array.isArray(rows)) {
+        warns.push({ scenario: sc.name, message: `@cases:${ds} → dataset "${ds}" is missing or not a list in test-data.` });
+      } else {
+        const colSets = rows.map((r) => new Set(Object.keys(r || {}).filter((k) => !ROW_META.has(k))));
+        const allCols = new Set<string>();
+        colSets.forEach((s) => s.forEach((c) => allCols.add(c)));
+        for (const c of allCols) {
+          const missing = colSets.filter((s) => !s.has(c)).length;
+          if (missing) warns.push({ scenario: sc.name, message: `@cases:${ds} → column "${c}" is missing in ${missing}/${rows.length} row(s) — rows are inconsistent.` });
+          if (topKeys.has(c)) warns.push({ scenario: sc.name, message: `@cases:${ds} → "${c}" is both a dataset column and a top-level test-data key — the row value shadows the top-level one.` });
+        }
+        for (const r of refs) {
+          const head = r.split(/[.[]/)[0];
+          if (!allCols.has(head) && !topKeys.has(head)) {
+            warns.push({ scenario: sc.name, message: `@cases:${ds} → {{${r}}} is neither a dataset column nor a top-level test-data key.` });
+          }
+        }
+      }
+    }
+
+    // --- @query -----------------------------------------------------------
+    for (const t of tags) {
+      const m = t.match(/^@query:([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/);
+      if (!m) continue;
+      const name = m[1];
+      const overrides = overrideKeys(m[2]);
+      let entry;
+      try {
+        entry = resolveQuery(name, screenName, cwd);
+      } catch (e: any) {
+        warns.push({ scenario: sc.name, message: e?.message || `@query:${name} → cannot resolve query.` });
+        continue;
+      }
+      for (const p of entry.params || []) {
+        if (!overrides.has(p) && !topKeys.has(p)) {
+          warns.push({ scenario: sc.name, message: `@query:${name} → param "${p}" has no value: not in the annotation and not a top-level test-data key.` });
+        }
+      }
+    }
+  }
+
+  // Catalog-level lint (SELECT-only, params declared/used, datasource present).
+  try {
+    for (const e of lintCatalog(screenName, null, cwd).errors) warns.push({ message: e });
+  } catch {
+    /* no catalog → nothing to lint */
+  }
+  return warns;
+}

package/src/harness/parse.ts

@@ -30,6 +30,8 @@ export interface ScenarioInfo {
   haystack: string;           // lowercase name + steps text (for keyword coverage)
   stepsText: string;          // lowercase steps ONLY (name excluded) — for claim-proof
   vpId?: string;              // raw leading ID token of the title (project's scheme: VP0-001, MS-HP-001, VP-LIST-001)
+  casesDataset?: string;      // @cases:<dataset> — data-driven; one scenario expands to N row-tests
+  queryRefs?: string[];       // named queries referenced by this scenario (inline `query [name]` + @query: tags)
 }
 
 /** Format-tolerant: is this token an ID (project's scheme), not a prose word?
@@ -98,6 +100,14 @@ const PRIORITY_TAGS: Record<string, Priority> = { '@high': 'high', '@normal': 'n
 function classifyScenario(sc: ParsedScenario): ScenarioInfo {
   const tags = sc.tags || [];
   const manual = tags.includes('@manual');
+  const casesTag = tags.find((t) => t.startsWith('@cases:'));
+  const casesDataset = casesTag ? casesTag.slice('@cases:'.length).trim() : undefined;
+  // Named-query references: @query:<name> tags + inline `query [name]` step refs.
+  const queryRefs = new Set<string>();
+  for (const t of tags) if (t.startsWith('@query:')) { const n = t.slice('@query:'.length).trim(); if (n) queryRefs.add(n); }
+  for (const step of (sc.steps as ParsedStep[]) || []) {
+    for (const m of (step.text || '').matchAll(/\bquery\s+\[([A-Za-z_][A-Za-z0-9_]*)\]/gi)) queryRefs.add(m[1]);
+  }
   let priority: Priority = 'unknown';
   for (const t of tags) if (PRIORITY_TAGS[t]) priority = PRIORITY_TAGS[t];
 
@@ -152,6 +162,8 @@ function classifyScenario(sc: ParsedScenario): ScenarioInfo {
     haystack: textParts.join(' ').toLowerCase(),
     stepsText: stepTextParts.join(' ').toLowerCase(),
     vpId,
+    casesDataset,
+    queryRefs: queryRefs.size ? [...queryRefs] : undefined,
   };
 }
 

package/src/harness/script-check.ts

@@ -15,7 +15,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { loadScenarios } from './parse';
+import { loadScenarios, ScenarioInfo } from './parse';
 
 export interface ScriptCheckResult {
   screen: string;
@@ -146,10 +146,13 @@ export async function runScriptCheck(screenDir: string, screenName: string, flow
   }
 
   // A. Structural 1:1
+  // A @cases scenario emits ONE source test() inside a per-row loop, titled
+  // `<name> — ${__row.__label}` — match that literal title, not the bare name.
+  const expectedTitle = (s: ScenarioInfo) => (s.casesDataset ? `${s.name} — ${'${'}__row.__label}` : s.name);
   const specTitleSet = new Set(specTitles);
-  const scenTitleSet = new Set(automated.map((s) => s.name));
-  const missingInSpec = automated.filter((s) => !specTitleSet.has(s.name)).map((s) => s.name);
-  const extraInSpec = specTitles.filter((t) => !scenTitleSet.has(t));
+  const expectedSet = new Set(automated.map(expectedTitle));
+  const missingInSpec = automated.filter((s) => !specTitleSet.has(expectedTitle(s))).map((s) => s.name);
+  const extraInSpec = specTitles.filter((t) => !expectedSet.has(t));
   const countMatch = committedSpec ? automated.length === specTitles.length : false;
   if (committedSpec && !countMatch) {
     findings.push(`Count mismatch: ${automated.length} automated scenarios vs ${specTitles.length} test() blocks.`);
@@ -193,7 +196,7 @@ export async function runScriptCheck(screenDir: string, screenName: string, flow
 
   // C. Anti-bypass / faithfulness
   const { assertionlessTests, hollowSteps } = committedSpec
-    ? analyzeFaithfulness(specSrc, scenTitleSet)
+    ? analyzeFaithfulness(specSrc, expectedSet)
     : { assertionlessTests: [], hollowSteps: [] };
   for (const t of assertionlessTests) {
     findings.push(`BYPASS: test "${t}" has 0 assertions (action-only — proves nothing). The testcase is not really automated.`);

package/src/orchestrator/templates/ai-instructions/claude-agent-challenge.md

@@ -15,11 +15,12 @@ Run `sungen challenge --screen <name>` (Bash) and read its report (`.sungen/repo
 - `.sungen/reports/<name>-audit.json` — what the gate already measured.
 - Blind-spot patterns — run `sungen blindspot list --prompt` (Bash) and check the suite against each known pattern.
 
-## Three critics
+## Four critics
 
 1. **Coverage critic** — viewpoints that are missing or covered only shallowly; areas over-covered with low value (e.g. many subscription edge cases while cart correctness is thin). Recommend rebalancing, not just adding.
 2. **Business-Depth critic** — scenarios whose **title claims more than the steps prove** (a set/collection asserted by one element; "correct X" asserted by mere visibility). For each, give the exact deep step to add. Confirm or dismiss the deterministic flags from `sungen challenge`.
-3. **Novelty critic** — 3–5 **non-obvious, valuable** scenarios outside the existing pattern, via risk lenses (double-submit, partial-load, boundary/unusual data, concurrency/back-button, historical incidents). Each must map to a risk or viewpoint and explain why it isn't a duplicate.
+3. **Data-driven critic** — surface `@cases`-worthy gaps, *spec-independent*: (a) **confirm the deterministic collapse suggestions** (`sungen challenge` flags ≥2 scenarios with the same step skeleton → propose the one `@cases:<dataset>` with the rows + a `case` label each); (b) for any action reaching a backend/logic (login, search, create, an API/error path), propose the **corner/error matrix** as `@cases` rows — *invalid · empty · boundary · injection · duplicate · not-found · unauthorized · malformed · rate-limit* — picking the family that fits the screen. These are the cases a spec/viewpoint usually under-specifies.
+4. **Novelty critic** — 3–5 **non-obvious, valuable** scenarios outside the existing pattern, via risk lenses (double-submit, partial-load, boundary/unusual data, concurrency/back-button, historical incidents). Each must map to a risk or viewpoint and explain why it isn't a duplicate.
 
 ## Guardrails (hard)
 - **Read-only.** Never edit the feature or any file. You return findings; the QA/orchestrator decides.