agentic-qe
Version:
Agentic Quality Engineering Fleet System - AI-driven quality management platform
222 lines • 6.21 kB
TypeScript
/**
* ApiContractValidatorAgent - P1 agent for API contract validation
* Prevents breaking changes and ensures backward compatibility
*
* Key Capabilities:
* - OpenAPI 3.0 / Swagger validation
* - GraphQL schema validation
* - Breaking change detection
* - Consumer impact analysis
* - Semantic versioning compliance
* - Contract diffing and migration guides
*
* Memory Keys: aqe/api-contract/*
* Events: api.contract.validated, api.breaking.change.detected
* ROI: 350% (prevents 15-20% of production incidents)
*/
import { BaseAgent, BaseAgentConfig } from './BaseAgent';
import { QETask, ApiContractValidatorConfig } from '../types';
interface ValidationResult {
valid: boolean;
errors: ValidationError[];
warnings?: ValidationWarning[];
}
interface ValidationError {
type: string;
message: string;
path?: string;
param?: string;
field?: string;
status?: number;
severity?: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
params?: any;
}
interface ValidationWarning {
type: string;
message: string;
}
interface BreakingChange {
type: string;
severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
message: string;
endpoint?: string;
method?: string;
param?: string;
field?: string;
status?: number;
oldType?: string;
newType?: string;
location?: string;
}
interface NonBreakingChange {
type: string;
message: string;
endpoint?: string;
param?: string;
field?: string;
status?: number;
location?: string;
}
interface ChangeDetectionResult {
breaking: BreakingChange[];
nonBreaking: NonBreakingChange[];
hasBreakingChanges: boolean;
summary: ChangeSummary;
}
interface ChangeSummary {
totalBreaking: number;
totalNonBreaking: number;
recommendation: string;
suggestedVersion?: string;
estimatedMigrationTime?: string;
affectedConsumers?: number;
}
interface VersionValidationResult {
valid: boolean;
currentVersion: string;
proposedVersion: string;
requiredBump: 'MAJOR' | 'MINOR' | 'PATCH';
actualBump: 'MAJOR' | 'MINOR' | 'PATCH';
recommendation: string;
violations: VersionViolation[];
}
interface VersionViolation {
severity: 'CRITICAL' | 'HIGH' | 'MEDIUM';
message: string;
expected: string;
actual: string;
}
interface ConsumerImpactAnalysis {
totalAffectedConsumers: number;
impacts: ConsumerImpact[];
coordinationRequired: boolean;
estimatedTotalMigrationTime: string;
}
interface ConsumerImpact {
consumer: string;
team: string;
contact: string;
affectedEndpoints: AffectedEndpoint[];
totalRequests: number;
estimatedMigrationTime: string;
priority: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
}
interface AffectedEndpoint {
endpoint: string;
method: string;
requestsPerDay: number;
changes: BreakingChange[];
migrationEffort: 'HIGH' | 'MEDIUM' | 'LOW';
}
interface Consumer {
name: string;
team: string;
contact: string;
apiUsage: ApiUsage[];
}
interface ApiUsage {
endpoint: string;
method: string;
requestsPerDay: number;
}
export interface ApiContractValidatorAgentConfig extends BaseAgentConfig {
validatorConfig: ApiContractValidatorConfig;
}
export declare class ApiContractValidatorAgent extends BaseAgent {
private readonly config;
private ajv;
constructor(config: ApiContractValidatorAgentConfig);
protected initializeComponents(): Promise<void>;
protected loadKnowledge(): Promise<void>;
protected cleanup(): Promise<void>;
protected performTask(task: QETask): Promise<any>;
/**
* Validate an API contract (OpenAPI, GraphQL, etc.)
*/
validateContract(params: {
schema: any;
format: 'openapi' | 'swagger' | 'graphql';
}): Promise<ValidationResult>;
/**
* Detect breaking changes between two schema versions
*/
detectBreakingChanges(params: {
baseline: any;
candidate: any;
format?: 'openapi' | 'graphql';
}): Promise<ChangeDetectionResult>;
/**
* Validate request/response against schema
*/
validateRequestResponse(params: {
request: any;
response: any;
schema: any;
endpoint: string;
method: string;
}): Promise<ValidationResult>;
/**
* Validate semantic version bump
*/
validateVersionBump(params: {
currentVersion: string;
proposedVersion: string;
changes: ChangeDetectionResult | {
breaking: any[];
nonBreaking: any[];
};
}): Promise<VersionValidationResult>;
/**
* Analyze consumer impact of API changes
*/
analyzeConsumerImpact(params: {
changes: {
breaking: BreakingChange[];
nonBreaking: NonBreakingChange[];
};
consumers: Consumer[];
}): Promise<ConsumerImpactAnalysis>;
/**
* Generate contract diff report
*/
generateDiff(params: {
baseline: any;
candidate: any;
format?: 'markdown' | 'json' | 'html';
}): Promise<string>;
/**
* Generate migration guide
*/
generateMigrationGuide(params: {
fromVersion: string;
toVersion: string;
changes: {
breaking: BreakingChange[];
nonBreaking: NonBreakingChange[];
};
}): Promise<string>;
private validateOpenAPISchema;
private validateGraphQLSchema;
private validateRequest;
private validateResponse;
private validateAgainstJSONSchema;
private detectOpenAPIBreakingChanges;
private detectGraphQLBreakingChanges;
private compareParameters;
private compareResponses;
private compareResponseSchemas;
private parseVersion;
private getActualBump;
private calculateRequiredVersionBump;
private generateSummary;
private generateMarkdownDiff;
private normalizeEndpoint;
private estimateMigrationEffort;
private calculateMigrationTime;
private calculatePriority;
private priorityScore;
private sumMigrationTimes;
private calculateMaxSeverity;
}
export {};
//# sourceMappingURL=ApiContractValidatorAgent.d.ts.map