@unispechq/unispec-core 0.1.1 → 0.2.0

package/README.md

@@ -59,7 +59,7 @@ Core Engine provides:
 
 - YAML/JSON loader  
 - JSON Schema validator  
-– Normalizer → canonical UniSpec output (REST paths/methods, GraphQL operations, WebSocket channels/messages)  
+– Normalizer → canonical UniSpec output (REST routes, GraphQL operations, WebSocket channels/messages)  
 – Diff engine (with basic breaking / non-breaking classification for REST, GraphQL and WebSocket)  
 – Converters:  
   - UniSpec → OpenAPI (REST-centric)  
@@ -77,19 +77,19 @@ This is the foundation used by:
 At the level of the Core Engine, protocol support is intentionally minimal but deterministic:
 
 - **REST**  
-  - Treated as a general OpenAPI-like structure defined by UniSpec JSON Schemas.  
-  - Normalizer orders `paths` and HTTP methods for stable diffs.  
-  - Diff engine annotates path/operation additions and removals with breaking/non-breaking severity.  
-  - Converter exposes REST as an OpenAPI 3.1 document while preserving the original UniSpec under `x-unispec`.
+  - Typed REST surface defined by `service.protocols.rest.routes[]` and reusable `service.schemas`.  
+  - Normalizer orders routes by `name` (or `path + method`) for stable diffs.  
+  - Diff engine annotates route additions and removals with breaking/non-breaking severity.  
+  - Converter exposes REST as an OpenAPI 3.1 document built from routes, schemas and environments, while preserving the original UniSpec under `x-unispec`.
 
 - **GraphQL**  
-  - Typed protocol with `schema` (SDL) and `operations` (queries/mutations/subscriptions).  
+  - Typed protocol with `schema` (SDL string) and `queries`/`mutations`/`subscriptions` as operation lists.  
   - Normalizer orders operation names within each bucket.  
   - Diff engine annotates operation additions/removals as non-breaking/breaking.  
   - Converter either passes through user-provided SDL or generates a minimal, deterministic SDL shell.
 
 - **WebSocket**  
-  - Typed protocol with channels and messages, plus extensions.  
+  - Typed protocol with channels and messages backed by reusable schemas and security schemes.  
   - Normalizer orders channels by name and messages by `name` within each channel.  
   - Diff engine annotates channel/message additions/removals as non-breaking/breaking changes.  
   - Converter produces a dashboard-friendly model with service metadata, a normalized channel list and the raw protocol.

