@suluk/cockpit 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/cockpit",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "The pure cockpit core (cycle model · builder model · codegen · deploy planning · validate/audit/preview) shared by the vscode extension and the /superadmin web admin panel. CANDIDATE tooling.",
   "type": "module",
   "main": "src/index.ts",

package/src/converge.ts

@@ -0,0 +1,96 @@
+/**
+ * Contract converge — a coherence audit over a WHOLE contract (the burhan-converge spirit). installModule
+ * refuses NAME collisions at merge time; converge catches the cross-cutting CONTRADICTIONS that survive a clean
+ * merge: an operation requiring a scope no security scheme declares, a security requirement naming a scheme
+ * that isn't defined, a $ref to a schema nothing provides, a path with no operations, an entity referenced by
+ * nothing. Run it after composing modules to know the merged platform is self-consistent, not just collision-free.
+ * Pure (no host) → unit-tested.
+ */
+import { buildAda } from "@suluk/core";
+import type { OpenAPIv4Document, Request, SchemaOrRef, SecurityRequirement } from "@suluk/core";
+import { schemaRefName } from "@suluk/builder";
+
+export type ConvergeCode = "dangling-ref" | "undeclared-scheme" | "orphan-scope" | "empty-path" | "unreferenced-entity";
+
+export interface ConvergeFinding {
+  code: ConvergeCode;
+  severity: "error" | "warn" | "info";
+  message: string;
+  where?: string;
+}
+export interface ConvergeReport {
+  findings: ConvergeFinding[];
+  /** true ⇒ no error-severity findings — the contract is self-consistent */
+  clean: boolean;
+}
+
+const hasOwn = (o: object, k: string) => Object.prototype.hasOwnProperty.call(o, k);
+
+/**
+ * The scope universe a scheme allows, for orphan-scope checking — or NULL when the scopes are not LOCALLY
+ * knowable (openIdConnect defines its scopes in a remote discovery document), so converge must not flag them.
+ * oauth2 → the union of its flows' declared scopes; apiKey/http/mutualTLS → the empty set (they declare none).
+ */
+function scopeUniverse(scheme: unknown): Set<string> | null {
+  const s = scheme as { type?: string; flows?: Record<string, { scopes?: Record<string, string> }> };
+  if (s?.type === "openIdConnect") return null; // scopes live in the OIDC discovery doc — not locally checkable
+  if (s?.type !== "oauth2") return new Set();
+  const out = new Set<string>();
+  for (const flow of Object.values(s.flows ?? {})) for (const name of Object.keys(flow?.scopes ?? {})) out.add(name);
+  return out;
+}
+
+/** Every schema name targeted by a `#/components/schemas/X` $ref anywhere in the document (deep/escaped-safe). */
+function referencedSchemas(doc: OpenAPIv4Document): Set<string> {
+  const names = new Set<string>();
+  const walk = (v: unknown): void => {
+    if (Array.isArray(v)) { v.forEach(walk); return; }
+    if (v && typeof v === "object") {
+      const o = v as Record<string, unknown>;
+      if (typeof o.$ref === "string") { const name = schemaRefName(o.$ref); if (name) names.add(name); }
+      for (const val of Object.values(o)) walk(val);
+    }
+  };
+  walk(doc);
+  return names;
+}
+
+/** Audit a contract for coherence contradictions a clean merge can still leave behind. */
+export function convergeContract(doc: OpenAPIv4Document): ConvergeReport {
+  const findings: ConvergeFinding[] = [];
+  const schemas = (doc.components?.schemas ?? {}) as Record<string, SchemaOrRef>;
+  const schemes = (doc.components?.securitySchemes ?? {}) as Record<string, unknown>;
+
+  // dangling $refs — a reference to a schema nothing provides
+  const referenced = referencedSchemas(doc);
+  for (const name of referenced) if (!hasOwn(schemas, name)) findings.push({ code: "dangling-ref", severity: "error", message: `$ref to schema "${name}" — nothing provides it`, where: name });
+
+  // security coherence — every required scheme is declared, and every required scope is declared by that scheme.
+  // Covers BOTH path operations AND webhooks (both carry security; the dangling-ref walk already covers webhooks).
+  const secured = [
+    ...buildAda(doc).operations.map((o) => ({ name: o.name, security: o.request.security as SecurityRequirement[] | undefined })),
+    ...Object.entries((doc as { webhooks?: Record<string, Request> }).webhooks ?? {}).map(([name, req]) => ({ name, security: req.security as SecurityRequirement[] | undefined })),
+  ];
+  for (const op of secured) {
+    for (const req of op.security ?? []) {
+      for (const [schemeName, scopes] of Object.entries(req)) {
+        if (!hasOwn(schemes, schemeName)) {
+          findings.push({ code: "undeclared-scheme", severity: "error", message: `operation "${op.name}" requires security scheme "${schemeName}", which is not declared in components.securitySchemes`, where: op.name });
+          continue;
+        }
+        const universe = scopeUniverse(schemes[schemeName]);
+        if (universe && Array.isArray(scopes)) for (const s of scopes) if (!universe.has(s)) findings.push({ code: "orphan-scope", severity: "error", message: `operation "${op.name}" requires scope "${s}", which scheme "${schemeName}" does not declare`, where: op.name });
+      }
+    }
+  }
+
+  // empty path items — a path that declares no operations
+  for (const [p, pi] of Object.entries(doc.paths ?? {})) {
+    if (!Object.keys((pi as { requests?: object }).requests ?? {}).length) findings.push({ code: "empty-path", severity: "error", message: `path "${p}" declares no operations`, where: p });
+  }
+
+  // unreferenced entities — a schema nothing $refs (dead weight; info, not an error)
+  for (const name of Object.keys(schemas)) if (!referenced.has(name)) findings.push({ code: "unreferenced-entity", severity: "info", message: `entity "${name}" is referenced by no $ref`, where: name });
+
+  return { findings, clean: !findings.some((f) => f.severity === "error") };
+}

