@unispechq/unispec-core 0.1.1 → 0.1.2

package/src/normalizer/index.ts

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

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

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

@@ -1,126 +0,0 @@
-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);
-});

package/tests/diff.test.mjs

@@ -1,240 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import * as core from "../dist/index.js";
-
-const { diffUniSpec } = core;
-
-test("diffUniSpec detects added and removed fields", () => {
-  const oldDoc = { info: { title: "Old" } };
-  const newDoc = { info: { title: "New", description: "Desc" } };
-
-  const result = diffUniSpec(oldDoc, newDoc);
-
-  const paths = result.changes.map((c) => c.path).sort();
-
-  assert.ok(paths.includes("/info/title"));
-  assert.ok(paths.includes("/info/description"));
-});
-
-test("diffUniSpec marks REST path and operation changes with severity and kind", () => {
-  const oldDoc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        rest: {
-          paths: {
-            "/ping": {
-              get: {},
-            },
-            "/status": {
-              get: {},
-            },
-          },
-        },
-      },
-    },
-  };
-
-  const newDoc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        rest: {
-          paths: {
-            "/ping": {
-              get: {},
-              post: {},
-            },
-          },
-        },
-      },
-    },
-  };
-
-  const result = diffUniSpec(oldDoc, newDoc);
-
-  const restChanges = result.changes.filter((c) => c.protocol === "rest");
-
-  const pathRemoved = restChanges.find((c) => c.kind === "rest.path.removed");
-  const opAdded = restChanges.find((c) => c.kind === "rest.operation.added");
-
-  assert.ok(pathRemoved);
-  assert.equal(pathRemoved.severity, "breaking");
-
-  assert.ok(opAdded);
-  assert.equal(opAdded.severity, "non-breaking");
-});
-
-test("diffUniSpec marks WebSocket channel changes with severity and kind", () => {
-  const oldDoc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        websocket: {
-          channels: {
-            chat: {},
-            metrics: {},
-          },
-        },
-      },
-    },
-  };
-
-  const newDoc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        websocket: {
-          channels: {
-            chat: {},
-            notifications: {},
-          },
-        },
-      },
-    },
-  };
-
-  const result = diffUniSpec(oldDoc, newDoc);
-
-  const wsChanges = result.changes.filter((c) => c.protocol === "websocket");
-
-  const channelRemoved = wsChanges.find((c) => c.kind === "websocket.channel.removed");
-  const channelAdded = wsChanges.find((c) => c.kind === "websocket.channel.added");
-
-  assert.ok(channelRemoved);
-  assert.equal(channelRemoved.severity, "breaking");
-
-  assert.ok(channelAdded);
-  assert.equal(channelAdded.severity, "non-breaking");
-});
-
-test("diffUniSpec marks WebSocket message changes with severity and kind", () => {
-  const oldDoc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        websocket: {
-          channels: {
-            chat: {
-              messages: [
-                { name: "messageA" },
-                { name: "messageB" },
-              ],
-            },
-          },
-        },
-      },
-    },
-  };
-
-  const newDoc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        websocket: {
-          channels: {
-            chat: {
-              messages: [
-                { name: "messageA" },
-                { name: "messageB" },
-                { name: "messageC" },
-              ],
-            },
-          },
-        },
-      },
-    },
-  };
-
-  const result = diffUniSpec(oldDoc, newDoc);
-
-  const wsChangesAdd = result.changes.filter((c) => c.protocol === "websocket" && c.kind === "websocket.message.added");
-
-  assert.ok(wsChangesAdd.length > 0);
-  wsChangesAdd.forEach((change) => {
-    assert.equal(change.severity, "non-breaking");
-  });
-
-  const newDoc2 = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        websocket: {
-          channels: {
-            chat: {
-              messages: [
-                { name: "messageA" },
-              ],
-            },
-          },
-        },
-      },
-    },
-  };
-
-  const result2 = diffUniSpec(oldDoc, newDoc2);
-
-  const wsChangesRemove = result2.changes.filter((c) => c.protocol === "websocket" && c.kind === "websocket.message.removed");
-
-  assert.ok(wsChangesRemove.length > 0);
-  wsChangesRemove.forEach((change) => {
-    assert.equal(change.severity, "breaking");
-  });
-});
-
-test("diffUniSpec marks GraphQL operation changes with severity and kind", () => {
-  const oldDoc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        graphql: {
-          operations: {
-            queries: {
-              me: {},
-              ping: {},
-            },
-          },
-        },
-      },
-    },
-  };
-
-  const newDoc = {
-    unispecVersion: "0.1.0",
-    service: {
-      name: "test-service",
-      protocols: {
-        graphql: {
-          operations: {
-            queries: {
-              ping: {},
-              status: {},
-            },
-          },
-        },
-      },
-    },
-  };
-
-  const result = diffUniSpec(oldDoc, newDoc);
-
-  const graphqlChanges = result.changes.filter((c) => c.protocol === "graphql");
-
-  const opRemoved = graphqlChanges.find((c) => c.kind === "graphql.operation.removed");
-  const opAdded = graphqlChanges.find((c) => c.kind === "graphql.operation.added");
-
-  assert.ok(opRemoved);
-  assert.equal(opRemoved.severity, "breaking");
-
-  assert.ok(opAdded);
-  assert.equal(opAdded.severity, "non-breaking");
-});

package/tests/loader-validator.test.mjs

@@ -1,19 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import * as core from "../dist/index.js";
-
-const { loadUniSpec, validateUniSpec } = core;
-
-test("loadUniSpec loads JSON string into object", async () => {
-  const input = '{"info": {"title": "Test"}}';
-  const doc = await loadUniSpec(input);
-  assert.equal(typeof doc, "object");
-  assert.equal(doc.info.title, "Test");
-});
-
-test("validateUniSpec returns ValidationResult shape", async () => {
-  const result = await validateUniSpec({});
-  assert.equal(typeof result.valid, "boolean");
-  assert.ok(Array.isArray(result.errors));
-});