@unispechq/unispec-core 0.2.13 → 0.3.0

package/dist/cjs/validator/unispec-validator.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateUniSpec = validateUniSpec;
+const errors_1 = require("../errors/index.js");
+const ajv_validator_1 = require("./ajv-validator.js");
+const reference_validator_1 = require("./reference-validator.js");
+const semantic_validator_1 = require("./semantic-validator.js");
+const validator_factory_1 = require("./validator-factory.js");
+/**
+ * Validate a UniSpec document with optional extended validation.
+ *
+ * This function performs:
+ * - JSON Schema validation (always)
+ * - Semantic validation (optional, when enableExtendedValidation is true)
+ * - Reference validation (optional, when enableExtendedValidation is true)
+ *
+ * @param doc - The UniSpec document to validate
+ * @param options - Validation options
+ * @returns Validation result with optional extended results
+ */
+async function validateUniSpec(doc, options = {}) {
+    // Always perform basic JSON Schema validation
+    const basicResult = await validateUniSpecBase(doc, options);
+    // If extended validation is disabled, return basic result
+    if (!options.enableExtendedValidation) {
+        return basicResult;
+    }
+    // Perform extended validation
+    const result = {
+        valid: basicResult.valid,
+        errors: [...basicResult.errors],
+    };
+    // Perform semantic validation
+    if (options.semanticValidation) {
+        const semanticResult = (0, semantic_validator_1.validateSemantic)(doc, options.semanticValidation);
+        result.semantic = semanticResult;
+        if (!semanticResult.valid) {
+            result.valid = false;
+            result.errors.push(...semanticResult.errors);
+        }
+    }
+    // Perform reference validation
+    if (options.referenceValidation) {
+        const referenceResult = (0, reference_validator_1.validateReferences)(doc, options.referenceValidation);
+        result.references = referenceResult;
+        if (!referenceResult.valid) {
+            result.valid = false;
+            result.errors.push(...referenceResult.errors);
+        }
+    }
+    return result;
+}
+/**
+ * Internal function for basic JSON Schema validation.
+ */
+async function validateUniSpecBase(doc, options = {}) {
+    try {
+        const { validateUniSpecFn } = await (0, ajv_validator_1.getValidator)(options);
+        // Ensure the document has required fields for validation
+        const docForValidation = {
+            unispecVersion: doc.unispecVersion || "1.0.0",
+            service: doc.service,
+        };
+        const valid = validateUniSpecFn(docForValidation);
+        const schemaErrors = (0, validator_factory_1.mapAjvErrors)(validateUniSpecFn.errors);
+        if (valid) {
+            return {
+                valid: true,
+                errors: [],
+            };
+        }
+        return {
+            valid: false,
+            errors: schemaErrors,
+        };
+    }
+    catch (error) {
+        const validationError = errors_1.ErrorFactory.fromError(error, "validation_error");
+        return {
+            valid: false,
+            errors: [validationError.toJSON()],
+        };
+    }
+}

package/dist/cjs/validator/validator-factory.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createValidator = createValidator;
+exports.mapAjvErrors = mapAjvErrors;
+const errors_1 = require("../errors/index.js");
+/**
+ * Generic validator factory to reduce code duplication.
+ */
+function createValidator(documentType, getValidatorFn, customValidation) {
+    return async function validate(doc, options = {}) {
+        try {
+            const validateFn = await getValidatorFn(options);
+            if (!validateFn) {
+                return {
+                    valid: false,
+                    errors: [
+                        {
+                            message: `${documentType} validation schema is not available. Provide appropriate schema in ValidateOptions.`,
+                            path: "",
+                            code: "schema_missing",
+                        },
+                    ],
+                };
+            }
+            const valid = validateFn(doc);
+            // Run custom validation if provided
+            const customErrors = customValidation ? customValidation(doc) : [];
+            const schemaErrors = valid ? [] : mapAjvErrors(validateFn.errors);
+            const allErrors = [...schemaErrors, ...customErrors];
+            if (valid && customErrors.length === 0) {
+                return {
+                    valid: true,
+                    errors: [],
+                };
+            }
+            return {
+                valid: false,
+                errors: allErrors,
+            };
+        }
+        catch (error) {
+            const validationError = errors_1.ErrorFactory.fromError(error, `${documentType}_validation_error`);
+            return {
+                valid: false,
+                errors: [validationError.toJSON()],
+            };
+        }
+    };
+}
+/**
+ * Map AJV errors to specific UniSpec validation errors.
+ */
+function mapAjvErrors(errors) {
+    if (!errors)
+        return [];
+    return errors.map((error) => {
+        const message = error.message || "UniSpec validation error";
+        const path = error.instancePath || error.schemaPath;
+        const _code = error.keyword;
+        // Create specific error types based on keyword
+        switch (error.keyword) {
+            case "required":
+                return errors_1.ErrorFactory.createSchemaError(`Missing required property: ${message}`, path, { keyword: error.keyword, params: error.params });
+            case "type":
+                return errors_1.ErrorFactory.createSchemaError(`Invalid type: ${message}`, path, { keyword: error.keyword, params: error.params });
+            case "format":
+                return errors_1.ErrorFactory.createSchemaError(`Invalid format: ${message}`, path, { keyword: error.keyword, params: error.params });
+            case "additionalProperties":
+                return errors_1.ErrorFactory.createSchemaError(`Additional property not allowed: ${message}`, path, { keyword: error.keyword, params: error.params });
+            default:
+                return errors_1.ErrorFactory.createSchemaError(message, path, {
+                    keyword: error.keyword,
+                    params: error.params,
+                });
+        }
+    });
+}

