@suluk/cockpit 0.1.9 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/cockpit",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "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/diagram.ts

@@ -0,0 +1,109 @@
+/**
+ * Diagrams (D2) — ANOTHER projection from the one v4 contract. Suluk already derives data/API/docs/UI/cost from
+ * the contract; a diagram is the same move in visual form. contractToD2 emits D2 (d2lang.com) source for a few
+ * views: an ERD (entities + their references), the declarative cycle (one contract → every layer), and the
+ * operation surface (paths → operations, grouped by tag). Pure text generation (no host, no renderer) →
+ * unit-tested; the extension/docs render the D2 (d2 CLI, the playground, or a service like kroki.io).
+ */
+import { buildAda, type OpenAPIv4Document, type SchemaOrRef } from "@suluk/core";
+import { schemaRefName } from "@suluk/builder";
+import { buildCycle } from "./cycle";
+
+export type DiagramView = "erd" | "cycle" | "operations";
+export function diagramViews(): { id: DiagramView; title: string; description: string }[] {
+  return [
+    { id: "erd", title: "Entity relationships", description: "components.schemas as tables + their $ref relationships" },
+    { id: "cycle", title: "The declarative cycle", description: "one v4 contract → every projected layer" },
+    { id: "operations", title: "Operation surface", description: "paths → operations, grouped by tag/entity" },
+  ];
+}
+
+// D2 reserved keywords — interpreted specially when they appear in a KEY position (inside any map), so a schema
+// field literally named "shape"/"label"/… must be QUOTED there or D2 treats it as a directive and corrupts the node.
+const D2_RESERVED = new Set([
+  "shape", "label", "style", "constraint", "width", "height", "icon", "near", "tooltip", "link", "class", "direction",
+  "grid-rows", "grid-columns", "source-arrowhead", "target-arrowhead", "vertical-gap", "horizontal-gap", "top", "left",
+]);
+const quote = (name: string): string => `"${name.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+/** A D2 name on the VALUE side (a type) — quote only when it isn't a bare word (reserved words are safe as values). */
+function d2id(name: string): string {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : quote(name);
+}
+/** A D2 name in a KEY position (node/field name, edge endpoint) — also quote reserved keywords. */
+function d2key(name: string): string {
+  return D2_RESERVED.has(name) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? quote(name) : name;
+}
+function d2label(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+
+/** The display type of a property, and the entity it references (if any). */
+function fieldType(schema: unknown, entities: Set<string>): { type: string; ref?: string } {
+  const s = schema as { $ref?: string; type?: string; items?: unknown; enum?: unknown[] };
+  if (typeof s?.$ref === "string") { const r = schemaRefName(s.$ref); return { type: r ?? "ref", ref: r && entities.has(r) ? r : undefined }; }
+  if (s?.type === "array") { const inner = fieldType(s.items, entities); return { type: `${inner.type}[]`, ref: inner.ref }; }
+  if (Array.isArray(s?.enum)) return { type: "enum" };
+  return { type: s?.type ?? "any" };
+}
+
+function erdD2(doc: OpenAPIv4Document): string {
+  const schemas = (doc.components?.schemas ?? {}) as Record<string, SchemaOrRef>;
+  const entities = new Set(Object.keys(schemas));
+  const lines: string[] = ["# Suluk ERD — entities + references (generated from the v4 contract)", "direction: right", ""];
+  const edges: string[] = [];
+  for (const [name, sObj] of Object.entries(schemas)) {
+    const s = sObj as { properties?: Record<string, unknown>; required?: string[] };
+    const required = new Set(s.required ?? []);
+    lines.push(`${d2key(name)}: {`, "  shape: sql_table");
+    for (const [fname, fObj] of Object.entries(s.properties ?? {})) {
+      const { type, ref } = fieldType(fObj, entities);
+      lines.push(`  ${d2key(fname)}: ${d2id(type)}${required.has(fname) ? " {constraint: NOT NULL}" : ""}`);
+      if (ref) edges.push(`${d2key(name)}.${d2key(fname)} -> ${d2key(ref)}: references`);
+    }
+    if (!Object.keys(s.properties ?? {}).length) lines.push('  "(no fields)": ""');
+    lines.push("}");
+  }
+  if (!entities.size) lines.push("note: 'no components.schemas entities'");
+  return [...lines, "", ...edges].join("\n");
+}
+
+function cycleD2(doc: OpenAPIv4Document): string {
+  const cyc = buildCycle(doc);
+  const layers = cyc.layers.filter((l) => l.id !== "document"); // document is the hub itself, drawn as `contract`
+  return [
+    "# Suluk — one v4 contract projected into every layer",
+    "direction: down",
+    "",
+    // the hub is named `_hub` (NOT `contract`) so it can't collide with the "contract" (API) layer node
+    `_hub: {label: "v4 contract\\n${d2label(doc.info?.title ?? "")}"; shape: document; style.bold: true}`,
+    ...layers.map((l) => `${l.id}: {label: "${d2label(l.title)}\\n${d2label(l.summary)}"; shape: rectangle}`),
+    "",
+    ...layers.map((l) => `_hub -> ${l.id}`),
+  ].join("\n");
+}
+
+function operationsD2(doc: OpenAPIv4Document): string {
+  const ops = buildAda(doc).operations;
+  const byTag = new Map<string, { name: string; method: string; path: string }[]>();
+  for (const o of ops) {
+    const tag = (o.request.tags?.[0] as string | undefined) ?? "untagged";
+    (byTag.get(tag) ?? byTag.set(tag, []).get(tag)!).push({ name: o.name, method: o.request.method.toUpperCase(), path: o.pathTemplate });
+  }
+  const lines: string[] = ["# Suluk — operation surface, grouped by tag", "direction: right", ""];
+  for (const [tag, list] of byTag) {
+    lines.push(`${d2key(tag)}: {`, "  shape: package");
+    for (const o of list) lines.push(`  ${d2key(o.name)}: {label: "${d2label(`${o.method} ${o.path}`)}"}`);
+    lines.push("}");
+  }
+  if (!ops.length) lines.push("note: 'no operations'");
+  return lines.join("\n");
+}
+
+/** Generate D2 diagram source for a view of the contract. */
+export function contractToD2(doc: OpenAPIv4Document, view: DiagramView): string {
+  switch (view) {
+    case "erd": return erdD2(doc);
+    case "cycle": return cycleD2(doc);
+    case "operations": return operationsD2(doc);
+  }
+}

package/src/index.ts

@@ -16,6 +16,8 @@ export { diffContracts, canonical, type ContractDiff, type ChangedOp, type OpRef
 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";
+// diagrams: D2 source for views of the contract (ERD / the declarative cycle / the operation surface) — another projection.
+export { contractToD2, diagramViews, type DiagramView } from "./diagram";
 // 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/diagram.test.ts

@@ -0,0 +1,74 @@
+import { test, expect, describe } from "bun:test";
+import { parseDocument } from "@suluk/core";
+import { installModule, ECOMMERCE } from "@suluk/builder";
+import { contractToD2, diagramViews } from "../src/diagram";
+
+const host = () => parseDocument(`openapi: 4.0.0-candidate
+info: { title: Shop, version: 1.0.0 }
+paths: {}
+components: { schemas: { User: { type: object, required: [ email ], properties: { id: { type: integer }, email: { type: string } } } } }`);
+
+describe("diagramViews", () => {
+  test("lists the available views", () => {
+    expect(diagramViews().map((v) => v.id)).toEqual(["erd", "cycle", "operations"]);
+  });
+});
+
+describe("contractToD2 — ERD", () => {
+  const doc = installModule(host(), ECOMMERCE).doc; // User + Product + Order (Order.customer -> User)
+  const d2 = contractToD2(doc, "erd");
+  test("emits a sql_table per entity", () => {
+    expect(d2).toContain("User: {");
+    expect(d2).toContain("Order: {");
+    expect(d2).toContain("shape: sql_table");
+  });
+  test("draws the cross-entity reference as an edge", () => {
+    expect(d2).toContain("Order.customer -> User: references");
+  });
+  test("marks required fields NOT NULL", () => {
+    expect(d2).toContain("NOT NULL"); // Order.items / Product.name are required
+  });
+  test("quotes a field whose name isn't a bare word", () => {
+    const odd = parseDocument(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: {}
+components: { schemas: { "Weird Name": { type: object, properties: { "a-b": { type: string } } } } }`);
+    const e = contractToD2(odd, "erd");
+    expect(e).toContain('"Weird Name": {');
+    expect(e).toContain('"a-b"');
+  });
+});
+
+describe("contractToD2 — cycle + operations", () => {
+  const doc = installModule(host(), ECOMMERCE).doc;
+  test("the cycle view links a distinct hub to its projected layers (no contract/contract collision or self-loop)", () => {
+    const d2 = contractToD2(doc, "cycle");
+    expect(d2).toContain("_hub: {"); // the document-shaped hub, named so it can't collide with the contract layer
+    expect(d2).toContain("_hub -> data");
+    expect(d2).toContain("_hub -> cost");
+    expect(d2).not.toContain("contract -> contract"); // no self-loop
+    expect(d2).toContain("contract: {"); // the Contract (API) layer still renders as its own node
+  });
+  test("a schema field named a D2 reserved keyword (shape) is quoted, not a directive", () => {
+    const odd = parseDocument(`openapi: 4.0.0-candidate
+info: { title: T, version: 1.0.0 }
+paths: {}
+components: { schemas: { Box: { type: object, properties: { shape: { type: string }, label: { type: string } } } } }`);
+    const e = contractToD2(odd, "erd");
+    expect(e).toContain('"shape": string'); // quoted as a field, not a bare `shape:` directive
+    expect(e).toContain('"label": string');
+  });
+  test("the operations view groups operations and shows method + path", () => {
+    const d2 = contractToD2(doc, "operations");
+    expect(d2).toContain("shape: package");
+    expect(d2).toContain("listProduct");
+    expect(d2).toContain("POST"); // createProduct etc.
+  });
+  test("an empty contract still produces valid (non-empty) D2 for every view", () => {
+    const empty = parseDocument(`openapi: 4.0.0-candidate
+info: { title: E, version: 1.0.0 }
+paths: {}
+components: { schemas: {} }`);
+    for (const v of diagramViews()) expect(contractToD2(empty, v.id).length).toBeGreaterThan(0);
+  });
+});