@unispechq/unispec-core 0.1.0

package/src/diff/index.ts

@@ -0,0 +1,235 @@
+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[];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+
+function diffValues(oldVal: unknown, newVal: unknown, basePath: string, out: UniSpecChange[]): void {
+  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 as Record<string, unknown>)[key], (newVal as Record<string, unknown>)[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: UniSpecChange): UniSpecChange {
+  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: UniSpecChange = {
+    ...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: UniSpecChange): UniSpecChange {
+  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: UniSpecChange = {
+    ...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: UniSpecChange): UniSpecChange {
+  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: UniSpecChange = {
+    ...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: UniSpecDocument, newDoc: UniSpecDocument): DiffResult {
+  const changes: UniSpecChange[] = [];
+  diffValues(oldDoc, newDoc, "", changes);
+  const annotated = changes.map((change) => annotateWebSocketChange(annotateGraphQLChange(annotateRestChange(change))));
+  return { changes: annotated };
+}

package/src/index.ts

@@ -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/src/loader/index.ts

@@ -0,0 +1,25 @@
+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 async function loadUniSpec(input: string | object, _options: LoadOptions = {}): Promise<UniSpecDocument> {
+  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) as UniSpecDocument;
+  }
+  return input as UniSpecDocument;
+}

package/src/normalizer/index.ts

@@ -0,0 +1,156 @@
+import { UniSpecDocument, UniSpecWebSocketProtocol, UniSpecWebSocketChannel, UniSpecWebSocketMessage } from "../types";
+
+export interface NormalizeOptions {
+  // Placeholder for future normalization options
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+
+function normalizeValue(value: unknown): unknown {
+  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: Record<string, unknown> = {};
+    for (const [key, val] of entries) {
+      normalized[key] = normalizeValue(val);
+    }
+    return normalized;
+  }
+
+  return value;
+}
+
+function normalizeRestPaths(doc: UniSpecDocument): UniSpecDocument {
+  if (!doc || !doc.service || !doc.service.protocols) {
+    return doc;
+  }
+
+  const protocols: any = doc.service.protocols;
+  const rest: any = protocols.rest;
+
+  if (!rest || !rest.paths || typeof rest.paths !== "object") {
+    return doc;
+  }
+
+  const httpMethodOrder = ["get", "head", "options", "post", "put", "patch", "delete"];
+
+  const normalizedPaths: Record<string, unknown> = {};
+
+  for (const path of Object.keys(rest.paths).sort()) {
+    const pathItem = (rest.paths as any)[path];
+
+    if (!pathItem || typeof pathItem !== "object") {
+      normalizedPaths[path] = pathItem;
+      continue;
+    }
+
+    const pathItemObj: Record<string, unknown> = pathItem as Record<string, unknown>;
+
+    const ordered: Record<string, unknown> = {};
+
+    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: UniSpecDocument): UniSpecDocument {
+  if (!doc || !doc.service || !doc.service.protocols) {
+    return doc;
+  }
+
+  const protocols: any = doc.service.protocols;
+  const websocket: UniSpecWebSocketProtocol | undefined = protocols.websocket;
+
+  if (!websocket || !websocket.channels || typeof websocket.channels !== "object") {
+    return doc;
+  }
+
+  const originalChannels = websocket.channels as Record<string, UniSpecWebSocketChannel>;
+  const sortedChannels: Record<string, UniSpecWebSocketChannel> = {};
+
+  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: UniSpecWebSocketMessage, b: UniSpecWebSocketMessage) => {
+        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: UniSpecDocument): UniSpecDocument {
+  if (!doc || !doc.service || !doc.service.protocols) {
+    return doc;
+  }
+
+  const protocols: any = doc.service.protocols;
+  const graphql: any = protocols.graphql;
+
+  if (!graphql || !graphql.operations) {
+    return doc;
+  }
+
+  const kinds = ["queries", "mutations", "subscriptions"] as const;
+
+  for (const kind of kinds) {
+    const bucket = graphql.operations[kind];
+    if (!bucket || typeof bucket !== "object") {
+      continue;
+    }
+
+    const sorted: Record<string, unknown> = {};
+    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: UniSpecDocument, _options: NormalizeOptions = {}): UniSpecDocument {
+  const normalized = normalizeValue(doc) as UniSpecDocument;
+  return normalizeWebSocket(normalizeGraphqlOperations(normalizeRestPaths(normalized)));
+}

package/src/types/index.ts

@@ -0,0 +1,67 @@
+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/src/validator/index.ts

@@ -0,0 +1,61 @@
+import Ajv2020, { ErrorObject } from "ajv/dist/2020.js";
+import { createRequire } from "module";
+import { unispec as unispecSchema, manifest as unispecManifest } from "@unispechq/unispec-schema";
+import { UniSpecDocument, ValidationResult } from "../types";
+
+export interface ValidateOptions {
+  // Placeholder for future validation options (e.g., strict mode, schema version)
+}
+
+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 as any)?.types ?? {};
+  const typeSchemaPaths: string[] = Object.values(types).map((rel: unknown) => String(rel));
+
+  const loadedTypeSchemas = typeSchemaPaths.map((relPath) => require(schemaDir + relPath));
+
+  ajv.addSchema(loadedTypeSchemas as object | object[]);
+} 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 as object);
+
+function mapAjvErrors(errors: ErrorObject[] | null | undefined): ValidationResult["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: UniSpecDocument, _options: ValidateOptions = {}): Promise<ValidationResult> {
+  const valid = validateFn(doc);
+
+  if (valid) {
+    return {
+      valid: true,
+      errors: [],
+    };
+  }
+
+  return {
+    valid: false,
+    errors: mapAjvErrors(validateFn.errors),
+  };
+}

