@unispechq/unispec-core 0.1.0 → 0.1.1

package/tests/normalizer.test.mjs

@@ -1,115 +1,115 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import * as core from "../dist/index.js";
-
-const { normalizeUniSpec } = core;
-
-test("normalizeUniSpec sorts object keys deterministically", () => {
-  const doc = {
-    b: 1,
-    a: {
-      d: 3,
-      c: 2,
-    },
-  };
-
-  const normalized = normalizeUniSpec(doc);
-
-  assert.deepEqual(Object.keys(normalized), ["a", "b"]);
-  assert.deepEqual(Object.keys(normalized.a), ["c", "d"]);
-});
-
-test("normalizeUniSpec normalizes REST paths and HTTP methods order", () => {
-  const doc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        rest: {
-          paths: {
-            "/z": {
-              post: {},
-              get: {},
-            },
-            "/a": {
-              delete: {},
-              get: {},
-            },
-          },
-        },
-      },
-    },
-  };
-
-  const normalized = normalizeUniSpec(doc);
-
-  const paths = normalized.service.protocols.rest.paths;
-
-  assert.deepEqual(Object.keys(paths), ["/a", "/z"]);
-  assert.deepEqual(Object.keys(paths["/z"]), ["get", "post"]);
-  assert.deepEqual(Object.keys(paths["/a"]), ["get", "delete"]);
-});
-
-test("normalizeUniSpec normalizes GraphQL operations order", () => {
-  const doc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        graphql: {
-          operations: {
-            queries: {
-              me: {},
-              ping: {},
-              a: {},
-            },
-          },
-        },
-      },
-    },
-  };
-
-  const normalized = normalizeUniSpec(doc);
-
-  const queries = normalized.service.protocols.graphql.operations.queries;
-  assert.deepEqual(Object.keys(queries), ["a", "me", "ping"]);
-});
-
-test("normalizeUniSpec normalizes WebSocket channels and messages order", () => {
-  const doc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        websocket: {
-          channels: {
-            zChannel: {
-              messages: [
-                { name: "msgB" },
-                { name: "msgA" },
-              ],
-            },
-            aChannel: {
-              messages: [
-                { name: "z" },
-                { name: "a" },
-              ],
-            },
-          },
-        },
-      },
-    },
-  };
-
-  const normalized = normalizeUniSpec(doc);
-
-  const channels = normalized.service.protocols.websocket.channels;
-  assert.deepEqual(Object.keys(channels), ["aChannel", "zChannel"]);
-
-  const aMessages = channels.aChannel.messages;
-  const zMessages = channels.zChannel.messages;
-
-  assert.deepEqual(aMessages.map((m) => m.name), ["a", "z"]);
-  assert.deepEqual(zMessages.map((m) => m.name), ["msgA", "msgB"]);
-});
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import * as core from "../dist/index.js";
+
+const { normalizeUniSpec } = core;
+
+test("normalizeUniSpec sorts object keys deterministically", () => {
+  const doc = {
+    b: 1,
+    a: {
+      d: 3,
+      c: 2,
+    },
+  };
+
+  const normalized = normalizeUniSpec(doc);
+
+  assert.deepEqual(Object.keys(normalized), ["a", "b"]);
+  assert.deepEqual(Object.keys(normalized.a), ["c", "d"]);
+});
+
+test("normalizeUniSpec normalizes REST paths and HTTP methods order", () => {
+  const doc = {
+    unispecVersion: "0.1.0",
+    service: {
+      name: "test-service",
+      protocols: {
+        rest: {
+          paths: {
+            "/z": {
+              post: {},
+              get: {},
+            },
+            "/a": {
+              delete: {},
+              get: {},
+            },
+          },
+        },
+      },
+    },
+  };
+
+  const normalized = normalizeUniSpec(doc);
+
+  const paths = normalized.service.protocols.rest.paths;
+
+  assert.deepEqual(Object.keys(paths), ["/a", "/z"]);
+  assert.deepEqual(Object.keys(paths["/z"]), ["get", "post"]);
+  assert.deepEqual(Object.keys(paths["/a"]), ["get", "delete"]);
+});
+
+test("normalizeUniSpec normalizes GraphQL operations order", () => {
+  const doc = {
+    unispecVersion: "0.1.0",
+    service: {
+      name: "test-service",
+      protocols: {
+        graphql: {
+          operations: {
+            queries: {
+              me: {},
+              ping: {},
+              a: {},
+            },
+          },
+        },
+      },
+    },
+  };
+
+  const normalized = normalizeUniSpec(doc);
+
+  const queries = normalized.service.protocols.graphql.operations.queries;
+  assert.deepEqual(Object.keys(queries), ["a", "me", "ping"]);
+});
+
+test("normalizeUniSpec normalizes WebSocket channels and messages order", () => {
+  const doc = {
+    unispecVersion: "0.1.0",
+    service: {
+      name: "test-service",
+      protocols: {
+        websocket: {
+          channels: {
+            zChannel: {
+              messages: [
+                { name: "msgB" },
+                { name: "msgA" },
+              ],
+            },
+            aChannel: {
+              messages: [
+                { name: "z" },
+                { name: "a" },
+              ],
+            },
+          },
+        },
+      },
+    },
+  };
+
+  const normalized = normalizeUniSpec(doc);
+
+  const channels = normalized.service.protocols.websocket.channels;
+  assert.deepEqual(Object.keys(channels), ["aChannel", "zChannel"]);
+
+  const aMessages = channels.aChannel.messages;
+  const zMessages = channels.zChannel.messages;
+
+  assert.deepEqual(aMessages.map((m) => m.name), ["a", "z"]);
+  assert.deepEqual(zMessages.map((m) => m.name), ["msgA", "msgB"]);
+});

