@sungen/driver-mock 3.2.19

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@sungen/driver-mock",
+  "version": "3.2.19",
+  "description": "Sungen Mock capability (Network Mocking) — the @mock tag, mocks.yaml catalog, mock-install/call-count steps, and the specs/mock.ts runtime template. Plugs into @sun-asterisk/sungen via the capability SPI.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "sungen": {
+    "capability": "mock"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json"
+  },
+  "author": "eqe team (engineer & quality) — Sun Asterisk",
+  "license": "MIT",
+  "dependencies": {
+    "@sun-asterisk/sungen": "3.2.19"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @sungen/driver-mock — Sungen Mock capability (network mocking).
+ *
+ * Owns the `@mock` tag family: the mocks.yaml catalog (self-contained named
+ * responses), the mock-install / call-count step patterns, and the specs/mock.ts
+ * runtime template (module singleton + WeakMap<Page, MockState> — state follows
+ * page lifetime on both the per-test and @serial paths). Plugs into core via the
+ * capability SPI; core discovers and calls `register()` at runtime.
+ *
+ * Blocking posture (spec: sungen_mock_driver_spec.md §5): once a scenario has any
+ * active mock, a catch-all route fails the test on any unmatched fetch/XHR/websocket
+ * request (fail-on-unmocked, the locked default). `@mock:passthrough` on a scenario
+ * opts out — named mocks still apply, the rest reaches the real backend.
+ */
+import type { CapabilityRegistry } from '@sun-asterisk/sungen';
+import { mockPatterns, isMockStep } from './patterns/mock-patterns';
+
+/**
+ * `@mock:passthrough` → relax the catch-all for this scenario. Emitted as a
+ * precondition so the flag is set before any request fires; the plain `@mock`
+ * tag needs no precondition (install steps carry the behavior).
+ */
+function mockPreconditionCodegen(input: { tags: string[]; screenName: string; cwd: string }): Array<{ comment?: string; code: string; boundVars?: string[] }> {
+  if (!input.tags.some((t) => t === '@mock:passthrough')) return [];
+  return [{
+    comment: '@mock:passthrough — unmatched requests reach the real backend for this scenario',
+    code: 'mock.setPassthrough(page);',
+  }];
+}
+
+/** Register the Mock capability. */
+export function register(registry: CapabilityRegistry): void {
+  registry.register({
+    id: 'mock',
+    annotations: ['@mock', '@network'],
+    patterns: [...mockPatterns],
+    runtimeHelpers: [{ file: 'mock.ts', template: 'specs-mock.ts' }], // template resolved from core's templates dir
+    detectsStep: isMockStep, // mock steps activate the capability even without a tag
+    preconditionCodegen: mockPreconditionCodegen,
+  });
+}
+
+export const sungenDriver = { capability: 'mock', register } as const;

package/src/mock-catalog.ts

@@ -0,0 +1,117 @@
+/**
+ * mocks.yaml catalog loader — `qa/screens/<name>/mock/mocks.yaml`.
+ *
+ * Every entry is a named, self-contained response definition (no api_ref
+ * indirection — mocks are reviewable and secret-scannable in one file):
+ *
+ *   reservations-check-500:
+ *     method: POST                     # required — HTTP verb or "*"
+ *     url: "**\/api/reservations/check" # required — page.route glob; "re:" prefix = regex
+ *     status: 500                      # required
+ *     headers: { content-type: application/json }   # optional
+ *     body: { message: "Internal Server Error" }    # optional — inline, or a "{{var}}" test-data ref
+ *     delay_ms: 5000                   # optional — hold the response N ms (the timeout simulator)
+ *
+ * The loader ERRORS on an incomplete or unknown-keyed entry, naming the entry and
+ * the valid keys — a malformed mock must never silently vanish from the suite
+ * (the api-catalog loader's silent `continue` is a known trap, deliberately not
+ * copied). There is no `abort` on purpose: route.abort() is a network error
+ * (ERR_FAILED), not a timeout — a mock named "timeout" that aborts makes tests
+ * green for the wrong reason. mocks.yaml is COMMITTED: credentials in bodies must
+ * be `${QA_*}` refs (the secret scan covers mock/*.yaml).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+
+export interface MockEntry {
+  name: string;
+  method: string;
+  url: string;
+  status: number;
+  headers?: Record<string, string>;
+  body?: unknown;
+  delay_ms?: number;
+}
+
+const VALID_KEYS = ['method', 'url', 'status', 'headers', 'body', 'delay_ms'];
+const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', '*'];
+
+/** Absolute path of a unit's mock catalog (screens only in MVP — the locked unit shape). */
+export function mockCatalogPath(screenName: string, cwd: string = process.cwd()): string {
+  return path.join(cwd, 'qa', 'screens', screenName, 'mock', 'mocks.yaml');
+}
+
+/** Load and validate the unit's catalog. Missing file → empty catalog (steps then error by name). */
+export function loadMockCatalog(screenName: string, cwd: string = process.cwd()): Record<string, MockEntry> {
+  const p = mockCatalogPath(screenName, cwd);
+  if (!fs.existsSync(p)) return {};
+  const raw = parseYaml(fs.readFileSync(p, 'utf-8'));
+  if (raw === null || raw === undefined) return {};
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${rel(p, cwd)}: expected a map of named mock entries`);
+  }
+  const catalog: Record<string, MockEntry> = {};
+  for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
+    catalog[name] = validateEntry(name, value, rel(p, cwd));
+  }
+  return catalog;
+}
+
+/** Resolve one entry by name — throws listing the valid names (fail-fast at compile). */
+export function resolveMock(name: string, screenName: string, cwd: string = process.cwd()): MockEntry {
+  const catalog = loadMockCatalog(screenName, cwd);
+  const entry = catalog[name];
+  if (!entry) {
+    const names = Object.keys(catalog);
+    const hint = names.length
+      ? `valid names: ${names.join(', ')}`
+      : `no catalog found — create ${rel(mockCatalogPath(screenName, cwd), cwd)} (mock catalogs are SCREEN units in this version; flows are not yet supported)`;
+    throw new Error(`mock "${name}" is not defined for screen "${screenName}" — ${hint}`);
+  }
+  return entry;
+}
+
+function validateEntry(name: string, value: unknown, file: string): MockEntry {
+  const where = `${file}: mock "${name}"`;
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${where}: entry must be a map with keys ${VALID_KEYS.join('/')}`);
+  }
+  const obj = value as Record<string, unknown>;
+  const unknown = Object.keys(obj).filter((k) => !VALID_KEYS.includes(k));
+  if (unknown.length) {
+    throw new Error(`${where}: unknown key(s) ${unknown.join(', ')} — valid keys: ${VALID_KEYS.join(', ')}` +
+      (unknown.includes('abort') ? ' (no `abort`: route.abort() is a network error, not a timeout — use a large delay_ms)' : ''));
+  }
+  const method = String(obj.method ?? '').toUpperCase();
+  if (!obj.method || !METHODS.includes(method)) {
+    throw new Error(`${where}: "method" is required and must be one of ${METHODS.join('/')}`);
+  }
+  if (!obj.url || typeof obj.url !== 'string') {
+    throw new Error(`${where}: "url" is required (a page.route glob, or "re:<pattern>" for a regex)`);
+  }
+  const status = Number(obj.status);
+  if (obj.status === undefined || !Number.isInteger(status) || status < 100 || status > 599) {
+    throw new Error(`${where}: "status" is required and must be an HTTP status code (100-599)`);
+  }
+  if (obj.delay_ms !== undefined && (!Number.isFinite(Number(obj.delay_ms)) || Number(obj.delay_ms) < 0)) {
+    throw new Error(`${where}: "delay_ms" must be a non-negative number`);
+  }
+  if (obj.headers !== undefined && (typeof obj.headers !== 'object' || obj.headers === null || Array.isArray(obj.headers))) {
+    throw new Error(`${where}: "headers" must be a map of header name → value`);
+  }
+  return {
+    name,
+    method,
+    url: obj.url,
+    status,
+    headers: obj.headers as Record<string, string> | undefined,
+    body: obj.body,
+    delay_ms: obj.delay_ms === undefined ? undefined : Number(obj.delay_ms),
+  };
+}
+
+function rel(p: string, cwd: string): string {
+  return path.relative(cwd, p) || p;
+}

