@unispechq/unispec-core 0.3.2 → 0.3.4

package/dist/src/validator/semantic-validator.js

@@ -1,325 +0,0 @@
-/**
- * Validate naming conventions across the UniSpec document.
- */
-function validateNamingConventions(doc, options) {
-    const errors = [];
-    if (!options.strictNaming)
-        return errors;
-    // Validate service name
-    if (doc.service.name) {
-        if (!/^[a-z][a-z0-9-]*$/.test(doc.service.name)) {
-            errors.push({
-                message: "Service name should use kebab-case starting with lowercase letter",
-                path: "/service/name",
-                code: "naming_convention",
-            });
-        }
-    }
-    // Validate REST route names
-    const restRoutes = doc.service?.protocols?.rest?.routes || [];
-    for (const route of restRoutes) {
-        if (route.name && !/^[a-z][a-zA-Z0-9]*$/.test(route.name)) {
-            errors.push({
-                message: "REST route name should use camelCase starting with lowercase letter",
-                path: `/service/protocols/rest/routes/${route.name}/name`,
-                code: "naming_convention",
-            });
-        }
-        // Validate path parameters naming
-        if (route.pathParams) {
-            for (const param of route.pathParams) {
-                if (param.name && !/^[a-z][a-zA-Z0-9]*$/.test(param.name)) {
-                    errors.push({
-                        message: "Path parameter name should use camelCase starting with lowercase letter",
-                        path: `/service/protocols/rest/routes/${route.name}/pathParams/${param.name}/name`,
-                        code: "naming_convention",
-                    });
-                }
-            }
-        }
-    }
-    // Validate GraphQL operation names
-    const graphql = doc.service?.protocols?.graphql;
-    if (graphql) {
-        const operations = [
-            ...(graphql.queries || []),
-            ...(graphql.mutations || []),
-            ...(graphql.subscriptions || []),
-        ];
-        for (const op of operations) {
-            if (op.name && !/^[A-Z][a-zA-Z]*$/.test(op.name)) {
-                errors.push({
-                    message: "GraphQL operation name should use PascalCase starting with uppercase letter",
-                    path: `/service/protocols/graphql/${op.name}/name`,
-                    code: "naming_convention",
-                });
-            }
-        }
-    }
-    // Validate WebSocket channel and message names
-    const websocket = doc.service?.protocols?.websocket;
-    if (websocket?.channels) {
-        for (const channel of websocket.channels) {
-            if (channel.name && !/^[a-z][a-zA-Z0-9]*$/.test(channel.name)) {
-                errors.push({
-                    message: "WebSocket channel name should use camelCase starting with lowercase letter",
-                    path: `/service/protocols/websocket/channels/${channel.name}/name`,
-                    code: "naming_convention",
-                });
-            }
-            if (channel.messages) {
-                for (const message of channel.messages) {
-                    if (message.name && !/^[a-z][a-zA-Z0-9]*$/.test(message.name)) {
-                        errors.push({
-                            message: "WebSocket message name should use camelCase starting with lowercase letter",
-                            path: `/service/protocols/websocket/channels/${channel.name}/messages/${message.name}/name`,
-                            code: "naming_convention",
-                        });
-                    }
-                }
-            }
-        }
-    }
-    return errors;
-}
-/**
- * Validate URL patterns and formats.
- */
-function validateUrlPatterns(doc, options) {
-    const errors = [];
-    if (!options.checkUrlPatterns)
-        return errors;
-    // Validate baseUrl
-    if (doc.service.baseUrl) {
-        try {
-            new URL(doc.service.baseUrl);
-            if (!doc.service.baseUrl.startsWith("http") &&
-                !doc.service.baseUrl.startsWith("https")) {
-                errors.push({
-                    message: "baseUrl should start with http:// or https://",
-                    path: "/service/baseUrl",
-                    code: "invalid_url",
-                });
-            }
-        }
-        catch {
-            errors.push({
-                message: "baseUrl is not a valid URL",
-                path: "/service/baseUrl",
-                code: "invalid_url",
-            });
-        }
-    }
-    // Validate REST route paths
-    const restRoutes = doc.service?.protocols?.rest?.routes || [];
-    for (const route of restRoutes) {
-        if (route.path) {
-            // Path should start with /
-            if (!route.path.startsWith("/")) {
-                errors.push({
-                    message: "REST route path should start with '/'",
-                    path: `/service/protocols/rest/routes/${route.name}/path`,
-                    code: "invalid_path",
-                });
-            }
-            // Check for path parameter consistency
-            const pathParamMatches = route.path.match(/:\w+/g) || [];
-            const declaredParams = route.pathParams?.map((p) => p.name) || [];
-            for (const param of pathParamMatches) {
-                const paramName = param.slice(1); // Remove ':'
-                if (!declaredParams.includes(paramName)) {
-                    errors.push({
-                        message: `Path parameter '${paramName}' is used in path but not declared in pathParams`,
-                        path: `/service/protocols/rest/routes/${route.name}/path`,
-                        code: "undeclared_parameter",
-                    });
-                }
-            }
-            // Check for declared parameters not used in path
-            for (const declaredParam of declaredParams) {
-                if (!pathParamMatches.some((match) => match.slice(1) === declaredParam)) {
-                    errors.push({
-                        message: `Path parameter '${declaredParam}' is declared but not used in path`,
-                        path: `/service/protocols/rest/routes/${route.name}/pathParams/${declaredParam}`,
-                        code: "unused_parameter",
-                    });
-                }
-            }
-        }
-    }
-    return errors;
-}
-/**
- * Check for name conflicts across different components.
- */
-function validateNameConflicts(doc, options) {
-    const errors = [];
-    if (!options.checkNameConflicts)
-        return errors;
-    const allNames = new Map();
-    // Collect REST route names
-    const restRoutes = doc.service?.protocols?.rest?.routes || [];
-    for (const route of restRoutes) {
-        if (route.name) {
-            const existing = allNames.get(route.name) || [];
-            existing.push(`REST route: ${route.path} ${route.method}`);
-            allNames.set(route.name, existing);
-        }
-    }
-    // Collect GraphQL operation names
-    const graphql = doc.service?.protocols?.graphql;
-    if (graphql) {
-        const operations = [
-            ...(graphql.queries || []),
-            ...(graphql.mutations || []),
-            ...(graphql.subscriptions || []),
-        ];
-        for (const op of operations) {
-            if (op.name) {
-                const existing = allNames.get(op.name) || [];
-                existing.push(`GraphQL operation`);
-                allNames.set(op.name, existing);
-            }
-        }
-    }
-    // Collect WebSocket channel names
-    const websocket = doc.service?.protocols?.websocket;
-    if (websocket?.channels) {
-        for (const channel of websocket.channels) {
-            if (channel.name) {
-                const existing = allNames.get(channel.name) || [];
-                existing.push(`WebSocket channel`);
-                allNames.set(channel.name, existing);
-            }
-        }
-    }
-    // Check for conflicts
-    for (const [name, locations] of allNames.entries()) {
-        if (locations.length > 1) {
-            errors.push({
-                message: `Name '${name}' is used in multiple locations: ${locations.join(", ")}`,
-                path: "",
-                code: "name_conflict",
-            });
-        }
-    }
-    return errors;
-}
-/**
- * Check for circular dependencies in schemas.
- */
-function validateCircularDependencies(doc, options) {
-    const errors = [];
-    if (!options.checkCircularDependencies)
-        return errors;
-    const schemas = doc.service?.schemas;
-    if (!schemas)
-        return errors;
-    // Build dependency graph
-    const dependencies = new Map();
-    for (const [schemaName, schema] of Object.entries(schemas)) {
-        const deps = new Set();
-        findSchemaReferences(schema.jsonSchema, deps);
-        dependencies.set(schemaName, deps);
-    }
-    // Check for circular dependencies
-    const visited = new Set();
-    const recursionStack = new Set();
-    function hasCycle(schemaName, path) {
-        if (recursionStack.has(schemaName)) {
-            const cycle = [...path.slice(path.indexOf(schemaName)), schemaName].join(" -> ");
-            errors.push({
-                message: `Circular dependency detected in schemas: ${cycle}`,
-                path: `/service/schemas/${schemaName}`,
-                code: "circular_dependency",
-            });
-            return true;
-        }
-        if (visited.has(schemaName))
-            return false;
-        visited.add(schemaName);
-        recursionStack.add(schemaName);
-        const deps = dependencies.get(schemaName) || new Set();
-        for (const dep of deps) {
-            if (hasCycle(dep, [...path, schemaName])) {
-                return true;
-            }
-        }
-        recursionStack.delete(schemaName);
-        return false;
-    }
-    for (const schemaName of Object.keys(schemas)) {
-        if (!visited.has(schemaName)) {
-            hasCycle(schemaName, []);
-        }
-    }
-    return errors;
-}
-/**
- * Find all schema references in a JSON Schema object.
- */
-function findSchemaReferences(schema, dependencies) {
-    if (!schema || typeof schema !== "object")
-        return;
-    const schemaRecord = schema;
-    // Check for $ref
-    if (schemaRecord.$ref && typeof schemaRecord.$ref === "string") {
-        const ref = schemaRecord.$ref;
-        if (ref.startsWith("#/service/schemas/")) {
-            const schemaName = ref.split("/").pop();
-            if (schemaName) {
-                dependencies.add(schemaName);
-            }
-        }
-    }
-    // Check for schemaRef
-    if (schemaRecord.schemaRef && typeof schemaRecord.schemaRef === "string") {
-        dependencies.add(schemaRecord.schemaRef);
-    }
-    // Recursively check all properties
-    for (const [_key, value] of Object.entries(schemaRecord)) {
-        if (Array.isArray(value)) {
-            for (const item of value) {
-                findSchemaReferences(item, dependencies);
-            }
-        }
-        else if (typeof value === "object" && value !== null) {
-            findSchemaReferences(value, dependencies);
-        }
-    }
-}
-/**
- * Perform semantic validation on a UniSpec document.
- *
- * This function goes beyond JSON Schema validation to check:
- * - Naming conventions
- * - URL patterns
- * - Name conflicts
- * - Circular dependencies
- *
- * @param doc - The UniSpec document to validate
- * @param options - Validation options
- * @returns Semantic validation result
- */
-export function validateSemantic(doc, options = {}) {
-    const errors = [];
-    const warnings = [];
-    // Default options
-    const opts = {
-        strictNaming: true,
-        checkUrlPatterns: true,
-        checkNameConflicts: true,
-        checkCircularDependencies: true,
-        ...options,
-    };
-    // Run all semantic validations
-    errors.push(...validateNamingConventions(doc, opts));
-    errors.push(...validateUrlPatterns(doc, opts));
-    errors.push(...validateNameConflicts(doc, opts));
-    errors.push(...validateCircularDependencies(doc, opts));
-    return {
-        valid: errors.length === 0,
-        errors,
-        warnings,
-    };
-}