package/tests/converters.test.mjs

@@ -0,0 +1,126 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import * as core from "../dist/index.js";
+
+const { toOpenAPI, toGraphQLSDL, toWebSocketModel } = core;
+
+test("toOpenAPI produces basic OpenAPI structure from UniSpec document", () => {
+  const doc = {
+    unispecVersion: "0.1.0",
+    service: {
+      name: "test-service",
+      title: "Service",
+      description: "Desc",
+      protocols: {
+        rest: {
+          servers: [{ url: "https://api.example.com" }],
+          paths: {
+            "/ping": {
+              get: {},
+            },
+          },
+          components: {
+            schemas: {
+              PingResponse: {
+                type: "object",
+              },
+            },
+          },
+          security: [{ bearerAuth: [] }],
+          tags: [
+            {
+              name: "ping",
+              description: "Ping operations",
+            },
+          ],
+          "x-extra-rest-field": true,
+        },
+      },
+    },
+  };
+
+  const openapi = toOpenAPI(doc);
+
+  assert.equal(openapi.openapi, "3.1.0");
+  assert.equal(openapi.info.title, "Service");
+  assert.equal(openapi.info.description, "Desc");
+  assert.ok(openapi.paths["/ping"]);
+  assert.ok(openapi.components);
+  assert.ok(openapi.components.schemas.PingResponse);
+  assert.ok(Array.isArray(openapi.security));
+  assert.ok(Array.isArray(openapi.tags));
+  assert.equal(openapi["x-extra-rest-field"], true);
+});
+
+test("toGraphQLSDL returns SDL string wrapper", () => {
+  const doc = {
+    unispecVersion: "0.1.0",
+    service: {
+      name: "test-service",
+      title: "GraphQL Service",
+      description: "GraphQL description",
+      protocols: {
+        graphql: {
+          schema: {
+            sdl: "type Query { hello: String! }",
+          },
+        },
+      },
+    },
+  };
+
+  const result = toGraphQLSDL(doc);
+
+  assert.equal(typeof result, "object");
+  assert.equal(typeof result.sdl, "string");
+  assert.equal(result.sdl, "type Query { hello: String! }");
+});
+
+test("toWebSocketModel returns WS model wrapper", () => {
+  const doc = {
+    unispecVersion: "0.1.0",
+    service: {
+      name: "test-service",
+      title: "WS Service",
+      description: "WebSocket description",
+      protocols: {
+        websocket: {
+          channels: {
+            ping: {
+              summary: "Ping channel",
+              description: "Ping messages",
+              direction: "bidirectional",
+              messages: [
+                {
+                  name: "ping",
+                  summary: "Ping message",
+                },
+              ],
+            },
+          },
+        },
+      },
+    },
+  };
+
+  const model = toWebSocketModel(doc);
+
+  assert.equal(typeof model, "object");
+  assert.ok(model["x-unispec-ws"]);
+  assert.deepEqual(model.service, {
+    name: "test-service",
+    title: "WS Service",
+    description: "WebSocket description",
+  });
+  assert.ok(Array.isArray(model.channels));
+  assert.equal(model.channels.length, 1);
+  assert.equal(model.channels[0].name, "ping");
+  assert.equal(model.channels[0].summary, "Ping channel");
+  assert.equal(model.channels[0].description, "Ping messages");
+  assert.equal(model.channels[0].direction, "bidirectional");
+  assert.ok(Array.isArray(model.channels[0].messages));
+  assert.equal(model.channels[0].messages[0].name, "ping");
+  assert.equal(model.channels[0].messages[0].summary, "Ping message");
+  assert.ok(model.rawProtocol);
+});