@unispechq/unispec-core 0.1.0 → 0.1.1

package/src/diff/index.ts

@@ -1,235 +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 };
-}
+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

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

@@ -1,25 +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;
-}
+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;
+}