package/tsconfig.json

@@ -1,15 +1,15 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "Node",
-    "outDir": "dist",
-    "rootDir": "src",
-    "declaration": true,
-    "strict": true,
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true
-  },
-  "include": ["src"]
-}
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/dist/converters/index.d.ts

@@ -1,13 +0,0 @@
-import { UniSpecDocument } from "../types";
-export interface OpenAPIDocument {
-    [key: string]: unknown;
-}
-export interface GraphQLSDLOutput {
-    sdl: string;
-}
-export interface WebSocketModel {
-    [key: string]: unknown;
-}
-export declare function toOpenAPI(doc: UniSpecDocument): OpenAPIDocument;
-export declare function toGraphQLSDL(doc: UniSpecDocument): GraphQLSDLOutput;
-export declare function toWebSocketModel(doc: UniSpecDocument): WebSocketModel;

package/dist/converters/index.js

@@ -1,89 +0,0 @@
-export function toOpenAPI(doc) {
-    const service = doc.service;
-    const rest = service.protocols?.rest;
-    const info = {
-        title: service.title ?? service.name,
-        description: service.description,
-    };
-    const servers = rest?.servers ?? [];
-    const paths = rest?.paths ?? {};
-    // Transparently forward additional REST protocol fields into the OpenAPI document.
-    // This allows users to describe components, security, tags and other structures
-    // without forcing a specific REST model at the core layer.
-    const { servers: _omitServers, paths: _omitPaths, ...restExtras } = rest ?? {};
-    return {
-        openapi: "3.1.0",
-        info,
-        servers,
-        paths,
-        ...restExtras,
-        "x-unispec": doc,
-    };
-}
-export function toGraphQLSDL(doc) {
-    // Minimal implementation: generate a basic SDL that exposes service metadata
-    // via a Query field. This does not attempt to interpret the full GraphQL
-    // protocol structure yet, but provides a stable, deterministic SDL shape
-    // based on top-level UniSpec document fields.
-    const graphql = doc.service.protocols?.graphql;
-    const customSDL = graphql?.schema?.sdl;
-    if (typeof customSDL === "string" && customSDL.trim()) {
-        return { sdl: customSDL };
-    }
-    const service = doc.service;
-    const title = service.title ?? service.name;
-    const description = service.description ?? "";
-    const lines = [];
-    if (title || description) {
-        lines.push("\"\"");
-        if (title) {
-            lines.push(title);
-        }
-        if (description) {
-            lines.push("");
-            lines.push(description);
-        }
-        lines.push("\"\"");
-    }
-    lines.push("schema {");
-    lines.push("  query: Query");
-    lines.push("}");
-    lines.push("");
-    lines.push("type Query {");
-    lines.push("  _serviceInfo: String!\n");
-    lines.push("}");
-    const sdl = lines.join("\n");
-    return { sdl };
-}
-export function toWebSocketModel(doc) {
-    // Base WebSocket model intended for a modern, dashboard-oriented UI.
-    // It exposes service metadata, a normalized list of channels and the raw
-    // websocket protocol object, while also embedding the original UniSpec
-    // document under a technical key for debugging and introspection.
-    const service = doc.service;
-    const websocket = (service.protocols?.websocket ?? {});
-    const channelsRecord = (websocket && typeof websocket === "object" && websocket.channels && typeof websocket.channels === "object")
-        ? websocket.channels
-        : {};
-    const channels = Object.keys(channelsRecord).sort().map((name) => {
-        const channel = channelsRecord[name] ?? {};
-        return {
-            name,
-            summary: channel.summary ?? channel.title,
-            description: channel.description,
-            direction: channel.direction,
-            messages: channel.messages,
-            raw: channel,
-        };
-    });
-    return {
-        service: {
-            name: service.name,
-            title: service.title,
-            description: service.description,
-        },
-        channels,
-        rawProtocol: websocket,
-        "x-unispec-ws": doc,
-    };
-}