package/dist/converters/index.d.ts

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,201 @@
+export function toOpenAPI(doc) {
+    const service = doc.service;
+    const rest = (service.protocols?.rest ?? {});
+    const info = {
+        title: service.title ?? service.name,
+        description: service.description,
+    };
+    // Derive OpenAPI servers from UniSpec environments when available.
+    const servers = Array.isArray(service.environments)
+        ? service.environments.map((env) => ({
+            url: env.baseUrl,
+            description: env.name,
+        }))
+        : [];
+    const paths = {};
+    const components = {};
+    // Map service.schemas into OpenAPI components.schemas
+    const schemas = (service.schemas ?? {});
+    const componentsSchemas = {};
+    for (const [name, def] of Object.entries(schemas)) {
+        componentsSchemas[name] = def.jsonSchema;
+    }
+    if (Object.keys(componentsSchemas).length > 0) {
+        components.schemas = componentsSchemas;
+    }
+    // Helper to build a $ref into components.schemas when schemaRef is present.
+    function schemaRefToOpenAPI(schemaRef) {
+        if (!schemaRef) {
+            return {};
+        }
+        return { $ref: `#/components/schemas/${schemaRef}` };
+    }
+    // Build paths from REST routes.
+    if (Array.isArray(rest.routes)) {
+        for (const route of rest.routes) {
+            const pathItem = (paths[route.path] ?? {});
+            const method = route.method.toLowerCase();
+            const parameters = [];
+            // Path params
+            for (const param of route.pathParams ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "path",
+                    required: param.required ?? true,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Query params
+            for (const param of route.queryParams ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "query",
+                    required: param.required ?? false,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Header params
+            for (const param of route.headers ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "header",
+                    required: param.required ?? false,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Request body
+            let requestBody;
+            if (route.requestBody && route.requestBody.content) {
+                const content = {};
+                for (const [mediaType, media] of Object.entries(route.requestBody.content)) {
+                    content[mediaType] = {
+                        schema: schemaRefToOpenAPI(media.schemaRef),
+                    };
+                }
+                requestBody = {
+                    description: route.requestBody.description,
+                    required: route.requestBody.required,
+                    content,
+                };
+            }
+            // Responses
+            const responses = {};
+            for (const [status, resp] of Object.entries(route.responses ?? {})) {
+                const content = {};
+                if (resp.content) {
+                    for (const [mediaType, media] of Object.entries(resp.content)) {
+                        content[mediaType] = {
+                            schema: schemaRefToOpenAPI(media.schemaRef),
+                        };
+                    }
+                }
+                responses[status] = {
+                    description: resp.description ?? "",
+                    ...(Object.keys(content).length > 0 ? { content } : {}),
+                };
+            }
+            const operation = {
+                operationId: route.name,
+                summary: route.summary,
+                description: route.description,
+                ...(parameters.length > 0 ? { parameters } : {}),
+                responses: Object.keys(responses).length > 0 ? responses : { default: { description: "" } },
+            };
+            if (requestBody) {
+                operation.requestBody = requestBody;
+            }
+            // Security requirements
+            if (Array.isArray(route.security) && route.security.length > 0) {
+                operation.security = route.security.map((req) => {
+                    const obj = {};
+                    for (const schemeName of req) {
+                        obj[schemeName] = [];
+                    }
+                    return obj;
+                });
+            }
+            pathItem[method] = operation;
+            paths[route.path] = pathItem;
+        }
+    }
+    // Security schemes pass-through from REST protocol
+    const componentsSecuritySchemes = rest.securitySchemes ?? {};
+    if (Object.keys(componentsSecuritySchemes).length > 0) {
+        components.securitySchemes = componentsSecuritySchemes;
+    }
+    return {
+        openapi: "3.1.0",
+        info,
+        servers,
+        paths,
+        ...(Object.keys(components).length > 0 ? { components } : {}),
+        "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;
+    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 channelsArray = Array.isArray(websocket.channels) ? websocket.channels : [];
+    const channels = [...channelsArray]
+        .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""))
+        .map((channel) => ({
+        name: channel.name,
+        summary: undefined,
+        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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,233 @@
+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
+    if (Array.isArray(oldVal) && Array.isArray(newVal)) {
+        // Special handling for UniSpec collections identified by "name"
+        const isNamedCollection = basePath === "/service/protocols/rest/routes" ||
+            basePath === "/service/protocols/websocket/channels" ||
+            basePath === "/service/protocols/graphql/queries" ||
+            basePath === "/service/protocols/graphql/mutations" ||
+            basePath === "/service/protocols/graphql/subscriptions";
+        if (isNamedCollection) {
+            const oldByName = new Map();
+            const newByName = new Map();
+            for (const item of oldVal) {
+                if (item && typeof item === "object" && typeof item.name === "string") {
+                    oldByName.set(item.name, item);
+                }
+            }
+            for (const item of newVal) {
+                if (item && typeof item === "object" && typeof item.name === "string") {
+                    newByName.set(item.name, item);
+                }
+            }
+            // Removed
+            for (const [name, oldItem] of oldByName.entries()) {
+                if (!newByName.has(name)) {
+                    out.push({
+                        path: `${basePath}/${name}`,
+                        description: "Item removed",
+                        severity: "unknown",
+                    });
+                }
+                else {
+                    const newItem = newByName.get(name);
+                    diffValues(oldItem, newItem, `${basePath}/${name}`, out);
+                }
+            }
+            // Added
+            for (const [name] of newByName.entries()) {
+                if (!oldByName.has(name)) {
+                    out.push({
+                        path: `${basePath}/${name}`,
+                        description: "Item added",
+                        severity: "unknown",
+                    });
+                }
+            }
+            return;
+        }
+        // Generic shallow index-based compare
+        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/routes/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected shape: ["service", "protocols", "rest", "routes", index]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "rest" || segments[3] !== "routes") {
+        return change;
+    }
+    const index = segments[4];
+    if (typeof index === "undefined") {
+        return change;
+    }
+    const annotated = {
+        ...change,
+        protocol: "rest",
+    };
+    if (change.description === "Item removed" || change.description === "Field removed") {
+        annotated.kind = "rest.route.removed";
+        annotated.severity = "breaking";
+    }
+    else if (change.description === "Item added" || change.description === "Field added") {
+        annotated.kind = "rest.route.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 base: ["service","protocols","websocket","channels", channelIndex, ...]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "websocket" || segments[3] !== "channels") {
+        return change;
+    }
+    const channelIndex = segments[4];
+    const next = segments[5];
+    const annotated = {
+        ...change,
+        protocol: "websocket",
+    };
+    if (typeof channelIndex === "undefined") {
+        return annotated;
+    }
+    // Channel-level changes: /service/protocols/websocket/channels/{index}
+    if (!next) {
+        if (change.description === "Item removed" || change.description === "Field removed") {
+            annotated.kind = "websocket.channel.removed";
+            annotated.severity = "breaking";
+        }
+        else if (change.description === "Item added" || change.description === "Field added") {
+            annotated.kind = "websocket.channel.added";
+            annotated.severity = "non-breaking";
+        }
+        return annotated;
+    }
+    // Message-level changes: /service/protocols/websocket/channels/{index}/messages/{msgIndex}
+    if (next === "messages") {
+        const messageIndex = segments[6];
+        if (typeof messageIndex === "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/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected: ["service","protocols","graphql", kind, index, ...]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "graphql") {
+        return change;
+    }
+    const opKind = segments[3];
+    const index = segments[4];
+    if (!opKind || typeof index === "undefined") {
+        return change;
+    }
+    if (opKind !== "queries" && opKind !== "mutations" && opKind !== "subscriptions") {
+        return change;
+    }
+    const annotated = {
+        ...change,
+        protocol: "graphql",
+    };
+    if (change.description === "Item removed" || change.description === "Field removed") {
+        annotated.kind = "graphql.operation.removed";
+        annotated.severity = "breaking";
+    }
+    else if (change.description === "Item added" || 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.js

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,19 @@
+/**
+ * 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

@@ -0,0 +1,11 @@
+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;

package/dist/normalizer/index.js

@@ -0,0 +1,104 @@
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === "[object Object]";
+}
+function normalizeValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeValue(item));
+    }
+    if (isPlainObject(value)) {
+        const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+        const normalized = {};
+        for (const [key, val] of entries) {
+            normalized[key] = normalizeValue(val);
+        }
+        return normalized;
+    }
+    return value;
+}
+function normalizeRestRoutes(doc) {
+    if (!doc || !doc.service || !doc.service.protocols) {
+        return doc;
+    }
+    const protocols = doc.service.protocols;
+    const rest = protocols.rest;
+    if (!rest || !Array.isArray(rest.routes)) {
+        return doc;
+    }
+    const routes = [...rest.routes];
+    routes.sort((a, b) => {
+        const keyA = a.name || `${a.path} ${a.method}`;
+        const keyB = b.name || `${b.path} ${b.method}`;
+        return keyA.localeCompare(keyB);
+    });
+    rest.routes = routes;
+    return doc;
+}
+function normalizeWebSocket(doc) {
+    if (!doc || !doc.service || !doc.service.protocols) {
+        return doc;
+    }
+    const protocols = doc.service.protocols;
+    const websocket = protocols.websocket;
+    if (!websocket || !Array.isArray(websocket.channels)) {
+        return doc;
+    }
+    const channels = websocket.channels.map((channel) => {
+        if (!channel || !Array.isArray(channel.messages)) {
+            return channel;
+        }
+        const sortedMessages = [...channel.messages].sort((a, b) => {
+            const aName = a?.name ?? "";
+            const bName = b?.name ?? "";
+            return aName.localeCompare(bName);
+        });
+        return {
+            ...channel,
+            messages: sortedMessages,
+        };
+    });
+    channels.sort((a, b) => {
+        const aName = a?.name ?? "";
+        const bName = b?.name ?? "";
+        return aName.localeCompare(bName);
+    });
+    websocket.channels = channels;
+    return doc;
+}
+function normalizeGraphqlOperations(doc) {
+    if (!doc || !doc.service || !doc.service.protocols) {
+        return doc;
+    }
+    const protocols = doc.service.protocols;
+    const graphql = protocols.graphql;
+    if (!graphql) {
+        return doc;
+    }
+    const kinds = [
+        "queries",
+        "mutations",
+        "subscriptions",
+    ];
+    for (const kind of kinds) {
+        const ops = graphql[kind];
+        if (!Array.isArray(ops)) {
+            continue;
+        }
+        graphql[kind] = [...ops].sort((a, b) => {
+            const aName = a?.name ?? "";
+            const bName = b?.name ?? "";
+            return aName.localeCompare(bName);
+        });
+    }
+    return doc;
+}
+/**
+ * Normalize a UniSpec document into a canonical, deterministic form.
+ *
+ * Current behavior:
+ * - Recursively sorts object keys lexicographically.
+ * - Preserves values as-is.
+ */
+export function normalizeUniSpec(doc, _options = {}) {
+    const normalized = normalizeValue(doc);
+    return normalizeWebSocket(normalizeGraphqlOperations(normalizeRestRoutes(normalized)));
+}