@unispechq/unispec-core 0.1.1 → 0.1.2

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,89 @@
+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

@@ -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,195 @@
+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.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,116 @@
+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 normalizeRestPaths(doc) {
+    if (!doc || !doc.service || !doc.service.protocols) {
+        return doc;
+    }
+    const protocols = doc.service.protocols;
+    const rest = protocols.rest;
+    if (!rest || !rest.paths || typeof rest.paths !== "object") {
+        return doc;
+    }
+    const httpMethodOrder = ["get", "head", "options", "post", "put", "patch", "delete"];
+    const normalizedPaths = {};
+    for (const path of Object.keys(rest.paths).sort()) {
+        const pathItem = rest.paths[path];
+        if (!pathItem || typeof pathItem !== "object") {
+            normalizedPaths[path] = pathItem;
+            continue;
+        }
+        const pathItemObj = pathItem;
+        const ordered = {};
+        for (const method of httpMethodOrder) {
+            if (Object.prototype.hasOwnProperty.call(pathItemObj, method)) {
+                ordered[method] = pathItemObj[method];
+            }
+        }
+        const remainingKeys = Object.keys(pathItemObj).filter((k) => !httpMethodOrder.includes(k)).sort();
+        for (const key of remainingKeys) {
+            ordered[key] = pathItemObj[key];
+        }
+        normalizedPaths[path] = ordered;
+    }
+    rest.paths = normalizedPaths;
+    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 || !websocket.channels || typeof websocket.channels !== "object") {
+        return doc;
+    }
+    const originalChannels = websocket.channels;
+    const sortedChannels = {};
+    for (const name of Object.keys(originalChannels).sort()) {
+        const channel = originalChannels[name];
+        if (!channel) {
+            continue;
+        }
+        let messages = channel.messages;
+        if (Array.isArray(messages)) {
+            messages = [...messages].sort((a, b) => {
+                const aName = a?.name ?? "";
+                const bName = b?.name ?? "";
+                return aName.localeCompare(bName);
+            });
+        }
+        sortedChannels[name] = {
+            ...channel,
+            ...(messages ? { messages } : {}),
+        };
+    }
+    websocket.channels = sortedChannels;
+    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 || !graphql.operations) {
+        return doc;
+    }
+    const kinds = ["queries", "mutations", "subscriptions"];
+    for (const kind of kinds) {
+        const bucket = graphql.operations[kind];
+        if (!bucket || typeof bucket !== "object") {
+            continue;
+        }
+        const sorted = {};
+        for (const name of Object.keys(bucket).sort()) {
+            sorted[name] = bucket[name];
+        }
+        graphql.operations[kind] = sorted;
+    }
+    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(normalizeRestPaths(normalized)));
+}

package/dist/types/index.d.ts

@@ -0,0 +1,57 @@
+export interface UniSpecGraphQLSchema {
+    sdl?: string;
+}
+export interface UniSpecGraphQLOperations {
+    queries?: Record<string, unknown>;
+    mutations?: Record<string, unknown>;
+    subscriptions?: Record<string, unknown>;
+}
+export interface UniSpecGraphQLProtocol {
+    schema?: UniSpecGraphQLSchema;
+    operations?: UniSpecGraphQLOperations;
+    extensions?: Record<string, unknown>;
+}
+export interface UniSpecWebSocketMessage {
+    name?: string;
+    summary?: string;
+    description?: string;
+    payload?: unknown;
+    extensions?: Record<string, unknown>;
+}
+export interface UniSpecWebSocketChannel {
+    summary?: string;
+    title?: string;
+    description?: string;
+    direction?: string;
+    messages?: UniSpecWebSocketMessage[];
+    extensions?: Record<string, unknown>;
+}
+export interface UniSpecWebSocketProtocol {
+    channels?: Record<string, UniSpecWebSocketChannel>;
+    extensions?: Record<string, unknown>;
+}
+export interface UniSpecServiceProtocols {
+    rest?: unknown;
+    graphql?: UniSpecGraphQLProtocol;
+    websocket?: UniSpecWebSocketProtocol;
+}
+export interface UniSpecService {
+    name: string;
+    title?: string;
+    description?: string;
+    protocols?: UniSpecServiceProtocols;
+}
+export interface UniSpecDocument {
+    unispecVersion: string;
+    service: UniSpecService;
+    extensions?: Record<string, unknown>;
+}
+export interface ValidationError {
+    message: string;
+    path?: string;
+    code?: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/validator/index.d.ts

@@ -0,0 +1,7 @@
+import { UniSpecDocument, ValidationResult } from "../types";
+export interface ValidateOptions {
+}
+/**
+ * Validate a UniSpec document against the UniSpec JSON Schema.
+ */
+export declare function validateUniSpec(doc: UniSpecDocument, _options?: ValidateOptions): Promise<ValidationResult>;

package/dist/validator/index.js

@@ -0,0 +1,47 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import { createRequire } from "module";
+import { unispec as unispecSchema, manifest as unispecManifest } from "@unispechq/unispec-schema";
+const require = createRequire(import.meta.url);
+const ajv = new Ajv2020({
+    allErrors: true,
+    strict: true,
+});
+// Register all UniSpec subschemas so that Ajv can resolve internal $ref links
+try {
+    const schemaRootPath = require.resolve("@unispechq/unispec-schema");
+    const schemaDir = schemaRootPath.replace(/index\.(cjs|mjs|js)$/u, "schema/");
+    const types = unispecManifest?.types ?? {};
+    const typeSchemaPaths = Object.values(types).map((rel) => String(rel));
+    const loadedTypeSchemas = typeSchemaPaths.map((relPath) => require(schemaDir + relPath));
+    ajv.addSchema(loadedTypeSchemas);
+}
+catch {
+    // If subschemas cannot be loaded for some reason, validation will still work for
+    // parts of the schema that do not rely on those $ref references.
+}
+const validateFn = ajv.compile(unispecSchema);
+function mapAjvErrors(errors) {
+    if (!errors)
+        return [];
+    return errors.map((error) => ({
+        message: error.message || "UniSpec validation error",
+        path: error.instancePath || error.schemaPath,
+        code: error.keyword,
+    }));
+}
+/**
+ * Validate a UniSpec document against the UniSpec JSON Schema.
+ */
+export async function validateUniSpec(doc, _options = {}) {
+    const valid = validateFn(doc);
+    if (valid) {
+        return {
+            valid: true,
+            errors: [],
+        };
+    }
+    return {
+        valid: false,
+        errors: mapAjvErrors(validateFn.errors),
+    };
+}

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@unispechq/unispec-core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Central UniSpec Core Engine providing parsing, validation, normalization, diffing, and conversion of UniSpec specs.",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test tests/*.test.mjs",