package/dist/cjs/versions.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLatestUniSpecVersion = getLatestUniSpecVersion;
+exports.clearVersionCache = clearVersionCache;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+let cachedUniSpecVersion = null;
+let cachedSchemaPackagePath = null;
+/**
+ * Validate package.json content to ensure it's the correct @unispechq/unispec-schema package
+ * @param content Package.json content as string
+ * @returns Package info object if valid, null otherwise
+ */
+function validatePackageJson(content) {
+    try {
+        const packageInfo = JSON.parse(content);
+        if (packageInfo.name === "@unispechq/unispec-schema" &&
+            packageInfo.version) {
+            return packageInfo;
+        }
+    }
+    catch {
+        // Invalid JSON
+    }
+    return null;
+}
+/**
+ * Get current module directory (supports both ESM and CJS)
+ * @returns Current directory path
+ */
+function getCurrentDirectory() {
+    if (typeof __dirname !== "undefined") {
+        return __dirname;
+    }
+    // Try ESM import.meta.url
+    try {
+        if (typeof globalThis !== "undefined" &&
+            globalThis.import
+                ?.meta?.url) {
+            return (0, node_path_1.dirname)((0, node_url_1.fileURLToPath)(globalThis
+                .import.meta.url));
+        }
+    }
+    catch {
+        // Fallback to current working directory
+    }
+    return process.cwd();
+}
+/**
+ * Find the package.json path for @unispechq/unispec-schema
+ * Works in both ESM and CJS contexts with improved reliability
+ * @returns Path to package.json file
+ */
+function findSchemaPackagePath() {
+    // Return cached path if available
+    if (cachedSchemaPackagePath) {
+        return cachedSchemaPackagePath;
+    }
+    const currentDir = getCurrentDirectory();
+    // Define all possible paths to check
+    const candidatePaths = [
+        // Try direct package.json resolution first (most reliable for CJS)
+        () => {
+            if (typeof require !== "undefined") {
+                try {
+                    return require.resolve("@unispechq/unispec-schema/package.json");
+                }
+                catch {
+                    return null;
+                }
+            }
+            return null;
+        },
+        // Try require.resolve for main entry point
+        () => {
+            if (typeof require !== "undefined") {
+                try {
+                    const packageMainPath = require.resolve("@unispechq/unispec-schema");
+                    return (0, node_path_1.join)((0, node_path_1.dirname)(packageMainPath), "package.json");
+                }
+                catch {
+                    return null;
+                }
+            }
+            return null;
+        },
+        // Fallback paths
+        () => (0, node_path_1.join)(process.cwd(), "node_modules", "@unispechq", "unispec-schema", "package.json"),
+        () => (0, node_path_1.join)(currentDir, "..", "node_modules", "@unispechq", "unispec-schema", "package.json"),
+        () => (0, node_path_1.join)(currentDir, "..", "..", "node_modules", "@unispechq", "unispec-schema", "package.json"),
+        () => (0, node_path_1.join)(currentDir, "..", "..", "..", "node_modules", "@unispechq", "unispec-schema", "package.json"),
+    ];
+    // Try each candidate path
+    for (const getPath of candidatePaths) {
+        try {
+            const path = getPath();
+            if (!path)
+                continue;
+            const content = (0, node_fs_1.readFileSync)(path, "utf-8");
+            const packageInfo = validatePackageJson(content);
+            if (packageInfo) {
+                cachedSchemaPackagePath = path;
+                return path;
+            }
+        }
+        catch {
+            // Continue to next path
+        }
+    }
+    throw new Error(`Could not find @unispechq/unispec-schema package.json. Searched in multiple node_modules locations.`);
+}
+/**
+ * Get the latest supported UniSpec version from @unispechq/unispec-schema package
+ * The version is derived from the package.json version (major.minor.0 format)
+ * @returns The latest UniSpec format version (SemVer)
+ */
+function getLatestUniSpecVersion() {
+    if (cachedUniSpecVersion) {
+        return cachedUniSpecVersion;
+    }
+    try {
+        // Find and read package.json from @unispechq/unispec-schema
+        const schemaPackagePath = findSchemaPackagePath();
+        const packageJson = (0, node_fs_1.readFileSync)(schemaPackagePath, "utf-8");
+        const packageInfo = JSON.parse(packageJson);
+        // Extract version and convert to major.minor.0 format
+        const version = packageInfo.version;
+        const [major, minor] = version.split(".");
+        // Create UniSpec version in major.minor.0 format
+        const unispecVersion = `${major}.${minor}.0`;
+        cachedUniSpecVersion = unispecVersion;
+        return unispecVersion;
+    }
+    catch {
+        // Fallback to default version if package.json is not available
+        cachedUniSpecVersion = "1.0.0";
+        return cachedUniSpecVersion;
+    }
+}
+/**
+ * Clear the version cache (useful for testing or dynamic updates)
+ */
+function clearVersionCache() {
+    cachedUniSpecVersion = null;
+    cachedSchemaPackagePath = null;
+}

