@sungen/driver-api 3.1.2-beta.117 → 3.1.2-beta.119

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-api",
-  "version": "3.1.2-beta.117",
+  "version": "3.1.2-beta.119",
   "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.117",
+    "@sun-asterisk/sungen": "3.1.2-beta.119",
     "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/index.ts

@@ -20,6 +20,7 @@ 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
@@ -187,6 +188,8 @@ export function register(registry: CapabilityRegistry): void {
     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>`
   });
 }