package/src/index.ts

@@ -14,6 +14,8 @@ export type { DeployPlan, DeployStep, DeployProvider } from "@suluk/deploy";
 export { diffContracts, canonical, type ContractDiff, type ChangedOp, type OpRef, type ProviderDelta, type ProviderChange } from "./drift";
 // cross-cut (M1): one contract refracted through every viewer — the scope-gated surface, the moat.
 export { crossCut, documentScopes, defaultViewers, type Viewer, type ViewerView, type GatedOp, type CrossCut } from "./crosscut";
+// converge: a coherence audit over a whole contract — the cross-cutting contradictions a clean merge leaves behind.
+export { convergeContract, type ConvergeReport, type ConvergeFinding, type ConvergeCode } from "./converge";
 // cost formatting, re-exported so the extension shell can render a live /cost ledger without a direct @suluk/cost dep.
 export { formatMicroUsd, summarize, type CostSummary } from "@suluk/cost";
 // modules (C021): install a contract fragment into the hub doc — the cockpit then re-projects it for free.

package/test/converge.test.ts

@@ -0,0 +1,131 @@
+import { test, expect, describe } from "bun:test";
+import { parseDocument } from "@suluk/core";
+import { installModule, ECOMMERCE, composeModules, resolveTemplate, STACK_TEMPLATES } from "@suluk/builder";
+import { convergeContract } from "../src/converge";
+
+const doc = (s: string) => parseDocument(s);
+
+describe("convergeContract — coherence over a whole contract", () => {
+  test("a coherent contract is clean", () => {
+    const d = doc(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths:
+  "pet":
+    requests:
+      listPets: { method: get, responses: { ok: { status: 200, contentSchema: { $ref: "#/components/schemas/Pet" } } } }
+      createPet: { method: post, security: [ { auth: [ "write:pets" ] } ], responses: { created: { status: 201 } } }
+components:
+  schemas: { Pet: { type: object, properties: { name: { type: string } } } }
+  securitySchemes: { auth: { type: oauth2, flows: { implicit: { authorizationUrl: "https://x", scopes: { "write:pets": "w" } } } } }
+`);
+    const r = convergeContract(d);
+    expect(r.clean).toBe(true);
+    expect(r.findings.filter((f) => f.severity === "error")).toHaveLength(0);
+  });
+
+  test("an operation requiring an UNDECLARED scope is an error", () => {
+    const d = doc(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: { "pet": { requests: { createPet: { method: post, security: [ { auth: [ "delete:everything" ] } ], responses: { ok: { status: 201 } } } } } }
+components: { securitySchemes: { auth: { type: oauth2, flows: { implicit: { authorizationUrl: "https://x", scopes: { "write:pets": "w" } } } } } }
+`);
+    const r = convergeContract(d);
+    expect(r.clean).toBe(false);
+    expect(r.findings.some((f) => f.code === "orphan-scope" && f.message.includes("delete:everything"))).toBe(true);
+  });
+
+  test("an operation requiring an UNDECLARED scheme is an error", () => {
+    const d = doc(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: { "pet": { requests: { createPet: { method: post, security: [ { ghostAuth: [] } ], responses: { ok: { status: 201 } } } } } }
+components: { securitySchemes: {} }
+`);
+    const r = convergeContract(d);
+    expect(r.findings.some((f) => f.code === "undeclared-scheme" && f.message.includes("ghostAuth"))).toBe(true);
+    expect(r.clean).toBe(false);
+  });
+
+  test("a $ref to a missing schema is a dangling-ref error", () => {
+    const d = doc(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: { "pet": { requests: { getPet: { method: get, responses: { ok: { status: 200, contentSchema: { $ref: "#/components/schemas/Ghost" } } } } } } }
+components: { schemas: {} }
+`);
+    const r = convergeContract(d);
+    expect(r.findings.some((f) => f.code === "dangling-ref" && f.where === "Ghost")).toBe(true);
+  });
+
+  test("an unreferenced entity is reported as info (not an error)", () => {
+    const d = doc(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: { "pet": { requests: { ping: { method: get, responses: { ok: { status: 200 } } } } } }
+components: { schemas: { Orphan: { type: object } } }
+`);
+    const r = convergeContract(d);
+    expect(r.clean).toBe(true); // info, not error
+    expect(r.findings.some((f) => f.code === "unreferenced-entity" && f.where === "Orphan")).toBe(true);
+  });
+
+  test("an openIdConnect scheme's scopes are NOT locally checkable — no false orphan-scope", () => {
+    const d = doc(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: { "x": { requests: { getX: { method: get, security: [ { oidc: [ "profile", "email" ] } ], responses: { ok: { status: 200 } } } } } }
+components: { securitySchemes: { oidc: { type: openIdConnect, openIdConnectUrl: "https://idp/.well-known/openid-configuration" } } }
+`);
+    const r = convergeContract(d);
+    expect(r.findings.filter((f) => f.code === "orphan-scope")).toHaveLength(0);
+    expect(r.clean).toBe(true);
+  });
+
+  test("a DEEP $ref (.../Order/properties/id) resolves to its root — not a false dangling-ref", () => {
+    const d = doc(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: { "o": { requests: { getId: { method: get, responses: { ok: { status: 200, contentSchema: { $ref: "#/components/schemas/Order/properties/id" } } } } } } }
+components: { schemas: { Order: { type: object, properties: { id: { type: integer } } } } }
+`);
+    const r = convergeContract(d);
+    expect(r.findings.some((f) => f.code === "dangling-ref")).toBe(false);
+    expect(r.findings.some((f) => f.code === "unreferenced-entity" && f.where === "Order")).toBe(false); // Order IS referenced
+  });
+
+  test("a security issue inside a WEBHOOK is caught (not just path operations)", () => {
+    const d = doc(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: {}
+webhooks: { onEvent: { method: post, security: [ { ghostHook: [] } ], responses: { ok: { status: 200 } } } }
+components: { securitySchemes: {} }
+`);
+    expect(convergeContract(d).findings.some((f) => f.code === "undeclared-scheme" && f.message.includes("ghostHook"))).toBe(true);
+  });
+
+  test("a malformed (non-array) scope value never iterates character-by-character", () => {
+    const d = doc(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: { "x": { requests: { getX: { method: get, security: [ { auth: "write" } ], responses: { ok: { status: 200 } } } } } }
+components: { securitySchemes: { auth: { type: oauth2, flows: { implicit: { authorizationUrl: "https://x", scopes: { write: "w" } } } } } }
+`);
+    const r = convergeContract(d);
+    expect(r.findings.filter((f) => f.code === "orphan-scope")).toHaveLength(0); // not w,r,i,t,e
+  });
+
+  test("a freshly composed platform (auth + ecommerce + crm) converges clean", () => {
+    const empty = doc(`openapi: 4.0.0-candidate
+info: { title: P, version: 1.0.0 }
+paths: {}
+components: { schemas: {} }`);
+    const composed = composeModules(empty, resolveTemplate(STACK_TEMPLATES.find((t) => t.name === "Everything")!).modules);
+    expect(composed.ok).toBe(true);
+    expect(convergeContract(composed.doc).clean).toBe(true); // no dangling refs, no orphan scopes across modules
+  });
+
+  test("a module installed WITHOUT its required entity would dangle — but install refuses it; converge catches a hand-built dangle", () => {
+    // installModule refuses ecommerce without User; convergeContract independently flags a doc someone hand-merged wrong
+    const broken = installModule(doc(`openapi: 4.0.0-candidate
+info: { title: H, version: 1.0.0 }
+paths: {}
+components: { schemas: { User: { type: object } } }`), ECOMMERCE).doc;
+    // remove User after the fact (simulating a bad hand-edit) → Order.customer now dangles
+    delete (broken.components!.schemas as Record<string, unknown>).User;
+    expect(convergeContract(broken).findings.some((f) => f.code === "dangling-ref" && f.where === "User")).toBe(true);
+  });
+});