@unispechq/unispec-core 0.1.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,74 @@
+name: CI & Publish UniSpec Core
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "unispec-core-v*"
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  ci:
+    name: CI (install & pack)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+
+      - name: Run tests (if defined)
+        run: |
+          if npm run | grep -q " test"; then
+            npm test
+          else
+            echo "No test script defined, skipping tests"
+          fi
+
+      - name: Verify package can be packed
+        run: npm pack --dry-run
+
+  publish:
+    name: Publish to npm
+    needs: ci
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/unispec-core-v')
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Use Node.js with npm registry
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          scope: "@unispechq"
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+
+      - name: Publish @unispechq/unispec-core to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

package/.windsurfrules

@@ -0,0 +1,138 @@
+# WindSurf Rules for `unispec-core`
+# ---------------------------------
+# This ruleset defines how AI assistants, contributors, and reviewers must
+# interact with the UniSpec Core Engine repository.
+# The Core Engine provides validation, parsing, normalization, diffing,
+# and conversion logic for UniSpec specifications.
+
+repository:
+  name: "unispec-core"
+  description: "Runtime implementation of the UniSpec Core Engine (loader, validator, normalizer, diff engine, converters, shared types). This repository contains only the Core Engine used by other UniSpec platform components (CLI, Registry, Portal, adapters, SDKs)."
+  visibility: public
+  criticality: core
+
+goals:
+  - Implement the runtime mechanics of the UniSpec format defined in `unispec-spec`.
+  - Provide parsing, validation, normalization, and diffing for UniSpec documents.
+  - Provide reusable shared types and utilities for CLI, adapters, registry, and portal.
+  - Ensure strict alignment with the specification and JSON Schemas.
+  - Consume organization-wide context through MCP GitHub server without violating boundaries.
+  - Remain lightweight, stable, deterministic, and fully spec-compliant.
+
+assistant_instructions:
+  allowed_actions:
+    - Read and reference content from other UniSpec repositories via MCP GitHub.
+    - Generate and update logic within this repository related to:
+        - parsing UniSpec documents,
+        - JSON Schema validation,
+        - normalization,
+        - diffing,
+        - conversions (OpenAPI, GraphQL SDL, WebSocket models),
+        - shared types and interfaces.
+    - Suggest architectural improvements to core modules.
+    - Assist in writing documentation, API descriptions, comments, and design notes.
+    - Validate behavior using actual spec files from `unispec-spec`.
+
+  forbidden_actions:
+    - Modify any files in external repositories.
+    - Introduce changes to the UniSpec language itself (belongs to `unispec-spec`).
+    - Implement features that are not grounded in the official spec.
+    - Add framework-specific or platform-specific logic (belongs to adapters).
+    - Add server code, API endpoints, frontend components, or CLI commands.
+    - Introduce non-deterministic behavior or global mutable state.
+    - Modify specification version numbers (belongs to `unispec-spec`).
+
+  escalation_policy:
+    - Any behavior that deviates from the official UniSpec spec must require maintainer confirmation.
+    - If MCP data reveals discrepancies between spec and code, assistant must warn and suggest alignment.
+    - For potentially breaking API changes, assistant must halt and request maintainer approval.
+
+context_model:
+  mcp_github_usage:
+    allowed:
+      - Access organization repositories for context (read-only).
+      - Inspect:
+          - UniSpec format (`unispec-spec`)
+          - CLI behavior (`unispec-platform`)
+          - Adapters (`unispec-js-adapters`, `unispec-python-adapters`)
+          - Registry and Portal APIs
+      - Use cross-repo information to ensure Core Engine behavior matches platform expectations.
+    forbidden:
+      - Editing or mutating files in other repositories.
+      - Making assumptions not supported by spec.
+      - Introducing coupling that makes core depend on implementation details.
+    behaviors:
+      - Treat external repos purely as reference sources.
+      - Maintain strict alignment with the spec repo.
+      - Do not derive new behaviors not defined by the spec.
+
+file_structure:
+  required_directories:
+    src: "Source code for the Core Engine logic"
+    src/loader: "Spec loader and YAML/JSON reading utilities"
+    src/validator: "Schema validation logic using official UniSpec JSON Schemas"
+    src/normalizer: "Canonical normalization of UniSpec documents"
+    src/diff: "Diff engine and breaking change detection"
+    src/converters: "Converters for OpenAPI, GraphQL, WebSocket, etc."
+    src/types: "Shared public-facing TypeScript types/interfaces"
+    docs: "Developer documentation and design notes"
+
+  required_files:
+    - "README.md"
+    - "package.json"
+    - "src/index.ts"
+    - "src/types/index.ts"
+
+content_guidelines:
+  code_requirements:
+    - Must be deterministic, pure, and side-effect-free where possible.
+    - Must strictly follow the UniSpec JSON Schema definitions.
+    - Must use official schemas from `unispec-spec` (via MCP reference or local import).
+    - Should be modular, composable, and testable.
+    - Must not depend on frameworks (Express, Nest, FastAPI, etc).
+    - Must not include platform logic (Registry/Portal).
+
+  documentation:
+    - All modules must have clear API descriptions and rationale.
+    - Example inputs and outputs should reference real UniSpec examples.
+    - Must reflect the latest UniSpec specification.
+
+  testing:
+    - Core behavior must be validated using examples from `unispec-spec/examples`.
+    - All changes must include tests for validation, normalization, diffing, and conversions.
+    - Tests must cover edge cases and backward compatibility.
+
+versioning_policy:
+  rules:
+    - Core versioning follows the platform, not the spec.
+    - Breaking API changes require:
+        - Maintainer approval
+    - Minor versions may add new converters or metadata fields if spec permits.
+    - Patch versions fix issues, improve accuracy, or correct types.
+
+pull_request_rules:
+  - PRs must describe:
+      - intent,
+      - expected behavior,
+      - impact on users,
+      - compatibility implications.
+  - PRs affecting validation, types, or normalization must include:
+      - tests,
+      - updated docs,
+      - verification against real examples.
+  - Schema-dependent logic must be checked against `unispec-spec` via MCP.
+
+tone_and_style:
+  - Code and docs must be clean, consistent, and professional.
+  - Naming conventions must follow spec terminology.
+  - No noisy logs, no temporary/debug code.
+
+license:
+  - Must remain open-source.
+  - Core engine logic must be available for public use.
+
+notes:
+  - This repository implements the *mechanics* of UniSpec, not the language definition.
+  - The UniSpec format itself lives in `unispec-spec`.
+  - Adapters, CLI, Registry, and Portal depend on core — keep APIs stable and predictable.
+  - MCP GitHub context may be used for reasoning but not for cross-repo modifications.