package/dist/diff/index.d.ts

@@ -1,21 +0,0 @@
-import { UniSpecDocument } from "../types";
-export type ChangeSeverity = "breaking" | "non-breaking" | "unknown";
-export interface UniSpecChange {
-    path: string;
-    description: string;
-    severity: ChangeSeverity;
-    protocol?: "rest" | "graphql" | "websocket";
-    kind?: string;
-}
-export interface DiffResult {
-    changes: UniSpecChange[];
-}
-/**
- * Compute a structural diff between two UniSpec documents.
- *
- * Current behavior:
- * - Tracks added, removed, and changed fields and array items.
- * - Uses JSON Pointer-like paths rooted at "" (e.g., "/info/title").
- * - Marks all changes with severity "unknown" for now.
- */
-export declare function diffUniSpec(oldDoc: UniSpecDocument, newDoc: UniSpecDocument): DiffResult;

package/dist/diff/index.js

@@ -1,195 +0,0 @@
-function isPlainObject(value) {
-    return Object.prototype.toString.call(value) === "[object Object]";
-}
-function diffValues(oldVal, newVal, basePath, out) {
-    if (oldVal === newVal) {
-        return;
-    }
-    // Both plain objects → recurse by keys
-    if (isPlainObject(oldVal) && isPlainObject(newVal)) {
-        const oldKeys = new Set(Object.keys(oldVal));
-        const newKeys = new Set(Object.keys(newVal));
-        // Removed keys
-        for (const key of oldKeys) {
-            if (!newKeys.has(key)) {
-                out.push({
-                    path: `${basePath}/${key}`,
-                    description: "Field removed",
-                    severity: "unknown",
-                });
-            }
-        }
-        // Added / changed keys
-        for (const key of newKeys) {
-            const childPath = `${basePath}/${key}`;
-            if (!oldKeys.has(key)) {
-                out.push({
-                    path: childPath,
-                    description: "Field added",
-                    severity: "unknown",
-                });
-                continue;
-            }
-            diffValues(oldVal[key], newVal[key], childPath, out);
-        }
-        return;
-    }
-    // Arrays → shallow compare by index for now
-    if (Array.isArray(oldVal) && Array.isArray(newVal)) {
-        const maxLen = Math.max(oldVal.length, newVal.length);
-        for (let i = 0; i < maxLen; i++) {
-            const childPath = `${basePath}/${i}`;
-            if (i >= oldVal.length) {
-                out.push({
-                    path: childPath,
-                    description: "Item added",
-                    severity: "unknown",
-                });
-            }
-            else if (i >= newVal.length) {
-                out.push({
-                    path: childPath,
-                    description: "Item removed",
-                    severity: "unknown",
-                });
-            }
-            else {
-                diffValues(oldVal[i], newVal[i], childPath, out);
-            }
-        }
-        return;
-    }
-    // Primitive or mismatched types → treat as value change
-    out.push({
-        path: basePath,
-        description: "Value changed",
-        severity: "unknown",
-    });
-}
-function annotateRestChange(change) {
-    if (!change.path.startsWith("/service/protocols/rest/paths/")) {
-        return change;
-    }
-    const segments = change.path.split("/").filter(Boolean);
-    // Expected shape: ["service", "protocols", "rest", "paths", pathKey?, method?]
-    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "rest" || segments[3] !== "paths") {
-        return change;
-    }
-    const pathKey = segments[4];
-    const method = segments[5];
-    const httpMethods = new Set(["get", "head", "options", "post", "put", "patch", "delete"]);
-    const annotated = {
-        ...change,
-        protocol: "rest",
-    };
-    if (change.description === "Field removed") {
-        if (pathKey && !method) {
-            annotated.kind = "rest.path.removed";
-            annotated.severity = "breaking";
-        }
-        else if (pathKey && method && httpMethods.has(method)) {
-            annotated.kind = "rest.operation.removed";
-            annotated.severity = "breaking";
-        }
-    }
-    else if (change.description === "Field added") {
-        if (pathKey && !method) {
-            annotated.kind = "rest.path.added";
-            annotated.severity = "non-breaking";
-        }
-        else if (pathKey && method && httpMethods.has(method)) {
-            annotated.kind = "rest.operation.added";
-            annotated.severity = "non-breaking";
-        }
-    }
-    return annotated;
-}
-function annotateWebSocketChange(change) {
-    if (!change.path.startsWith("/service/protocols/websocket/channels/")) {
-        return change;
-    }
-    const segments = change.path.split("/").filter(Boolean);
-    // Expected: ["service","protocols","websocket","channels", channelName, ...]
-    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "websocket" || segments[3] !== "channels") {
-        return change;
-    }
-    const channelName = segments[4];
-    const next = segments[5];
-    const annotated = {
-        ...change,
-        protocol: "websocket",
-    };
-    if (!channelName) {
-        return annotated;
-    }
-    // Channel-level changes
-    if (!next) {
-        if (change.description === "Field removed") {
-            annotated.kind = "websocket.channel.removed";
-            annotated.severity = "breaking";
-        }
-        else if (change.description === "Field added") {
-            annotated.kind = "websocket.channel.added";
-            annotated.severity = "non-breaking";
-        }
-        return annotated;
-    }
-    // Message-level changes (channels/{channelName}/messages/{index})
-    if (next === "messages") {
-        const index = segments[6];
-        if (typeof index === "undefined") {
-            return annotated;
-        }
-        if (change.description === "Item removed") {
-            annotated.kind = "websocket.message.removed";
-            annotated.severity = "breaking";
-        }
-        else if (change.description === "Item added") {
-            annotated.kind = "websocket.message.added";
-            annotated.severity = "non-breaking";
-        }
-    }
-    return annotated;
-}
-function annotateGraphQLChange(change) {
-    if (!change.path.startsWith("/service/protocols/graphql/operations/")) {
-        return change;
-    }
-    const segments = change.path.split("/").filter(Boolean);
-    // Expected: ["service","protocols","graphql","operations", kind, opName?]
-    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "graphql" || segments[3] !== "operations") {
-        return change;
-    }
-    const opKind = segments[4];
-    const opName = segments[5];
-    if (!opKind || !opName) {
-        return change;
-    }
-    const annotated = {
-        ...change,
-        protocol: "graphql",
-    };
-    if (change.description === "Field removed") {
-        annotated.kind = "graphql.operation.removed";
-        annotated.severity = "breaking";
-    }
-    else if (change.description === "Field added") {
-        annotated.kind = "graphql.operation.added";
-        annotated.severity = "non-breaking";
-    }
-    return annotated;
-}
-/**
- * Compute a structural diff between two UniSpec documents.
- *
- * Current behavior:
- * - Tracks added, removed, and changed fields and array items.
- * - Uses JSON Pointer-like paths rooted at "" (e.g., "/info/title").
- * - Marks all changes with severity "unknown" for now.
- */
-export function diffUniSpec(oldDoc, newDoc) {
-    const changes = [];
-    diffValues(oldDoc, newDoc, "", changes);
-    const annotated = changes.map((change) => annotateWebSocketChange(annotateGraphQLChange(annotateRestChange(change))));
-    return { changes: annotated };
-}

