@sungen/driver-api 3.1.2-beta.111 → 3.1.2-beta.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-api",
-  "version": "3.1.2-beta.111",
+  "version": "3.1.2-beta.113",
   "description": "Sungen API capability — the @api annotation, API catalog, OpenAPI import + `sungen api import`, and the specs/api.ts runtime template. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -13,7 +13,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.1.2-beta.111",
+    "@sun-asterisk/sungen": "3.1.2-beta.113",
     "commander": "^14.0.2",
     "yaml": "^2.8.2"
   },

package/src/index.ts

@@ -55,6 +55,18 @@ export { importCsv, parseCsv } from './csv-import';
 function apiPreconditionCodegen(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 = /^@api:([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
+  // @concurrent:N (AP-5): fire each @api call N times in parallel and bind aggregates
+  // ({{name.ok_count}}, {{name.status_counts}}) — the idempotency/race oracle. Applies to the
+  // scenario's @api call(s); pair with @query to cross-check the DB ("exactly one charge").
+  const concMatch = input.tags.map((t) => t.match(/^@concurrent:(\d+)$/)).find(Boolean);
+  const concurrent = concMatch ? Math.max(1, parseInt(concMatch[1], 10)) : 0;
+  // @hybrid (AP-6): reuse the UI session — load the scenario's @auth:<role> storageState
+  // (specs/.auth/<role>.json, written by the auth global-setup before any test) so the API request
+  // carries the same authenticated cookies as the browser. No effect without an @auth role.
+  const authMatch = input.tags.map((t) => t.match(/^@auth:([A-Za-z0-9_-]+)$/)).find(Boolean);
+  const optsArg = input.tags.includes('@hybrid') && authMatch
+    ? `, { storageState: ${JSON.stringify(`specs/.auth/${authMatch[1]}.json`)} }`
+    : '';
   for (const tag of input.tags) {
     const m = tag.match(TAG);
     if (!m) continue;
@@ -71,9 +83,16 @@ function apiPreconditionCodegen(input: { tags: string[]; screenName: string; cwd
     // mechanism (the dynamic value comes via an override like `token={{login.body.token}}`).
     const hdr = entry.headers && Object.keys(entry.headers).length ? `, headers: ${JSON.stringify(entry.headers)}` : '';
     const req = `{ method: ${JSON.stringify(entry.method)}, path: ${JSON.stringify(entry.path)}${entry.body !== undefined ? `, body: ${JSON.stringify(entry.body)}` : ''}${hdr}, datasource: ${ds} }`;
+    // @concurrent:N → callN (N parallel calls, aggregate result); else a single call. @hybrid adds
+    // the storageState opts so the request reuses the UI auth session.
+    const callExpr = concurrent
+      ? `await api.callN(${label}, ${req}, { ${paramsObj} }, ${concurrent}${optsArg})`
+      : `await api.call(${label}, ${req}, { ${paramsObj} }${optsArg})`;
     out.push({
-      comment: `@api:${name} → bind {{${name}}} (${entry.method} ${entry.path})`,
-      code: `testData.bind(${JSON.stringify(name)}, await api.call(${label}, ${req}, { ${paramsObj} }));`,
+      comment: concurrent
+        ? `@api:${name} ×${concurrent} (@concurrent) → bind {{${name}}} aggregates (${entry.method} ${entry.path})`
+        : `@api:${name} → bind {{${name}}} (${entry.method} ${entry.path})`,
+      code: `testData.bind(${JSON.stringify(name)}, ${callExpr});`,
       boundVars: [name],
     });
   }
@@ -105,6 +124,58 @@ const apiVerificationSensor: Sensor<GateInput> = {
   },
 };
 
+/**
+ * API `viewpoints` gate sensor (AP-6): coverage feedback for the API surface, advisory (warn/info,
+ * never fails the gate). Classifies the feature's `@api` scenarios into the three API viewpoints and
+ * surfaces gaps — severity-weighted by method (read-only GET/HEAD surfaces don't expect error/idempotency):
+ *  - `api-contract`     — every invoked endpoint must have its response asserted ({{name.status|body}}).
+ *  - `api-error`        — a mutating endpoint without ANY failure scenario (@cases matrix or a 4xx/5xx) — the 70% band.
+ *  - `api-idempotency`  — a mutating endpoint without a @concurrent aggregate check ({{name.ok_count}}) — the 10% band.
+ * Reads the already-parsed scenarios (apiRefs + lowercase stepsText + casesDataset) — no re-parse.
+ */
+const apiViewpointSensor: Sensor<GateInput> = {
+  id: 'api-viewpoints',
+  capability: 'api',
+  kind: 'gate',
+  run: ({ screenName, scenarios, cwd }) => {
+    const findings = [] as ReturnType<Sensor['run']>;
+    const add = (severity: 'warn' | 'info', message: string) => findings.push({ sensorId: 'api-viewpoints', capability: 'api', message, severity });
+    const apiScenarios = scenarios.filter((s) => (s.apiRefs ?? []).length);
+    if (!apiScenarios.length) return findings;
+
+    const refs = new Set<string>();
+    for (const s of apiScenarios) for (const r of s.apiRefs ?? []) refs.add(r);
+
+    // api-contract — each invoked endpoint's response is asserted somewhere.
+    for (const name of refs) {
+      const re = new RegExp(`\\b${name.toLowerCase()}\\.(status|ok|body|headers|ok_count|status_counts)\\b`);
+      if (!apiScenarios.some((s) => re.test(s.stepsText ?? ''))) {
+        add('warn', `VIEWPOINT-API-CONTRACT: @api:${name} is invoked but its response is never asserted — add the contract check (expect {{${name}.status}} / {{${name}.body.…}}).`);
+      }
+    }
+
+    // Method-aware: error + idempotency only apply when a referenced endpoint MUTATES.
+    const mutating: string[] = [];
+    for (const name of refs) {
+      try { if (/^(POST|PUT|PATCH|DELETE)$/.test(resolveApi(name, screenName, cwd).method)) mutating.push(name); } catch { /* unresolved → the verification sensor reports it */ }
+    }
+    if (!mutating.length) return findings; // read-only surface — no error/idempotency expectation
+
+    // api-error — a failure scenario exists: a @cases matrix, or an asserted 4xx/5xx.
+    const hasError = apiScenarios.some((s) => s.casesDataset || /\b[45]\d\d\b/.test(s.stepsText ?? ''));
+    if (!hasError) {
+      add('warn', `VIEWPOINT-API-ERROR: mutating endpoint(s) ${mutating.join(', ')} have no failure scenario (4xx/auth/validation) — add a @cases error matrix or an explicit 4xx assertion (the ~70% success+failure band).`);
+    }
+
+    // api-idempotency — a @concurrent aggregate check exists.
+    const hasIdem = apiScenarios.some((s) => /\b\w+\.(ok_count|status_counts)\b/.test(s.stepsText ?? ''));
+    if (!hasIdem) {
+      add('info', `VIEWPOINT-API-IDEMPOTENCY: no @concurrent idempotency/race check on a mutating endpoint — consider @concurrent:N + a @query DB cross-check (the ~10% band).`);
+    }
+    return findings;
+  },
+};
+
 /** Register the API capability. */
 export function register(registry: CapabilityRegistry): void {
   registry.register({
@@ -112,7 +183,7 @@ export function register(registry: CapabilityRegistry): void {
     annotations: ['@api'],
     runtimeHelpers: [{ file: 'api.ts', template: 'specs-api.ts' }], // template resolved from core's templates dir
     preconditionCodegen: apiPreconditionCodegen, // @api:<name> → bind {{name}}
-    sensors: [apiVerificationSensor],
+    sensors: [apiVerificationSensor, apiViewpointSensor],
     cliCommands: [registerApiCommand as (program: unknown) => void], // `sungen api import <openapi>`
   });
 }