@unispechq/unispec-core 0.1.0 → 0.1.2

package/.windsurfrules

@@ -1,138 +0,0 @@
-# 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/scripts/release.js

@@ -1,51 +0,0 @@
-#!/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.`);

package/src/converters/index.ts

@@ -1,120 +0,0 @@
-import { UniSpecDocument, UniSpecWebSocketProtocol, UniSpecWebSocketChannel } from "../types";
-
-export interface OpenAPIDocument {
-  [key: string]: unknown;
-}
-
-export interface GraphQLSDLOutput {
-  sdl: string;
-}
-
-export interface WebSocketModel {
-  [key: string]: unknown;
-}
-
-export function toOpenAPI(doc: UniSpecDocument): OpenAPIDocument {
-  const service = doc.service;
-  const rest = service.protocols?.rest as any | undefined;
-
-  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: UniSpecDocument): GraphQLSDLOutput {
-  // 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: string[] = [];
-
-  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: UniSpecDocument): WebSocketModel {
-  // 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 ?? {}) as UniSpecWebSocketProtocol;
-
-  const channelsRecord = (websocket && typeof websocket === "object" && websocket.channels && typeof websocket.channels === "object")
-    ? (websocket.channels as Record<string, UniSpecWebSocketChannel>)
-    : {};
-
-  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/src/diff/index.ts

@@ -1,235 +0,0 @@
-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[];
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return Object.prototype.toString.call(value) === "[object Object]";
-}
-
-function diffValues(oldVal: unknown, newVal: unknown, basePath: string, out: UniSpecChange[]): void {
-  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 as Record<string, unknown>)[key], (newVal as Record<string, unknown>)[key], childPath, out);
-    }
-
-    return;
-  }
-
-  // Arrays → shallow compare by index for now
-  if (Array.isArray(oldVal) && Array.isArray(newVal)) {
-    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: UniSpecChange): UniSpecChange {
-  if (!change.path.startsWith("/service/protocols/rest/paths/")) {
-    return change;
-  }
-
-  const segments = change.path.split("/").filter(Boolean);
-  // Expected shape: ["service", "protocols", "rest", "paths", pathKey?, method?]
-  if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "rest" || segments[3] !== "paths") {
-    return change;
-  }
-
-  const pathKey = segments[4];
-  const method = segments[5];
-
-  const httpMethods = new Set(["get", "head", "options", "post", "put", "patch", "delete"]);
-
-  const annotated: UniSpecChange = {
-    ...change,
-    protocol: "rest",
-  };
-
-  if (change.description === "Field removed") {
-    if (pathKey && !method) {
-      annotated.kind = "rest.path.removed";
-      annotated.severity = "breaking";
-    } else if (pathKey && method && httpMethods.has(method)) {
-      annotated.kind = "rest.operation.removed";
-      annotated.severity = "breaking";
-    }
-  } else if (change.description === "Field added") {
-    if (pathKey && !method) {
-      annotated.kind = "rest.path.added";
-      annotated.severity = "non-breaking";
-    } else if (pathKey && method && httpMethods.has(method)) {
-      annotated.kind = "rest.operation.added";
-      annotated.severity = "non-breaking";
-    }
-  }
-
-  return annotated;
-}
-
-function annotateWebSocketChange(change: UniSpecChange): UniSpecChange {
-  if (!change.path.startsWith("/service/protocols/websocket/channels/")) {
-    return change;
-  }
-
-  const segments = change.path.split("/").filter(Boolean);
-  // Expected: ["service","protocols","websocket","channels", channelName, ...]
-  if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "websocket" || segments[3] !== "channels") {
-    return change;
-  }
-
-  const channelName = segments[4];
-  const next = segments[5];
-
-  const annotated: UniSpecChange = {
-    ...change,
-    protocol: "websocket",
-  };
-
-  if (!channelName) {
-    return annotated;
-  }
-
-  // Channel-level changes
-  if (!next) {
-    if (change.description === "Field removed") {
-      annotated.kind = "websocket.channel.removed";
-      annotated.severity = "breaking";
-    } else if (change.description === "Field added") {
-      annotated.kind = "websocket.channel.added";
-      annotated.severity = "non-breaking";
-    }
-    return annotated;
-  }
-
-  // Message-level changes (channels/{channelName}/messages/{index})
-  if (next === "messages") {
-    const index = segments[6];
-    if (typeof index === "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: UniSpecChange): UniSpecChange {
-  if (!change.path.startsWith("/service/protocols/graphql/operations/")) {
-    return change;
-  }
-
-  const segments = change.path.split("/").filter(Boolean);
-  // Expected: ["service","protocols","graphql","operations", kind, opName?]
-  if (segments[0] !== "service" || segments[1] !== "protocols" || segments[2] !== "graphql" || segments[3] !== "operations") {
-    return change;
-  }
-
-  const opKind = segments[4];
-  const opName = segments[5];
-
-  if (!opKind || !opName) {
-    return change;
-  }
-
-  const annotated: UniSpecChange = {
-    ...change,
-    protocol: "graphql",
-  };
-
-  if (change.description === "Field removed") {
-    annotated.kind = "graphql.operation.removed";
-    annotated.severity = "breaking";
-  } else if (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.
- */
-export function diffUniSpec(oldDoc: UniSpecDocument, newDoc: UniSpecDocument): DiffResult {
-  const changes: UniSpecChange[] = [];
-  diffValues(oldDoc, newDoc, "", changes);
-  const annotated = changes.map((change) => annotateWebSocketChange(annotateGraphQLChange(annotateRestChange(change))));
-  return { changes: annotated };
-}

package/src/index.ts

@@ -1,6 +0,0 @@
-export * from "./types/index.js";
-export * from "./loader/index.js";
-export * from "./validator/index.js";
-export * from "./normalizer/index.js";
-export * from "./diff/index.js";
-export * from "./converters/index.js";

package/src/loader/index.ts

@@ -1,25 +0,0 @@
-import { UniSpecDocument } from "../types";
-
-export interface LoadOptions {
-  filename?: string;
-}
-
-/**
- * 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.
- */
-export async function loadUniSpec(input: string | object, _options: LoadOptions = {}): Promise<UniSpecDocument> {
-  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) as UniSpecDocument;
-  }
-  return input as UniSpecDocument;
-}