@sun-asterisk/sungen 3.1.0 → 3.1.2-beta.100

package/src/orchestrator/templates/ai-instructions/claude-skill-test-design-techniques.md

@@ -17,6 +17,12 @@ Apply selectively — not every screen needs all four techniques. Use the techni
 
 **Rule:** These techniques determine **how many** and **which** scenarios to generate. `sungen-viewpoint` determines **which viewpoints** to cover.
 
+**Implementing the data table → `@cases` (data-driven):** when EP classes / BVA boundary triples /
+decision-table rows share the *same step shape* and differ only by input/expected values, encode
+them as ONE `@cases:<dataset>` scenario (each class/boundary/rule = one row in the test-data list,
+labelled by a `case` column) instead of N near-duplicate scenarios. The technique still decides the
+rows; `@cases` is how you write them compactly. See `sungen-gherkin-syntax` → Data-driven.
+
 ---
 
 ## 1. Equivalence Partitioning (EP)

package/src/orchestrator/templates/ai-instructions/copilot-cmd-create-test.md

@@ -26,9 +26,10 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
    **Screen**: Verify `qa/screens/${input:name}/` exists. If not → `/sungen-add-screen` first.
 2. Check if `.feature` already has scenarios.
    - If yes → summarize existing coverage and ask update mode (options depend on which tiers already exist — see `sungen-tc-generation` skill for details).
-   - If no → fresh creation. Ask generation scope:
-     - **1) Tier 1 — Critical & High priority** — ~10-15 scenarios/section covering happy paths, core validation, security basics **(Recommended)**
-     - **2) Full coverage — All tiers at once** — generates Tier 1 + 2 + 3 in one run. Large output (~40-60 scenarios/section), best for experienced users who want complete coverage immediately
+   - If no → fresh creation. **Write the feature file incrementally** (successive writes/edits, ≈10-15 scenarios per call) — never emit the whole suite in one response, or it can exceed the model's output-token cap (`response exceeded the N output token maximum`). Ask generation scope:
+     - **1) Tier 1 — Critical & High priority** — ~10-15 scenarios/section: happy paths, core validation, security basics **(Recommended)**
+     - **2) Full coverage (incremental)** — Tier 1 + 2 + 3, written tier-by-tier in batches. Safe on any output-token budget.
+     - **3) Full coverage (single pass)** — everything in one go (~40-60 scenarios/section). Faster, but **only if you raised your output cap** (`CLAUDE_CODE_MAX_OUTPUT_TOKENS ≥ 64000`) — otherwise it errors mid-generation. For power users on a high-token model/config.
 3. **Read project context + screen requirements**
 
    **Project context** — check `qa/context.md` (project root, not screen-specific):

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-gherkin-syntax.md

@@ -102,6 +102,22 @@ User see [Table] table match data:
 
 Row scope: `see [Ref] row in [Table] table with {{v}}` enters scope. Subsequent `see [Col] column with {{v}}` checks cell in that row. Use `table match data:` for multi-row verification.
 
