@sun-asterisk/sungen 3.0.1 → 3.1.1

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,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 {
@@ -63,7 +64,7 @@ export interface TestGeneratorAdapter {
   // Template rendering methods
   renderTestFile(data: TestFileData): string;
   renderScenario(data: ScenarioData): string;
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean }): string;
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string;
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string;

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

@@ -26,7 +26,7 @@ export class PlaywrightAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string {
     return this.templateEngine.renderImports(options);
   }
 

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

@@ -3,6 +3,9 @@ import { type Page, type BrowserContext } from '@playwright/test';
 {{#if runtimeData}}
 import { TestDataLoader } from '{{basePath}}/test-data';
 {{/if}}
+{{#if needsDb}}
+import { db } from '{{basePath}}/db';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten

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

@@ -4,6 +4,8 @@ import { ParsedFeature, ParsedScenario, ParsedStep } from '../gherkin-parser';
 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.
@@ -73,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 {
@@ -169,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>();
 
@@ -236,7 +240,11 @@ export class CodeGenerator {
     const hasCleanupTags = (feature.tags || []).some(t => t.startsWith('@cleanup:'));
     const needsCleanupImport = !isParallelFeature && hasCleanupTags;
 
-    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport });
+    // Data Driver: if any step verifies DB state, import the `db` helper + emit specs/db.ts
+    const needsDb = this.featureUsesDb(feature);
+    if (needsDb) this.ensureDbFile(outputDir);
+
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb });
 
     // Generate test code (async now to support AI mapping)
     const testCode = await this.generateTestCode(feature);
@@ -292,8 +300,82 @@ export class CodeGenerator {
   /**
    * Ensure specs/base.ts exists in the output directory
    */
+  /** True when any step (background or scenario) in the feature is a DB-verification step. */
+  private featureUsesDb(feature: ParsedFeature): boolean {
+    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);
+    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). */
+  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');
+      }
+    }
+  }
+
   ensureBaseFile(outputDir: string): void {
-    const templatesRoot = path.join(__dirname, '..', '..', '..', 'orchestrator', 'templates');
+    const templatesRoot = path.join(__dirname, '..', '..', 'orchestrator', 'templates');
 
     const basePath = path.join(outputDir, 'base.ts');
     if (!fs.existsSync(basePath)) {
@@ -364,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);
@@ -610,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)) {
@@ -639,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

@@ -0,0 +1,96 @@
+import { ParsedStep } from '../../gherkin-parser';
+import { StepPattern, PatternContext } from './types';
+import { MappedStep } from '../step-mapper';
+
+/**
+ * Database verification patterns (Data Driver v1) — declarative, no-SQL DB assertions
+ * that compile to calls on the runtime `db` helper (specs/db.ts). Read-only.
+ *
+ *   User see [users] row where [email] is {{reg_email}}
+ *   User see [users] row where [email] is {{reg_email}} has [status] = "active"
+ *   User see [users] no row where [email] is {{dup_email}}
+ *   User see [orders] where [buyer] is {{buyer}} count is {{expected_count}}
+ *
+ * Identifiers ([table]/[column]) are validated by the helper; values bind as parameters.
+ */
+
+const TABLE = String.raw`\[([A-Za-z_][A-Za-z0-9_]*)\]`;
+const VALUE = String.raw`\{\{[^}]+\}\}|"[^"]*"|'[^']*'|-?\d+(?:\.\d+)?`;
+
+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 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);
+}
+
+/** 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);
+}
+
+/** Parse a `[col] is VALUE [and [col2] is VALUE2]` segment into a JS object literal. */
+function parseFilter(segment: string): string {
+  const re = new RegExp(`\\[([A-Za-z_][A-Za-z0-9_]*)\\]\\s+is\\s+(${VALUE})`, 'gi');
+  const parts: string[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(segment))) parts.push(`${JSON.stringify(m[1])}: ${valueExpr(m[2])}`);
+  return `{ ${parts.join(', ')} }`;
+}
+
+/** Parse a `has [col] = VALUE [and [col2] = VALUE2]` segment into a JS object literal. */
+function parseExpected(segment: string): string {
+  const re = new RegExp(`\\[([A-Za-z_][A-Za-z0-9_]*)\\]\\s*=\\s*(${VALUE})`, 'gi');
+  const parts: string[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(segment))) parts.push(`${JSON.stringify(m[1])}: ${valueExpr(m[2])}`);
+  return parts.length ? `{ ${parts.join(', ')} }` : '';
+}
+
+export const databasePatterns: StepPattern[] = [
+  {
+    name: 'db-no-row',
+    priority: 60, // above generic see-assertions
+    matcher: (step: ParsedStep) => reNoRow.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      const m = step.text.match(new RegExp(`${TABLE}\\s+no\\s+row\\s+where\\s+(.+)$`, 'i'))!;
+      const table = m[1];
+      const filter = parseFilter(m[2]);
+      return { code: `await db.assertNoRow(${JSON.stringify(table)}, ${filter});`, comment: `DB: no row in ${table}` };
+    },
+  },
+  {
+    name: 'db-count',
+    priority: 60,
+    matcher: (step: ParsedStep) => reCount.test(step.text) && !reRow.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      const m = step.text.match(new RegExp(`${TABLE}(?:\\s+where\\s+(.+?))?\\s+count\\s+is\\s+(${VALUE})`, 'i'))!;
+      const table = m[1];
+      const filter = m[2] ? parseFilter(m[2]) : '{}';
+      return { code: `await db.assertCount(${JSON.stringify(table)}, ${filter}, Number(${valueExpr(m[3])}));`, comment: `DB: count rows in ${table}` };
+    },
+  },
+  {
+    name: 'db-row',
+    priority: 60,
+    matcher: (step: ParsedStep) => reRow.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      // [table] row where <filter> [has <expected>]
+      const m = step.text.match(new RegExp(`${TABLE}\\s+row\\s+where\\s+(.+?)(?:\\s+has\\s+(.+))?$`, 'i'))!;
+      const table = m[1];
+      const filter = parseFilter(m[2]);
+      const expected = m[3] ? parseExpected(m[3]) : '';
+      const args = expected ? `${JSON.stringify(table)}, ${filter}, ${expected}` : `${JSON.stringify(table)}, ${filter}`;
+      return { code: `await db.assertRow(${args});`, comment: `DB: row in ${table}` };
+    },
+  },
+];

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