package/dist/src/validator/tests-validator.d.ts

@@ -1,9 +0,0 @@
-import type { ValidateOptions } from "./types.js";
-/**
- * Validate a UniSpec Tests document against the UniSpec Tests JSON Schema.
- *
- * @param doc - The UniSpec Tests document to validate
- * @param options - Validation options including custom schemas
- * @returns Validation result with success status and error details
- */
-export declare const validateUniSpecTests: (doc: unknown, options?: ValidateOptions) => Promise<import("../index.js").ValidationResult>;

package/dist/src/validator/tests-validator.js

@@ -1,13 +0,0 @@
-import { getValidator } from "./ajv-validator.js";
-import { createValidator } from "./validator-factory.js";
-/**
- * Validate a UniSpec Tests document against the UniSpec Tests JSON Schema.
- *
- * @param doc - The UniSpec Tests document to validate
- * @param options - Validation options including custom schemas
- * @returns Validation result with success status and error details
- */
-export const validateUniSpecTests = createValidator("unispecTests", async (options) => {
-    const { validateUniSpecTestsFn } = await getValidator(options);
-    return validateUniSpecTestsFn;
-});

package/dist/src/validator/types.d.ts

@@ -1,29 +0,0 @@
-import type { ValidationResult } from "../types/index.js";
-import type { ReferenceValidationOptions, ReferenceValidationResult } from "./reference-validator.js";
-import type { SemanticValidationOptions, SemanticValidationResult } from "./semantic-validator.js";
-export interface SchemaProvider {
-    getSchema: (schemaPath: string) => Promise<object>;
-}
-export interface ValidatorSchemas {
-    unispec: object;
-    unispecTests?: object;
-    unispecConfig?: object;
-    subschemas?: object[];
-}
-export interface ValidateOptions {
-    schemas?: ValidatorSchemas;
-    schemaProvider?: SchemaProvider;
-    ajvOptions?: ConstructorParameters<typeof Ajv2020>[0];
-    semanticValidation?: SemanticValidationOptions;
-    referenceValidation?: ReferenceValidationOptions;
-    enableExtendedValidation?: boolean;
-}
-export interface ExtendedValidationResult extends ValidationResult {
-    semantic?: SemanticValidationResult;
-    references?: ReferenceValidationResult;
-}
-import type Ajv2020 from "ajv/dist/2020.js";
-export type { Ajv2020 };
-export type AjvValidateFn = ((data: unknown) => boolean) & {
-    errors?: import("ajv/dist/2020.js").ErrorObject[] | null | undefined;
-};

