agentic-qe 3.2.3 → 3.3.0

package/v3/dist/domains/test-generation/coherence-gate.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Agentic QE v3 - Test Generation Coherence Gate
+ * ADR-052: Coherence verification before test generation
+ *
+ * Verifies requirement coherence using Prime Radiant mathematical gates
+ * before allowing test generation to proceed.
+ *
+ * @module domains/test-generation/coherence-gate
+ */
+import { Result } from '../../shared/types/index.js';
+import type { ICoherenceService } from '../../integrations/coherence/coherence-service.js';
+import type { ComputeLane } from '../../integrations/coherence/types.js';
+/**
+ * A requirement for test generation
+ */
+export interface Requirement {
+    /** Unique requirement identifier */
+    id: string;
+    /** Requirement description */
+    description: string;
+    /** Optional priority */
+    priority?: 'high' | 'medium' | 'low';
+    /** Optional source of the requirement */
+    source?: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Test specification containing requirements
+ */
+export interface TestSpecification {
+    /** Specification identifier */
+    id: string;
+    /** Name of the test specification */
+    name: string;
+    /** Requirements to generate tests for */
+    requirements: Requirement[];
+    /** Test type */
+    testType: 'unit' | 'integration' | 'e2e';
+    /** Target framework */
+    framework: string;
+    /** Additional context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Enrichment recommendation from coherence analysis
+ */
+export interface EnrichmentRecommendation {
+    /** Type of enrichment */
+    type: 'clarify' | 'add-context' | 'resolve-ambiguity' | 'split-requirement';
+    /** Target requirement ID */
+    requirementId: string;
+    /** Description of what to do */
+    description: string;
+    /** Optional suggested resolution */
+    suggestedResolution?: string;
+}
+/**
+ * Result of coherence check on requirements
+ */
+export interface RequirementCoherenceResult {
+    /** Whether requirements are coherent */
+    isCoherent: boolean;
+    /** Coherence energy (lower = more coherent) */
+    energy: number;
+    /** Recommended compute lane */
+    lane: ComputeLane;
+    /** Detected contradictions between requirements */
+    contradictions: RequirementContradiction[];
+    /** Recommendations for resolving issues */
+    recommendations: EnrichmentRecommendation[];
+    /** Duration of the check in milliseconds */
+    durationMs: number;
+    /** Whether fallback logic was used */
+    usedFallback: boolean;
+}
+/**
+ * Severity type for requirement contradictions
+ */
+export type ContradictionSeverity = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * A contradiction between requirements
+ */
+export interface RequirementContradiction {
+    /** First requirement ID */
+    requirementId1: string;
+    /** Second requirement ID */
+    requirementId2: string;
+    /** Severity of the contradiction */
+    severity: ContradictionSeverity;
+    /** Description of the contradiction */
+    description: string;
+    /** Confidence that this is a true contradiction */
+    confidence: number;
+    /** Suggested resolution */
+    suggestedResolution?: string;
+}
+/**
+ * Configuration for the coherence gate
+ */
+export interface TestGenerationCoherenceGateConfig {
+    /** Whether coherence checking is enabled */
+    enabled: boolean;
+    /** Coherence threshold for passing (default: 0.1) */
+    coherenceThreshold: number;
+    /** Whether to block on human lane (default: true) */
+    blockOnHumanLane: boolean;
+    /** Whether to enrich spec on retrieval lane (default: true) */
+    enrichOnRetrievalLane: boolean;
+    /** Embedding dimension for requirements (default: 384) */
+    embeddingDimension: number;
+}
+/**
+ * Default configuration
+ */
+export declare const DEFAULT_COHERENCE_GATE_CONFIG: TestGenerationCoherenceGateConfig;
+/**
+ * Error thrown when requirements have unresolvable contradictions
+ */
+export declare class CoherenceError extends Error {
+    readonly contradictions: RequirementContradiction[];
+    readonly lane: ComputeLane;
+    constructor(message: string, contradictions: RequirementContradiction[], lane: ComputeLane);
+}
+/**
+ * Interface for embedding service (dependency injection)
+ */
+export interface IEmbeddingService {
+    /** Generate embedding for text */
+    embed(text: string): Promise<number[]>;
+}
+/**
+ * Test Generation Coherence Gate
+ *
+ * Verifies requirement coherence before allowing test generation.
+ * Per ADR-052, this gate uses Prime Radiant mathematical coherence
+ * checking to detect contradictions and route to appropriate compute lanes.
+ *
+ * @example
+ * ```typescript
+ * const gate = new TestGenerationCoherenceGate(coherenceService);
+ *
+ * const result = await gate.checkRequirementCoherence(spec.requirements);
+ *
+ * if (result.lane === 'human') {
+ *   throw new CoherenceError('Requirements contain unresolvable contradictions', result.contradictions);
+ * }
+ *
+ * if (result.lane === 'retrieval') {
+ *   spec = await gate.enrichSpecification(spec, result.recommendations);
+ * }
+ * ```
+ */
+export declare class TestGenerationCoherenceGate {
+    private readonly coherenceService;
+    private readonly config;
+    private readonly embeddingService;
+    constructor(coherenceService: ICoherenceService | null, embeddingService?: IEmbeddingService, config?: Partial<TestGenerationCoherenceGateConfig>);
+    /**
+     * Check coherence of requirements
+     *
+     * @param requirements - Array of requirements to check
+     * @returns Coherence result with lane recommendation
+     */
+    checkRequirementCoherence(requirements: Requirement[]): Promise<RequirementCoherenceResult>;
+    /**
+     * Enrich a test specification based on coherence recommendations
+     *
+     * @param spec - Original test specification
+     * @param recommendations - Recommendations from coherence check
+     * @returns Enriched specification
+     */
+    enrichSpecification(spec: TestSpecification, recommendations: EnrichmentRecommendation[]): Promise<TestSpecification>;
+    /**
+     * Validate requirements before test generation
+     *
+     * Convenience method that combines coherence check with automatic
+     * enrichment and error handling per ADR-052 specification.
+     *
+     * @param spec - Test specification to validate
+     * @returns Validated (and possibly enriched) specification
+     * @throws CoherenceError if requirements have unresolvable contradictions
+     */
+    validateAndEnrich(spec: TestSpecification): Promise<Result<TestSpecification, CoherenceError>>;
+    /**
+     * Check if the gate is available (coherence service is initialized)
+     */
+    isAvailable(): boolean;
+    /**
+     * Convert requirements to coherence nodes
+     */
+    private requirementsToNodes;
+    /**
+     * Transform coherence result to requirement-specific format
+     */
+    private transformCoherenceResult;
+    /**
+     * Generate enrichment recommendations based on coherence result
+     */
+    private generateRecommendations;
+    /**
+     * Generate a resolution suggestion for a contradiction
+     */
+    private generateResolutionSuggestion;
+    /**
+     * Create a passing coherence result
+     */
+    private createPassingResult;
+    /**
+     * Convert priority to weight
+     */
+    private priorityToWeight;
+    /**
+     * Map Severity type to ContradictionSeverity
+     * Coherence Severity includes 'info' which we map to 'low'
+     */
+    private mapSeverity;
+    /**
+     * Add clarification note to requirement updates
+     */
+    private addClarificationNote;
+    /**
+     * Add disambiguation note to requirement updates
+     */
+    private addDisambiguationNote;
+}
+/**
+ * Create a TestGenerationCoherenceGate
+ *
+ * @param coherenceService - Optional coherence service (can be null for disabled mode)
+ * @param embeddingService - Optional embedding service
+ * @param config - Optional configuration
+ * @returns Configured coherence gate
+ *
+ * @example
+ * ```typescript
+ * // With coherence service
+ * const gate = createTestGenerationCoherenceGate(coherenceService);
+ *
+ * // Disabled mode (no blocking)
+ * const disabledGate = createTestGenerationCoherenceGate(null, null, { enabled: false });
+ * ```
+ */
+export declare function createTestGenerationCoherenceGate(coherenceService: ICoherenceService | null, embeddingService?: IEmbeddingService, config?: Partial<TestGenerationCoherenceGateConfig>): TestGenerationCoherenceGate;
+//# sourceMappingURL=coherence-gate.d.ts.map

package/v3/dist/domains/test-generation/coherence-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coherence-gate.d.ts","sourceRoot":"","sources":["../../../src/domains/test-generation/coherence-gate.ts"],"names":[],"mappings":"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"}