@sungen/driver-api 3.1.2-beta.124 → 3.1.2-beta.126

package/package.json

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

package/src/api-harness.ts

@@ -22,6 +22,7 @@ interface ApiScenario {
   queryRefs?: string[];
   casesDataset?: string;
   stepsText?: string; // lowercase steps text
+  manual?: boolean;   // @manual — not automated, so excluded from automation businessDepth
 }
 
 interface ApiGateInput {
@@ -112,7 +113,10 @@ export function apiGateProvider(input: ApiGateInput): { gate: GateResult; depth:
   // An error scenario (a @cases matrix, or one asserting a 4xx/5xx) proves the failure CONTRACT —
   // the status IS its correct assertion (the API analog of UI NAV), so it is not depth-required.
   const errorLike = (s: ApiScenario) => !!s.casesDataset || /\bis\s+["']?[45]\d\d\b/.test(s.stepsText ?? '');
-  const depthRequired = apiScenarios.filter((s) => (s.apiRefs ?? []).some(isMutating) && !errorLike(s));
+  // businessDepth measures AUTOMATED proof — a @manual scenario isn't automated, so it can't count
+  // toward depth (else deferring an automatable mutation to @manual inflates the score). The
+  // api-viewpoints sensor separately flags @manual scenarios whose endpoint resolves (automatable).
+  const depthRequired = apiScenarios.filter((s) => !s.manual && (s.apiRefs ?? []).some(isMutating) && !errorLike(s));
   const isDeep = (s: ApiScenario): boolean => {
     const t = s.stepsText ?? '';
     return /\b[a-z_][a-z0-9_]*\.body\b/.test(t)                 // asserts a response body field

package/src/api-repair.ts

@@ -21,6 +21,8 @@ export const apiRepair: RepairProvider = {
       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`).' },
+    { id: 'api-manual-automatable', match: /VIEWPOINT-API-MANUAL-AUTOMATABLE/i,
+      fix: 'A @manual scenario is automatable (its endpoint resolves) — drop @manual and use @api (+ @cases for error rows / @concurrent for idempotency). Reserve @manual for genuine judgment cases.' },
 
     // ── Runtime failures (from the Playwright test-result) ────────────────────────────────────
     { id: 'api-auth', match: /\b40[13]\b|unauthor|forbidden/i,

package/src/index.ts

@@ -159,6 +159,16 @@ const apiViewpointSensor: Sensor<GateInput> = {
       }
     }
 
+    // api-manual-automatable — a @manual scenario whose @api endpoint RESOLVES is automatable; flag it
+    // so automatable work isn't deferred to manual (a common run-test reflex when the call failed).
+    for (const s of apiScenarios) {
+      if (!s.manual) continue;
+      const automatable = (s.apiRefs ?? []).filter((r) => { try { resolveApi(r, screenName, cwd); return true; } catch { return false; } });
+      if (automatable.length) {
+        add('warn', `VIEWPOINT-API-MANUAL-AUTOMATABLE: "${s.name}" is @manual but its endpoint(s) ${automatable.join(', ')} resolve in the catalog — automate with @api (+ @cases for error rows); don't defer an automatable API check to manual.`);
+      }
+    }
+
     // Method-aware: error + idempotency only apply when a referenced endpoint MUTATES.
     const mutating: string[] = [];
     for (const name of refs) {