package/src/patterns/mock-patterns.ts

@@ -0,0 +1,96 @@
+/**
+ * Mock step patterns — catalog-ref grammar only (no inline request definitions):
+ *
+ *   Given [reservations-check-500] mock is active
+ *   Then User see [reservations-check-500] mock called {{n}} times   # also: called 1 time
+ *
+ * `[name]` is a CATALOG reference, not a selector — the pattern parses the bracket
+ * and resolves the entry from mocks.yaml at COMPILE time (unknown name = compile
+ * error listing valid names), then inlines the response config into the generated
+ * spec. A `{{var}}` body compiles to JSON.stringify(testData.raw('var')) directly —
+ * never through the marker pipeline.
+ *
+ * Priority 70-73: band 60 is taken by the db patterns — sharing it would make
+ * capability composition depend on registration-order tie-breaks. Matchers run on
+ * MASKED text ([name] → [~]) and anchor on the `mock is active` / `mock called`
+ * discriminators, which live outside the bracket.
+ */
+
+import { StepPattern } from '@sun-asterisk/sungen';
+import { MockEntry, resolveMock } from '../mock-catalog';
+
+const reInstallMasked = /\[~\]\s+mock\s+is\s+active\b/i;
+const reCallCountMasked = /\[~\]\s+mock\s+called\s+(?:\{\{~\}\}|\d+)\s+times?\b/i;
+
+/** The capability is active for a feature when any step speaks mock grammar (no tag needed). */
+export function isMockStep(text: string): boolean {
+  // Raw-text twins of the masked matchers (callers pass ORIGINAL step text here).
+  return /\[[^\]]+\]\s+mock\s+is\s+active\b/i.test(text) ||
+         /\[[^\]]+\]\s+mock\s+called\s+(?:\{\{[^}]+\}\}|\d+)\s+times?\b/i.test(text);
+}
+
+/** Bracket content from the ORIGINAL text (resolvers never see masked text). */
+function mockName(text: string): string {
+  const m = text.match(/\[([^\]]+)\]\s+mock\b/i);
+  return m ? m[1] : '';
+}
+
+/**
+ * Render the entry as the JS config object literal `mock.install` receives.
+ * The body is serialized HERE (compile time): a `"{{var}}"` body becomes a
+ * runtime testData.raw() expression; anything else is baked in as JSON.
+ */
+function entryExpr(entry: MockEntry): string {
+  const parts = [
+    `name: ${JSON.stringify(entry.name)}`,
+    `method: ${JSON.stringify(entry.method)}`,
+    `url: ${JSON.stringify(entry.url)}`,
+    `status: ${entry.status}`,
+  ];
+  if (entry.headers) parts.push(`headers: ${JSON.stringify(entry.headers)}`);
+  if (entry.delay_ms !== undefined) parts.push(`delay_ms: ${entry.delay_ms}`);
+  if (entry.body !== undefined) {
+    const ref = typeof entry.body === 'string' && /^\{\{\s*([^}]+?)\s*\}\}$/.exec(entry.body);
+    parts.push(ref
+      ? `body: JSON.stringify(testData.raw(${JSON.stringify(ref[1])}))`
+      : `body: ${JSON.stringify(JSON.stringify(entry.body))}`);
+  }
+  return `{ ${parts.join(', ')} }`;
+}
+
+export const mockPatterns: StepPattern[] = [
+  {
+    name: 'mock-install',
+    matcher: (step) => reInstallMasked.test(step.text),
+    generator: (step, context) => {
+      const name = mockName(step.text);
+      const entry = resolveMock(name, context.screenName || context.featureName || '', process.cwd());
+      return {
+        code: `await mock.install(page, ${entryExpr(entry)});`,
+        comment: `Mock ${name}: ${entry.method} ${entry.url} → ${entry.status}${entry.delay_ms ? ` after ${entry.delay_ms}ms` : ''}`,
+      };
+    },
+    priority: 70,
+  },
+  {
+    name: 'mock-call-count',
+    matcher: (step) => reCallCountMasked.test(step.text),
+    generator: (step, context) => {
+      const name = mockName(step.text);
+      // Compile-time validation: the name must exist in the catalog (a typo here
+      // otherwise becomes a runtime "never installed" that reads like a test bug).
+      resolveMock(name, context.screenName || context.featureName || '', process.cwd());
+      const m = step.text.match(/called\s+(\{\{[^}]+\}\}|\d+)\s+times?\b/i);
+      const raw = m ? m[1] : '0';
+      const v = raw.match(/^\{\{\s*([^}]+?)\s*\}\}$/);
+      const expected = v ? `Number(testData.get(${JSON.stringify(v[1])}))` : raw;
+      // callCount THROWS for a name never installed in this scenario — an exact 0
+      // on an uninstalled mock must be a loud error, not a passing assertion.
+      return {
+        code: `expect(mock.callCount(page, ${JSON.stringify(name)}), ${JSON.stringify(`mock ${name} call count`)}).toBe(${expected});`,
+        comment: `Assert mock ${name} called ${raw} time(s)`,
+      };
+    },
+    priority: 71,
+  },
+];