@sungen/driver-api 3.1.2-beta.116 → 3.1.2-beta.118

package/package.json

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

package/src/api-context.ts

@@ -0,0 +1,52 @@
+/**
+ * API discovery + context-mapping (AO-3) — the `api` capability's Discover → Contextualize hooks.
+ *
+ * Discovery reads the reviewed catalog (apis.yaml) + notes the spec source; context-mapping turns
+ * the endpoints into generation units by method-profile: every endpoint → a `matrix` unit (contract
+ * + error), each mutating endpoint → also an `async` unit (idempotency), and an api flow → a `flow`
+ * unit (the ordered journey). The orchestration loop (`sungen context` → `/sungen:design`) consumes
+ * these to know WHAT to author before writing scenarios. Type-only on core.
+ */
+import type { Context, DiscoveryProvider, ContextMapper, GenerationUnit } from '@sun-asterisk/sungen';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { lintApiCatalog } from './api-catalog';
+
+interface EndpointFact { name: string; method: string; path: string; datasource?: string; expectStatus?: number | string }
+
+const MUTATING = /^(POST|PUT|PATCH|DELETE)$/;
+
+export const apiDiscovery: DiscoveryProvider = {
+  appliesTo: (t) => t.kind === 'api',
+  discover: async (target, scope) => {
+    const cwd = (scope as { cwd?: string } | undefined)?.cwd ?? process.cwd();
+    const unitId = target.id; // `api/<area>` | `api/flows/<flow>`
+    let endpoints: EndpointFact[] = [];
+    try {
+      endpoints = lintApiCatalog(unitId, null, cwd).entries.map((e) => ({
+        name: e.name, method: e.method, path: e.path, datasource: e.datasource, expectStatus: e.expect?.status,
+      }));
+    } catch { /* no catalog → the verification gate reports it */ }
+
+    const sources: Record<string, unknown> = {};
+    const specPath = path.join(cwd, 'qa', unitId, 'requirements', 'spec.md');
+    if (fs.existsSync(specPath)) sources.spec = path.relative(cwd, specPath);
+
+    return { target: { ...target, capability: 'api' }, sources, facts: { endpoints } };
+  },
+};
+
+export const apiContextMapper: ContextMapper = {
+  decompose: (ctx: Context): GenerationUnit[] => {
+    const endpoints = ((ctx.facts ?? {}) as { endpoints?: EndpointFact[] }).endpoints ?? [];
+    const units: GenerationUnit[] = [];
+    const isFlow = typeof ctx.target.id === 'string' && ctx.target.id.includes('/flows/');
+    if (isFlow) units.push({ mode: 'flow', targetSlice: ctx.target }); // the ordered journey is one unit
+    for (const e of endpoints) {
+      units.push({ mode: 'matrix', targetSlice: e });                       // contract + error matrix (70%)
+      if (MUTATING.test(e.method)) units.push({ mode: 'async', targetSlice: e }); // idempotency/concurrency (10%)
+    }
+    if (!units.length) units.push({ mode: 'matrix', targetSlice: ctx.target });
+    return units;
+  },
+};

package/src/api-harness.ts