@@ -11,6 +11,8 @@ import { scrollPatterns } from './scroll-patterns';
 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
@@ -36,6 +38,8 @@ export class PatternRegistry {
     this.patterns.push(...scopePatterns);
     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));
@@ -165,4 +169,5 @@ export { keyboardPatterns } from './keyboard-patterns';
 export { scrollPatterns } from './scroll-patterns';
 export { scopePatterns } from './scope-patterns';
 export { tablePatterns } from './table-patterns';
+export { databasePatterns, isDbStep } from './database-patterns';
 export * from './types';

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

@@ -229,8 +229,8 @@ export class TemplateEngine {
     this.baseContext = {};
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean }): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport });
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string {
+    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb });
   }
 
   renderTestFile(data: {
@@ -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/audit.ts

@@ -4,7 +4,7 @@
  *
  * The score is INTENTIONALLY weighted toward business-critical coverage/depth
  * (not breadth), so it surfaces the gaps a count-based view hides. See
- * docs/orchestration-spec.md §5 and reports/sungen_home_gherkin_viewpoint_coverage_review.md.
+ * docs/orchestration-spec.md §5 and docs/spec/sungen_refactor_spec.md.
  */
 import * as path from 'path';
 import * as fs from 'fs';

package/src/harness/capability-plan.ts

@@ -4,7 +4,7 @@
  * Classifies each scenario's execution mode + each @manual case by reason code
  * (M1–M9), maps capability-reasons to drivers, and emits the manual-reason KPI.
  * Never installs anything (that's `sungen capability add`). See
- * reports/sungen_phase2b_spec.md.
+ * docs/spec/sungen_phase2b_spec.md.
  */
 import * as fs from 'fs';
 import * as path from 'path';

package/src/harness/catalog/drivers.yaml

@@ -1,6 +1,6 @@
 # Driver Catalog (metadata only — NO driver code is bundled here).
 # Lets Sungen RECOMMEND/RESOLVE a driver that may not be installed yet, and tells
-# `sungen capability add` which package to install. See reports/sungen_phase2a_spec.md.
+# `sungen capability add` which package to install. See docs/spec/sungen_phase2a_spec.md.
 #
 # kind: platform → the runtime/codegen adapter for a target (pick ONE per project)
 # kind: capability → an extra ability added on top of a platform (Phase 3)

package/src/harness/catalog/universal-viewpoints.yaml

@@ -5,7 +5,7 @@
 #
 # Each page-type lists must-cover themes. A theme is "covered" when the project's
 # viewpoint-overview (or generated scenarios) contains one of its keywords.
-# See docs/orchestration-spec.md §5.2 and reports/sungen_refactor_spec.md §9.
+# See docs/orchestration-spec.md §5.2 and docs/spec/sungen_refactor_spec.md §9.
 #
 # `depth:` (optional, harness-roadmap P1) marks a theme as DATA-correctness:
 #   requires: data-assertion  → scenarios on this theme must assert DATA (not just