package/dist/src/validator/types.js

@@ -1 +0,0 @@
-export {};

package/dist/src/validator/unispec-validator.d.ts

@@ -1,15 +0,0 @@
-import type { UniSpecDocument, ValidationResult } from "../types/index.js";
-import type { ExtendedValidationResult, ValidateOptions } from "./types.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
- */
-export declare function validateUniSpec(doc: UniSpecDocument, options?: ValidateOptions): Promise<ValidationResult | ExtendedValidationResult>;

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

@@ -1,77 +0,0 @@
-import { ErrorFactory } from "../errors/index.js";
-import { getValidator } from "./ajv-validator.js";
-import { validateReferences } from "./reference-validator.js";
-import { validateSemantic } from "./semantic-validator.js";
-import { mapAjvErrors } from "./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
- */
-export 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 = 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 = 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 getValidator(options);
-        // Validate the document as-is to ensure all required fields are present
-        const valid = validateUniSpecFn(doc);
-        const schemaErrors = mapAjvErrors(validateUniSpecFn.errors);
-        if (valid) {
-            return {
-                valid: true,
-                errors: [],
-            };
-        }
-        return {
-            valid: false,
-            errors: schemaErrors,
-        };
-    }
-    catch (error) {
-        const validationError = ErrorFactory.fromError(error, "validation_error");
-        return {
-            valid: false,
-            errors: [validationError.toJSON()],
-        };
-    }
-}

