@sungen/driver-api 3.2.28 → 3.2.30

package/package.json

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

package/src/api-harness.ts

@@ -12,8 +12,11 @@
  * 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 * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
 import type { Catalog, GateResult, DepthResult } from '@sun-asterisk/sungen';
-import { resolveApi } from './api-catalog';
+import { resolveApi, type ApiEntry } from './api-catalog';
 
 /** A scenario as the audit parses it (the subset the API gate reads). */
 interface ApiScenario {
@@ -67,16 +70,29 @@ export function apiGateProvider(input: ApiGateInput): { gate: GateResult; depth:
   const criticalMethods = (input.businessCriticalMethods?.length ? input.businessCriticalMethods : DEFAULT_CRITICAL).map((m) => m.toUpperCase());
   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>();
+  // Resolve each referenced entry (best-effort; unresolved → the verification sensor already fails
+  // the gate, so we just skip it here — it contributes no theme).
+  const entryOf = new Map<string, ApiEntry>();
   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 */ }
+      if (entryOf.has(name)) continue;
+      try { entryOf.set(name, resolveApi(name, screenName, cwd)); } catch { /* unresolved */ }
     }
   }
-  const isMutating = (name: string) => criticalMethods.includes((methodOf.get(name) ?? '').toUpperCase());
+  const isMutating = (name: string) => criticalMethods.includes((entryOf.get(name)?.method ?? '').toUpperCase());
+
+  // Alias groups: two catalog entries that are the same request under two names — the `<x>_control`
+  // clone an author adds so one scenario can bind two responses of one endpoint — are ONE endpoint.
+  // Counting the clone separately demanded its own error scenario, a gap nothing but a duplicate
+  // scenario could close. Entries on the same route that differ in any request/response detail
+  // (encoding, body, headers, expect, …) stay distinct contracts.
+  const defaultDatasource = defaultDatasourceName(cwd);
+  const aliasGroups = new Map<string, string[]>(); // fingerprint → alias names, first referenced = label
+  for (const [name, entry] of entryOf) {
+    const key = endpointFingerprint(entry, defaultDatasource);
+    const group = aliasGroups.get(key);
+    if (group) group.push(name); else aliasGroups.set(key, [name]);
+  }
 
   // ── Coverage: must-cover viewpoints per resolved endpoint ──────────────────────────────────
   // read (GET/HEAD): {contract}; mutating: {contract, error}. (auth/idempotency/side-effect are
@@ -90,12 +106,14 @@ export function apiGateProvider(input: ApiGateInput): { gate: GateResult; depth:
   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 aliases of aliasGroups.values()) {
+    const label = aliases[0];
+    const vps: ('contract' | 'error')[] = isMutating(label) ? ['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' });
+      // A theme is covered when ANY alias of the endpoint asserts it.
+      if (apiScenarios.some((s) => aliases.some((alias) => asserts(s, alias, vp)))) covered++;
+      else gaps.push({ theme: `${label}:${vp}`, keywords: [], status: 'missing' });
     }
   }
   const coverageRatio = themesTotal ? covered / themesTotal : 0;
@@ -142,3 +160,65 @@ export function apiGateProvider(input: ApiGateInput): { gate: GateResult; depth:
 
   return { gate, depth };
 }
+
+/**
+ * The datasource a request without an explicit `datasource` runs against — the same rule as the
+ * runtime client: the first `kind: api` entry of datasources.yaml (project root, then qa/), else the
+ * first entry. `undefined` when the project has no datasources.yaml (then only entries that both
+ * omit the field can match each other).
+ */
+function defaultDatasourceName(cwd: string): string | undefined {
+  const file = [path.join(cwd, 'datasources.yaml'), path.join(cwd, 'qa', 'datasources.yaml')].find((f) => fs.existsSync(f));
+  if (!file) return undefined;
+  try {
+    const doc = parseYaml(fs.readFileSync(file, 'utf8')) as { datasources?: Record<string, { kind?: string }> } | null;
+    const all = doc?.datasources ?? {};
+    const keys = Object.keys(all);
+    return keys.find((k) => (all[k]?.kind || 'api') === 'api') ?? keys[0];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Identity of the request/response contract an entry describes — every field except how the entry
+ * is named (`name`, `description`) and where it lives (`scope`, `file`), with the effective
+ * datasource filled in. Canonical (sorted keys), so YAML key order never splits an alias.
+ */
+function endpointFingerprint(entry: ApiEntry, defaultDatasource: string | undefined): string {
+  const { name: _name, description: _description, scope: _scope, file: _file, ...contract } = entry;
+  const sorted = (xs: string[] | undefined) => (xs ? [...xs].sort() : undefined);
+  return canonicalJson({
+    ...contract,
+    datasource: entry.datasource ?? defaultDatasource,
+    // Sets, not sequences: `params` is validated against the `:refs` in both directions with no order,
+    // `arrayPaths` is a membership list — a retyped clone must not split on order.
+    params: sorted(entry.params),
+    arrayPaths: sorted(entry.arrayPaths),
+    // The runtime treats header names case-insensitively — so does the identity.
+    headers: entry.headers ? Object.fromEntries(Object.entries(entry.headers).map(([k, v]) => [k.toLowerCase(), v])) : undefined,
+    // `status: 201` and `status: "201"` are the same expectation (every consumer reads it via String());
+    // an `expect:` block without a status is no expectation at all.
+    expect: entry.expect?.status != null ? { status: String(entry.expect.status) } : undefined,
+  });
+}
+
+/** Deterministic JSON: sorted object keys, `undefined` members dropped, cycles and non-finite numbers named. */
+function canonicalJson(value: unknown, seen: WeakSet<object> = new WeakSet()): string {
+  if (typeof value === 'number' && !Number.isFinite(value)) return String(value); // NaN/Infinity ≠ null
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return '"[cycle]"';
+    seen.add(value);
+    return `[${value.map((v) => canonicalJson(v, seen)).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    if (seen.has(value)) return '"[cycle]"'; // a self-referencing YAML anchor must not crash the audit
+    seen.add(value);
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v, seen)}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}