package/README.md

@@ -0,0 +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 paths/methods, 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**  
+  - Treated as a general OpenAPI-like structure defined by UniSpec JSON Schemas.  
+  - Normalizer orders `paths` and HTTP methods for stable diffs.  
+  - Diff engine annotates path/operation additions and removals with breaking/non-breaking severity.  
+  - Converter exposes REST as an OpenAPI 3.1 document while preserving the original UniSpec under `x-unispec`.
+
+- **GraphQL**  
+  - Typed protocol with `schema` (SDL) and `operations` (queries/mutations/subscriptions).  
+  - 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, plus extensions.  
+  - 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/converters/index.d.ts

@@ -0,0 +1,13 @@
+import { UniSpecDocument } from "../types";
+export interface OpenAPIDocument {
+    [key: string]: unknown;
+}
+export interface GraphQLSDLOutput {
+    sdl: string;
+}
+export interface WebSocketModel {
+    [key: string]: unknown;
+}
+export declare function toOpenAPI(doc: UniSpecDocument): OpenAPIDocument;
+export declare function toGraphQLSDL(doc: UniSpecDocument): GraphQLSDLOutput;
+export declare function toWebSocketModel(doc: UniSpecDocument): WebSocketModel;

package/dist/converters/index.js

@@ -0,0 +1,89 @@
+export function toOpenAPI(doc) {
+    const service = doc.service;
+    const rest = service.protocols?.rest;
+    const info = {
+        title: service.title ?? service.name,
+        description: service.description,
+    };
+    const servers = rest?.servers ?? [];
+    const paths = rest?.paths ?? {};
+    // Transparently forward additional REST protocol fields into the OpenAPI document.
+    // This allows users to describe components, security, tags and other structures
+    // without forcing a specific REST model at the core layer.
+    const { servers: _omitServers, paths: _omitPaths, ...restExtras } = rest ?? {};
+    return {
+        openapi: "3.1.0",
+        info,
+        servers,
+        paths,
+        ...restExtras,
+        "x-unispec": doc,
+    };
+}
+export 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?.sdl;
+    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 };
+}
+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 service = doc.service;
+    const websocket = (service.protocols?.websocket ?? {});
+    const channelsRecord = (websocket && typeof websocket === "object" && websocket.channels && typeof websocket.channels === "object")
+        ? websocket.channels
+        : {};
+    const channels = Object.keys(channelsRecord).sort().map((name) => {
+        const channel = channelsRecord[name] ?? {};
+        return {
+            name,
+            summary: channel.summary ?? channel.title,
+            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/diff/index.d.ts

@@ -0,0 +1,21 @@
+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[];
+}
+/**
+ * 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 declare function diffUniSpec(oldDoc: UniSpecDocument, newDoc: UniSpecDocument): DiffResult;