@unispechq/unispec-core 0.2.13 → 0.3.0

package/dist/types/index.d.ts

@@ -1,40 +1,108 @@
-export interface UniSpecGraphQLOperation {
+export interface UniSpecNamedItem {
     name: string;
     description?: string;
+}
+export interface UniSpecDeprecatedItem {
     deprecated?: boolean;
     deprecationReason?: string;
 }
-export interface UniSpecGraphQLProtocol {
+export interface UniSpecTaggedItem {
+    tags?: string[];
+}
+export interface UniSpecProtocolBase {
     url?: string;
-    schema?: string;
-    queries?: UniSpecGraphQLOperation[];
-    mutations?: UniSpecGraphQLOperation[];
-    subscriptions?: UniSpecGraphQLOperation[];
+    securitySchemes?: Record<string, UniSpecSecurityScheme>;
 }
 export interface UniSpecSecurityRequirement extends Array<string> {
 }
-export interface UniSpecWebSocketMessage {
+export interface UniSpecBaseHeader {
     name: string;
     description?: string;
+    required?: boolean;
+}
+export interface UniSpecHeader extends UniSpecBaseHeader {
+    defaultValue?: string;
     schemaRef?: string;
 }
-export interface UniSpecWebSocketChannel {
+export interface UniSpecApiKeyScheme {
+    type: "apiKey";
     name: string;
+    in: "header" | "query" | "cookie";
+    description?: string;
+}
+export interface UniSpecHttpScheme {
+    type: "http";
+    scheme: "basic" | "bearer" | "digest";
+    bearerFormat?: string;
     description?: string;
+}
+export interface UniSpecOAuth2Flow {
+    authorizationUrl: string;
+    tokenUrl: string;
+    refreshUrl?: string;
+    scopes: Record<string, string>;
+}
+export interface UniSpecOAuth2Scheme {
+    type: "oauth2";
+    flows: {
+        authorizationCode?: UniSpecOAuth2Flow;
+        clientCredentials?: UniSpecOAuth2Flow;
+        implicit?: UniSpecOAuth2Flow;
+    };
+    description?: string;
+}
+export interface UniSpecJwtScheme {
+    type: "jwt";
+    issuer?: string;
+    audience?: string[];
+    algorithms?: string[];
+    description?: string;
+}
+export type UniSpecSecurityScheme = UniSpecApiKeyScheme | UniSpecHttpScheme | UniSpecOAuth2Scheme | UniSpecJwtScheme;
+export interface UniSpecGraphQLArgument extends UniSpecNamedItem, UniSpecDeprecatedItem {
+    type: string;
+    defaultValue?: unknown;
+}
+export interface UniSpecGraphQLOperation extends UniSpecNamedItem, UniSpecDeprecatedItem, UniSpecTaggedItem {
+    args?: UniSpecGraphQLArgument[];
+    returnType?: string;
+    headers?: UniSpecGraphQLHeader[];
+    security?: UniSpecSecurityRequirement[];
+}
+export interface UniSpecGraphQLHeader extends UniSpecBaseHeader {
+}
+export interface UniSpecGraphQLProtocol extends UniSpecProtocolBase {
+    schema?: string;
+    headers?: UniSpecGraphQLHeader[];
+    queries?: UniSpecGraphQLOperation[];
+    mutations?: UniSpecGraphQLOperation[];
+    subscriptions?: UniSpecGraphQLOperation[];
+}
+export interface UniSpecWebSocketMessage extends UniSpecNamedItem, UniSpecDeprecatedItem {
     direction?: "publish" | "subscribe" | "both";
+    schemaRef?: string;
+}
+export interface UniSpecWebSocketHeader extends UniSpecBaseHeader {
+}
+export interface UniSpecWebSocketReconnectStrategy {
+    maxAttempts?: number;
+    delay?: number;
+    backoffMultiplier?: number;
+}
+export interface UniSpecWebSocketChannel extends UniSpecNamedItem, UniSpecDeprecatedItem, UniSpecTaggedItem {
+    namespace?: string;
+    direction?: "publish" | "subscribe" | "both";
+    connectionParams?: Record<string, string>;
+    reconnectStrategy?: UniSpecWebSocketReconnectStrategy;
+    headers?: UniSpecWebSocketHeader[];
     messages?: UniSpecWebSocketMessage[];
     security?: UniSpecSecurityRequirement[];
-    extensions?: Record<string, unknown>;
 }
-export interface UniSpecWebSocketProtocol {
-    url?: string;
+export interface UniSpecWebSocketProtocol extends UniSpecProtocolBase {
+    headers?: UniSpecWebSocketHeader[];
     channels?: UniSpecWebSocketChannel[];
-    securitySchemes?: Record<string, Record<string, unknown>>;
 }
-export interface UniSpecRestParameter {
-    name: string;
-    description?: string;
-    required?: boolean;
+export interface UniSpecRestParameter extends UniSpecBaseHeader {
     schemaRef?: string;
 }
 export interface UniSpecRestMediaType {
@@ -48,14 +116,15 @@ export interface UniSpecRestRequestBody {
     required?: boolean;
     content?: UniSpecRestContent;
 }
+export interface UniSpecRestResponseHeader extends UniSpecHeader {
+}
 export interface UniSpecRestResponse {
     description?: string;
+    headers?: UniSpecRestResponseHeader[];
     content?: UniSpecRestContent;
 }
-export interface UniSpecRestRoute {
-    name?: string;
+export interface UniSpecRestRoute extends UniSpecNamedItem, UniSpecDeprecatedItem, UniSpecTaggedItem {
     summary?: string;
-    description?: string;
     path: string;
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     pathParams?: UniSpecRestParameter[];
@@ -65,12 +134,23 @@ export interface UniSpecRestRoute {
     responses?: Record<string, UniSpecRestResponse>;
     security?: UniSpecSecurityRequirement[];
 }
-export interface UniSpecRestProtocol {
+export interface UniSpecRestProtocol extends UniSpecProtocolBase {
     routes?: UniSpecRestRoute[];
-    securitySchemes?: Record<string, Record<string, unknown>>;
 }
-export interface UniSpecSchemaDefinition {
+export interface UniSpecSchemaValidation {
+    strict?: boolean;
+    additionalProperties?: boolean;
+    customValidators?: UniSpecCustomValidator[];
+}
+export interface UniSpecCustomValidator {
+    name: string;
+    rule: string;
+    message: string;
+}
+export interface UniSpecSchemaDefinition extends UniSpecNamedItem, UniSpecDeprecatedItem {
+    examples?: unknown[];
     jsonSchema: Record<string, unknown>;
+    validation?: UniSpecSchemaValidation;
 }
 export interface UniSpecSchemas {
     [name: string]: UniSpecSchemaDefinition;
@@ -82,6 +162,30 @@ export interface UniSpecEnvironment {
     labels?: Record<string, string>;
     isDefault?: boolean;
 }
+export interface UniSpecServer {
+    url: string;
+    description?: string;
+}
+export interface UniSpecContact {
+    name?: string;
+    email?: string;
+    url?: string;
+}
+export interface UniSpecLicense {
+    name?: string;
+    url?: string;
+}
+export interface UniSpecRateLimit {
+    requestsPerMinute?: number;
+    requestsPerHour?: number;
+    requestsPerDay?: number;
+    burstLimit?: number;
+    perUser?: boolean;
+    perApiKey?: boolean;
+    customKey?: string;
+}
+export type UniSpecCompliance = "GDPR" | "SOC2" | "HIPAA" | "PCI-DSS" | "ISO27001" | "CCPA";
+export type UniSpecDataClassification = "public" | "internal" | "confidential" | "restricted";
 export interface UniSpecServiceProtocols {
     rest?: UniSpecRestProtocol;
     graphql?: UniSpecGraphQLProtocol;
@@ -90,14 +194,19 @@ export interface UniSpecServiceProtocols {
 export interface UniSpecDocument {
     unispecVersion: string;
     service: UniSpecService;
-    extensions?: Record<string, unknown>;
 }
-export interface UniSpecService {
-    name: string;
-    description?: string;
+export interface UniSpecService extends UniSpecNamedItem, UniSpecTaggedItem {
     version?: string;
+    baseUrl?: string;
+    contact?: UniSpecContact;
+    license?: UniSpecLicense;
+    servers?: UniSpecServer[];
     protocols?: UniSpecServiceProtocols;
     schemas?: UniSpecSchemas;
+    securitySchemes?: Record<string, UniSpecSecurityScheme>;
+    rateLimit?: UniSpecRateLimit;
+    compliance?: UniSpecCompliance[];
+    dataClassification?: UniSpecDataClassification;
 }
 export interface ValidationError {
     message: string;
@@ -108,6 +217,10 @@ export interface ValidationResult {
     valid: boolean;
     errors: ValidationError[];
 }
+export interface UniSpecTestRequestBase {
+    headers?: Record<string, unknown>;
+    authProfile?: string;
+}
 export type UniSpecTestProtocol = "rest" | "graphql" | "websocket";
 export interface UniSpecTestTarget {
     protocol: UniSpecTestProtocol;
@@ -118,16 +231,13 @@ export interface UniSpecRestTestParams {
     path?: Record<string, unknown>;
     query?: Record<string, unknown>;
 }
-export interface UniSpecRestTestRequest {
+export interface UniSpecRestTestRequest extends UniSpecTestRequestBase {
     params?: UniSpecRestTestParams;
-    headers?: Record<string, unknown>;
     body?: unknown;
-    authProfile?: string;
 }
 export type UniSpecRestExpectedStatus = number | number[];
-export type UniSpecRestBodyExpectationMode = "exact" | "contains" | "schemaOnly" | "snapshot";
 export interface UniSpecRestBodyExpectation {
-    mode?: UniSpecRestBodyExpectationMode;
+    mode?: "exact" | "contains" | "schemaOnly" | "snapshot";
     json?: unknown;
     schemaRef?: string;
 }
@@ -136,12 +246,10 @@ export interface UniSpecRestTestExpect {
     headers?: Record<string, unknown>;
     body?: UniSpecRestBodyExpectation;
 }
-export interface UniSpecGraphQLTestRequest {
+export interface UniSpecGraphQLTestRequest extends UniSpecTestRequestBase {
     operationName?: string;
     query: string;
     variables?: Record<string, unknown>;
-    headers?: Record<string, unknown>;
-    authProfile?: string;
 }
 export interface UniSpecGraphQLTestExpect {
     data?: unknown;
@@ -154,11 +262,10 @@ export interface UniSpecWebSocketTestMessageAction {
     messageName: string;
     payload?: unknown;
 }
-export interface UniSpecWebSocketTestRequest {
+export interface UniSpecWebSocketTestRequest extends UniSpecTestRequestBase {
     channel: string;
     direction?: "publish" | "subscribe" | "both";
     messages?: UniSpecWebSocketTestMessageAction[];
-    authProfile?: string;
 }
 export interface UniSpecWebSocketTestExpect {
     messages?: UniSpecWebSocketTestMessageAction[];
@@ -174,14 +281,11 @@ export interface UniSpecTestExpect {
     graphql?: UniSpecGraphQLTestExpect;
     websocket?: UniSpecWebSocketTestExpect;
 }
-export interface UniSpecTestCase {
-    name: string;
-    description?: string;
+export interface UniSpecTestCase extends UniSpecNamedItem {
     target: UniSpecTestTarget;
     request: UniSpecTestRequest;
     expect: UniSpecTestExpect;
     tags?: string[];
-    extensions?: Record<string, unknown>;
 }
 export interface UniSpecTestsDocument {
     uniSpecTestsVersion: string;
@@ -191,5 +295,139 @@ export interface UniSpecTestsDocument {
         environment?: string;
     };
     tests: UniSpecTestCase[];
-    extensions?: Record<string, unknown>;
+    loadTesting?: {
+        concurrentUsers?: number;
+        duration?: string;
+        rampUp?: string;
+        thresholds?: {
+            responseTime?: string;
+            errorRate?: number;
+            throughput?: string;
+        };
+        scenario?: {
+            weight?: Record<string, number>;
+            thinkTime?: string;
+        };
+    };
+}
+export interface UniSpecConfigDocument {
+    version: number;
+    services: UniSpecConfigServiceEntry[];
+    discovery?: UniSpecConfigDiscovery;
+    environments?: UniSpecConfigEnvironment[];
+}
+export interface UniSpecConfigServiceEntry {
+    name: string;
+    baseUrl?: string;
+    spec: UniSpecConfigSpecReference;
+    health?: UniSpecConfigHealth;
+    discovery?: UniSpecConfigDiscovery;
+    headers?: UniSpecConfigHeader[];
+    security?: UniSpecConfigSecurityRequirement[];
+}
+export type UniSpecConfigSpecReference = string | UniSpecConfigHttpSpecReference | UniSpecConfigFileSpecReference | UniSpecConfigRegistrySpecReference;
+export interface UniSpecConfigHttpSpecReference {
+    type: "http";
+    url?: string;
+    path?: string;
+}
+export interface UniSpecConfigFileSpecReference {
+    type: "file";
+    path: string;
+}
+export interface UniSpecConfigRegistrySpecReference {
+    type: "registry";
+    ref: string;
+}
+export interface UniSpecConfigHealth {
+    path: string;
+}
+export interface UniSpecConfigDiscovery {
+    dnsTemplate?: string;
+}
+export interface UniSpecConfigEnvironment {
+    name: string;
+    overrides?: UniSpecConfigEnvironmentOverrides;
+    observability?: UniSpecConfigObservability;
+    deployment?: UniSpecConfigDeployment;
+    dataResidency?: string;
+    audit?: UniSpecConfigAudit;
+}
+export interface UniSpecConfigEnvironmentOverrides {
+    services?: Record<string, UniSpecConfigServiceOverride>;
+}
+export interface UniSpecConfigServiceOverride {
+    baseUrl?: string;
+    spec?: UniSpecConfigSpecReference;
+    health?: UniSpecConfigHealth;
+    discovery?: UniSpecConfigDiscovery;
+    headers?: UniSpecConfigHeader[];
+    security?: UniSpecConfigSecurityRequirement[];
+}
+export interface UniSpecConfigHeader {
+    name: string;
+    description?: string;
+    required?: boolean;
+    defaultValue?: string;
+}
+export type UniSpecConfigSecurityRequirement = string[];
+export interface UniSpecConfigObservability {
+    logging?: {
+        level?: "debug" | "info" | "warn" | "error";
+        format?: "json" | "text";
+        fields?: string[];
+    };
+    metrics?: {
+        enabled?: boolean;
+        endpoints?: string[];
+        customMetrics?: UniSpecConfigCustomMetric[];
+    };
+    tracing?: {
+        enabled?: boolean;
+        samplingRate?: number;
+        exporter?: string;
+    };
+}
+export interface UniSpecConfigCustomMetric {
+    name: string;
+    type: "counter" | "gauge" | "histogram" | "summary";
+    description?: string;
+    labels?: string[];
+}
+export interface UniSpecConfigDeployment {
+    kubernetes?: UniSpecConfigKubernetesConfig;
+    docker?: UniSpecConfigDockerConfig;
+    replicas?: number;
+    resources?: UniSpecConfigResources;
+}
+export interface UniSpecConfigKubernetesConfig {
+    namespace?: string;
+    image?: string;
+    port?: number;
+    serviceType?: "ClusterIP" | "NodePort" | "LoadBalancer";
+    ingress?: {
+        host?: string;
+        path?: string;
+        tls?: boolean;
+    };
+}
+export interface UniSpecConfigDockerConfig {
+    image?: string;
+    port?: number;
+    environment?: Record<string, string>;
+    volumes?: string[];
+}
+export interface UniSpecConfigResources {
+    cpu?: string;
+    memory?: string;
+    storage?: string;
+}
+export interface UniSpecConfigAudit {
+    enabled?: boolean;
+    retention?: string;
+    fields?: string[];
+    export?: {
+        format?: "json" | "csv";
+        destination?: string;
+    };
 }

package/dist/types/index.js

@@ -1,2 +1 @@
-// GraphQL protocol types
 export {};

package/dist/validator/ajv-validator.d.ts

@@ -0,0 +1,15 @@
+import type { AjvValidateFn, ValidateOptions } from "./types.js";
+declare let cached: {
+    validateUniSpecFn: AjvValidateFn;
+    validateUniSpecTestsFn?: AjvValidateFn;
+    validateUniSpecConfigFn?: AjvValidateFn;
+} | null;
+/**
+ * Get compiled AJV validators for different document types.
+ */
+export declare function getValidator(options?: ValidateOptions): Promise<NonNullable<typeof cached>>;
+/**
+ * Clear cached validators (useful for testing or when schemas change).
+ */
+export declare function clearValidatorCache(): void;
+export {};

package/dist/validator/ajv-validator.js

@@ -0,0 +1,75 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import { GENERATED_SCHEMAS } from "../generated-schemas.js";
+let cached = null;
+/**
+ * Load default schemas from generated schemas.
+ */
+async function loadDefaultSchemas() {
+    // Always use generated schemas - they work in all environments
+    return {
+        unispec: GENERATED_SCHEMAS.unispec,
+        unispecTests: GENERATED_SCHEMAS.unispecTests,
+        unispecConfig: GENERATED_SCHEMAS.unispecConfig,
+        subschemas: GENERATED_SCHEMAS.subschemas,
+    };
+}
+/**
+ * Create AJV instance with custom formats and options.
+ */
+function createAjv(options) {
+    const ajv = new Ajv2020({
+        allErrors: true,
+        strict: false, // Disabled to support discriminator keyword in new schema
+        ...(options.ajvOptions ?? {}),
+    });
+    // Add format validators
+    ajv.addFormat("uri", true);
+    ajv.addFormat("email", {
+        type: "string",
+        validate: (data) => {
+            // Basic email validation regex
+            const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+            return typeof data === "string" && emailRegex.test(data);
+        },
+    });
+    return ajv;
+}
+/**
+ * Get compiled AJV validators for different document types.
+ */
+export async function getValidator(options = {}) {
+    if (cached &&
+        !options.schemas &&
+        !options.schemaProvider &&
+        !options.ajvOptions)
+        return cached;
+    const schemas = options.schemas ?? (await loadDefaultSchemas());
+    const ajv = createAjv(options);
+    if (schemas.subschemas?.length) {
+        ajv.addSchema(schemas.subschemas);
+    }
+    const validateUniSpecFn = ajv.compile(schemas.unispec);
+    let validateUniSpecTestsFn;
+    if (schemas.unispecTests) {
+        validateUniSpecTestsFn = ajv.compile(schemas.unispecTests);
+    }
+    let validateUniSpecConfigFn;
+    if (schemas.unispecConfig) {
+        validateUniSpecConfigFn = ajv.compile(schemas.unispecConfig);
+    }
+    const result = {
+        validateUniSpecFn,
+        validateUniSpecTestsFn,
+        validateUniSpecConfigFn,
+    };
+    if (!options.schemas && !options.schemaProvider && !options.ajvOptions) {
+        cached = result;
+    }
+    return result;
+}
+/**
+ * Clear cached validators (useful for testing or when schemas change).
+ */
+export function clearValidatorCache() {
+    cached = null;
+}

package/dist/validator/config-validator-main.d.ts

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

package/dist/validator/config-validator-main.js

@@ -0,0 +1,31 @@
+import { ErrorFactory } from "../errors/index.js";
+import { getValidator } from "./ajv-validator.js";
+import { validateConfigCustomRules } from "./config-validator.js";
+import { createValidator } from "./validator-factory.js";
+/**
+ * Validate a UniSpec Config document against the UniSpec Config JSON Schema.
+ *
+ * @param doc - The UniSpec Config document to validate
+ * @param options - Validation options including custom schemas
+ * @returns Validation result with success status and error details
+ */
+export async function validateUniSpecConfig(doc, options = {}) {
+    // Handle null input
+    if (doc === null || doc === undefined) {
+        const error = ErrorFactory.fromError(new Error("Config validation error: input must be an object"), "validation_error");
+        return {
+            valid: false,
+            errors: [error.toJSON()],
+        };
+    }
+    // Use factory for the rest of validation
+    const factoryValidator = createValidator("unispecConfig", async (options) => {
+        // If custom schemas are provided but unispecConfig is missing, return undefined
+        if (options.schemas && !options.schemas.unispecConfig) {
+            return undefined; // Will trigger schema missing error
+        }
+        const { validateUniSpecConfigFn } = await getValidator(options);
+        return validateUniSpecConfigFn;
+    }, validateConfigCustomRules);
+    return await factoryValidator(doc, options);
+}

package/dist/validator/config-validator.d.ts

@@ -0,0 +1,5 @@
+import type { UniSpecConfigDocument, ValidationError } from "../types/index.js";
+/**
+ * Custom validation for UniSpec Config documents.
+ */
+export declare function validateConfigCustomRules(doc: UniSpecConfigDocument): ValidationError[];

package/dist/validator/config-validator.js

@@ -0,0 +1,14 @@
+import { ErrorFactory } from "../errors/index.js";
+/**
+ * Custom validation for UniSpec Config documents.
+ */
+export function validateConfigCustomRules(doc) {
+    const customErrors = [];
+    // Check for empty services array
+    if (doc.services &&
+        Array.isArray(doc.services) &&
+        doc.services.length === 0) {
+        customErrors.push(ErrorFactory.createConfigError("services array must contain at least one service", "/services", { code: "minItems" }).toJSON());
+    }
+    return customErrors;
+}

package/dist/validator/index.d.ts

@@ -1,23 +1,10 @@
-import Ajv2020 from "ajv/dist/2020.js";
-import { UniSpecDocument, UniSpecTestsDocument, ValidationResult } from "../types";
-export interface SchemaProvider {
-    getSchema: (schemaPath: string) => Promise<object>;
-}
-export interface ValidatorSchemas {
-    unispec: object;
-    unispecTests?: object;
-    subschemas?: object[];
-}
-export interface ValidateOptions {
-    schemas?: ValidatorSchemas;
-    schemaProvider?: SchemaProvider;
-    ajvOptions?: ConstructorParameters<typeof Ajv2020>[0];
-}
-/**
- * Validate a UniSpec document against the UniSpec JSON Schema.
- */
-export declare function validateUniSpec(doc: UniSpecDocument, options?: ValidateOptions): Promise<ValidationResult>;
-/**
- * Validate a UniSpec Tests document against the UniSpec Tests JSON Schema.
- */
-export declare function validateUniSpecTests(doc: UniSpecTestsDocument, options?: ValidateOptions): Promise<ValidationResult>;
+export { clearValidatorCache, getValidator } from "./ajv-validator.js";
+export { validateUniSpecConfig } from "./config-validator-main.js";
+export type { ReferenceValidationOptions, ReferenceValidationResult, } from "./reference-validator.js";
+export { validateReferences } from "./reference-validator.js";
+export type { SemanticValidationOptions, SemanticValidationResult, } from "./semantic-validator.js";
+export { validateSemantic } from "./semantic-validator.js";
+export { validateUniSpecTests } from "./tests-validator.js";
+export type { Ajv2020, AjvValidateFn, ExtendedValidationResult, SchemaProvider, ValidateOptions, ValidatorSchemas, } from "./types.js";
+export { validateUniSpec } from "./unispec-validator.js";
+export { createValidator, mapAjvErrors } from "./validator-factory.js";