@unispechq/unispec-core 0.2.0 → 0.2.2

package/README.md

@@ -1,223 +1,223 @@
-# UniSpec Core Platform
-**The official UniSpec Core Engine package — parser, validator, normalizer, diff engine, and converters for the UniSpec format**
-
----
-
-## 🚀 Overview
-
-**UniSpec Core Engine** is the central runtime package of the UniSpec ecosystem.  
-It implements the mechanics of the **UniSpec Format**: loading, JSON Schema validation, normalization, diffing, and conversion to other formats.
-
-This repository contains **only the Core Engine**, which is consumed by other UniSpec platform components (CLI, Registry, Portal, adapters, SDKs) that live in separate repositories.
-
-Core Engine capabilities:
-
-- 🧠 **Core Engine** — parser, validator, normalizer, diff engine, converters  
-- 🔄 **Format conversion** — UniSpec → OpenAPI, UniSpec → GraphQL SDL, UniSpec → WebSocket channel models  
-- 🧩 **Shared types and utilities** — types and helper functions used by the CLI, adapters, Registry, and Portal  
-
-UniSpec is designed to unify documentation for:
-
-- REST  
-- GraphQL  
-- WebSocket  
-- Event-driven APIs (future)  
-- Multi-service architectures  
-
----
-
-## 📦 Repository Structure
-
-```pgsql
-unispec-core/
-├─ src/
-│  ├─ loader/           # File loading (YAML/JSON → JS object)
-│  ├─ validator/        # JSON Schema validation
-│  ├─ normalizer/       # UniSpec structure normalization
-│  ├─ diff/             # Comparison of two UniSpec documents
-│  ├─ converters/       # OpenAPI, GraphQL SDL, WS, etc.
-│  ├─ types/            # UniSpec types/interfaces
-│  ├─ utils/            # Small helpers
-│  └─ index.ts          # Public API
-├─ tests/               # Unit tests
-├─ package.json
-└─ README.md
-```
-
----
-
-## 🧠 Core Concepts
-
-### 📐 1. UniSpec Format  
-Defined in a separate repository: **`unispec-spec`**.  
-UniSpec Core Engine *implements* this format but does **not** define it.
-
-### 🧱 2. Core Engine  
-Located in this repository, under the `src/` directory.
-
-Core Engine provides:
-
-- YAML/JSON loader  
-- JSON Schema validator  
-– Normalizer → canonical UniSpec output (REST routes, GraphQL operations, WebSocket channels/messages)  
-– Diff engine (with basic breaking / non-breaking classification for REST, GraphQL and WebSocket)  
-– Converters:  
-  - UniSpec → OpenAPI (REST-centric)  
-  - UniSpec → GraphQL SDL  
-  - UniSpec → WebSocket channel models for dashboards  
-
-This is the foundation used by:
-
-- the CLI (in a separate repository/package)  
-- framework adapters  
-- Registry and Portal (as separate UniSpec platform services)  
-
-### 🌉 3. Protocol Coverage in Core
-
-At the level of the Core Engine, protocol support is intentionally minimal but deterministic:
-
-- **REST**  
-  - Typed REST surface defined by `service.protocols.rest.routes[]` and reusable `service.schemas`.  
-  - Normalizer orders routes by `name` (or `path + method`) for stable diffs.  
-  - Diff engine annotates route additions and removals with breaking/non-breaking severity.  
-  - Converter exposes REST as an OpenAPI 3.1 document built from routes, schemas and environments, while preserving the original UniSpec under `x-unispec`.
-
-- **GraphQL**  
-  - Typed protocol with `schema` (SDL string) and `queries`/`mutations`/`subscriptions` as operation lists.  
-  - Normalizer orders operation names within each bucket.  
-  - Diff engine annotates operation additions/removals as non-breaking/breaking.  
-  - Converter either passes through user-provided SDL or generates a minimal, deterministic SDL shell.
-
-- **WebSocket**  
-  - Typed protocol with channels and messages backed by reusable schemas and security schemes.  
-  - Normalizer orders channels by name and messages by `name` within each channel.  
-  - Diff engine annotates channel/message additions/removals as non-breaking/breaking changes.  
-  - Converter produces a dashboard-friendly model with service metadata, a normalized channel list and the raw protocol.
-
-### 💻 4. CLI (separate platform component)  
-The CLI uses UniSpec Core Engine for validation, conversion, and working with UniSpec specifications.
-
-Example UniSpec CLI commands:
-
-```pgsql
-unispec validate
-unispec push
-unispec dev
-unispec open
-unispec diff
-unispec convert
-```
-
-
-### 🗂 5. Registry API (separate service)  
-Stores UniSpec specs from multiple services and uses Core Engine for validation, normalization, and change analysis.  
-Effectively acts as the "system of record" for all APIs in the company.
-
-### 🌐 6. Portal Web + API (separate service)  
-API documentation portal built on top of UniSpec and Core Engine:
-
-- service catalog  
-- API endpoints  
-- schemas  
-- interactive playgrounds  
-- version comparison  
-
----
-
-## 🛒 Use Cases
-
-### 🟦 Monolith mode (Swagger-like)  
-A backend service includes an adapter →  
-`/unispec.json` + `/docs` are served automatically.
-
-### 🟧 Microservice mode  
-Each service pushes its UniSpec into Registry →  
-Portal Web assembles your entire company's API landscape.
-
-### 🟩 Enterprise mode  
-Includes:
-
-- SSO / permissions  
-- RBAC  
-- auditing  
-- topology map  
-- advanced analytics  
-
-(Handled via private repos.)
-
----
-
-## 🏁 Getting Started
-
-### 1. Clone the repo
-
-```pgsql
-git clone https://github.com/unispec/unispec-core.git
-cd unispec-core
-```
-
-### 2. Install dependencies
-
-```pgsql
-pnpm install
-```
-
-### 3. Build all packages
-
-```pgsql
-pnpm build
-```
-
-### 4. Run locally (dev mode)
-
----
-
-## 🤝 Contributing
-
-Contributions are welcome!  
-Before contributing, please review:
-
-- `docs/development.md`
-- `.windsurfrules`
-
-All core changes must comply with:
-
-- the UniSpec format from `unispec-spec`
-- compatibility rules  
-- test coverage  
-- platform architecture
-
----
-
-## Related Repositories
-
-| Repository             | Purpose |
-|------------------------|---------|
-| `unispec-spec`         | UniSpec format definition (schemas, examples) |
-| `unispec-core`         | **This repo** — UniSpec Core Engine implementation |
-| `unispec-docs`         | Documentation site |
-| `unispec-js-adapters`  | Framework integrations (Express/Nest/Fastify) built on top of Core Engine |
-| `unispec-infra`        | Helm charts, Docker, Terraform for deploying the UniSpec platform |
-
----
-
-## License
-
-UniSpec Core Engine is open-source and free to use under the MIT License.
-
----
-
-## 🔥 Summary
-
-`unispec-core` is the **heart of the UniSpec ecosystem** at the code level.  
-It provides the Core Engine used to:
-
-- validate  
-- normalize  
-- diff  
-- convert  
-- and integrate  
-
-API specifications in the UniSpec format.
-
-If you're building tools, adapters, or platform services that rely on UniSpec → **this is where the engine lives.**
+# UniSpec Core Platform
+**The official UniSpec Core Engine package — parser, validator, normalizer, diff engine, and converters for the UniSpec format**
+
+---
+
+## 🚀 Overview
+
+**UniSpec Core Engine** is the central runtime package of the UniSpec ecosystem.  
+It implements the mechanics of the **UniSpec Format**: loading, JSON Schema validation, normalization, diffing, and conversion to other formats.
+
+This repository contains **only the Core Engine**, which is consumed by other UniSpec platform components (CLI, Registry, Portal, adapters, SDKs) that live in separate repositories.
+
+Core Engine capabilities:
+
+- 🧠 **Core Engine** — parser, validator, normalizer, diff engine, converters  
+- 🔄 **Format conversion** — UniSpec → OpenAPI, UniSpec → GraphQL SDL, UniSpec → WebSocket channel models  
+- 🧩 **Shared types and utilities** — types and helper functions used by the CLI, adapters, Registry, and Portal  
+
+UniSpec is designed to unify documentation for:
+
+- REST  
+- GraphQL  
+- WebSocket  
+- Event-driven APIs (future)  
+- Multi-service architectures  
+
+---
+
+## 📦 Repository Structure
+
+```pgsql
+unispec-core/
+├─ src/
+│  ├─ loader/           # File loading (YAML/JSON → JS object)
+│  ├─ validator/        # JSON Schema validation
+│  ├─ normalizer/       # UniSpec structure normalization
+│  ├─ diff/             # Comparison of two UniSpec documents
+│  ├─ converters/       # OpenAPI, GraphQL SDL, WS, etc.
+│  ├─ types/            # UniSpec types/interfaces
+│  ├─ utils/            # Small helpers
+│  └─ index.ts          # Public API
+├─ tests/               # Unit tests
+├─ package.json
+└─ README.md
+```
+
+---
+
+## 🧠 Core Concepts
+
+### 📐 1. UniSpec Format  
+Defined in a separate repository: **`unispec-spec`**.  
+UniSpec Core Engine *implements* this format but does **not** define it.
+
+### 🧱 2. Core Engine  
+Located in this repository, under the `src/` directory.
+
+Core Engine provides:
+
+- YAML/JSON loader  
+- JSON Schema validator  
+– Normalizer → canonical UniSpec output (REST routes, GraphQL operations, WebSocket channels/messages)  
+– Diff engine (with basic breaking / non-breaking classification for REST, GraphQL and WebSocket)  
+– Converters:  
+  - UniSpec → OpenAPI (REST-centric)  
+  - UniSpec → GraphQL SDL  
+  - UniSpec → WebSocket channel models for dashboards  
+
+This is the foundation used by:
+
+- the CLI (in a separate repository/package)  
+- framework adapters  
+- Registry and Portal (as separate UniSpec platform services)  
+
+### 🌉 3. Protocol Coverage in Core
+
+At the level of the Core Engine, protocol support is intentionally minimal but deterministic:
+
+- **REST**  
+  - Typed REST surface defined by `service.protocols.rest.routes[]` and reusable `service.schemas`.  
+  - Normalizer orders routes by `name` (or `path + method`) for stable diffs.  
+  - Diff engine annotates route additions and removals with breaking/non-breaking severity.  
+  - Converter exposes REST as an OpenAPI 3.1 document built from routes, schemas and environments, while preserving the original UniSpec under `x-unispec`.
+
+- **GraphQL**  
+  - Typed protocol with `schema` (SDL string) and `queries`/`mutations`/`subscriptions` as operation lists.  
+  - Normalizer orders operation names within each bucket.  
+  - Diff engine annotates operation additions/removals as non-breaking/breaking.  
+  - Converter either passes through user-provided SDL or generates a minimal, deterministic SDL shell.
+
+- **WebSocket**  
+  - Typed protocol with channels and messages backed by reusable schemas and security schemes.  
+  - Normalizer orders channels by name and messages by `name` within each channel.  
+  - Diff engine annotates channel/message additions/removals as non-breaking/breaking changes.  
+  - Converter produces a dashboard-friendly model with service metadata, a normalized channel list and the raw protocol.
+
+### 💻 4. CLI (separate platform component)  
+The CLI uses UniSpec Core Engine for validation, conversion, and working with UniSpec specifications.
+
+Example UniSpec CLI commands:
+
+```pgsql
+unispec validate
+unispec push
+unispec dev
+unispec open
+unispec diff
+unispec convert
+```
+
+
+### 🗂 5. Registry API (separate service)  
+Stores UniSpec specs from multiple services and uses Core Engine for validation, normalization, and change analysis.  
+Effectively acts as the "system of record" for all APIs in the company.
+
+### 🌐 6. Portal Web + API (separate service)  
+API documentation portal built on top of UniSpec and Core Engine:
+
+- service catalog  
+- API endpoints  
+- schemas  
+- interactive playgrounds  
+- version comparison  
+
+---
+
+## 🛒 Use Cases
+
+### 🟦 Monolith mode (Swagger-like)  
+A backend service includes an adapter →  
+`/unispec.json` + `/docs` are served automatically.
+
+### 🟧 Microservice mode  
+Each service pushes its UniSpec into Registry →  
+Portal Web assembles your entire company's API landscape.
+
+### 🟩 Enterprise mode  
+Includes:
+
+- SSO / permissions  
+- RBAC  
+- auditing  
+- topology map  
+- advanced analytics  
+
+(Handled via private repos.)
+
+---
+
+## 🏁 Getting Started
+
+### 1. Clone the repo
+
+```pgsql
+git clone https://github.com/unispec/unispec-core.git
+cd unispec-core
+```
+
+### 2. Install dependencies
+
+```pgsql
+pnpm install
+```
+
+### 3. Build all packages
+
+```pgsql
+pnpm build
+```
+
+### 4. Run locally (dev mode)
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome!  
+Before contributing, please review:
+
+- `docs/development.md`
+- `.windsurfrules`
+
+All core changes must comply with:
+
+- the UniSpec format from `unispec-spec`
+- compatibility rules  
+- test coverage  
+- platform architecture
+
+---
+
+## Related Repositories
+
+| Repository             | Purpose |
+|------------------------|---------|
+| `unispec-spec`         | UniSpec format definition (schemas, examples) |
+| `unispec-core`         | **This repo** — UniSpec Core Engine implementation |
+| `unispec-docs`         | Documentation site |
+| `unispec-js-adapters`  | Framework integrations (Express/Nest/Fastify) built on top of Core Engine |
+| `unispec-infra`        | Helm charts, Docker, Terraform for deploying the UniSpec platform |
+
+---
+
+## License
+
+UniSpec Core Engine is open-source and free to use under the MIT License.
+
+---
+
+## 🔥 Summary
+
+`unispec-core` is the **heart of the UniSpec ecosystem** at the code level.  
+It provides the Core Engine used to:
+
+- validate  
+- normalize  
+- diff  
+- convert  
+- and integrate  
+
+API specifications in the UniSpec format.
+
+If you're building tools, adapters, or platform services that rely on UniSpec → **this is where the engine lives.**

