@sungen/driver-db 3.1.2-beta.100

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@sungen/driver-db",
+  "version": "3.1.2-beta.100",
+  "description": "Sungen DB capability (Data Driver) — the @query annotation, query catalog, declarative DB steps, and the specs/db.ts runtime template. Plugs into @sun-asterisk/sungen via the capability SPI.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "sungen": {
+    "capability": "db",
+    "emitDependencies": {
+      "pg": "^8",
+      "better-sqlite3": "^11"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json"
+  },
+  "author": "eqe team (engineer & quality) — Sun Asterisk",
+  "license": "MIT",
+  "dependencies": {
+    "@sun-asterisk/sungen": "3.1.2-beta.100"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * @sungen/driver-db — Sungen DB capability (Data Driver).
+ *
+ * Owns the `@query` annotation: the named-query catalog (queries.yaml), the precondition codegen that
+ * binds a query result to `{{name}}`, the declarative DB step patterns, and the gate sensor that
+ * verifies every referenced query resolves + lints clean. Plugs into core via the capability SPI;
+ * core discovers and calls `register()` at runtime (core never imports this package).
+ *
+ * Relocated from core in R5.5 (was `database-patterns.ts` + the db parts of `builtins.ts`). Two
+ * pieces stay in core, mirroring the R5.4 boundary calls:
+ *  - `query-catalog` (resolve/compile/lint) — shared with core's data-driven advisory lint, so it
+ *    stays in core's harness and is imported here from `@sun-asterisk/sungen`;
+ *  - the `specs-db.ts` runtime-helper template — emitted by the core generator via `runtimeHelpers`
+ *    (resolved by filename from core's templates dir). Full relocation is an OE concern (#287).
+ * Verification of `@query` refs stays in core's generic `verification` gate sensor (it uses the
+ * core-resident catalog), so this driver registers no gate sensor.
+ */
+import type { CapabilityRegistry } from '@sun-asterisk/sungen';
+import { parseQueryOverrides, resolveQuery, compileQuery } from '@sun-asterisk/sungen';
+import { databasePatterns, isDbStep } from './patterns/database-patterns';
+
+/**
+ * DB precondition codegen: `@query:<name>[(p={{v}},…)]` → run the catalog query and bind its rows
+ * to `{{name}}`.
+ */
+function dbPreconditionCodegen(input: { tags: string[]; screenName: string; cwd: string }): Array<{ comment?: string; code: string; boundVars?: string[] }> {
+  const out: Array<{ comment?: string; code: string; boundVars?: string[] }> = [];
+  const TAG = /^@query:([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
+  for (const tag of input.tags) {
+    const m = tag.match(TAG);
+    if (!m) continue;
+    const name = m[1];
+    const overrides = parseQueryOverrides(m[2]);
+    const entry = resolveQuery(name, input.screenName, input.cwd); // 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: `testData.bind(${JSON.stringify(name)}, await db.fetchQuery(${label}, ${JSON.stringify(sql)}, [${paramExprs.join(', ')}], ${ds}));`,
+      boundVars: [name],
+    });
+  }
+  return out;
+}
+
+/** Register the DB (Data Driver) capability. */
+export function register(registry: CapabilityRegistry): void {
+  registry.register({
+    id: 'db',
+    annotations: ['@query'],
+    patterns: [...databasePatterns],
+    runtimeHelpers: [{ file: 'db.ts', template: 'specs-db.ts' }], // template resolved from core's templates dir
+    detectsStep: isDbStep, // declarative `User see [table] row where …` (no annotation tag)
+    preconditionCodegen: dbPreconditionCodegen, // @query:<name> → bind {{name}}
+  });
+}
+
+export const sungenDriver = { capability: 'db', register } as const;

package/src/patterns/database-patterns.ts

@@ -0,0 +1,96 @@
+import { ParsedStep } from '@sun-asterisk/sungen';
+import { StepPattern, PatternContext } from '@sun-asterisk/sungen';
+import { MappedStep } from '@sun-asterisk/sungen';
+
+/**
+ * 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}` };
+    },
+  },
+];