package/dist/index.d.ts

@@ -1,6 +0,0 @@
-export * from "./types/index.js";
-export * from "./loader/index.js";
-export * from "./validator/index.js";
-export * from "./normalizer/index.js";
-export * from "./diff/index.js";
-export * from "./converters/index.js";

package/dist/index.js

@@ -1,6 +0,0 @@
-export * from "./types/index.js";
-export * from "./loader/index.js";
-export * from "./validator/index.js";
-export * from "./normalizer/index.js";
-export * from "./diff/index.js";
-export * from "./converters/index.js";

package/dist/loader/index.d.ts

@@ -1,13 +0,0 @@
-import { UniSpecDocument } from "../types";
-export interface LoadOptions {
-    filename?: string;
-}
-/**
- * Load a UniSpec document from a raw input value.
- * Currently supports:
- * - JavaScript objects (treated as already parsed UniSpec)
- * - JSON strings
- *
- * YAML and filesystem helpers will be added later, keeping this API stable.
- */
-export declare function loadUniSpec(input: string | object, _options?: LoadOptions): Promise<UniSpecDocument>;

package/dist/loader/index.js

@@ -1,19 +0,0 @@
-/**
- * Load a UniSpec document from a raw input value.
- * Currently supports:
- * - JavaScript objects (treated as already parsed UniSpec)
- * - JSON strings
- *
- * YAML and filesystem helpers will be added later, keeping this API stable.
- */
-export async function loadUniSpec(input, _options = {}) {
-    if (typeof input === "string") {
-        const trimmed = input.trim();
-        if (!trimmed) {
-            throw new Error("Cannot load UniSpec: input string is empty");
-        }
-        // For now we assume JSON; YAML support will be added later.
-        return JSON.parse(trimmed);
-    }
-    return input;
-}

package/dist/normalizer/index.d.ts

@@ -1,11 +0,0 @@
-import { UniSpecDocument } from "../types";
-export interface NormalizeOptions {
-}
-/**
- * Normalize a UniSpec document into a canonical, deterministic form.
- *
- * Current behavior:
- * - Recursively sorts object keys lexicographically.
- * - Preserves values as-is.
- */
-export declare function normalizeUniSpec(doc: UniSpecDocument, _options?: NormalizeOptions): UniSpecDocument;