@kya-os/mcp-i-core 1.3.13 → 1.3.15

package/src/compliance/schema-verifier.ts

@@ -1,708 +0,0 @@
-/**
- * Schema Compliance Verification Tool
- *
- * Supports JSON Schema draft-07 features:
- * - $ref resolution
- * - oneOf, anyOf, allOf
- * - Nested required fields
- * - Array tuple validation
- * - Format, pattern, enum, const
- * - Recursive object validation
- */
-
-export interface SchemaMetadata {
-  id: string;
-  url: string;
-  version: string;
-  type: string;
-  description?: string;
-}
-
-export interface FieldComplianceResult {
-  fieldPath: string;
-  present: boolean;
-  expectedType: string;
-  actualType?: string;
-  typeMatches: boolean;
-  required: boolean;
-  status: 'pass' | 'fail' | 'warning';
-  reason?: string;
-}
-
-export interface SchemaComplianceReport {
-  schema: SchemaMetadata;
-  compliant: boolean;
-  compliancePercentage: number;
-  fields: FieldComplianceResult[];
-  issues: string[];
-  warnings: string[];
-  timestamp: number;
-}
-
-export interface FullComplianceReport {
-  totalSchemas: number;
-  compliantSchemas: number;
-  overallCompliance: number;
-  schemaReports: SchemaComplianceReport[];
-  criticalIssues: string[];
-  timestamp: number;
-}
-
-/**
- * Schema Verifier with JSON Schema draft-07 support
- */
-export class SchemaVerifier {
-  private schemasBaseUrl = 'https://schemas.kya-os.ai';
-  private schemaCache = new Map<string, any>();
-
-  constructor(options?: { schemasBaseUrl?: string }) {
-    if (options?.schemasBaseUrl) {
-      this.schemasBaseUrl = options.schemasBaseUrl;
-    }
-  }
-
-  /**
-   * Verify a single schema against implementation
-   */
-  async verifySchema(
-    schema: SchemaMetadata,
-    implementation: any
-  ): Promise<SchemaComplianceReport> {
-    const fields: FieldComplianceResult[] = [];
-    const issues: string[] = [];
-    const warnings: string[] = [];
-
-    // Fetch the canonical schema
-    let canonicalSchema: any;
-    try {
-      canonicalSchema = await this.fetchSchema(schema.url);
-    } catch (error) {
-      return {
-        schema,
-        compliant: false,
-        compliancePercentage: 0,
-        fields: [],
-        issues: [
-          `Failed to fetch schema: ${error instanceof Error ? error.message : 'Unknown error'}`,
-        ],
-        warnings: [],
-        timestamp: Date.now(),
-      };
-    }
-
-    // Resolve $ref if present at root
-    const resolvedSchema = this.resolveRef(canonicalSchema, canonicalSchema);
-
-    // Validate the implementation against the schema
-    const validationResult = this.validateAgainstSchema(
-      implementation,
-      resolvedSchema,
-      canonicalSchema,
-      ''
-    );
-
-    fields.push(...validationResult.fields);
-
-    // Separate issues and warnings
-    for (const field of fields) {
-      if (field.status === 'fail') {
-        issues.push(`${field.fieldPath}: ${field.reason}`);
-      } else if (field.status === 'warning') {
-        warnings.push(`${field.fieldPath}: ${field.reason}`);
-      }
-    }
-
-    // Calculate compliance
-    const requiredFields = fields.filter((f) => f.required);
-    const passingRequiredFields = requiredFields.filter(
-      (f) => f.status === 'pass'
-    ).length;
-
-    const compliancePercentage =
-      requiredFields.length > 0
-        ? (passingRequiredFields / requiredFields.length) * 100
-        : 100; // If no required fields, 100% compliant
-
-    const compliant = issues.length === 0 && compliancePercentage >= 95;
-
-    return {
-      schema,
-      compliant,
-      compliancePercentage,
-      fields,
-      issues,
-      warnings,
-      timestamp: Date.now(),
-    };
-  }
-
-  /**
-   * Verify all schemas
-   */
-  async verifyAll(
-    schemas: SchemaMetadata[],
-    implementations: Map<string, any>
-  ): Promise<FullComplianceReport> {
-    const schemaReports: SchemaComplianceReport[] = [];
-    const criticalIssues: string[] = [];
-
-    for (const schema of schemas) {
-      const implementation = implementations.get(schema.id);
-      if (!implementation) {
-        criticalIssues.push(`No implementation found for schema: ${schema.id}`);
-        continue;
-      }
-
-      const report = await this.verifySchema(schema, implementation);
-      schemaReports.push(report);
-
-      if (!report.compliant) {
-        criticalIssues.push(`${schema.id}: ${report.issues.join(', ')}`);
-      }
-    }
-
-    const compliantSchemas = schemaReports.filter((r) => r.compliant).length;
-    const overallCompliance =
-      schemas.length > 0 ? (compliantSchemas / schemas.length) * 100 : 0;
-
-    return {
-      totalSchemas: schemas.length,
-      compliantSchemas,
-      overallCompliance,
-      schemaReports,
-      criticalIssues,
-      timestamp: Date.now(),
-    };
-  }
-
-  /**
-   * Validate implementation against schema recursively
-   */
-  private validateAgainstSchema(
-    value: any,
-    schema: any,
-    rootSchema: any,
-    path: string
-  ): { fields: FieldComplianceResult[] } {
-    const fields: FieldComplianceResult[] = [];
-
-    // Resolve $ref
-    schema = this.resolveRef(schema, rootSchema);
-
-    // Handle oneOf, anyOf, allOf
-    if (schema.oneOf || schema.anyOf || schema.allOf) {
-      return this.validateUnion(value, schema, rootSchema, path);
-    }
-
-    // Handle type: object
-    if (schema.type === 'object' && schema.properties) {
-      const required = schema.required || [];
-
-      for (const [propName, propSchema] of Object.entries<any>(
-        schema.properties
-      )) {
-        const propPath = path ? `${path}.${propName}` : propName;
-        const propValue = value?.[propName];
-        const isRequired = required.includes(propName);
-
-        const fieldResult = this.checkField(
-          propPath,
-          propValue,
-          propSchema,
-          rootSchema,
-          isRequired
-        );
-
-        fields.push(fieldResult);
-
-        // Recurse into nested objects
-        if (propValue !== undefined && propSchema.type === 'object') {
-          const nestedResult = this.validateAgainstSchema(
-            propValue,
-            propSchema,
-            rootSchema,
-            propPath
-          );
-          fields.push(...nestedResult.fields);
-        }
-      }
-    }
-
-    // Handle type: array
-    if (schema.type === 'array' && value && Array.isArray(value)) {
-      const arrayResult = this.validateArray(value, schema, rootSchema, path);
-      fields.push(...arrayResult.fields);
-    }
-
-    return { fields };
-  }
-
-  /**
-   * Validate against oneOf, anyOf, allOf
-   */
-  private validateUnion(
-    value: any,
-    schema: any,
-    rootSchema: any,
-    path: string
-  ): { fields: FieldComplianceResult[] } {
-    const fields: FieldComplianceResult[] = [];
-
-    // For anyOf/oneOf, try to find a matching schema
-    if (schema.anyOf || schema.oneOf) {
-      const options = schema.anyOf || schema.oneOf;
-      let matched = false;
-
-      for (const option of options) {
-        const resolvedOption = this.resolveRef(option, rootSchema);
-
-        // Try to validate against this option
-        try {
-          if (this.matchesSchema(value, resolvedOption, rootSchema)) {
-            // Found a match, validate with this schema
-            const result = this.validateAgainstSchema(
-              value,
-              resolvedOption,
-              rootSchema,
-              path
-            );
-            fields.push(...result.fields);
-            matched = true;
-            break;
-          }
-        } catch (e) {
-          // Doesn't match this option, try next
-          continue;
-        }
-      }
-
-      if (!matched && path) {
-        // Didn't match any option
-        fields.push({
-          fieldPath: path,
-          present: value !== undefined,
-          expectedType: 'oneOf/anyOf options',
-          actualType: typeof value,
-          typeMatches: false,
-          required: true,
-          status: 'fail',
-          reason: 'Value does not match any of the schema options',
-        });
-      }
-    }
-
-    // For allOf, validate against all schemas
-    if (schema.allOf) {
-      for (const subSchema of schema.allOf) {
-        const resolvedSubSchema = this.resolveRef(subSchema, rootSchema);
-        const result = this.validateAgainstSchema(
-          value,
-          resolvedSubSchema,
-          rootSchema,
-          path
-        );
-        fields.push(...result.fields);
-      }
-    }
-
-    return { fields };
-  }
-
-  /**
-   * Check if value matches schema (lightweight check)
-   */
-  private matchesSchema(value: any, schema: any, rootSchema: any): boolean {
-    schema = this.resolveRef(schema, rootSchema);
-
-    // Check type
-    if (schema.type) {
-      const actualType = Array.isArray(value) ? 'array' : typeof value;
-      // JSON Schema "integer" matches JavaScript "number" (if it's an integer)
-      if (schema.type === 'integer' && actualType === 'number') {
-        if (!Number.isInteger(value)) {
-          return false;
-        }
-      } else if (schema.type !== actualType) {
-        return false;
-      }
-    }
-
-    // Check const
-    if (schema.const !== undefined && value !== schema.const) {
-      return false;
-    }
-
-    // Check enum
-    if (schema.enum && !schema.enum.includes(value)) {
-      return false;
-    }
-
-    // Check pattern (for strings)
-    if (schema.pattern && typeof value === 'string') {
-      const regex = new RegExp(schema.pattern);
-      if (!regex.test(value)) {
-        return false;
-      }
-    }
-
-    // Check required properties (for objects)
-    if (schema.type === 'object' && schema.required) {
-      for (const requiredProp of schema.required) {
-        if (!(requiredProp in value)) {
-          return false;
-        }
-      }
-    }
-
-    return true;
-  }
-
-  /**
-   * Validate array against schema
-   */
-  private validateArray(
-    value: any[],
-    schema: any,
-    rootSchema: any,
-    path: string
-  ): { fields: FieldComplianceResult[] } {
-    const fields: FieldComplianceResult[] = [];
-
-    // Check minItems
-    if (schema.minItems !== undefined && value.length < schema.minItems) {
-      fields.push({
-        fieldPath: `${path}.length`,
-        present: true,
-        expectedType: `array with minItems: ${schema.minItems}`,
-        actualType: `array with length: ${value.length}`,
-        typeMatches: false,
-        required: true,
-        status: 'fail',
-        reason: `Array length ${value.length} is less than minItems ${schema.minItems}`,
-      });
-    }
-
-    // Check tuple validation (items as array)
-    if (Array.isArray(schema.items)) {
-      for (let i = 0; i < schema.items.length; i++) {
-        const itemSchema = schema.items[i];
-        const itemValue = value[i];
-        const itemPath = `${path}[${i}]`;
-
-        if (itemValue !== undefined) {
-          const resolvedItemSchema = this.resolveRef(itemSchema, rootSchema);
-          const itemResult = this.validateAgainstSchema(
-            itemValue,
-            resolvedItemSchema,
-            rootSchema,
-            itemPath
-          );
-          fields.push(...itemResult.fields);
-        }
-      }
-
-      // Check additionalItems
-      if (schema.additionalItems !== undefined && value.length > schema.items.length) {
-        for (let i = schema.items.length; i < value.length; i++) {
-          const itemValue = value[i];
-          const itemPath = `${path}[${i}]`;
-          const itemResult = this.validateAgainstSchema(
-            itemValue,
-            schema.additionalItems,
-            rootSchema,
-            itemPath
-          );
-          fields.push(...itemResult.fields);
-        }
-      }
-    } else if (schema.items) {
-      // Single schema for all items
-      for (let i = 0; i < value.length; i++) {
-        const itemValue = value[i];
-        const itemPath = `${path}[${i}]`;
-        const resolvedItemSchema = this.resolveRef(schema.items, rootSchema);
-        const itemResult = this.validateAgainstSchema(
-          itemValue,
-          resolvedItemSchema,
-          rootSchema,
-          itemPath
-        );
-        fields.push(...itemResult.fields);
-      }
-    }
-
-    // Check contains (at least one item must match)
-    if (schema.contains) {
-      const containsSchema = this.resolveRef(schema.contains, rootSchema);
-      const hasMatch = value.some((item) =>
-        this.matchesSchema(item, containsSchema, rootSchema)
-      );
-
-      if (!hasMatch) {
-        fields.push({
-          fieldPath: `${path}.contains`,
-          present: true,
-          expectedType: 'array containing matching item',
-          actualType: 'array without matching item',
-          typeMatches: false,
-          required: true,
-          status: 'fail',
-          reason: 'Array does not contain any item matching the "contains" schema',
-        });
-      }
-    }
-
-    return { fields };
-  }
-
-  /**
-   * Check a single field
-   */
-  private checkField(
-    fieldPath: string,
-    value: any,
-    schema: any,
-    rootSchema: any,
-    required: boolean
-  ): FieldComplianceResult {
-    schema = this.resolveRef(schema, rootSchema);
-
-    const present = value !== undefined;
-    const actualType = this.getActualType(value);
-
-    // Get expected type
-    let expectedType = 'unknown';
-    if (schema.type) {
-      expectedType = schema.type;
-    } else if (schema.anyOf) {
-      expectedType = 'anyOf';
-    } else if (schema.oneOf) {
-      expectedType = 'oneOf';
-    } else if (schema.allOf) {
-      expectedType = 'allOf';
-    }
-
-    // Check if required field is missing
-    if (required && !present) {
-      return {
-        fieldPath,
-        present,
-        expectedType,
-        actualType,
-        typeMatches: false,
-        required,
-        status: 'fail',
-        reason: 'Required field missing',
-      };
-    }
-
-    // Check if optional field is missing
-    if (!required && !present) {
-      return {
-        fieldPath,
-        present,
-        expectedType,
-        actualType,
-        typeMatches: true, // Optional field can be missing
-        required,
-        status: 'pass',
-      };
-    }
-
-    // Value is present, check if it matches schema
-    const typeMatches = this.matchesSchema(value, schema, rootSchema);
-
-    if (!typeMatches) {
-      return {
-        fieldPath,
-        present,
-        expectedType,
-        actualType,
-        typeMatches: false,
-        required,
-        status: 'fail',
-        reason: `Type/value mismatch`,
-      };
-    }
-
-    // All good
-    return {
-      fieldPath,
-      present,
-      expectedType,
-      actualType,
-      typeMatches: true,
-      required,
-      status: 'pass',
-    };
-  }
-
-  /**
-   * Get actual JavaScript type
-   */
-  private getActualType(value: any): string {
-    if (value === null) return 'null';
-    if (Array.isArray(value)) return 'array';
-    if (typeof value === 'number' && Number.isInteger(value)) return 'integer';
-    return typeof value;
-  }
-
-  /**
-   * Resolve $ref reference
-   */
-  private resolveRef(schema: any, rootSchema: any): any {
-    if (!schema.$ref) {
-      return schema;
-    }
-
-    const ref = schema.$ref;
-
-    // Handle #/definitions/Foo
-    if (ref.startsWith('#/definitions/')) {
-      const defName = ref.substring('#/definitions/'.length);
-      if (rootSchema.definitions && rootSchema.definitions[defName]) {
-        return rootSchema.definitions[defName];
-      }
-    }
-
-    // Handle #/$defs/Foo (draft-07+)
-    if (ref.startsWith('#/$defs/')) {
-      const defName = ref.substring('#/$defs/'.length);
-      if (rootSchema.$defs && rootSchema.$defs[defName]) {
-        return rootSchema.$defs[defName];
-      }
-    }
-
-    // Handle # (root)
-    if (ref === '#') {
-      return rootSchema;
-    }
-
-    // If we can't resolve, return original
-    return schema;
-  }
-
-  /**
-   * Fetch a schema from URL
-   */
-  private async fetchSchema(url: string): Promise<any> {
-    // Check cache
-    if (this.schemaCache.has(url)) {
-      return this.schemaCache.get(url);
-    }
-
-    try {
-      const response = await fetch(url);
-
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-      }
-
-      const schema = await response.json();
-      this.schemaCache.set(url, schema);
-      return schema;
-    } catch (error) {
-      if (error instanceof Error) {
-        throw new Error(`Failed to fetch schema from ${url}: ${error.message}`);
-      }
-      throw new Error(`Failed to fetch schema from ${url}: Unknown error`);
-    }
-  }
-
-  /**
-   * Generate a formatted report
-   */
-  generateReport(report: SchemaComplianceReport): string {
-    const lines: string[] = [];
-
-    lines.push(`\n${'='.repeat(80)}`);
-    lines.push(`SCHEMA COMPLIANCE REPORT: ${report.schema.id}`);
-    lines.push(`${'='.repeat(80)}\n`);
-
-    lines.push(`Schema: ${report.schema.type} v${report.schema.version}`);
-    lines.push(`URL: ${report.schema.url}`);
-    lines.push(
-      `Status: ${report.compliant ? '✅ COMPLIANT' : '❌ NON-COMPLIANT'}`
-    );
-    lines.push(`Compliance: ${report.compliancePercentage.toFixed(1)}%\n`);
-
-    if (report.issues.length > 0) {
-      lines.push(`\n🚨 ISSUES (${report.issues.length}):`);
-      report.issues.forEach((issue, i) => {
-        lines.push(`  ${i + 1}. ${issue}`);
-      });
-    }
-
-    if (report.warnings.length > 0) {
-      lines.push(`\n⚠️  WARNINGS (${report.warnings.length}):`);
-      report.warnings.forEach((warning, i) => {
-        lines.push(`  ${i + 1}. ${warning}`);
-      });
-    }
-
-    lines.push(`\n📊 FIELD DETAILS:\n`);
-    const requiredFields = report.fields.filter((f) => f.required);
-    const passing = requiredFields.filter((f) => f.status === 'pass').length;
-    const failing = requiredFields.filter((f) => f.status === 'fail').length;
-    const warnings = report.fields.filter((f) => f.status === 'warning').length;
-
-    lines.push(`  ✅ Pass: ${passing}/${requiredFields.length} required fields`);
-    lines.push(`  ❌ Fail: ${failing}/${requiredFields.length} required fields`);
-    lines.push(`  ⚠️  Warn: ${warnings} optional fields`);
-    lines.push(`  📝 Total: ${report.fields.length} fields checked\n`);
-
-    lines.push(`${'='.repeat(80)}\n`);
-
-    return lines.join('\n');
-  }
-
-  /**
-   * Generate full report
-   */
-  generateFullReport(report: FullComplianceReport): string {
-    const lines: string[] = [];
-
-    lines.push(`\n${'='.repeat(80)}`);
-    lines.push(`FULL SCHEMA COMPLIANCE REPORT`);
-    lines.push(`${'='.repeat(80)}\n`);
-
-    lines.push(`Total Schemas: ${report.totalSchemas}`);
-    lines.push(`Compliant: ${report.compliantSchemas}`);
-    lines.push(
-      `Non-Compliant: ${report.totalSchemas - report.compliantSchemas}`
-    );
-    lines.push(`Overall Compliance: ${report.overallCompliance.toFixed(1)}%\n`);
-
-    if (report.criticalIssues.length > 0) {
-      lines.push(`\n🚨 CRITICAL ISSUES (${report.criticalIssues.length}):`);
-      report.criticalIssues.slice(0, 10).forEach((issue, i) => {
-        lines.push(`  ${i + 1}. ${issue}`);
-      });
-      if (report.criticalIssues.length > 10) {
-        lines.push(
-          `  ... and ${report.criticalIssues.length - 10} more issues`
-        );
-      }
-    }
-
-    lines.push(`\n📊 SCHEMA BREAKDOWN:\n`);
-    report.schemaReports.forEach((schemaReport) => {
-      const icon = schemaReport.compliant ? '✅' : '❌';
-      const percentage = schemaReport.compliancePercentage.toFixed(1);
-      lines.push(`  ${icon} ${schemaReport.schema.id}: ${percentage}%`);
-    });
-
-    lines.push(`\n${'='.repeat(80)}\n`);
-
-    return lines.join('\n');
-  }
-}
-
-/**
- * Create a schema verifier
- */
-export function createSchemaVerifier(options?: {
-  schemasBaseUrl?: string;
-}): SchemaVerifier {
-  return new SchemaVerifier(options);
-}