@unispechq/unispec-core 0.2.10 → 0.2.12

package/dist/cjs/validator/index.js

@@ -1,37 +1,4 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -39,58 +6,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateUniSpec = validateUniSpec;
 exports.validateUniSpecTests = validateUniSpecTests;
 const _2020_js_1 = __importDefault(require("ajv/dist/2020.js"));
+const generated_schemas_js_1 = require("./generated-schemas.js");
 let cached = null;
-async function tryCreateNodeSchemaProvider() {
-    try {
-        const fs = await Promise.resolve().then(() => __importStar(require("node:fs/promises")));
-        const path = await Promise.resolve().then(() => __importStar(require("node:path")));
-        const module = await Promise.resolve().then(() => __importStar(require("node:module")));
-        const requireBasePath = typeof __filename === "string" && __filename.length > 0
-            ? __filename
-            : path.join(process.cwd(), "__unispec_core_require__.js");
-        const require = module.createRequire(requireBasePath);
-        const schemaIndexPath = require.resolve("@unispechq/unispec-schema/schema");
-        const schemaRoot = path.dirname(schemaIndexPath);
-        return {
-            getSchema: async (schemaPath) => {
-                const fullPath = path.join(schemaRoot, schemaPath);
-                const json = await fs.readFile(fullPath, "utf8");
-                return JSON.parse(json);
-            },
-        };
-    }
-    catch {
-        return undefined;
-    }
-}
 async function loadDefaultSchemas() {
-    const schemaProvider = await tryCreateNodeSchemaProvider();
-    if (!schemaProvider) {
-        throw new Error("UniSpec validator: default schema loading is not available in this environment. " +
-            "Provide ValidateOptions.schemas (recommended for browsers/edge runtimes) or ValidateOptions.schemaProvider.");
-    }
-    const { manifest, unispec } = (await Promise.resolve().then(() => __importStar(require("@unispechq/unispec-schema"))));
-    const types = manifest?.types ?? {};
-    const typeSchemaPaths = Object.values(types).map((rel) => String(rel));
-    const subschemas = await Promise.all(typeSchemaPaths.map(async (relPath) => {
-        try {
-            return await schemaProvider.getSchema(relPath);
-        }
-        catch {
-            return null;
-        }
-    }));
-    let unispecTests;
-    try {
-        unispecTests = await schemaProvider.getSchema("unispec-tests.schema.json");
-    }
-    catch {
-        unispecTests = undefined;
-    }
+    // Always use generated schemas - they work in all environments
     return {
-        unispec: unispec,
-        unispecTests,
-        subschemas: subschemas.filter((s) => Boolean(s)),
+        unispec: generated_schemas_js_1.GENERATED_SCHEMAS.unispec,
+        unispecTests: generated_schemas_js_1.GENERATED_SCHEMAS.unispecTests,
+        subschemas: generated_schemas_js_1.GENERATED_SCHEMAS.subschemas,
     };
 }
 function createAjv(options) {
@@ -138,15 +61,10 @@ function mapAjvErrors(errors) {
  */
 async function validateUniSpec(doc, options = {}) {
     const { validateUniSpecFn } = await getValidator(options);
+    // Ensure the document has required fields for validation
     const docForValidation = {
-        unispecVersion: "0.0.0",
-        service: {
-            name: doc.name,
-            description: doc.description,
-            version: doc.version,
-            protocols: doc.protocols,
-            schemas: doc.schemas,
-        },
+        unispecVersion: doc.unispecVersion || "1.0.0",
+        service: doc.service,
         extensions: doc.extensions,
     };
     const valid = validateUniSpecFn(docForValidation);

package/dist/converters/index.d.ts

@@ -4,6 +4,7 @@ export interface OpenAPIDocument {
 }
 export interface GraphQLSDLOutput {
     sdl: string;
+    url?: string;
 }
 export interface WebSocketModel {
     [key: string]: unknown;

package/dist/converters/index.js

@@ -1,14 +1,14 @@
 export function toOpenAPI(doc) {
-    const rest = (doc.protocols?.rest ?? {});
+    const rest = (doc.service?.protocols?.rest ?? {});
     const info = {
-        title: doc.name,
-        description: doc.description,
+        title: doc.service.name,
+        description: doc.service.description,
     };
     const servers = [];
     const paths = {};
     const components = {};
-    // Map doc.schemas into OpenAPI components.schemas
-    const schemas = (doc.schemas ?? {});
+    // Map doc.service.schemas into OpenAPI components.schemas
+    const schemas = (doc.service?.schemas ?? {});
     const componentsSchemas = {};
     for (const [name, def] of Object.entries(schemas)) {
         componentsSchemas[name] = def.jsonSchema;
@@ -133,13 +133,16 @@ export function toGraphQLSDL(doc) {
     // 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.protocols?.graphql;
+    const graphql = doc.service?.protocols?.graphql;
     const customSDL = graphql?.schema;
     if (typeof customSDL === "string" && customSDL.trim()) {
-        return { sdl: customSDL };
+        return {
+            sdl: customSDL,
+            url: graphql?.url
+        };
     }
-    const title = doc.name;
-    const description = doc.description ?? "";
+    const title = doc.service.name;
+    const description = doc.service.description ?? "";
     const lines = [];
     if (title || description) {
         lines.push("\"\"");
@@ -160,14 +163,17 @@ export function toGraphQLSDL(doc) {
     lines.push("  _serviceInfo: String!\n");
     lines.push("}");
     const sdl = lines.join("\n");
-    return { sdl };
+    return {
+        sdl,
+        url: graphql?.url
+    };
 }
 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 websocket = (doc.protocols?.websocket ?? {});
+    const websocket = (doc.service?.protocols?.websocket ?? {});
     const channelsArray = Array.isArray(websocket.channels) ? websocket.channels : [];
     const channels = [...channelsArray]
         .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""))
@@ -181,10 +187,11 @@ export function toWebSocketModel(doc) {
     }));
     return {
         service: {
-            name: doc.name,
+            name: doc.service.name,
             title: undefined,
-            description: doc.description,
+            description: doc.service.description,
         },
+        url: websocket.url,
         channels,
         rawProtocol: websocket,
         "x-unispec-ws": doc,

package/dist/diff/index.d.ts

@@ -11,11 +11,24 @@ export interface DiffResult {
     changes: UniSpecChange[];
 }
 /**
- * Compute a structural diff between two UniSpec documents.
+ * Compare two UniSpec documents and return detected changes.
  *
- * 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.
+ * This function performs a deep comparison between two UniSpec documents
+ * and categorizes changes by severity and protocol. Useful for:
+ * - API change detection in CI/CD pipelines
+ * - Breaking change analysis
+ * - Version compatibility checks
+ * - Audit trails for API evolution
+ *
+ * Features:
+ * - Detects added/removed fields at any depth
+ * - Special handling for named collections (routes, operations, channels)
+ * - Severity classification: "breaking" | "non-breaking" | "unknown"
+ * - Protocol categorization: "rest" | "graphql" | "websocket"
+ * - Detailed change descriptions with JSON paths
+ *
+ * @param oldDoc - The previous version of the UniSpec document
+ * @param newDoc - The current version of the UniSpec document
+ * @returns Object containing all detected changes
  */
 export declare function diffUniSpec(oldDoc: UniSpecDocument, newDoc: UniSpecDocument): DiffResult;

package/dist/diff/index.js

@@ -218,12 +218,25 @@ function annotateGraphQLChange(change) {
     return annotated;
 }
 /**
- * Compute a structural diff between two UniSpec documents.
+ * Compare two UniSpec documents and return detected changes.
  *
- * 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.
+ * This function performs a deep comparison between two UniSpec documents
+ * and categorizes changes by severity and protocol. Useful for:
+ * - API change detection in CI/CD pipelines
+ * - Breaking change analysis
+ * - Version compatibility checks
+ * - Audit trails for API evolution
+ *
+ * Features:
+ * - Detects added/removed fields at any depth
+ * - Special handling for named collections (routes, operations, channels)
+ * - Severity classification: "breaking" | "non-breaking" | "unknown"
+ * - Protocol categorization: "rest" | "graphql" | "websocket"
+ * - Detailed change descriptions with JSON paths
+ *
+ * @param oldDoc - The previous version of the UniSpec document
+ * @param newDoc - The current version of the UniSpec document
+ * @returns Object containing all detected changes
  */
 export function diffUniSpec(oldDoc, newDoc) {
     const changes = [];

package/dist/loader/index.d.ts

@@ -4,10 +4,9 @@ export interface LoadOptions {
 }
 /**
  * Load a UniSpec document from a raw input value.
- * Currently supports:
+ * Supports:
  * - JavaScript objects (treated as already parsed UniSpec)
  * - JSON strings
- *
- * YAML and filesystem helpers will be added later, keeping this API stable.
+ * - YAML strings
  */
-export declare function loadUniSpec(input: string | object, _options?: LoadOptions): Promise<UniSpecDocument>;
+export declare function loadUniSpec(input: string | object, options?: LoadOptions): Promise<UniSpecDocument>;

package/dist/loader/index.js

@@ -1,19 +1,41 @@
 /**
  * Load a UniSpec document from a raw input value.
- * Currently supports:
+ * Supports:
  * - JavaScript objects (treated as already parsed UniSpec)
  * - JSON strings
- *
- * YAML and filesystem helpers will be added later, keeping this API stable.
+ * - YAML strings
  */
-export async function loadUniSpec(input, _options = {}) {
+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);
+        // Try JSON first (faster and more common)
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch (jsonError) {
+            // If JSON fails, try YAML
+            try {
+                // Dynamic import to avoid bundling yaml parser if not needed
+                const yamlModule = await import("js-yaml");
+                if (!yamlModule.load) {
+                    throw new Error("js-yaml module not available");
+                }
+                const doc = yamlModule.load(trimmed, {
+                    filename: options.filename,
+                    // Basic security options
+                    schema: yamlModule.FAILSAFE_SCHEMA
+                });
+                return doc;
+            }
+            catch (yamlError) {
+                const jsonMsg = jsonError instanceof Error ? jsonError.message : String(jsonError);
+                const yamlMsg = yamlError instanceof Error ? yamlError.message : String(yamlError);
+                throw new Error(`Failed to parse input as JSON or YAML. JSON error: ${jsonMsg}. YAML error: ${yamlMsg}`);
+            }
+        }
     }
     return input;
 }

package/dist/normalizer/index.d.ts

@@ -4,8 +4,22 @@ export interface NormalizeOptions {
 /**
  * Normalize a UniSpec document into a canonical, deterministic form.
  *
+ * This function ensures consistent representation of UniSpec documents
+ * by sorting object keys and protocol-specific structures in a predictable order.
+ * Useful for:
+ * - Generating stable diffs between documents
+ * - Creating consistent output for caching
+ * - Ensuring reproducible builds
+ *
  * Current behavior:
- * - Recursively sorts object keys lexicographically.
- * - Preserves values as-is.
+ * - Recursively sorts object keys lexicographically
+ * - Sorts REST routes by name or path+method
+ * - Sorts GraphQL operations by name within each operation type
+ * - Sorts WebSocket channels and messages by name
+ * - Preserves all values as-is
+ *
+ * @param doc - The UniSpec document to normalize
+ * @param options - Normalization options (currently unused, reserved for future)
+ * @returns The normalized UniSpec document
  */
 export declare function normalizeUniSpec(doc: UniSpecDocument, _options?: NormalizeOptions): UniSpecDocument;

package/dist/normalizer/index.js

@@ -16,10 +16,10 @@ function normalizeValue(value) {
     return value;
 }
 function normalizeRestRoutes(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const rest = protocols.rest;
     if (!rest || !Array.isArray(rest.routes)) {
         return doc;
@@ -34,10 +34,10 @@ function normalizeRestRoutes(doc) {
     return doc;
 }
 function normalizeWebSocket(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const websocket = protocols.websocket;
     if (!websocket || !Array.isArray(websocket.channels)) {
         return doc;
@@ -65,10 +65,10 @@ function normalizeWebSocket(doc) {
     return doc;
 }
 function normalizeGraphqlOperations(doc) {
-    if (!doc || !doc.protocols) {
+    if (!doc || !doc.service?.protocols) {
         return doc;
     }
-    const protocols = doc.protocols;
+    const protocols = doc.service.protocols;
     const graphql = protocols.graphql;
     if (!graphql) {
         return doc;
@@ -94,9 +94,23 @@ function normalizeGraphqlOperations(doc) {
 /**
  * Normalize a UniSpec document into a canonical, deterministic form.
  *
+ * This function ensures consistent representation of UniSpec documents
+ * by sorting object keys and protocol-specific structures in a predictable order.
+ * Useful for:
+ * - Generating stable diffs between documents
+ * - Creating consistent output for caching
+ * - Ensuring reproducible builds
+ *
  * Current behavior:
- * - Recursively sorts object keys lexicographically.
- * - Preserves values as-is.
+ * - Recursively sorts object keys lexicographically
+ * - Sorts REST routes by name or path+method
+ * - Sorts GraphQL operations by name within each operation type
+ * - Sorts WebSocket channels and messages by name
+ * - Preserves all values as-is
+ *
+ * @param doc - The UniSpec document to normalize
+ * @param options - Normalization options (currently unused, reserved for future)
+ * @returns The normalized UniSpec document
  */
 export function normalizeUniSpec(doc, _options = {}) {
     const normalized = normalizeValue(doc);

package/dist/schemas/index.js

@@ -27,21 +27,24 @@ export function resolveSchemaRef(doc, ref) {
     const name = normalizeSchemaRef(ref);
     if (!name)
         return undefined;
-    return doc.schemas?.[name];
+    return doc.service?.schemas?.[name];
 }
 export function registerSchema(doc, name, jsonSchema) {
-    if (!doc.schemas) {
-        doc.schemas = {};
+    if (!doc.service) {
+        doc.service = { name: "" };
+    }
+    if (!doc.service.schemas) {
+        doc.service.schemas = {};
     }
     const definition = {
         jsonSchema,
     };
-    doc.schemas[name] = definition;
+    doc.service.schemas[name] = definition;
     return definition;
 }
 function updateSchemaRefs(doc, mapping) {
-    const rest = doc.protocols?.rest;
-    const websocket = doc.protocols?.websocket;
+    const rest = doc.service?.protocols?.rest;
+    const websocket = doc.service?.protocols?.websocket;
     if (rest?.routes) {
         for (const route of rest.routes) {
             for (const params of [route.pathParams, route.queryParams, route.headers]) {
@@ -101,13 +104,13 @@ function updateSchemaRefs(doc, mapping) {
     }
 }
 export function dedupeSchemas(doc) {
-    if (!doc.schemas)
+    if (!doc.service?.schemas)
         return;
-    const names = Object.keys(doc.schemas);
+    const names = Object.keys(doc.service.schemas);
     const hashToName = new Map();
     const renameMap = {};
     for (const name of names) {
-        const schema = doc.schemas[name];
+        const schema = doc.service.schemas[name];
         const hash = stableStringify(schema?.jsonSchema ?? null);
         const existing = hashToName.get(hash);
         if (!existing) {
@@ -121,6 +124,6 @@ export function dedupeSchemas(doc) {
         return;
     updateSchemaRefs(doc, renameMap);
     for (const dup of duplicates) {
-        delete doc.schemas[dup];
+        delete doc.service.schemas[dup];
     }
 }

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export interface UniSpecGraphQLOperation {
     deprecationReason?: string;
 }
 export interface UniSpecGraphQLProtocol {
+    url?: string;
     schema?: string;
     queries?: UniSpecGraphQLOperation[];
     mutations?: UniSpecGraphQLOperation[];
@@ -26,6 +27,7 @@ export interface UniSpecWebSocketChannel {
     extensions?: Record<string, unknown>;
 }
 export interface UniSpecWebSocketProtocol {
+    url?: string;
     channels?: UniSpecWebSocketChannel[];
     securitySchemes?: Record<string, Record<string, unknown>>;
 }
@@ -86,12 +88,16 @@ export interface UniSpecServiceProtocols {
     websocket?: UniSpecWebSocketProtocol;
 }
 export interface UniSpecDocument {
+    unispecVersion: string;
+    service: UniSpecService;
+    extensions?: Record<string, unknown>;
+}
+export interface UniSpecService {
     name: string;
     description?: string;
     version?: string;
     protocols?: UniSpecServiceProtocols;
     schemas?: UniSpecSchemas;
-    extensions?: Record<string, unknown>;
 }
 export interface ValidationError {
     message: string;