@unispechq/unispec-core 0.1.0 → 0.1.1

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 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.**
+# 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/package.json

@@ -1,28 +1,28 @@
-{
-  "name": "@unispechq/unispec-core",
-  "version": "0.1.0",
-  "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",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test tests/*.test.mjs",
-    "release:patch": "node scripts/release.js patch",
-    "release:minor": "node scripts/release.js minor",
-    "release:major": "node scripts/release.js major"
-  },
-  "dependencies": {
-    "@unispechq/unispec-schema": "^0.2.1",
-    "ajv": "^8.12.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.10.1",
-    "typescript": "^5.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@unispechq/unispec-core",
+  "version": "0.1.1",
+  "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",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "release:patch": "node scripts/release.js patch",
+    "release:minor": "node scripts/release.js minor",
+    "release:major": "node scripts/release.js major"
+  },
+  "dependencies": {
+    "@unispechq/unispec-schema": "^0.2.1",
+    "ajv": "^8.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/release.js

@@ -1,51 +1,51 @@
-#!/usr/bin/env node
-
-import { execSync } from 'node:child_process';
-import { readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-const bumpType = process.argv[2];
-
-if (!['patch', 'minor', 'major'].includes(bumpType)) {
-  console.error('Usage: npm run release:<patch|minor|major>');
-  process.exit(1);
-}
-
-const root = process.cwd();
-const pkgPath = join(root, 'package.json');
-
-const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-
-function bumpVersion(version, type) {
-  const [major, minor, patch] = version.split('.').map(Number);
-
-  if (type === 'patch') return `${major}.${minor}.${patch + 1}`;
-  if (type === 'minor') return `${major}.${minor + 1}.0`;
-  if (type === 'major') return `${major + 1}.0.0`;
-
-  throw new Error(`Unsupported bump type: ${type}`);
-}
-
-const oldVersion = pkg.version;
-if (!oldVersion) {
-  console.error('package.json has no version field');
-  process.exit(1);
-}
-
-const newVersion = bumpVersion(oldVersion, bumpType);
-pkg.version = newVersion;
-
-writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
-
-const currentBranch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim();
-
-execSync('git add package.json', { stdio: 'inherit' });
-execSync(`git commit -m "chore: release unispec-core v${newVersion}"`, { stdio: 'inherit' });
-
-const tagName = `unispec-core-v${newVersion}`;
-execSync(`git tag ${tagName}`, { stdio: 'inherit' });
-
-execSync(`git push origin ${currentBranch}`, { stdio: 'inherit' });
-execSync(`git push origin ${tagName}`, { stdio: 'inherit' });
-
-console.log(`\nPushed ${currentBranch} and tag ${tagName} to origin.`);
+#!/usr/bin/env node
+
+import { execSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const bumpType = process.argv[2];
+
+if (!['patch', 'minor', 'major'].includes(bumpType)) {
+  console.error('Usage: npm run release:<patch|minor|major>');
+  process.exit(1);
+}
+
+const root = process.cwd();
+const pkgPath = join(root, 'package.json');
+
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+
+function bumpVersion(version, type) {
+  const [major, minor, patch] = version.split('.').map(Number);
+
+  if (type === 'patch') return `${major}.${minor}.${patch + 1}`;
+  if (type === 'minor') return `${major}.${minor + 1}.0`;
+  if (type === 'major') return `${major + 1}.0.0`;
+
+  throw new Error(`Unsupported bump type: ${type}`);
+}
+
+const oldVersion = pkg.version;
+if (!oldVersion) {
+  console.error('package.json has no version field');
+  process.exit(1);
+}
+
+const newVersion = bumpVersion(oldVersion, bumpType);
+pkg.version = newVersion;
+
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+
+const currentBranch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim();
+
+execSync('git add package.json', { stdio: 'inherit' });
+execSync(`git commit -m "chore: release unispec-core v${newVersion}"`, { stdio: 'inherit' });
+
+const tagName = `unispec-core-v${newVersion}`;
+execSync(`git tag ${tagName}`, { stdio: 'inherit' });
+
+execSync(`git push origin ${currentBranch}`, { stdio: 'inherit' });
+execSync(`git push origin ${tagName}`, { stdio: 'inherit' });
+
+console.log(`\nPushed ${currentBranch} and tag ${tagName} to origin.`);