package/dist/src/validator/validator-factory.d.ts

@@ -1,10 +0,0 @@
-import type { ValidationError } from "../types/index.js";
-import type { AjvValidateFn, ValidateOptions } from "./types.js";
-/**
- * Generic validator factory to reduce code duplication.
- */
-export declare function createValidator<T>(documentType: "unispec" | "unispecTests" | "unispecConfig", getValidatorFn: (options: ValidateOptions) => Promise<AjvValidateFn | undefined>, customValidation?: (doc: T) => ValidationError[]): (doc: T, options?: ValidateOptions) => Promise<import("../types/index.js").ValidationResult>;
-/**
- * Map AJV errors to specific UniSpec validation errors.
- */
-export declare function mapAjvErrors(errors: import("ajv/dist/2020.js").ErrorObject[] | null | undefined): ValidationError[];

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

@@ -1,73 +0,0 @@
-import { ErrorFactory } from "../errors/index.js";
-/**
- * Generic validator factory to reduce code duplication.
- */
-export 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 = ErrorFactory.fromError(error, `${documentType}_validation_error`);
-            return {
-                valid: false,
-                errors: [validationError.toJSON()],
-            };
-        }
-    };
-}
-/**
- * Map AJV errors to specific UniSpec validation errors.
- */
-export 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 ErrorFactory.createSchemaError(`Missing required property: ${message}`, path, { keyword: error.keyword, params: error.params });
-            case "type":
-                return ErrorFactory.createSchemaError(`Invalid type: ${message}`, path, { keyword: error.keyword, params: error.params });
-            case "format":
-                return ErrorFactory.createSchemaError(`Invalid format: ${message}`, path, { keyword: error.keyword, params: error.params });
-            case "additionalProperties":
-                return ErrorFactory.createSchemaError(`Additional property not allowed: ${message}`, path, { keyword: error.keyword, params: error.params });
-            default:
-                return ErrorFactory.createSchemaError(message, path, {
-                    keyword: error.keyword,
-                    params: error.params,
-                });
-        }
-    });
-}

package/dist/src/versions.d.ts

@@ -1,10 +0,0 @@
-/**
- * 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)
- */
-export declare function getLatestUniSpecVersion(): string;
-/**
- * Clear the version cache (useful for testing or dynamic updates)
- */
-export declare function clearVersionCache(): void;