@bryan-thompson/inspector-assessment-client 1.28.0 → 1.29.0

package/lib/services/assessment/modules/ToolAnnotationAssessor.js

@@ -15,11 +15,25 @@
  * - BehaviorInference: Infers expected behavior from tool names
  * - AnnotationDeceptionDetector: Detects keyword-based misalignments
  * - DescriptionPoisoningDetector: Detects malicious content in descriptions
+ *
+ * Refactored in Issue #105 to delegate to extracted helper modules:
+ * - AlignmentChecker: Tool alignment assessment and metrics
+ * - ExplanationGenerator: Explanation and recommendation generation
+ * - EventEmitter: Progress event emission
+ * - ClaudeIntegration: Claude-enhanced behavior inference
  */
 import { BaseAssessor } from "./BaseAssessor.js";
 import { getDefaultCompiledPatterns, detectPersistenceModel, } from "../config/annotationPatterns.js";
-// Import from extracted modules
-import { scanDescriptionForPoisoning, detectAnnotationDeception, isActionableConfidence, inferBehavior, detectArchitecture, } from "./annotations/index.js";
+// Import from extracted modules (Issue #105)
+import { detectArchitecture, 
+// Alignment checking
+assessSingleTool, determineAnnotationStatus, calculateMetrics, 
+// Explanation generation
+generateExplanation, generateEnhancedExplanation, generateRecommendations, generateEnhancedRecommendations, 
+// Event emission
+emitAnnotationEvents, 
+// Claude integration
+enhanceWithClaudeInference, createPatternBasedInference, } from "./annotations/index.js";
 export class ToolAnnotationAssessor extends BaseAssessor {
     claudeBridge;
     compiledPatterns;
@@ -112,10 +126,11 @@ export class ToolAnnotationAssessor extends BaseAssessor {
         }
         for (const tool of context.tools) {
             this.testCount++;
-            const result = this.assessTool(tool);
+            // Use extracted assessSingleTool function
+            const result = assessSingleTool(tool, this.compiledPatterns, this.persistenceContext);
             // Enhance with Claude inference if available
             if (useClaudeInference) {
-                const enhancedResult = await this.enhanceWithClaudeInference(tool, result);
+                const enhancedResult = await enhanceWithClaudeInference(tool, result, this.claudeBridge, this.logger);
                 toolResults.push(enhancedResult);
                 if (enhancedResult.claudeInference &&
                     enhancedResult.claudeInference.confidence >= 70 &&
@@ -127,26 +142,9 @@ export class ToolAnnotationAssessor extends BaseAssessor {
                 }
             }
             else {
-                const inferredBehavior = result.inferredBehavior ?? {
-                    expectedReadOnly: false,
-                    expectedDestructive: false,
-                    reason: "No behavior inference available",
-                };
-                toolResults.push({
-                    ...result,
-                    claudeInference: {
-                        expectedReadOnly: inferredBehavior.expectedReadOnly,
-                        expectedDestructive: inferredBehavior.expectedDestructive,
-                        confidence: 50,
-                        reasoning: inferredBehavior.reason,
-                        suggestedAnnotations: {
-                            readOnlyHint: inferredBehavior.expectedReadOnly,
-                            destructiveHint: inferredBehavior.expectedDestructive,
-                        },
-                        misalignmentDetected: result.issues.some((i) => i.includes("misaligned")),
-                        source: "pattern-based",
-                    },
-                });
+                // Use pattern-based inference fallback
+                const enhancedResult = createPatternBasedInference(result);
+                toolResults.push(enhancedResult);
                 if (result.issues.some((i) => i.includes("misaligned"))) {
                     misalignedAnnotationsCount++;
                 }
@@ -222,13 +220,14 @@ export class ToolAnnotationAssessor extends BaseAssessor {
                     });
                 }
             }
-            // Emit annotation events
-            this.emitAnnotationEvents(context, tool, latestResult);
-        }
-        const status = this.determineAnnotationStatus(toolResults, context.tools.length);
-        const explanation = this.generateExplanation(annotatedCount, missingAnnotationsCount, misalignedAnnotationsCount, context.tools.length);
-        const recommendations = this.generateRecommendations(toolResults);
-        const { metrics, alignmentBreakdown } = this.calculateMetrics(toolResults, context.tools.length);
+            // Emit annotation events using extracted function
+            emitAnnotationEvents(context.onProgress, tool, latestResult);
+        }
+        // Use extracted functions for status, explanation, and recommendations
+        const status = determineAnnotationStatus(toolResults, context.tools.length);
+        const explanation = generateExplanation(annotatedCount, missingAnnotationsCount, misalignedAnnotationsCount, context.tools.length);
+        const recommendations = generateRecommendations(toolResults);
+        const { metrics, alignmentBreakdown } = calculateMetrics(toolResults, context.tools.length);
         this.logger.info(`Assessment complete: ${annotatedCount}/${context.tools.length} tools annotated, ${misalignedAnnotationsCount} misaligned, ${alignmentBreakdown.reviewRecommended} need review, ${poisonedDescriptionsCount} poisoned`);
         if (useClaudeInference) {
             const highConfidenceMisalignments = toolResults.filter((r) => r.claudeInference &&
@@ -240,8 +239,8 @@ export class ToolAnnotationAssessor extends BaseAssessor {
                 missingAnnotationsCount,
                 misalignedAnnotationsCount,
                 status,
-                explanation: this.generateEnhancedExplanation(annotatedCount, missingAnnotationsCount, highConfidenceMisalignments.length, context.tools.length),
-                recommendations: this.generateEnhancedRecommendations(toolResults),
+                explanation: generateEnhancedExplanation(annotatedCount, missingAnnotationsCount, highConfidenceMisalignments.length, context.tools.length),
+                recommendations: generateEnhancedRecommendations(toolResults),
                 metrics,
                 alignmentBreakdown,
                 annotationSources: annotationSourceCounts,
@@ -288,596 +287,4 @@ export class ToolAnnotationAssessor extends BaseAssessor {
             },
         };
     }
-    /**
-     * Emit annotation-related progress events
-     */
-    emitAnnotationEvents(context, tool, result) {
-        if (!context.onProgress || !result.inferredBehavior)
-            return;
-        const annotations = result.annotations;
-        const inferred = result.inferredBehavior;
-        const confidence = result.claudeInference?.confidence ?? 50;
-        const toolParams = this.extractToolParams(tool.inputSchema);
-        const toolAnnotations = this.extractAnnotations(tool);
-        // Emit missing annotation event
-        if (!result.hasAnnotations) {
-            context.onProgress({
-                type: "annotation_missing",
-                tool: tool.name,
-                title: toolAnnotations.title,
-                description: tool.description,
-                parameters: toolParams,
-                inferredBehavior: {
-                    expectedReadOnly: inferred.expectedReadOnly,
-                    expectedDestructive: inferred.expectedDestructive,
-                    reason: inferred.reason,
-                },
-            });
-            return;
-        }
-        // Emit aligned event
-        if (result.alignmentStatus === "ALIGNED") {
-            context.onProgress({
-                type: "annotation_aligned",
-                tool: tool.name,
-                confidence: inferred.confidence ?? "medium",
-                annotations: {
-                    readOnlyHint: annotations?.readOnlyHint,
-                    destructiveHint: annotations?.destructiveHint,
-                    openWorldHint: annotations?.openWorldHint,
-                    idempotentHint: annotations?.idempotentHint,
-                },
-            });
-            return;
-        }
-        // Check readOnlyHint mismatch
-        if (annotations?.readOnlyHint !== undefined &&
-            annotations.readOnlyHint !== inferred.expectedReadOnly) {
-            this.emitMismatchEvent(context, tool, toolParams, toolAnnotations, "readOnlyHint", annotations.readOnlyHint, inferred.expectedReadOnly, confidence, inferred, result.alignmentStatus);
-        }
-        // Check destructiveHint mismatch
-        if (annotations?.destructiveHint !== undefined &&
-            annotations.destructiveHint !== inferred.expectedDestructive) {
-            this.emitMismatchEvent(context, tool, toolParams, toolAnnotations, "destructiveHint", annotations.destructiveHint, inferred.expectedDestructive, confidence, inferred, result.alignmentStatus);
-        }
-    }
-    /**
-     * Emit mismatch event (misaligned or review_recommended)
-     */
-    emitMismatchEvent(context, tool, toolParams, toolAnnotations, field, actual, expected, confidence, inferred, alignmentStatus) {
-        if (!context.onProgress)
-            return;
-        if (alignmentStatus === "REVIEW_RECOMMENDED") {
-            context.onProgress({
-                type: "annotation_review_recommended",
-                tool: tool.name,
-                title: toolAnnotations.title,
-                description: tool.description,
-                parameters: toolParams,
-                field,
-                actual,
-                inferred: expected,
-                confidence: inferred.confidence,
-                isAmbiguous: inferred.isAmbiguous,
-                reason: inferred.reason,
-            });
-        }
-        else if (!inferred.isAmbiguous &&
-            isActionableConfidence(inferred.confidence)) {
-            context.onProgress({
-                type: "annotation_misaligned",
-                tool: tool.name,
-                title: toolAnnotations.title,
-                description: tool.description,
-                parameters: toolParams,
-                field,
-                actual,
-                expected,
-                confidence,
-                reason: `Tool has ${field}=${actual}, but ${inferred.reason}`,
-            });
-        }
-    }
-    /**
-     * Enhance tool assessment with Claude inference
-     */
-    async enhanceWithClaudeInference(tool, baseResult) {
-        const inferredBehavior = baseResult.inferredBehavior ?? {
-            expectedReadOnly: false,
-            expectedDestructive: false,
-            reason: "No behavior inference available",
-        };
-        if (!this.claudeBridge) {
-            return {
-                ...baseResult,
-                claudeInference: {
-                    expectedReadOnly: inferredBehavior.expectedReadOnly,
-                    expectedDestructive: inferredBehavior.expectedDestructive,
-                    confidence: 50,
-                    reasoning: inferredBehavior.reason,
-                    suggestedAnnotations: {
-                        readOnlyHint: inferredBehavior.expectedReadOnly,
-                        destructiveHint: inferredBehavior.expectedDestructive,
-                    },
-                    misalignmentDetected: baseResult.issues.some((i) => i.includes("misaligned")),
-                    source: "pattern-based",
-                },
-            };
-        }
-        try {
-            const currentAnnotations = baseResult.annotations
-                ? {
-                    readOnlyHint: baseResult.annotations.readOnlyHint,
-                    destructiveHint: baseResult.annotations.destructiveHint,
-                }
-                : undefined;
-            const inference = await this.claudeBridge.inferToolBehavior(tool, currentAnnotations);
-            if (!inference) {
-                return {
-                    ...baseResult,
-                    claudeInference: {
-                        expectedReadOnly: inferredBehavior.expectedReadOnly,
-                        expectedDestructive: inferredBehavior.expectedDestructive,
-                        confidence: 0,
-                        reasoning: "Claude inference unavailable. Using pattern-based analysis.",
-                        suggestedAnnotations: {},
-                        misalignmentDetected: false,
-                        source: "pattern-based",
-                    },
-                };
-            }
-            const updatedIssues = [...baseResult.issues];
-            const updatedRecommendations = [...baseResult.recommendations];
-            if (inference.misalignmentDetected && inference.confidence >= 70) {
-                const misalignmentMsg = inference.misalignmentDetails
-                    ? `Claude analysis (${inference.confidence}% confidence): ${inference.misalignmentDetails}`
-                    : `Claude analysis detected annotation misalignment with ${inference.confidence}% confidence`;
-                if (!updatedIssues.some((i) => i.includes("Claude analysis"))) {
-                    updatedIssues.push(misalignmentMsg);
-                }
-                if (inference.suggestedAnnotations) {
-                    const { readOnlyHint, destructiveHint, idempotentHint } = inference.suggestedAnnotations;
-                    if (readOnlyHint !== undefined &&
-                        readOnlyHint !== baseResult.annotations?.readOnlyHint) {
-                        updatedRecommendations.push(`Claude suggests: Set readOnlyHint=${readOnlyHint} for ${tool.name}`);
-                    }
-                    if (destructiveHint !== undefined &&
-                        destructiveHint !== baseResult.annotations?.destructiveHint) {
-                        updatedRecommendations.push(`Claude suggests: Set destructiveHint=${destructiveHint} for ${tool.name}`);
-                    }
-                    if (idempotentHint !== undefined) {
-                        updatedRecommendations.push(`Claude suggests: Consider adding idempotentHint=${idempotentHint} for ${tool.name}`);
-                    }
-                }
-            }
-            return {
-                ...baseResult,
-                issues: updatedIssues,
-                recommendations: updatedRecommendations,
-                claudeInference: {
-                    expectedReadOnly: inference.expectedReadOnly,
-                    expectedDestructive: inference.expectedDestructive,
-                    confidence: inference.confidence,
-                    reasoning: inference.reasoning,
-                    suggestedAnnotations: inference.suggestedAnnotations,
-                    misalignmentDetected: inference.misalignmentDetected,
-                    misalignmentDetails: inference.misalignmentDetails,
-                    source: "claude-inferred",
-                },
-            };
-        }
-        catch (error) {
-            this.logger.error(`Claude inference failed for ${tool.name}`, { error });
-            return {
-                ...baseResult,
-                claudeInference: {
-                    expectedReadOnly: inferredBehavior.expectedReadOnly,
-                    expectedDestructive: inferredBehavior.expectedDestructive,
-                    confidence: 50,
-                    reasoning: `Claude inference failed, using pattern-based: ${inferredBehavior.reason}`,
-                    suggestedAnnotations: {
-                        readOnlyHint: inferredBehavior.expectedReadOnly,
-                        destructiveHint: inferredBehavior.expectedDestructive,
-                    },
-                    misalignmentDetected: baseResult.issues.some((i) => i.includes("misaligned")),
-                    source: "pattern-based",
-                },
-            };
-        }
-    }
-    /**
-     * Assess a single tool's annotations
-     */
-    assessTool(tool) {
-        const issues = [];
-        const recommendations = [];
-        const annotations = this.extractAnnotations(tool);
-        const hasAnnotations = annotations.readOnlyHint !== undefined ||
-            annotations.destructiveHint !== undefined;
-        const inferredBehavior = inferBehavior(tool.name, tool.description, this.compiledPatterns, this.persistenceContext);
-        let alignmentStatus = "ALIGNED";
-        if (!hasAnnotations) {
-            issues.push("Missing tool annotations (readOnlyHint, destructiveHint)");
-            recommendations.push(`Add annotations to ${tool.name}: readOnlyHint=${inferredBehavior.expectedReadOnly}, destructiveHint=${inferredBehavior.expectedDestructive}`);
-            alignmentStatus = "UNKNOWN";
-        }
-        else {
-            // Check for high-confidence deception
-            const deception = detectAnnotationDeception(tool.name, {
-                readOnlyHint: annotations.readOnlyHint,
-                destructiveHint: annotations.destructiveHint,
-            });
-            if (deception) {
-                alignmentStatus = "MISALIGNED";
-                issues.push(`DECEPTIVE ANNOTATION: ${deception.reason}`);
-                recommendations.push(`CRITICAL: Fix deceptive ${deception.field} for ${tool.name} - tool name contains '${deception.matchedKeyword}' which contradicts the annotation`);
-                if (deception.field === "readOnlyHint") {
-                    inferredBehavior.expectedReadOnly = false;
-                    inferredBehavior.confidence = "high";
-                    inferredBehavior.isAmbiguous = false;
-                    inferredBehavior.reason = deception.reason;
-                }
-                else {
-                    inferredBehavior.expectedDestructive = true;
-                    inferredBehavior.confidence = "high";
-                    inferredBehavior.isAmbiguous = false;
-                    inferredBehavior.reason = deception.reason;
-                }
-            }
-            else {
-                // Check for misaligned annotations
-                const readOnlyMismatch = annotations.readOnlyHint !== undefined &&
-                    annotations.readOnlyHint !== inferredBehavior.expectedReadOnly;
-                const destructiveMismatch = annotations.destructiveHint !== undefined &&
-                    annotations.destructiveHint !== inferredBehavior.expectedDestructive;
-                if (readOnlyMismatch || destructiveMismatch) {
-                    if (!inferredBehavior.isAmbiguous &&
-                        isActionableConfidence(inferredBehavior.confidence)) {
-                        alignmentStatus = "MISALIGNED";
-                        if (readOnlyMismatch) {
-                            issues.push(`Potentially misaligned readOnlyHint: set to ${annotations.readOnlyHint}, expected ${inferredBehavior.expectedReadOnly} based on tool name pattern`);
-                            recommendations.push(`Verify readOnlyHint for ${tool.name}: currently ${annotations.readOnlyHint}, tool name suggests ${inferredBehavior.expectedReadOnly}`);
-                        }
-                        if (destructiveMismatch) {
-                            issues.push(`Potentially misaligned destructiveHint: set to ${annotations.destructiveHint}, expected ${inferredBehavior.expectedDestructive} based on tool name pattern`);
-                            recommendations.push(`Verify destructiveHint for ${tool.name}: currently ${annotations.destructiveHint}, tool name suggests ${inferredBehavior.expectedDestructive}`);
-                        }
-                    }
-                }
-            }
-        }
-        // Check for destructive tools without explicit hint
-        if (inferredBehavior.expectedDestructive &&
-            isActionableConfidence(inferredBehavior.confidence) &&
-            annotations.destructiveHint !== true) {
-            issues.push("Tool appears destructive but destructiveHint is not set to true");
-            recommendations.push(`Set destructiveHint=true for ${tool.name} - this tool appears to perform destructive operations`);
-            if (inferredBehavior.confidence === "high") {
-                alignmentStatus = "MISALIGNED";
-            }
-        }
-        // Scan for description poisoning
-        const descriptionPoisoning = scanDescriptionForPoisoning(tool);
-        if (descriptionPoisoning.detected) {
-            issues.push(`Tool description contains suspicious patterns: ${descriptionPoisoning.patterns.map((p) => p.name).join(", ")}`);
-            recommendations.push(`Review ${tool.name} description for potential prompt injection or hidden instructions`);
-        }
-        // Extract extended metadata (Issue #54)
-        const extendedMetadata = this.extractExtendedMetadata(tool);
-        return {
-            toolName: tool.name,
-            hasAnnotations,
-            annotations: hasAnnotations ? annotations : undefined,
-            annotationSource: annotations.source,
-            inferredBehavior,
-            alignmentStatus,
-            issues,
-            recommendations,
-            descriptionPoisoning,
-            extendedMetadata,
-        };
-    }
-    /**
-     * Extract annotations from a tool
-     */
-    extractAnnotations(tool) {
-        const toolAny = tool;
-        // Priority 1: Check annotations object (MCP 2024-11 spec)
-        if (toolAny.annotations) {
-            const hasAnnotations = toolAny.annotations.readOnlyHint !== undefined ||
-                toolAny.annotations.destructiveHint !== undefined;
-            if (hasAnnotations) {
-                return {
-                    readOnlyHint: toolAny.annotations.readOnlyHint,
-                    destructiveHint: toolAny.annotations.destructiveHint,
-                    title: toolAny.annotations.title || toolAny.title,
-                    description: tool.description,
-                    idempotentHint: toolAny.annotations.idempotentHint,
-                    openWorldHint: toolAny.annotations.openWorldHint,
-                    source: "mcp",
-                };
-            }
-        }
-        // Priority 2: Check direct properties
-        if (toolAny.readOnlyHint !== undefined ||
-            toolAny.destructiveHint !== undefined) {
-            return {
-                readOnlyHint: toolAny.readOnlyHint,
-                destructiveHint: toolAny.destructiveHint,
-                title: toolAny.title,
-                description: tool.description,
-                idempotentHint: toolAny.idempotentHint,
-                openWorldHint: toolAny.openWorldHint,
-                source: "mcp",
-            };
-        }
-        // Priority 3: Check metadata
-        if (toolAny.metadata) {
-            const hasMetadataAnnotations = toolAny.metadata.readOnlyHint !== undefined ||
-                toolAny.metadata.destructiveHint !== undefined;
-            if (hasMetadataAnnotations) {
-                return {
-                    readOnlyHint: toolAny.metadata.readOnlyHint,
-                    destructiveHint: toolAny.metadata.destructiveHint,
-                    title: toolAny.metadata.title || toolAny.title,
-                    description: tool.description,
-                    idempotentHint: toolAny.metadata.idempotentHint,
-                    openWorldHint: toolAny.metadata.openWorldHint,
-                    source: "mcp",
-                };
-            }
-        }
-        return {
-            title: toolAny.title,
-            description: tool.description,
-            source: "none",
-        };
-    }
-    /**
-     * Extract extended metadata from tool (Issue #54)
-     * Extracts rate limits, permissions, return schemas, and bulk operation support
-     */
-    extractExtendedMetadata(tool) {
-        const toolAny = tool;
-        const metadata = {};
-        // Rate limiting - check annotations, metadata, and direct props
-        const rateLimit = toolAny.rateLimit ||
-            toolAny.annotations?.rateLimit ||
-            toolAny.metadata?.rateLimit;
-        if (rateLimit && typeof rateLimit === "object") {
-            metadata.rateLimit = {
-                windowMs: rateLimit.windowMs,
-                maxRequests: rateLimit.maxRequests,
-                requestsPerMinute: rateLimit.requestsPerMinute,
-                requestsPerSecond: rateLimit.requestsPerSecond,
-            };
-        }
-        // Permissions - check requiredPermission, permissions, scopes
-        const permissions = toolAny.requiredPermission ||
-            toolAny.permissions ||
-            toolAny.annotations?.permissions ||
-            toolAny.metadata?.requiredPermission ||
-            toolAny.metadata?.permissions;
-        if (permissions) {
-            const required = Array.isArray(permissions) ? permissions : [permissions];
-            const scopes = toolAny.scopes ||
-                toolAny.annotations?.scopes ||
-                toolAny.metadata?.scopes;
-            metadata.permissions = {
-                required: required.filter((p) => typeof p === "string"),
-                scopes: Array.isArray(scopes)
-                    ? scopes.filter((s) => typeof s === "string")
-                    : undefined,
-            };
-        }
-        // Return schema - check outputSchema (MCP 2025-06-18 spec)
-        if (toolAny.outputSchema) {
-            metadata.returnSchema = {
-                hasSchema: true,
-                schema: toolAny.outputSchema,
-            };
-        }
-        // Bulk operations - check metadata for batch support
-        const bulkSupport = toolAny.supportsBulkOperations ||
-            toolAny.annotations?.supportsBulkOperations ||
-            toolAny.metadata?.supportsBulkOperations;
-        const maxBatchSize = toolAny.metadata?.maxBatchSize;
-        if (bulkSupport !== undefined || maxBatchSize !== undefined) {
-            metadata.bulkOperations = {
-                supported: !!bulkSupport,
-                maxBatchSize: typeof maxBatchSize === "number" ? maxBatchSize : undefined,
-            };
-        }
-        return Object.keys(metadata).length > 0 ? metadata : undefined;
-    }
-    /**
-     * Extract parameters from tool input schema
-     */
-    extractToolParams(schema) {
-        if (!schema || typeof schema !== "object")
-            return [];
-        const s = schema;
-        if (!s.properties || typeof s.properties !== "object")
-            return [];
-        const required = new Set(Array.isArray(s.required) ? s.required : []);
-        const properties = s.properties;
-        return Object.entries(properties).map(([name, prop]) => {
-            const param = {
-                name,
-                type: prop.type || "any",
-                required: required.has(name),
-            };
-            if (prop.description) {
-                param.description = prop.description;
-            }
-            return param;
-        });
-    }
-    /**
-     * Determine overall status
-     */
-    determineAnnotationStatus(results, totalTools) {
-        if (totalTools === 0)
-            return "PASS";
-        const annotatedCount = results.filter((r) => r.hasAnnotations).length;
-        const poisonedCount = results.filter((r) => r.descriptionPoisoning?.detected === true).length;
-        if (poisonedCount > 0)
-            return "FAIL";
-        const misalignedCount = results.filter((r) => r.alignmentStatus === "MISALIGNED").length;
-        const destructiveWithoutHint = results.filter((r) => r.inferredBehavior?.expectedDestructive === true &&
-            r.inferredBehavior?.confidence === "high" &&
-            r.annotations?.destructiveHint !== true).length;
-        if (destructiveWithoutHint > 0)
-            return "FAIL";
-        if (misalignedCount > 0)
-            return "FAIL";
-        if (annotatedCount === totalTools)
-            return "PASS";
-        const annotationRate = annotatedCount / totalTools;
-        if (annotationRate >= 0.8)
-            return "NEED_MORE_INFO";
-        if (annotationRate < 0.5)
-            return "FAIL";
-        return "NEED_MORE_INFO";
-    }
-    /**
-     * Calculate metrics and alignment breakdown
-     */
-    calculateMetrics(results, totalTools) {
-        const alignmentBreakdown = {
-            aligned: results.filter((r) => r.alignmentStatus === "ALIGNED").length,
-            misaligned: results.filter((r) => r.alignmentStatus === "MISALIGNED")
-                .length,
-            reviewRecommended: results.filter((r) => r.alignmentStatus === "REVIEW_RECOMMENDED").length,
-            unknown: results.filter((r) => r.alignmentStatus === "UNKNOWN").length,
-        };
-        const annotatedCount = results.filter((r) => r.hasAnnotations).length;
-        const metrics = {
-            coverage: totalTools > 0 ? (annotatedCount / totalTools) * 100 : 100,
-            consistency: totalTools > 0
-                ? ((totalTools - alignmentBreakdown.misaligned) / totalTools) * 100
-                : 100,
-            correctness: annotatedCount > 0
-                ? (alignmentBreakdown.aligned / annotatedCount) * 100
-                : 0,
-            reviewRequired: alignmentBreakdown.reviewRecommended,
-        };
-        return { metrics, alignmentBreakdown };
-    }
-    /**
-     * Generate explanation
-     */
-    generateExplanation(annotatedCount, missingCount, misalignedCount, totalTools) {
-        const parts = [];
-        if (totalTools === 0) {
-            return "No tools found to assess for annotations.";
-        }
-        parts.push(`Tool annotation coverage: ${annotatedCount}/${totalTools} tools have annotations.`);
-        if (missingCount > 0) {
-            parts.push(`${missingCount} tool(s) are missing required annotations (readOnlyHint, destructiveHint).`);
-        }
-        if (misalignedCount > 0) {
-            parts.push(`${misalignedCount} tool(s) have potentially misaligned annotations based on naming patterns.`);
-        }
-        if (missingCount === 0 && misalignedCount === 0) {
-            parts.push("All tools are properly annotated.");
-        }
-        return parts.join(" ");
-    }
-    /**
-     * Generate enhanced explanation with Claude analysis
-     */
-    generateEnhancedExplanation(annotatedCount, missingCount, highConfidenceMisalignments, totalTools) {
-        const parts = [];
-        if (totalTools === 0) {
-            return "No tools found to assess for annotations.";
-        }
-        parts.push(`Tool annotation coverage: ${annotatedCount}/${totalTools} tools have annotations.`);
-        if (missingCount > 0) {
-            parts.push(`${missingCount} tool(s) are missing required annotations (readOnlyHint, destructiveHint).`);
-        }
-        if (highConfidenceMisalignments > 0) {
-            parts.push(`Claude analysis identified ${highConfidenceMisalignments} high-confidence annotation misalignment(s).`);
-        }
-        parts.push("Analysis enhanced with Claude semantic behavior inference.");
-        return parts.join(" ");
-    }
-    /**
-     * Generate recommendations
-     */
-    generateRecommendations(results) {
-        const recommendations = [];
-        const allRecs = new Set();
-        for (const result of results) {
-            for (const rec of result.recommendations) {
-                allRecs.add(rec);
-            }
-        }
-        const destructiveRecs = Array.from(allRecs).filter((r) => r.includes("destructive"));
-        const otherRecs = Array.from(allRecs).filter((r) => !r.includes("destructive"));
-        if (destructiveRecs.length > 0) {
-            recommendations.push("PRIORITY: The following tools appear to perform destructive operations but lack proper destructiveHint annotation:");
-            recommendations.push(...destructiveRecs.slice(0, 5));
-        }
-        if (otherRecs.length > 0) {
-            recommendations.push(...otherRecs.slice(0, 5));
-        }
-        if (recommendations.length === 0) {
-            recommendations.push("All tools have proper annotations. No action required.");
-        }
-        else {
-            recommendations.push("Reference: MCP Directory Policy #17 requires tools to have readOnlyHint and destructiveHint annotations.");
-        }
-        return recommendations;
-    }
-    /**
-     * Generate enhanced recommendations with Claude analysis
-     */
-    generateEnhancedRecommendations(results) {
-        const recommendations = [];
-        const claudeMisalignments = results.filter((r) => r.claudeInference &&
-            r.claudeInference.source === "claude-inferred" &&
-            r.claudeInference.confidence >= 70 &&
-            r.claudeInference.misalignmentDetected);
-        if (claudeMisalignments.length > 0) {
-            recommendations.push("HIGH CONFIDENCE: Claude analysis identified the following annotation issues:");
-            for (const result of claudeMisalignments.slice(0, 5)) {
-                if (result.claudeInference) {
-                    recommendations.push(`  - ${result.toolName}: ${result.claudeInference.reasoning}`);
-                }
-            }
-        }
-        const claudeSuggestions = results
-            .filter((r) => r.claudeInference &&
-            r.claudeInference.source === "claude-inferred" &&
-            r.claudeInference.confidence >= 60)
-            .flatMap((r) => r.recommendations.filter((rec) => rec.includes("Claude")));
-        if (claudeSuggestions.length > 0) {
-            recommendations.push(...claudeSuggestions.slice(0, 5));
-        }
-        const patternRecs = new Set();
-        for (const result of results) {
-            for (const rec of result.recommendations) {
-                if (!rec.includes("Claude")) {
-                    patternRecs.add(rec);
-                }
-            }
-        }
-        const destructiveRecs = Array.from(patternRecs).filter((r) => r.includes("destructive"));
-        const otherRecs = Array.from(patternRecs).filter((r) => !r.includes("destructive"));
-        if (destructiveRecs.length > 0) {
-            recommendations.push("PRIORITY: Potential destructive tools without proper hints:");
-            recommendations.push(...destructiveRecs.slice(0, 3));
-        }
-        if (otherRecs.length > 0 && recommendations.length < 10) {
-            recommendations.push(...otherRecs.slice(0, 3));
-        }
-        if (recommendations.length === 0) {
-            recommendations.push("All tools have proper annotations. No action required.");
-        }
-        else {
-            recommendations.push("Reference: MCP Directory Policy #17 requires tools to have readOnlyHint and destructiveHint annotations.");
-        }
-        return recommendations;
-    }
 }