package/dist/diff/annotators.d.ts

@@ -0,0 +1,4 @@
+import type { UniSpecChange } from "./types.js";
+export declare function annotateRestChange(change: UniSpecChange): UniSpecChange;
+export declare function annotateWebSocketChange(change: UniSpecChange): UniSpecChange;
+export declare function annotateGraphQLChange(change: UniSpecChange): UniSpecChange;

package/dist/diff/annotators.js

@@ -0,0 +1,127 @@
+export 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", routeName, ...]
+    if (segments[0] !== "service" ||
+        segments[1] !== "protocols" ||
+        segments[2] !== "rest" ||
+        segments[3] !== "routes") {
+        return change;
+    }
+    const routeName = segments[4];
+    if (typeof routeName === "undefined") {
+        return change;
+    }
+    const annotated = {
+        ...change,
+        protocol: "rest",
+    };
+    if (change.description === "Item removed") {
+        annotated.kind = "rest.route.removed";
+        annotated.severity = "breaking";
+    }
+    else if (change.description === "Item added") {
+        annotated.kind = "rest.route.added";
+        annotated.severity = "non-breaking";
+    }
+    else if (change.path.includes("/required") &&
+        change.description === "Value changed") {
+        // Changing required field from false to true is breaking
+        annotated.kind = "rest.parameter.required_changed";
+        annotated.severity = "breaking";
+    }
+    return annotated;
+}
+export 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", 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 = {
+        ...change,
+        protocol: "websocket",
+    };
+    if (typeof channelName === "undefined") {
+        return annotated;
+    }
+    // Channel-level changes: /service/protocols/websocket/channels/{channelName}
+    if (!next) {
+        if (change.description === "Item removed") {
+            annotated.kind = "websocket.channel.removed";
+            annotated.severity = "breaking";
+        }
+        else if (change.description === "Item added") {
+            annotated.kind = "websocket.channel.added";
+            annotated.severity = "non-breaking";
+        }
+        return annotated;
+    }
+    // Message-level changes: /service/protocols/websocket/channels/{channelName}/messages/{messageName}
+    if (next === "messages") {
+        const messageName = segments[6];
+        if (typeof messageName === "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;
+}
+export function annotateGraphQLChange(change) {
+    if (!change.path.startsWith("/service/protocols/graphql/")) {
+        return change;
+    }
+    const segments = change.path.split("/").filter(Boolean);
+    // Expected: ["service","protocols","graphql", operationType, operationName, ...]
+    if (segments[0] !== "service" ||
+        segments[1] !== "protocols" ||
+        segments[2] !== "graphql") {
+        return change;
+    }
+    const operationType = segments[3];
+    const operationName = segments[4];
+    if (!operationType || typeof operationName === "undefined") {
+        return change;
+    }
+    if (operationType !== "queries" &&
+        operationType !== "mutations" &&
+        operationType !== "subscriptions") {
+        return change;
+    }
+    const annotated = {
+        ...change,
+        protocol: "graphql",
+    };
+    if (change.description === "Item removed") {
+        annotated.kind = "graphql.operation.removed";
+        annotated.severity = "breaking";
+    }
+    else if (change.description === "Item added") {
+        annotated.kind = "graphql.operation.added";
+        annotated.severity = "non-breaking";
+    }
+    else if (change.path.includes("/returnType") &&
+        change.description === "Value changed") {
+        // Changing return type is breaking
+        annotated.kind = "graphql.operation.return_type_changed";
+        annotated.severity = "breaking";
+    }
+    return annotated;
+}

package/dist/diff/change-reports.d.ts

@@ -0,0 +1,37 @@
+import type { EnhancedDiffResult, EnhancedUniSpecChange } from "./enhanced-diff.js";
+export interface ReportOptions {
+    format: "markdown" | "html" | "json";
+    includeSuggestions?: boolean;
+    includeExamples?: boolean;
+    groupByRisk?: boolean;
+    groupByProtocol?: boolean;
+    title?: string;
+    versionInfo?: {
+        oldVersion?: string;
+        newVersion?: string;
+        comparisonDate?: string;
+    };
+}
+export interface ChangeReport {
+    title: string;
+    summary: {
+        totalChanges: number;
+        breakingChanges: number;
+        compatibilityScore: number;
+        migrationEffort: string;
+    };
+    sections: ReportSection[];
+}
+export interface ReportSection {
+    title: string;
+    changes: EnhancedUniSpecChange[];
+    summary: string;
+}
+/**
+ * Generate a comprehensive change report.
+ *
+ * @param diff - Enhanced diff result
+ * @param options - Report generation options
+ * @returns Formatted report in the specified format
+ */
+export declare function generateChangeReport(diff: EnhancedDiffResult, options: ReportOptions): string;