@sun-asterisk/sungen 3.0.1 → 3.1.0

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

@@ -11,6 +11,7 @@ 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';
 
 /**
  * Pattern Registry - manages all step patterns
@@ -36,6 +37,7 @@ export class PatternRegistry {
     this.patterns.push(...scopePatterns);
     this.patterns.push(...tablePatterns);
     this.patterns.push(...capturePatterns);
+    this.patterns.push(...databasePatterns);
 
     // Sort by priority (higher first)
     this.patterns.sort((a, b) => (b.priority || 0) - (a.priority || 0));
@@ -165,4 +167,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/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: {

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

package/src/harness/flow-plan.ts

@@ -5,7 +5,7 @@
  * leg's SELECTOR READINESS + capability, folds in the manual-reason taxonomy
  * (capability-plan) and the run-test contract (flow-check), and emits a run-test
  * PLAN. Automates the manual diagnosis done while healing cart-and-filter.
- * See reports/sungen_phase2c_spec.md.
+ * See docs/spec/sungen_phase2c_spec.md.
  */
 import * as fs from 'fs';
 import * as path from 'path';

package/src/harness/script-check.ts

@@ -68,7 +68,10 @@ export function analyzeFaithfulness(specSrc: string, automatedTitles: Set<string
   for (const blk of extractTestBlocks(specSrc)) {
     if (!automatedTitles.has(blk.title)) continue; // only non-@manual scenarios
     const body = blk.body;
-    if (!body.some((l) => /expect\(/.test(l))) assertionlessTests.push(blk.title);
+    // An assertion is a Playwright `expect(...)` OR a Data Driver DB assertion
+    // (`db.assertRow/assertNoRow/assertCount/...`) — a DB check is a real oracle, so a
+    // DB-only scenario (no UI expect) is NOT a bypass.
+    if (!body.some((l) => /expect\(|\bdb\.assert\w*\s*\(/.test(l))) assertionlessTests.push(blk.title);
     // hollow step: a `// step` whose region (until the NEXT step-comment / block end)
     // contains no executable code. The region — not just the next line — is checked,
     // so block-style steps (`// Assert all … { … expect … }`) are correctly counted.

package/src/orchestrator/templates/ai-instructions/claude-skill-harness-audit.md

@@ -81,4 +81,4 @@ domain rủi ro+defect?→ YES: Defect-first
 → hỏi QA; QA chưa phản hồi → OUTPUT kèm ASSUMPTION LIST rõ ràng (không stall)
 ```
 
-See `docs/orchestration-spec.md` for the full flow and `reports/sungen_refactor_spec.md` for the design rationale.
+See `docs/orchestration-spec.md` for the full flow and `docs/spec/sungen_refactor_spec.md` for the design rationale.

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-harness-audit.md

@@ -81,4 +81,4 @@ domain rủi ro+defect?→ YES: Defect-first
 → hỏi QA; QA chưa phản hồi → OUTPUT kèm ASSUMPTION LIST rõ ràng (không stall)
 ```
 
-See `docs/orchestration-spec.md` for the full flow and `reports/sungen_refactor_spec.md` for the design rationale.
+See `docs/orchestration-spec.md` for the full flow and `docs/spec/sungen_refactor_spec.md` for the design rationale.

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

@@ -0,0 +1,147 @@
+/* eslint-disable */
+/**
+ * Sungen Data Driver — runtime DB-verification helper (auto-generated into specs/db.ts).
+ *
+ * Read-only by construction: it only ever issues a single parameterized SELECT, and
+ * table/column identifiers are validated against a strict allowlist pattern (identifiers
+ * can't be bound as parameters). Secrets come from .env.qa / process.env, never inline.
+ *
+ * Engines: PostgreSQL (`pg`) and SQLite (`better-sqlite3`), lazy-loaded on first use.
+ * Config: a `datasources.yaml` at the project root (or qa/), with ${VAR} resolved from env.
+ *
+ * DO NOT EDIT — regenerated by `sungen generate`.
+ */
+import { expect } from '@playwright/test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ident = (s: string): string => {
+  if (!IDENT.test(s)) throw new Error(`Unsafe identifier: ${JSON.stringify(s)} (allowed: [A-Za-z_][A-Za-z0-9_]*)`);
+  return s;
+};
+
+interface DataSourceConfig {
+  engine: 'postgres' | 'mysql' | 'sqlite';
+  url: string;
+  readonly?: boolean;
+  statement_timeout_ms?: number;
+  max_rows?: 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, DataSourceConfig> {
+  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('Data Driver: no datasources.yaml found (project root or qa/).');
+  let 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) || {};
+  if (!doc.datasources || typeof doc.datasources !== 'object') {
+    throw new Error('Data Driver: datasources.yaml must define a top-level `datasources:` map.');
+  }
+  return doc.datasources;
+}
+
+type Engine = { query(sql: string, params: any[]): Promise<any[]>; };
+
+class DataSource {
+  private configs: Record<string, DataSourceConfig> | null = null;
+  private engines = new Map<string, Engine>();
+
+  private cfg(name?: string): { key: string; conf: DataSourceConfig } {
+    if (!this.configs) this.configs = loadConfig();
+    const key = name || Object.keys(this.configs)[0];
+    const conf = this.configs[key];
+    if (!conf) throw new Error(`Data Driver: datasource "${key}" not found in datasources.yaml`);
+    return { key, conf };
+  }
+
+  private async engine(name?: string): Promise<{ engine: Engine; conf: DataSourceConfig }> {
+    const { key, conf } = this.cfg(name);
+    if (this.engines.has(key)) return { engine: this.engines.get(key)!, conf };
+    if (!conf.url) throw new Error(`Data Driver: datasource "${key}" has no url (set it in .env.qa).`);
+    let engine: Engine;
+    if (conf.engine === 'postgres') {
+      const { Pool } = require('pg');
+      const pool = new Pool({ connectionString: conf.url, max: 2, statement_timeout: conf.statement_timeout_ms ?? 4000 });
+      engine = { query: async (sql, params) => (await pool.query(sql, params)).rows };
+    } else if (conf.engine === 'sqlite') {
+      const Database = require('better-sqlite3');
+      const db = new Database(conf.url.replace(/^sqlite:/, ''), { readonly: conf.readonly !== false });
+      engine = { query: async (sql, params) => db.prepare(sql).all(...params) };
+    } else {
+      throw new Error(`Data Driver: engine "${conf.engine}" not supported yet (postgres | sqlite).`);
+    }
+    this.engines.set(key, engine);
+    return { engine, conf };
+  }
+
+  private build(table: string, filter: Record<string, any>): { sql: string; params: any[] } {
+    const cols = Object.keys(filter);
+    const where = cols.map((c, i) => `${ident(c)} = $${i + 1}`).join(' AND ');
+    const sql = `SELECT * FROM ${ident(table)}${where ? ' WHERE ' + where : ''} LIMIT 50`;
+    return { sql, params: cols.map((c) => filter[c]) };
+  }
+
+  /** A row matching `filter` must exist; if `expected` given, assert those columns on the first match. */
+  async assertRow(table: string, filter: Record<string, any>, expected?: Record<string, any>, datasource?: string): Promise<void> {
+    const { engine, conf } = await this.engine(datasource);
+    const { sql, params } = this.build(table, filter);
+    const rows = await engine.query(this.sqlFor(conf, sql), params);
+    expect(rows.length, `Expected a row in "${table}" where ${desc(filter)} — found ${rows.length}`).toBeGreaterThanOrEqual(1);
+    if (expected) {
+      const row = rows[0];
+      for (const [col, val] of Object.entries(expected)) {
+        ident(col);
+        expect(String(row[col]), `Column "${col}" of "${table}" where ${desc(filter)}`).toBe(String(val));
+      }
+    }
+  }
+
+  /** No row matching `filter` may exist. */
+  async assertNoRow(table: string, filter: Record<string, any>, datasource?: string): Promise<void> {
+    const { engine, conf } = await this.engine(datasource);
+    const { sql, params } = this.build(table, filter);
+    const rows = await engine.query(this.sqlFor(conf, sql), params);
+    expect(rows.length, `Expected NO row in "${table}" where ${desc(filter)} — found ${rows.length}`).toBe(0);
+  }
+
+  /** Exactly `count` rows must match `filter`. */
+  async assertCount(table: string, filter: Record<string, any>, count: number, datasource?: string): Promise<void> {
+    const { engine, conf } = await this.engine(datasource);
+    const cols = Object.keys(filter);
+    const where = cols.map((c, i) => `${ident(c)} = $${i + 1}`).join(' AND ');
+    const sql = `SELECT count(*) AS n FROM ${ident(table)}${where ? ' WHERE ' + where : ''}`;
+    const rows = await engine.query(this.sqlFor(conf, sql), cols.map((c) => filter[c]));
+    const n = Number(rows[0]?.n ?? rows[0]?.['count(*)'] ?? 0);
+    expect(n, `Expected ${count} row(s) in "${table}"${cols.length ? ' where ' + desc(filter) : ''} — found ${n}`).toBe(Number(count));
+  }
+
+  /** Rewrites $1/$2 placeholders to `?` for SQLite. */
+  private sqlFor(conf: DataSourceConfig, sql: string): string {
+    return conf.engine === 'sqlite' ? sql.replace(/\$\d+/g, '?') : sql;
+  }
+}
+
+function desc(filter: Record<string, any>): string {
+  return Object.entries(filter).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(', ');
+}
+
+export const db = new DataSource();