+### Database verification (optional Data Driver)
+
+Read-only DB-state checks. **Prefer named queries** — SQL lives in `qa/screens/<screen>/database/queries.yaml` (reviewed once, parameterized). Invoke with the `@query:<name>` annotation; it binds the result rows to `{{name}}`, then assert with `expect`:
+
+```gherkin
+@query:active_user                 # precondition: run query, bind {{active_user}}
+@query:orders(buyer={{email}})     # …with explicit param override
+Scenario: ...
+  Then expect {{active_user.count}} is at least {{one}}   # ≥1 row
+  And  expect {{active_user.first.status}} is "active"     # first row's column
+  And  expect {{orders.count}} is {{expected}}             # exact count
+  And  User see [Total] text is {{orders.first.total}}     # UI ↔ DB
+```
+
+Path access on a bound result: `{{q.count}}`/`{{q.length}}`, `{{q.first.col}}`, `{{q.last.col}}`, `{{q[2].col}}`, `{{q.col}}` (= first row's col). `expect A is B` also supports `is at least` / `is at most` / `is not`. Tier-2 declarative (trivial inline, no catalog): `User see [<table>] row where [<col>] is {{v}} [has [<col2>] = "x"]`, `… no row where …`, `… count is {{n}}`. Full grammar + catalog/datasource/secret rules → **Advanced → Database** doc. Only emit DB steps when the project has a `database/` catalog / `datasources.yaml`.
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
@@ -195,6 +211,31 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
 | `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |
 | `@flow` | Mark feature as E2E flow (cross-screen testing) |
+| `@cases:dataset` | Data-driven: run the scenario once per row of the `dataset` LIST in test-data → one `test()` per row |
+| `@query:name` | Database: run the named query from `database/queries.yaml` (precondition) and bind its rows to `{{name}}`; assert with `expect {{name.count}} …` + path access. Override params `@query:name(p={{v}})`. Repeatable. (Optional Data Driver — see Database verification above) |
+| `@api:name` | API: run the named request from `api/apis.yaml` (precondition) and bind the response to `{{name}}`; assert with `expect {{name.status}} …` + path access (`{{name.body.<path>}}`). Override params `@api:name(p={{v}})`. Repeatable. (Optional API Driver) |
+
+### Data-driven scenarios (`@cases`)
+
+For one test case × many inputs (email/format/boundary validation, decision tables), tag the
+scenario `@cases:<dataset>` and reference each row's columns as `{{col}}`. Put the rows as a LIST
+in test-data — NOT inline; data stays runtime + env-overlayable.
+
+```gherkin
+@high @cases:email_validation
+Scenario: VP-VAL-001 The email field rejects invalid formats
+  When User fill [Email] field with {{email}}
+  Then User see [Login Error] message with {{expected_error}}
+```
+```yaml
+# test-data/<screen>.yaml
+email_validation:
+  - { case: "no @",    email: "plainaddress", expected_error: "Invalid email" }
+  - { case: "valid",   email: "ok@x.com",     expected_error: "" }
+```
+An optional `case`/`name`/`label` column labels each run. Each row → its own pass/fail. Prefer
+`@cases` over duplicating a scenario per value. (Gherkin `Scenario Outline`/`Examples` is NOT
+supported — use `@cases`.)
 
 ### Pass-through tags (filter at runtime via Playwright --grep)
 

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-tc-generation.md

@@ -6,6 +6,9 @@ user-invocable: false
 
 ## ⚠️ Gotchas — read before generating
 
+- **Write incrementally — never emit the whole suite in one response.** Build the `.feature` in batches via successive `Write`/`Edit` (≈10–15 scenarios per call). For **Full coverage**, write tier-by-tier: `Write` Tier 1 → `Edit` append Tier 2 → `Edit` append Tier 3.
+  → One huge `Write` can exceed the model's output-token cap → `API Error: Claude's response exceeded the N output token maximum`. Single-pass full coverage only fits when `CLAUDE_CODE_MAX_OUTPUT_TOKENS ≥ 64000`; otherwise batch. Batching also lets the audit/reviewer run per batch — higher quality.
+
 - `spec_figma.md` exists → read file only, **NEVER** call `mcp__figma__*`
   → PAT auth flow already done by `sungen-capture` (mode figma-pat); re-calling fails or duplicates work.
 
@@ -54,6 +57,25 @@ user-invocable: false
   OR condition: generate 1 scenario per branch where that branch alone triggers the outcome.
   → Happy-path only = missing the most common multi-condition implementation bug.
 
+- **Many inputs, same steps → ONE data-driven scenario (`@cases`), not N copies:**
+  When a rule needs lots of inputs with the *same* step shape (email/format validation,
+  BVA boundary triples, EP classes, decision-table rows), tag one scenario `@cases:<dataset>`,
+  reference each row's columns as `{{col}}`, and put the rows as a LIST in test-data:
+  ```gherkin
+  @high @cases:email_validation
+  Scenario: VP-VAL-001 The email field rejects invalid formats
+    When User fill [Email] field with {{email}}
+    Then User see [Error] message with {{expected_error}}
+  ```
+  ```yaml
+  email_validation:
+    - { case: "no @",  email: "plainaddress", expected_error: "Invalid email" }
+    - { case: "valid", email: "ok@x.com",     expected_error: "" }
+  ```
+  → one `test()` per row, each labelled by `case`. Adding inputs = editing test-data (no recompile),
+  and env overlays apply. Prefer this over duplicating a scenario per value. (Gherkin
+  `Scenario Outline`/`Examples` is NOT supported — use `@cases`.)
+
 ---
 
 ## Tier System

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-tc-review.md

@@ -120,6 +120,7 @@ Build a mapping table: for each applicable group, does the feature have a matchi
 - **EP**: keep only **one representative** per invalid class; same-class duplicates → flag as redundant.
 - **BVA**: spec defines min/max → cover `min-1`, `min`, `max`, `max+1` (Maxlength, counts…).
 - Error messages must match the spec **word-for-word**, not generic.
+- **Data-driven (`@cases`)**: a `@cases:<dataset>` scenario legitimately covers many inputs in ONE scenario (one row per EP class / boundary / rule). Do **not** flag it as "too few negative cases" or as duplication — instead review the **dataset rows**: are all EP classes / boundary triples present, each labelled, expected values exact? N near-identical scenarios that differ only by input value → flag and recommend collapsing to `@cases`.
 
 ---
 

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-test-design-techniques.md

@@ -17,6 +17,12 @@ Apply selectively — not every screen needs all four techniques. Use the techni
 
 **Rule:** These techniques determine **how many** and **which** scenarios to generate. `sungen-viewpoint` determines **which viewpoints** to cover.
 
+**Implementing the data table → `@cases` (data-driven):** when EP classes / BVA boundary triples /
+decision-table rows share the *same step shape* and differ only by input/expected values, encode
+them as ONE `@cases:<dataset>` scenario (each class/boundary/rule = one row in the test-data list,
+labelled by a `case` column) instead of N near-duplicate scenarios. The technique still decides the
+rows; `@cases` is how you write them compactly. See `sungen-gherkin-syntax` → Data-driven.
+
 ---
 
 ## 1. Equivalence Partitioning (EP)

package/src/orchestrator/templates/specs-api.ts

@@ -0,0 +1,101 @@
+/* eslint-disable */
+/**
+ * Sungen API Driver — runtime helper (auto-generated into specs/api.ts).
+ *
+ * Runs a catalog-defined HTTP request and returns { status, ok, body, headers } — bound to a
+ * `{{name}}` variable by the `@api:<name>` annotation, asserted with `expect {{name.status}} …` /
+ * `{{name.body.<path>}}`. Base URL + auth come from a `kind: api` datasource in datasources.yaml,
+ * with `${VAR}` resolved from .env.qa / process.env — never inline.
+ *
+ * Safety: a datasource flagged `env: production` is refused unless SUNGEN_ALLOW_PROD=1.
+ * DO NOT EDIT — regenerated by `sungen generate`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface ApiDataSource {
+  kind?: string;
+  base_url?: string;
+  baseUrl?: string;
+  env?: string;
+  headers?: Record<string, string>;
+  timeout_ms?: number;
+}
+
+function loadEnvQa(): void {
+  for (const name of ['.env.qa', `.env.qa.${process.env.SUNGEN_ENV || ''}`]) {
+    const p = path.join(process.cwd(), name);
+    if (!name.endsWith('.') && fs.existsSync(p)) {
+      for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+        const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+        if (m && process.env[m[1]] === undefined) process.env[m[1]] = m[2].replace(/^["']|["']$/g, '');
+      }
+    }
+  }
+}
+
+function loadConfig(): Record<string, ApiDataSource> {
+  loadEnvQa();
+  const file = [path.join(process.cwd(), 'datasources.yaml'), path.join(process.cwd(), 'qa', 'datasources.yaml')].find((f) => fs.existsSync(f));
+  if (!file) throw new Error('API Driver: no datasources.yaml found (project root or qa/).');
+  const raw = fs.readFileSync(file, 'utf8').replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, k) => process.env[k] ?? '');
+  const { parse } = require('yaml');
+  const doc = parse(raw) || {};
+  return doc.datasources || {};
+}
+
+function substitute(text: string, params: Record<string, any>): string {
+  return text.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => encodeURIComponent(String(params[p] ?? '')));
+}
+
+class ApiClient {
+  private configs: Record<string, ApiDataSource> | null = null;
+
+  private cfg(name?: string): { key: string; conf: ApiDataSource } {
+    if (!this.configs) this.configs = loadConfig();
+    const key = name || Object.keys(this.configs).find((k) => (this.configs![k].kind || 'api') === 'api') || Object.keys(this.configs)[0];
+    const conf = this.configs[key];
+    if (!conf) throw new Error(`API Driver: datasource "${key}" not found in datasources.yaml`);
+    if (conf.env === 'production' && process.env.SUNGEN_ALLOW_PROD !== '1') {
+      throw new Error(`API Driver: datasource "${key}" is env: production — refused (set SUNGEN_ALLOW_PROD=1 to override).`);
+    }
+    return { key, conf };
+  }
+
+  /** Run a catalog request and return the response. `req` is embedded at compile time; `params` bind at runtime. */
+  async call(
+    label: string,
+    req: { method: string; path: string; body?: unknown; datasource?: string },
+    params: Record<string, any> = {},
+  ): Promise<{ status: number; ok: boolean; body: any; headers: Record<string, string> }> {
+    const { conf } = this.cfg(req.datasource);
+    const base = (conf.base_url || conf.baseUrl || '').replace(/\/$/, '');
+    if (!base) throw new Error(`API Driver: ${label} — datasource has no base_url (set it in .env.qa).`);
+    const url = base + substitute(req.path, params);
+
+    let body: string | undefined;
+    const headers: Record<string, string> = { ...(conf.headers || {}) };
+    if (req.body !== undefined && req.body !== null) {
+      const resolved = JSON.parse(JSON.stringify(req.body).replace(/":([A-Za-z_][A-Za-z0-9_]*)"/g, (_m, p) => JSON.stringify(params[p] ?? null)));
+      body = JSON.stringify(resolved);
+      if (!headers['content-type'] && !headers['Content-Type']) headers['content-type'] = 'application/json';
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), conf.timeout_ms ?? 15000);
+    let res: Response;
+    try {
+      res = await fetch(url, { method: req.method, headers, body, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let parsed: any = text;
+    try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }
+    const outHeaders: Record<string, string> = {};
+    res.headers.forEach((v, k) => { outHeaders[k] = v; });
+    return { status: res.status, ok: res.ok, body: parsed, headers: outHeaders };
+  }
+}
+
+export const api = new ApiClient();

package/src/orchestrator/templates/specs-db.ts

@@ -138,6 +138,28 @@ class DataSource {
   private sqlFor(conf: DataSourceConfig, sql: string): string {
     return conf.engine === 'sqlite' ? sql.replace(/\$\d+/g, '?') : sql;
   }
+
+  // --- Named queries (catalog-backed; SQL is resolved + embedded at compile time) -----------
+  /** Read-only guard (second layer): a named query must be a single SELECT/WITH statement. */
+  private assertSelectOnly(label: string, sql: string): void {
+    const s = sql.trim().replace(/;\s*$/, '');
+    if (!/^(SELECT|WITH)\b/i.test(s)) throw new Error(`Data Driver: ${label} is not a read-only SELECT — refused.`);
+    if (s.includes(';')) throw new Error(`Data Driver: ${label} contains multiple statements — refused.`);
+    if (/\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE|GRANT|REVOKE|MERGE|REPLACE|CALL|EXEC|EXECUTE|ATTACH|PRAGMA|VACUUM)\b/i.test(s)) {
+      throw new Error(`Data Driver: ${label} contains a write/DDL keyword — refused.`);
+    }
+  }
+
+  /**
+   * Run a catalog query (read-only) and return its rows. The result is bound to a `{{name}}`
+   * variable via `testData.bind(...)`, so the scenario asserts on it with `expect …` steps and
+   * path access (`{{name.count}}`, `{{name.first.col}}`, `{{name[2].col}}`).
+   */
+  async fetchQuery(label: string, sql: string, params: any[], datasource?: string): Promise<any[]> {
+    this.assertSelectOnly(label, sql);
+    const { engine, conf } = await this.engine(datasource);
+    return engine.query(this.sqlFor(conf, sql), params);
+  }
 }
 
 function desc(filter: Record<string, any>): string {

package/src/orchestrator/templates/specs-test-data.ts

@@ -5,6 +5,8 @@ import yaml from 'yaml';
 
 export class TestDataLoader {
   private data: Record<string, any>;
+  // Data-driven (@cases): when set (via withRow), get() prefers this row's columns.
+  private row?: Record<string, any>;
 
   private constructor(data: Record<string, any>) {
     this.data = data;
@@ -41,23 +43,56 @@ export class TestDataLoader {
   }
 
   get(key: string): string {
-    // Captured/runtime vars (set() below) are stored under their literal — possibly
-    // dotted — key (e.g. "cart.product_name"), so check the flat key first.
-    let current: any = this.data[key];
-    if (current === undefined || current === null) {
-      // Fall back to nested navigation for YAML-structured keys (e.g. "cart.qty_two").
-      current = this.data;
-      for (const part of key.split('.')) {
-        if (current == null || typeof current !== 'object') {
-          throw new Error(`Test data key not found: ${key} (failed at '${part}')`);
-        }
-        current = current[part];
-      }
-    }
-    if (current === undefined || current === null) {
+    const value = this.resolve(key);
+    if (value === undefined || value === null) {
       throw new Error(`Test data key not found: ${key}`);
     }
-    return String(current);
+    return String(value);
+  }
+
+  /**
+   * Resolve a `{{...}}` reference to its raw value. Supports:
+   *  - flat keys (incl. captured runtime vars stored under a literal dotted key);
+   *  - `@cases` row columns (the current row wins);
+   *  - structured paths over nested data AND `@query`-bound result arrays:
+   *      `q.count` / `q.length`  → number of rows
+   *      `q.first.col` / `q.last.col` / `q[2].col` → a specific row's column
+   *      `q.col`                → shorthand for the first row's column
+   */
+  private resolve(key: string): any {
+    // 1. Exact flat key — captured vars (set()) live under a literal, possibly dotted, key.
+    if (this.row && key in this.row && this.row[key] !== undefined && this.row[key] !== null) {
+      return this.row[key];
+    }
+    if (this.data[key] !== undefined && this.data[key] !== null) {
+      return this.data[key];
+    }
+    // 2. Structured path: head from the row (cases) or shared data, then walk segments.
+    const tokens = String(key).replace(/\[(\d+)\]/g, '.$1').split('.');
+    let cur: any = (this.row && tokens[0] in this.row) ? this.row[tokens[0]] : this.data[tokens[0]];
+    for (let i = 1; i < tokens.length && cur != null; i++) cur = TestDataLoader.step(cur, tokens[i]);
+    return cur;
+  }
+
+  /** One navigation step over an array (with count/first/last/index/field-shorthand) or object. */
+  private static step(cur: any, token: string): any {
+    if (Array.isArray(cur)) {
+      if (token === 'count' || token === 'length') return cur.length;
+      if (token === 'first') return cur[0];
+      if (token === 'last') return cur[cur.length - 1];
+      if (/^\d+$/.test(token)) return cur[Number(token)];
+      return cur[0] == null ? undefined : cur[0][token]; // shorthand: first row's field
+    }
+    if (cur && typeof cur === 'object') return cur[token];
+    return undefined;
+  }
+
+  /**
+   * Bind a raw value (e.g. an `@query` result array) under `key` so `{{key.…}}` paths resolve.
+   * Unlike set(), the value is stored as-is (array/object), not coerced to a string.
+   */
+  bind(key: string, value: any): void {
+    this.data[key] = value;
   }
 
   /**
@@ -68,6 +103,32 @@ export class TestDataLoader {
   set(key: string, value: string): void {
     this.data[key] = value;
   }
+
+  /**
+   * Data-driven (@cases): return the list of rows at `key` (after env-overlay merge),
+   * each stamped with `__label` for the test title / report. Throws if missing or not a list.
+   */
+  cases(key: string): Array<Record<string, any>> {
+    const list = this.data[key];
+    if (!Array.isArray(list)) {
+      throw new Error(`@cases dataset "${key}" not found or not a list in test-data (got ${typeof list}).`);
+    }
+    return list.map((row: any, i: number) => {
+      const r: Record<string, any> = (row && typeof row === 'object' && !Array.isArray(row)) ? { ...row } : { value: row };
+      r.__label = String(r.case ?? r.name ?? r.label ?? `row ${i + 1}`);
+      return r;
+    });
+  }
+
+  /**
+   * Data-driven (@cases): a view whose get() prefers the given row's columns and falls
+   * back to the shared data. Used inside the per-row test() loop.
+   */
+  withRow(row: Record<string, any>): TestDataLoader {
+    const view = new TestDataLoader({ ...this.data }); // clone → per-row set() stays isolated
+    view.row = row;
+    return view;
+  }
 }
 
 function loadYamlSync(filePath: string): Record<string, any> | null {

package/dist/generators/test-generator/patterns/assertion-patterns.d.ts

@@ -1,7 +0,0 @@
-import { StepPattern } from './types';
-/**
- * Assertion patterns: visibility, text content, state, attributes
- * Uses template engine for framework-agnostic code generation
- */
-export declare const assertionPatterns: StepPattern[];
-//# sourceMappingURL=assertion-patterns.d.ts.map

package/dist/generators/test-generator/patterns/assertion-patterns.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"assertion-patterns.d.ts","sourceRoot":"","sources":["../../../../src/generators/test-generator/patterns/assertion-patterns.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAoB,MAAM,SAAS,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,EA2qB1C,CAAC"}