@sungen/driver-api 3.1.2-beta.121 → 3.1.2-beta.122

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-api",
-  "version": "3.1.2-beta.121",
+  "version": "3.1.2-beta.122",
   "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.121",
+    "@sun-asterisk/sungen": "3.1.2-beta.122",
     "commander": "^14.0.2",
     "yaml": "^2.8.2"
   },

package/src/api-repair.ts

@@ -0,0 +1,37 @@
+/**
+ * API repair catalog (#343) — the `api` capability's deterministic fix rules.
+ *
+ * `sungen repair --api <area>` matches each audit finding + runtime failure against these rules and
+ * proposes the concrete fix. Same catalog the `/sungen:run-test` API mode + `sungen-api-design`
+ * repair loop apply by hand — here it is capability-owned DATA, so it composes audit + runtime
+ * signals into one plan and a project/driver can extend it. Type-only on core.
+ */
+import type { RepairProvider } from '@sun-asterisk/sungen';
+
+export const apiRepair: RepairProvider = {
+  rules: [
+    // ── Coverage / depth (from `sungen audit --api`) ──────────────────────────────────────────
+    { id: 'api-contract', match: /VIEWPOINT-API-CONTRACT/i,
+      fix: 'The endpoint is invoked but its response is never asserted — add `expect {{name.status}} is …` plus a body check `{{name.body.<field>}}`.' },
+    { id: 'api-error', match: /VIEWPOINT-API-ERROR/i,
+      fix: 'A mutating endpoint has no failure scenario — add a `@cases` error matrix (input → expected status) or an explicit 4xx assertion (the ~70% band).' },
+    { id: 'api-idempotency', match: /VIEWPOINT-API-IDEMPOTENCY/i,
+      fix: 'A mutating endpoint has no race check — add `@concurrent:N` + assert `{{name.ok_count}} is 1`, cross-checked with a `@query` DB count (the ~10% band).' },
+    { id: 'api-depth', match: /DEPTH-?FAIL|businessDepth|SHALLOW/i,
+      fix: 'A mutating success scenario only asserts the status — make it PROVE THE EFFECT: assert a response body field, a `@query` DB side-effect, or a `@concurrent` `ok_count` invariant.' },
+    { id: 'api-verification', match: /VERIFICATION-FAIL|does not resolve|not found in/i,
+      fix: 'An `@api:<name>` does not resolve in the catalog — fix the name, or add/import the endpoint into `api/apis.yaml` (`sungen api import`).' },
+
+    // ── Runtime failures (from the Playwright test-result) ────────────────────────────────────
+    { id: 'api-auth', match: /\b40[13]\b|unauthor|forbidden/i,
+      fix: 'Auth failure (401/403) — tag the scenario `@hybrid` + `@auth:<role>` to reuse the UI session, or wire a catalog `authorization: "Bearer :token"` header; capture a session with `sungen makeauth <role>`.' },
+    { id: 'api-datasource', match: /base_url|ECONNREFUSED|ENOTFOUND|ENETUNREACH|getaddrinfo/i,
+      fix: 'The API was unreachable — set the datasource `${X_URL}` key in `.env.qa` (from `sungen api init`) and confirm the service is up / non-prod.' },
+    { id: 'api-status-mismatch', match: /expected.*status|status.*expected|toBe.*\b[45]\d\d\b|received.*\b[45]\d\d\b/i,
+      fix: 'Asserted status ≠ actual — reconcile the expectation against `apis.yaml`/spec (the catalog is the oracle). Never hand-edit the generated spec; fix the feature/test-data and re-`generate --api`.' },
+    { id: 'api-timeout', match: /timeout|timed out|exceeded/i,
+      fix: 'Request timed out — raise the datasource `timeout_ms`, or check the endpoint/path; for flows ensure prior steps bound the values the call needs.' },
+    { id: 'api-flaky', match: /flak|intermitt|conflict|already exists|duplicate key/i,
+      fix: 'Likely state bleed — make the flow self-cleaning (delete what it created / `@cleanup`), isolate `@cases` rows, and cap `@concurrent`.' },
+  ],
+};

package/src/index.ts

@@ -21,6 +21,7 @@ import { resolveApi, apiParamNames, lintApiCatalog } from './api-catalog';
 import { registerApiCommand } from './cli-import';
 import { apiViewpoints, apiGateProvider } from './api-harness';
 import { apiDiscovery, apiContextMapper } from './api-context';
+import { apiRepair } from './api-repair';
 
 /**
  * Parse `name(a={{x}},b="lit",c=3)` annotation overrides → JS expressions. Inlined from core
@@ -190,6 +191,7 @@ export function register(registry: CapabilityRegistry): void {
     gateProvider: apiGateProvider as (i: unknown) => unknown, // AO-2: API coverage + businessDepth
     discovery: apiDiscovery,           // AO-3: catalog/spec → Context slice
     contextMapper: apiContextMapper,   // AO-3: endpoints → matrix/async/flow generation units
+    repair: apiRepair,                 // #343: finding/failure → concrete fix catalog
     cliCommands: [registerApiCommand as (program: unknown) => void], // `sungen api import <openapi>`
   });
 }