@unispechq/unispec-core 0.2.0 → 0.2.3

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,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toOpenAPI = toOpenAPI;
+exports.toGraphQLSDL = toGraphQLSDL;
+exports.toWebSocketModel = toWebSocketModel;
+function toOpenAPI(doc) {
+    const rest = (doc.protocols?.rest ?? {});
+    const info = {
+        title: doc.name,
+        description: doc.description,
+    };
+    const servers = [];
+    const paths = {};
+    const components = {};
+    // Map doc.schemas into OpenAPI components.schemas
+    const schemas = (doc.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.protocols?.graphql;
+    const customSDL = graphql?.schema;
+    if (typeof customSDL === "string" && customSDL.trim()) {
+        return { sdl: customSDL };
+    }
+    const title = doc.name;
+    const description = doc.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 websocket = (doc.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: doc.name,
+            title: undefined,
+            description: doc.description,
+        },
+        channels,
+        rawProtocol: websocket,
+        "x-unispec-ws": doc,
+    };
+}