package/dist/cjs/converters/index.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toOpenAPI = toOpenAPI;
+exports.toGraphQLSDL = toGraphQLSDL;
+exports.toWebSocketModel = toWebSocketModel;
+function toOpenAPI(doc) {
+    const service = doc.service;
+    const rest = (service.protocols?.rest ?? {});
+    const info = {
+        title: service.title ?? service.name,
+        description: service.description,
+    };
+    // Derive OpenAPI servers from UniSpec environments when available.
+    const servers = Array.isArray(service.environments)
+        ? service.environments.map((env) => ({
+            url: env.baseUrl,
+            description: env.name,
+        }))
+        : [];
+    const paths = {};
+    const components = {};
+    // Map service.schemas into OpenAPI components.schemas
+    const schemas = (service.schemas ?? {});
+    const componentsSchemas = {};
+    for (const [name, def] of Object.entries(schemas)) {
+        componentsSchemas[name] = def.jsonSchema;
+    }
+    if (Object.keys(componentsSchemas).length > 0) {
+        components.schemas = componentsSchemas;
+    }
+    // Helper to build a $ref into components.schemas when schemaRef is present.
+    function schemaRefToOpenAPI(schemaRef) {
+        if (!schemaRef) {
+            return {};
+        }
+        return { $ref: `#/components/schemas/${schemaRef}` };
+    }
+    // Build paths from REST routes.
+    if (Array.isArray(rest.routes)) {
+        for (const route of rest.routes) {
+            const pathItem = (paths[route.path] ?? {});
+            const method = route.method.toLowerCase();
+            const parameters = [];
+            // Path params
+            for (const param of route.pathParams ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "path",
+                    required: param.required ?? true,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Query params
+            for (const param of route.queryParams ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "query",
+                    required: param.required ?? false,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Header params
+            for (const param of route.headers ?? []) {
+                parameters.push({
+                    name: param.name,
+                    in: "header",
+                    required: param.required ?? false,
+                    description: param.description,
+                    schema: schemaRefToOpenAPI(param.schemaRef),
+                });
+            }
+            // Request body
+            let requestBody;
+            if (route.requestBody && route.requestBody.content) {
+                const content = {};
+                for (const [mediaType, media] of Object.entries(route.requestBody.content)) {
+                    content[mediaType] = {
+                        schema: schemaRefToOpenAPI(media.schemaRef),
+                    };
+                }
+                requestBody = {
+                    description: route.requestBody.description,
+                    required: route.requestBody.required,
+                    content,
+                };
+            }
+            // Responses
+            const responses = {};
+            for (const [status, resp] of Object.entries(route.responses ?? {})) {
+                const content = {};
+                if (resp.content) {
+                    for (const [mediaType, media] of Object.entries(resp.content)) {
+                        content[mediaType] = {
+                            schema: schemaRefToOpenAPI(media.schemaRef),
+                        };
+                    }
+                }
+                responses[status] = {
+                    description: resp.description ?? "",
+                    ...(Object.keys(content).length > 0 ? { content } : {}),
+                };
+            }
+            const operation = {
+                operationId: route.name,
+                summary: route.summary,
+                description: route.description,
+                ...(parameters.length > 0 ? { parameters } : {}),
+                responses: Object.keys(responses).length > 0 ? responses : { default: { description: "" } },
+            };
+            if (requestBody) {
+                operation.requestBody = requestBody;
+            }
+            // Security requirements
+            if (Array.isArray(route.security) && route.security.length > 0) {
+                operation.security = route.security.map((req) => {
+                    const obj = {};
+                    for (const schemeName of req) {
+                        obj[schemeName] = [];
+                    }
+                    return obj;
+                });
+            }
+            pathItem[method] = operation;
+            paths[route.path] = pathItem;
+        }
+    }
+    // Security schemes pass-through from REST protocol
+    const componentsSecuritySchemes = rest.securitySchemes ?? {};
+    if (Object.keys(componentsSecuritySchemes).length > 0) {
+        components.securitySchemes = componentsSecuritySchemes;
+    }
+    return {
+        openapi: "3.1.0",
+        info,
+        servers,
+        paths,
+        ...(Object.keys(components).length > 0 ? { components } : {}),
+        "x-unispec": doc,
+    };
+}
+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;
+    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 };
+}
+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 channelsArray = Array.isArray(websocket.channels) ? websocket.channels : [];
+    const channels = [...channelsArray]
+        .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""))
+        .map((channel) => ({
+        name: channel.name,
+        summary: undefined,
+        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/cjs/diff/index.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffUniSpec = diffUniSpec;
+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
+    if (Array.isArray(oldVal) && Array.isArray(newVal)) {
+        // Special handling for UniSpec collections identified by "name"
+        const isNamedCollection = basePath === "/service/protocols/rest/routes" ||
+            basePath === "/service/protocols/websocket/channels" ||
+            basePath === "/service/protocols/graphql/queries" ||
+            basePath === "/service/protocols/graphql/mutations" ||
+            basePath === "/service/protocols/graphql/subscriptions";
+        if (isNamedCollection) {
+            const oldByName = new Map();
+            const newByName = new Map();
+            for (const item of oldVal) {
+                if (item && typeof item === "object" && typeof item.name === "string") {
+                    oldByName.set(item.name, item);
+                }
+            }
+            for (const item of newVal) {
+                if (item && typeof item === "object" && typeof item.name === "string") {
+                    newByName.set(item.name, item);
+                }
+            }
+            // Removed
+            for (const [name, oldItem] of oldByName.entries()) {
+                if (!newByName.has(name)) {
+                    out.push({
+                        path: `${basePath}/${name}`,
+                        description: "Item removed",
+                        severity: "unknown",
+                    });
+                }
+                else {
+                    const newItem = newByName.get(name);
+                    diffValues(oldItem, newItem, `${basePath}/${name}`, out);
+                }
+            }
+            // Added
+            for (const [name] of newByName.entries()) {
+                if (!oldByName.has(name)) {
+                    out.push({
+                        path: `${basePath}/${name}`,
+                        description: "Item added",
+                        severity: "unknown",
+                    });
+                }
+            }
+            return;
+        }
+        // Generic shallow index-based compare
+        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/routes/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected shape: ["service", "protocols", "rest", "routes", index]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "rest" || segments[3] !== "routes") {
+        return change;
+    }
+    const index = segments[4];
+    if (typeof index === "undefined") {
+        return change;
+    }
+    const annotated = {
+        ...change,
+        protocol: "rest",
+    };
+    if (change.description === "Item removed" || change.description === "Field removed") {
+        annotated.kind = "rest.route.removed";
+        annotated.severity = "breaking";
+    }
+    else if (change.description === "Item added" || change.description === "Field added") {
+        annotated.kind = "rest.route.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 base: ["service","protocols","websocket","channels", channelIndex, ...]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "websocket" || segments[3] !== "channels") {
+        return change;
+    }
+    const channelIndex = segments[4];
+    const next = segments[5];
+    const annotated = {
+        ...change,
+        protocol: "websocket",
+    };
+    if (typeof channelIndex === "undefined") {
+        return annotated;
+    }
+    // Channel-level changes: /service/protocols/websocket/channels/{index}
+    if (!next) {
+        if (change.description === "Item removed" || change.description === "Field removed") {
+            annotated.kind = "websocket.channel.removed";
+            annotated.severity = "breaking";
+        }
+        else if (change.description === "Item added" || change.description === "Field added") {
+            annotated.kind = "websocket.channel.added";
+            annotated.severity = "non-breaking";
+        }
+        return annotated;
+    }
+    // Message-level changes: /service/protocols/websocket/channels/{index}/messages/{msgIndex}
+    if (next === "messages") {
+        const messageIndex = segments[6];
+        if (typeof messageIndex === "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/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected: ["service","protocols","graphql", kind, index, ...]
+    if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "graphql") {
+        return change;
+    }
+    const opKind = segments[3];
+    const index = segments[4];
+    if (!opKind || typeof index === "undefined") {
+        return change;
+    }
+    if (opKind !== "queries" && opKind !== "mutations" && opKind !== "subscriptions") {
+        return change;
+    }
+    const annotated = {
+        ...change,
+        protocol: "graphql",
+    };
+    if (change.description === "Item removed" || change.description === "Field removed") {
+        annotated.kind = "graphql.operation.removed";
+        annotated.severity = "breaking";
+    }
+    else if (change.description === "Item added" || 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.
+ */
+function diffUniSpec(oldDoc, newDoc) {
+    const changes = [];
+    diffValues(oldDoc, newDoc, "", changes);
+    const annotated = changes.map((change) => annotateWebSocketChange(annotateGraphQLChange(annotateRestChange(change))));
+    return { changes: annotated };
+}

package/dist/cjs/index.js

@@ -0,0 +1,22 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types/index.js"), exports);
+__exportStar(require("./loader/index.js"), exports);
+__exportStar(require("./validator/index.js"), exports);
+__exportStar(require("./normalizer/index.js"), exports);
+__exportStar(require("./diff/index.js"), exports);
+__exportStar(require("./converters/index.js"), exports);

package/dist/cjs/loader/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadUniSpec = loadUniSpec;
+/**
+ * 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.
+ */
+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/cjs/normalizer/index.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeUniSpec = normalizeUniSpec;
+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 normalizeRestRoutes(doc) {
+    if (!doc || !doc.service || !doc.service.protocols) {
+        return doc;
+    }
+    const protocols = doc.service.protocols;
+    const rest = protocols.rest;
+    if (!rest || !Array.isArray(rest.routes)) {
+        return doc;
+    }
+    const routes = [...rest.routes];
+    routes.sort((a, b) => {
+        const keyA = a.name || `${a.path} ${a.method}`;
+        const keyB = b.name || `${b.path} ${b.method}`;
+        return keyA.localeCompare(keyB);
+    });
+    rest.routes = routes;
+    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 || !Array.isArray(websocket.channels)) {
+        return doc;
+    }
+    const channels = websocket.channels.map((channel) => {
+        if (!channel || !Array.isArray(channel.messages)) {
+            return channel;
+        }
+        const sortedMessages = [...channel.messages].sort((a, b) => {
+            const aName = a?.name ?? "";
+            const bName = b?.name ?? "";
+            return aName.localeCompare(bName);
+        });
+        return {
+            ...channel,
+            messages: sortedMessages,
+        };
+    });
+    channels.sort((a, b) => {
+        const aName = a?.name ?? "";
+        const bName = b?.name ?? "";
+        return aName.localeCompare(bName);
+    });
+    websocket.channels = channels;
+    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) {
+        return doc;
+    }
+    const kinds = [
+        "queries",
+        "mutations",
+        "subscriptions",
+    ];
+    for (const kind of kinds) {
+        const ops = graphql[kind];
+        if (!Array.isArray(ops)) {
+            continue;
+        }
+        graphql[kind] = [...ops].sort((a, b) => {
+            const aName = a?.name ?? "";
+            const bName = b?.name ?? "";
+            return aName.localeCompare(bName);
+        });
+    }
+    return doc;
+}
+/**
+ * Normalize a UniSpec document into a canonical, deterministic form.
+ *
+ * Current behavior:
+ * - Recursively sorts object keys lexicographically.
+ * - Preserves values as-is.
+ */
+function normalizeUniSpec(doc, _options = {}) {
+    const normalized = normalizeValue(doc);
+    return normalizeWebSocket(normalizeGraphqlOperations(normalizeRestRoutes(normalized)));
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/types/index.js

@@ -0,0 +1,3 @@
+"use strict";
+// GraphQL protocol types
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/validator/index.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateUniSpec = validateUniSpec;
+exports.validateUniSpecTests = validateUniSpecTests;
+const _2020_js_1 = __importDefault(require("ajv/dist/2020.js"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const unispec_schema_1 = require("@unispechq/unispec-schema");
+const ajv = new _2020_js_1.default({
+    allErrors: true,
+    strict: true,
+});
+// Register minimal URI format to satisfy UniSpec schemas (service.environments[*].baseUrl)
+ajv.addFormat("uri", true);
+// Register all UniSpec subschemas so that Ajv can resolve internal $ref links
+try {
+    const schemaDir = path_1.default.join(process.cwd(), "node_modules", "@unispechq", "unispec-schema", "schema");
+    const types = unispec_schema_1.manifest?.types ?? {};
+    const typeSchemaPaths = Object.values(types).map((rel) => String(rel));
+    const loadedTypeSchemas = typeSchemaPaths
+        .map((relPath) => path_1.default.join(schemaDir, relPath))
+        .filter((filePath) => fs_1.default.existsSync(filePath))
+        .map((filePath) => JSON.parse(fs_1.default.readFileSync(filePath, "utf8")));
+    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(unispec_schema_1.unispec);
+let validateTestsFn;
+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.
+ */
+async function validateUniSpec(doc, _options = {}) {
+    const valid = validateFn(doc);
+    if (valid) {
+        return {
+            valid: true,
+            errors: [],
+        };
+    }
+    return {
+        valid: false,
+        errors: mapAjvErrors(validateFn.errors),
+    };
+}
+/**
+ * Validate a UniSpec Tests document against the UniSpec Tests JSON Schema.
+ */
+async function validateUniSpecTests(doc, _options = {}) {
+    if (!validateTestsFn) {
+        const schemaDir = path_1.default.join(process.cwd(), "node_modules", "@unispechq", "unispec-schema", "schema");
+        const testsSchemaPath = path_1.default.join(schemaDir, "unispec-tests.schema.json");
+        const testsSchema = JSON.parse(fs_1.default.readFileSync(testsSchemaPath, "utf8"));
+        validateTestsFn = ajv.compile(testsSchema);
+    }
+    const valid = validateTestsFn(doc);
+    if (valid) {
+        return {
+            valid: true,
+            errors: [],
+        };
+    }
+    return {
+        valid: false,
+        errors: mapAjvErrors(validateTestsFn.errors),
+    };
+}

package/dist/index.cjs

@@ -0,0 +1,22 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types/index.js"), exports);
+__exportStar(require("./loader/index.js"), exports);
+__exportStar(require("./validator/index.js"), exports);
+__exportStar(require("./normalizer/index.js"), exports);
+__exportStar(require("./diff/index.js"), exports);
+__exportStar(require("./converters/index.js"), exports);

package/dist/validator/index.js

@@ -1,7 +1,7 @@
 import Ajv2020 from "ajv/dist/2020.js";
-import { createRequire } from "module";
+import fs from "fs";
+import path from "path";
 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,
@@ -10,11 +10,13 @@ const ajv = new Ajv2020({
 ajv.addFormat("uri", 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 schemaDir = path.join(process.cwd(), "node_modules", "@unispechq", "unispec-schema", "schema");
     const types = unispecManifest?.types ?? {};
     const typeSchemaPaths = Object.values(types).map((rel) => String(rel));
-    const loadedTypeSchemas = typeSchemaPaths.map((relPath) => require(schemaDir + relPath));
+    const loadedTypeSchemas = typeSchemaPaths
+        .map((relPath) => path.join(schemaDir, relPath))
+        .filter((filePath) => fs.existsSync(filePath))
+        .map((filePath) => JSON.parse(fs.readFileSync(filePath, "utf8")));
     ajv.addSchema(loadedTypeSchemas);
 }
 catch {
@@ -53,9 +55,9 @@ export async function validateUniSpec(doc, _options = {}) {
  */
 export async function validateUniSpecTests(doc, _options = {}) {
     if (!validateTestsFn) {
-        const schemaRootPath = require.resolve("@unispechq/unispec-schema");
-        const schemaDir = schemaRootPath.replace(/index\.(cjs|mjs|js)$/u, "schema/");
-        const testsSchema = require(`${schemaDir}unispec-tests.schema.json`);
+        const schemaDir = path.join(process.cwd(), "node_modules", "@unispechq", "unispec-schema", "schema");
+        const testsSchemaPath = path.join(schemaDir, "unispec-tests.schema.json");
+        const testsSchema = JSON.parse(fs.readFileSync(testsSchemaPath, "utf8"));
         validateTestsFn = ajv.compile(testsSchema);
     }
     const valid = validateTestsFn(doc);

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "@unispechq/unispec-core",
-  "version": "0.2.0",
+  "version": "0.2.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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
   "types": "dist/index.d.ts",
   "files": [
     "dist",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc -p tsconfig.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json && node scripts/postbuild-cjs.cjs",
     "test": "npm run build && node --test tests/*.test.mjs",
     "release:patch": "node scripts/release.js patch",
     "release:minor": "node scripts/release.js minor",