@@ -0,0 +1,135 @@
+/**
+ * API harness — the `api` capability's score-bearing gate + viewpoint catalog (AO-2).
+ *
+ * The audit engine is capability-routed (AO-1): for an `api/<area>` unit it calls THIS capability's
+ * `viewpoints()` + `gateProvider()` instead of the UI ones, then assembles the score with the same
+ * `0.4·coverage + 0.3·businessDepth + 0.15·balance + 0.15·trace` formula. We compute API-native
+ * coverage + depth here (not the UI keyword model), so an API area is scored on what matters for an
+ * API: contract + failure coverage, and — the headline — `businessDepth`: do the business-critical
+ * (mutating) scenarios PROVE THE EFFECT (assert body / DB side-effect / concurrency invariant), or
+ * just the status?
+ *
+ * Type-only on core (like the rest of the driver) — the depth threshold + project context arrive via
+ * the gate input, so loading the driver never forces a core runtime resolve.
+ */
+import type { Catalog, GateResult, DepthResult } from '@sun-asterisk/sungen';
+import { resolveApi } from './api-catalog';
+
+/** A scenario as the audit parses it (the subset the API gate reads). */
+interface ApiScenario {
+  name: string;
+  apiRefs?: string[];
+  queryRefs?: string[];
+  casesDataset?: string;
+  stepsText?: string; // lowercase steps text
+}
+
+interface ApiGateInput {
+  scenarios: ApiScenario[];
+  focus: string;
+  cwd: string;
+  screenName: string; // catalog-resolution id, e.g. `api/<area>`
+  threshold: number;  // required businessDepth for the focus (from core)
+}
+
+const MUTATING = /^(POST|PUT|PATCH|DELETE)$/;
+
+/**
+ * The API viewpoint catalog (display + the project-override seam). The gate computes coverage from
+ * the live `apis.yaml`, so this is intentionally light — one universal theme per viewpoint category.
+ */
+export function apiViewpoints(): Catalog {
+  const theme = (t: string, keywords: string[]) => ({ theme: t, keywords });
+  return {
+    page_types: {
+      // method-profiles (the API analog of UI page-types) — documented; the gate enforces them.
+      read: { detect_keywords: ['get', 'list', 'fetch'], must_cover: [theme('contract', ['status', 'body'])] },
+      mutating: {
+        detect_keywords: ['create', 'update', 'delete', 'post', 'put', 'patch'],
+        must_cover: [theme('contract', ['status', 'body']), theme('error', ['4', '5', 'invalid', 'cases'])],
+      },
+    },
+    universal: [theme('contract', ['status']), theme('error', ['4', '5'])],
+  };
+}
+
+/**
+ * Score-bearing API gate: coverage (must-cover viewpoints per endpoint, by method-profile) + depth
+ * (mutating scenarios that prove the effect). Returns the same `{gate, depth}` shape the audit
+ * assembles into the score.
+ */
+export function apiGateProvider(input: ApiGateInput): { gate: GateResult; depth: DepthResult } {
+  const { scenarios, focus, cwd, screenName, threshold } = input;
+  const apiScenarios = scenarios.filter((s) => (s.apiRefs ?? []).length);
+
+  // Resolve each referenced endpoint's HTTP method (best-effort; unresolved → the verification
+  // sensor already fails the gate, so we just skip it here).
+  const methodOf = new Map<string, string>();
+  for (const s of apiScenarios) {
+    for (const name of s.apiRefs ?? []) {
+      if (methodOf.has(name)) continue;
+      try { methodOf.set(name, resolveApi(name, screenName, cwd).method); } catch { /* unresolved */ }
+    }
+  }
+  const isMutating = (name: string) => MUTATING.test(methodOf.get(name) ?? '');
+
+  // ── Coverage: must-cover viewpoints per resolved endpoint ──────────────────────────────────
+  // read (GET/HEAD): {contract}; mutating: {contract, error}. (auth/idempotency/side-effect are
+  // advisory via the api-viewpoints sensor + rewarded through businessDepth, not coverage-gating.)
+  const asserts = (s: ApiScenario, endpoint: string, vp: 'contract' | 'error'): boolean => {
+    if (!(s.apiRefs ?? []).includes(endpoint)) return false;
+    const t = s.stepsText ?? '';
+    if (vp === 'contract') return new RegExp(`\\b${endpoint.toLowerCase()}\\.(status|ok|body|headers|ok_count|status_counts)\\b`).test(t);
+    return !!s.casesDataset || /\b[45]\d\d\b/.test(t); // error: a @cases matrix or an asserted 4xx/5xx
+  };
+  const gaps: GateResult['gaps'] = [];
+  let covered = 0;
+  let themesTotal = 0;
+  for (const endpoint of methodOf.keys()) {
+    const vps: ('contract' | 'error')[] = isMutating(endpoint) ? ['contract', 'error'] : ['contract'];
+    for (const vp of vps) {
+      themesTotal++;
+      if (apiScenarios.some((s) => asserts(s, endpoint, vp))) covered++;
+      else gaps.push({ theme: `${endpoint}:${vp}`, keywords: [], status: 'missing' });
+    }
+  }
+  const coverageRatio = themesTotal ? covered / themesTotal : 0;
+  const area = screenName.replace(/^api\//, '');
+  const gate: GateResult = {
+    pageType: `api:${area}`,
+    themesTotal,
+    themesCovered: covered,
+    coverageRatio,
+    gaps,
+    universalGaps: [],
+  };
+
+  // ── businessDepth: the SUCCESS path of a mutation must PROVE THE EFFECT, not just assert status ──
+  // 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));
+  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
+      || /\b[a-z_][a-z0-9_]*\.(ok_count|status_counts)\b/.test(t) // a concurrency invariant
+      || (s.queryRefs ?? []).length > 0;                          // a @query DB side-effect cross-check
+  };
+  const reqShallow = depthRequired.filter((s) => !isDeep(s));
+  const bcDepthRatio = depthRequired.length ? (depthRequired.length - reqShallow.length) / depthRequired.length : 1;
+  const verdict: DepthResult['verdict'] = bcDepthRatio < threshold ? (focus === 'smoke' ? 'warn' : 'fail') : 'pass';
+  const depth: DepthResult = {
+    total: apiScenarios.length,
+    shallowTotal: reqShallow.length,
+    shallowRatio: apiScenarios.length ? reqShallow.length / apiScenarios.length : 0,
+    businessCriticalTotal: depthRequired.length,
+    businessCriticalShallow: reqShallow.length,
+    bcDepthRatio,
+    shallowBusinessCritical: reqShallow.map((s) => ({ name: s.name, category: 'API' })),
+    focus,
+    threshold,
+    verdict,
+  };
+
+  return { gate, depth };
+}

package/src/index.ts

@@ -19,6 +19,8 @@
 import type { CapabilityRegistry, Sensor, GateInput } from '@sun-asterisk/sungen';
 import { resolveApi, apiParamNames, lintApiCatalog } from './api-catalog';
 import { registerApiCommand } from './cli-import';
+import { apiViewpoints, apiGateProvider } from './api-harness';
+import { apiDiscovery, apiContextMapper } from './api-context';
 
 /**
  * Parse `name(a={{x}},b="lit",c=3)` annotation overrides → JS expressions. Inlined from core
@@ -184,6 +186,10 @@ export function register(registry: CapabilityRegistry): void {
     runtimeHelpers: [{ file: 'api.ts', template: 'specs-api.ts' }], // template resolved from core's templates dir
     preconditionCodegen: apiPreconditionCodegen, // @api:<name> → bind {{name}}
     sensors: [apiVerificationSensor, apiViewpointSensor],
+    viewpoints: apiViewpoints as () => unknown,       // AO-2: API viewpoint catalog
+    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
     cliCommands: [registerApiCommand as (program: unknown) => void], // `sungen api import <openapi>`
   });
 }