@dotsetlabs/bellwether 1.0.3 → 2.0.0

package/dist/docs/contract.js

@@ -52,13 +52,15 @@ function classifyIssuesBySource(profiles) {
             // but tool didn't actually reject - this shouldn't happen with outcomeAssessment.correct check above
             // so we classify based on expected outcome and error classification
             // 1. Check for external dependency errors (highest priority for classification)
-            if (errorClassification && errorClassification.externalServiceErrors > 0 && detectedServices.length > 0) {
+            if (errorClassification &&
+                errorClassification.externalServiceErrors > 0 &&
+                detectedServices.length > 0) {
                 // Check if the error message matches known external service patterns
-                const isExternalError = detectedServices.some(service => {
+                const isExternalError = detectedServices.some((service) => {
                     const serviceConfig = EXTERNAL_DEPENDENCIES.SERVICES[service];
                     if (!serviceConfig)
                         return false;
-                    return serviceConfig.errorPatterns.some(pattern => pattern.test(errorMsg));
+                    return serviceConfig.errorPatterns.some((pattern) => pattern.test(errorMsg));
                 });
                 if (isExternalError) {
                     issue.service = detectedServices[0];
@@ -68,7 +70,7 @@ function classifyIssuesBySource(profiles) {
             }
             // 2. Check for environment configuration errors
             if (errorClassification && errorClassification.environmentErrors > 0) {
-                const isEnvironmentError = EXTERNAL_DEPENDENCIES.ENVIRONMENT_PATTERNS.some(pattern => pattern.test(errorMsg));
+                const isEnvironmentError = EXTERNAL_DEPENDENCIES.ENVIRONMENT_PATTERNS.some((pattern) => pattern.test(errorMsg));
                 if (isEnvironmentError) {
                     result.environment.push(issue);
                     continue;
@@ -99,7 +101,7 @@ function classifyIssuesBySource(profiles) {
                     continue;
                 }
                 // Check if error message indicates environment issue
-                const isEnvironmentError = EXTERNAL_DEPENDENCIES.ENVIRONMENT_PATTERNS.some(pattern => pattern.test(errorMsg));
+                const isEnvironmentError = EXTERNAL_DEPENDENCIES.ENVIRONMENT_PATTERNS.some((pattern) => pattern.test(errorMsg));
                 if (isEnvironmentError) {
                     result.environment.push(issue);
                     continue;
@@ -149,7 +151,7 @@ export function generateContractMd(result, options) {
     lines.push(`**Protocol Version:** ${discovery.protocolVersion}`);
     lines.push('');
     const performanceMetrics = calculatePerformanceMetrics(toolProfiles);
-    const performanceByTool = new Map(performanceMetrics.map(metric => [metric.toolName, metric]));
+    const performanceByTool = new Map(performanceMetrics.map((metric) => [metric.toolName, metric]));
     // Capabilities summary
     lines.push('## Capabilities');
     lines.push('');
@@ -176,7 +178,7 @@ export function generateContractMd(result, options) {
             const params = extractParameters(tool.inputSchema);
             const desc = tool.description?.substring(0, 50) || 'No description';
             const descDisplay = tool.description && tool.description.length > 50 ? `${desc}...` : desc;
-            const profile = toolProfiles.find(p => p.name === tool.name);
+            const profile = toolProfiles.find((p) => p.name === tool.name);
             const perf = performanceByTool.get(tool.name);
             const successRate = calculateToolSuccessRate(profile, {
                 countValidationAsSuccess,
@@ -291,7 +293,7 @@ export function generateContractMd(result, options) {
         lines.push('## Tools');
         lines.push('');
         for (const tool of discovery.tools) {
-            const profile = toolProfiles.find(p => p.name === tool.name);
+            const profile = toolProfiles.find((p) => p.name === tool.name);
             lines.push(`### ${tool.name}`);
             lines.push('');
             lines.push(tool.description || 'No description available.');
@@ -397,7 +399,7 @@ function calculateReliabilityMetrics(profile, options) {
     if (!profile) {
         return null;
     }
-    const interactions = profile.interactions.filter(i => !i.mocked);
+    const interactions = profile.interactions.filter((i) => !i.mocked);
     if (interactions.length === 0) {
         return null;
     }
@@ -408,7 +410,7 @@ function calculateReliabilityMetrics(profile, options) {
     for (const interaction of interactions) {
         const expected = interaction.question.expectedOutcome ?? 'success';
         const hasError = interaction.error || interaction.response?.isError;
-        const textContent = interaction.response?.content?.find(c => c.type === 'text');
+        const textContent = interaction.response?.content?.find((c) => c.type === 'text');
         const hasErrorText = textContent && 'text' in textContent && looksLikeError(String(textContent.text));
         const gotError = hasError || hasErrorText;
         if (expected === 'error') {
@@ -437,7 +439,9 @@ function calculateReliabilityMetrics(profile, options) {
     const reliabilityRate = total > 0 ? (correctOutcomes / total) * 100 : 0;
     const happyPathRate = happyPathTotal > 0 ? (happyPathSuccesses / happyPathTotal) * 100 : 100;
     const validationRate = options.separateValidationMetrics
-        ? (validationTotal > 0 ? (validationSuccesses / validationTotal) * 100 : 100)
+        ? validationTotal > 0
+            ? (validationSuccesses / validationTotal) * 100
+            : 100
         : 100;
     return {
         total,
@@ -481,8 +485,7 @@ function formatConfidenceIndicator(level) {
 function generateTransportIssuesSection(transportErrors, warnings) {
     const lines = [];
     // Skip if no transport issues to report
-    if ((!transportErrors || transportErrors.length === 0) &&
-        (!warnings || warnings.length === 0)) {
+    if ((!transportErrors || transportErrors.length === 0) && (!warnings || warnings.length === 0)) {
         return lines;
     }
     lines.push('## Transport Issues');
@@ -507,8 +510,8 @@ function generateTransportIssuesSection(transportErrors, warnings) {
         lines.push('The following transport-level errors were detected during server communication:');
         lines.push('');
         // Categorize errors
-        const serverBugErrors = transportErrors.filter(e => e.likelyServerBug);
-        const envErrors = transportErrors.filter(e => !e.likelyServerBug);
+        const serverBugErrors = transportErrors.filter((e) => e.likelyServerBug);
+        const envErrors = transportErrors.filter((e) => !e.likelyServerBug);
         // Server bugs (critical)
         if (serverBugErrors.length > 0) {
             lines.push('#### Likely Server Bugs');
@@ -548,8 +551,8 @@ function generateTransportIssuesSection(transportErrors, warnings) {
             lines.push('');
         }
         // Recommendations
-        const hasInvalidJson = transportErrors.some(e => e.category === 'invalid_json');
-        const hasProtocolError = transportErrors.some(e => e.category === 'protocol_violation');
+        const hasInvalidJson = transportErrors.some((e) => e.category === 'invalid_json');
+        const hasProtocolError = transportErrors.some((e) => e.category === 'protocol_violation');
         if (hasInvalidJson || hasProtocolError) {
             lines.push('### Recommendations');
             lines.push('');
@@ -607,7 +610,7 @@ function generateMetricsLegendSection() {
 }
 function generateValidationTestingSection(profiles) {
     const lines = [];
-    const validationSummary = profiles.map(profile => {
+    const validationSummary = profiles.map((profile) => {
         const buckets = {
             input: summarizeValidationBucket(profile, 'input'),
             type: summarizeValidationBucket(profile, 'type'),
@@ -615,7 +618,7 @@ function generateValidationTestingSection(profiles) {
         };
         return { profile, buckets };
     });
-    const hasValidationTests = validationSummary.some(summary => Object.values(summary.buckets).some(bucket => bucket.total > 0));
+    const hasValidationTests = validationSummary.some((summary) => Object.values(summary.buckets).some((bucket) => bucket.total > 0));
     if (!hasValidationTests) {
         return lines;
     }
@@ -668,8 +671,8 @@ function generateIssuesDetectedSection(profiles) {
         lines.push(`### ${ISSUE_CLASSIFICATION.ICONS.serverBug} ${ISSUE_CLASSIFICATION.HEADERS.serverBug}`);
         lines.push('');
         // Separate critical (accepts invalid input) from other bugs
-        const criticalBugs = classified.serverBug.filter(i => i.critical);
-        const otherBugs = classified.serverBug.filter(i => !i.critical);
+        const criticalBugs = classified.serverBug.filter((i) => i.critical);
+        const otherBugs = classified.serverBug.filter((i) => !i.critical);
         if (criticalBugs.length > 0) {
             lines.push('**Critical - Accepts Invalid Input:**');
             for (const issue of criticalBugs.slice(0, DISPLAY_LIMITS.ISSUES_DISPLAY_LIMIT)) {
@@ -809,7 +812,7 @@ function generateContractPerformanceSection(profiles, metricsOverride) {
         return [];
     }
     // Only show if we have meaningful data
-    const hasValidMetrics = metrics.some(m => m.callCount >= 2);
+    const hasValidMetrics = metrics.some((m) => m.callCount >= 2);
     if (!hasValidMetrics) {
         return [];
     }
@@ -830,11 +833,11 @@ function generateContractPerformanceSection(profiles, metricsOverride) {
     }
     lines.push('');
     // Show low confidence warning if any tools have low confidence
-    const lowConfidenceTools = metrics.filter(m => m.confidence?.confidenceLevel === 'low');
+    const lowConfidenceTools = metrics.filter((m) => m.confidence?.confidenceLevel === 'low');
     if (lowConfidenceTools.length > 0) {
         // Categorize low confidence by reason
-        const lowSampleTools = lowConfidenceTools.filter(m => (m.confidence?.successfulSamples ?? 0) < PERFORMANCE_CONFIDENCE.HIGH.MIN_SAMPLES);
-        const highVariabilityTools = lowConfidenceTools.filter(m => (m.confidence?.successfulSamples ?? 0) >= PERFORMANCE_CONFIDENCE.HIGH.MIN_SAMPLES &&
+        const lowSampleTools = lowConfidenceTools.filter((m) => (m.confidence?.successfulSamples ?? 0) < PERFORMANCE_CONFIDENCE.HIGH.MIN_SAMPLES);
+        const highVariabilityTools = lowConfidenceTools.filter((m) => (m.confidence?.successfulSamples ?? 0) >= PERFORMANCE_CONFIDENCE.HIGH.MIN_SAMPLES &&
             (m.confidence?.coefficientOfVariation ?? 0) > PERFORMANCE_CONFIDENCE.MEDIUM.MAX_CV);
         lines.push(`> **⚠️ Low Confidence**: ${lowConfidenceTools.length} tool(s) have low statistical confidence.`);
         if (lowSampleTools.length > 0) {
@@ -847,7 +850,7 @@ function generateContractPerformanceSection(profiles, metricsOverride) {
         lines.push('');
     }
     // Add confidence summary section (collapsed)
-    const hasConfidenceData = metrics.some(m => m.confidence);
+    const hasConfidenceData = metrics.some((m) => m.confidence);
     if (hasConfidenceData) {
         lines.push('<details>');
         lines.push('<summary>Confidence Metrics Details</summary>');
@@ -867,7 +870,9 @@ function generateContractPerformanceSection(profiles, metricsOverride) {
                 // In this case, display ~0% to indicate the variability is below measurement threshold
                 const rawCV = m.confidence.coefficientOfVariation * 100;
                 const cvDisplay = successfulSamples > 0
-                    ? (roundedStdDev === 0 && rawCV > 1 ? '~0%' : `${rawCV.toFixed(1)}%`)
+                    ? roundedStdDev === 0 && rawCV > 1
+                        ? '~0%'
+                        : `${rawCV.toFixed(1)}%`
                     : 'N/A';
                 const levelLabel = PERFORMANCE_CONFIDENCE.LABELS[m.confidence.confidenceLevel];
                 lines.push(`| \`${escapeTableCell(m.toolName)}\` | ${successfulSamples} | ${validationSamples} | ${totalTests} | ${stdDevDisplay} | ${cvDisplay} | ${levelLabel} |`);
@@ -931,11 +936,11 @@ function generateContractSecuritySection(fingerprints) {
     lines.push(`| Average Risk Score | ${avgRiskScore}/100 |`);
     // Count by severity
     const bySeverity = {
-        critical: allFindings.filter(f => f.riskLevel === 'critical').length,
-        high: allFindings.filter(f => f.riskLevel === 'high').length,
-        medium: allFindings.filter(f => f.riskLevel === 'medium').length,
-        low: allFindings.filter(f => f.riskLevel === 'low').length,
-        info: allFindings.filter(f => f.riskLevel === 'info').length,
+        critical: allFindings.filter((f) => f.riskLevel === 'critical').length,
+        high: allFindings.filter((f) => f.riskLevel === 'high').length,
+        medium: allFindings.filter((f) => f.riskLevel === 'medium').length,
+        low: allFindings.filter((f) => f.riskLevel === 'low').length,
+        info: allFindings.filter((f) => f.riskLevel === 'info').length,
     };
     if (bySeverity.critical > 0) {
         lines.push(`| Critical Findings | ${bySeverity.critical} |`);
@@ -954,7 +959,7 @@ function generateContractSecuritySection(fingerprints) {
         return lines;
     }
     // Show findings by severity
-    const criticalAndHigh = allFindings.filter(f => f.riskLevel === 'critical' || f.riskLevel === 'high');
+    const criticalAndHigh = allFindings.filter((f) => f.riskLevel === 'critical' || f.riskLevel === 'high');
     if (criticalAndHigh.length > 0) {
         lines.push('### Critical and High Severity Findings');
         lines.push('');
@@ -987,7 +992,7 @@ function generateContractSecuritySection(fingerprints) {
         lines.push('');
     }
     // Show medium/low findings in collapsed section
-    const mediumAndLow = allFindings.filter(f => f.riskLevel === 'medium' || f.riskLevel === 'low' || f.riskLevel === 'info');
+    const mediumAndLow = allFindings.filter((f) => f.riskLevel === 'medium' || f.riskLevel === 'low' || f.riskLevel === 'info');
     if (mediumAndLow.length > 0) {
         lines.push('<details>');
         lines.push(`<summary>Medium/Low Severity Findings (${mediumAndLow.length})</summary>`);
@@ -1027,10 +1032,10 @@ function generateWorkflowTestingSection(results) {
     if (results.length === 0) {
         return [];
     }
-    const passed = results.filter(r => r.success).length;
+    const passed = results.filter((r) => r.success).length;
     const failed = results.length - passed;
     const totalSteps = results.reduce((sum, r) => sum + r.workflow.steps.length, 0);
-    const passedSteps = results.reduce((sum, r) => sum + r.steps.filter(s => s.success).length, 0);
+    const passedSteps = results.reduce((sum, r) => sum + r.steps.filter((s) => s.success).length, 0);
     const totalDurationMs = results.reduce((sum, r) => sum + r.durationMs, 0);
     lines.push('## Workflow Testing');
     lines.push('');
@@ -1053,7 +1058,7 @@ function generateWorkflowTestingSection(results) {
     lines.push('|----------|--------|-------|----------|');
     for (const result of results) {
         const status = result.success ? '✓ Passed' : '✗ Failed';
-        const stepsInfo = `${result.steps.filter(s => s.success).length}/${result.workflow.steps.length}`;
+        const stepsInfo = `${result.steps.filter((s) => s.success).length}/${result.workflow.steps.length}`;
         const duration = formatDuration(result.durationMs);
         lines.push(`| ${escapeTableCell(result.workflow.name)} | ${status} | ${stepsInfo} | ${duration} |`);
     }
@@ -1083,8 +1088,8 @@ function generateWorkflowTestingSection(results) {
                 if (stepResult.error) {
                     notes = escapeTableCell(truncateString(stepResult.error, 40));
                 }
-                else if (stepResult.assertionResults?.some(a => !a.passed)) {
-                    const failedAssertions = stepResult.assertionResults.filter(a => !a.passed);
+                else if (stepResult.assertionResults?.some((a) => !a.passed)) {
+                    const failedAssertions = stepResult.assertionResults.filter((a) => !a.passed);
                     notes = `${failedAssertions.length} assertion(s) failed`;
                 }
             }
@@ -1177,17 +1182,17 @@ function generateSemanticTypesSection(inferences) {
         byType.set(inf.inferredType, existing);
     }
     // Sort by number of parameters (most common types first)
-    const sortedTypes = Array.from(byType.entries())
-        .sort((a, b) => b[1].length - a[1].length);
+    const sortedTypes = Array.from(byType.entries()).sort((a, b) => b[1].length - a[1].length);
     lines.push('| Type | Parameters | Expected Format |');
     lines.push('|------|------------|-----------------|');
     for (const [type, params] of sortedTypes) {
         const displayName = SEMANTIC_VALIDATION.TYPE_DISPLAY_NAMES[type] ?? type;
-        const exampleValue = SEMANTIC_VALIDATION.EXAMPLE_VALUES[type] ?? '';
+        const exampleValue = SEMANTIC_VALIDATION.EXAMPLE_VALUES[type] ??
+            '';
         // Format parameters as tool.param
         const paramList = params
             .slice(0, 3)
-            .map(p => `\`${p.toolName}.${p.paramName}\``)
+            .map((p) => `\`${p.toolName}.${p.paramName}\``)
             .join(', ');
         const moreCount = params.length > 3 ? ` +${params.length - 3} more` : '';
         lines.push(`| ${displayName} | ${paramList}${moreCount} | \`${exampleValue}\` |`);
@@ -1246,9 +1251,10 @@ function generateSchemaStabilitySection(schemaEvolution) {
     lines.push('Response schema consistency metrics for tools with sufficient test samples:');
     lines.push('');
     // Summary stats
-    const stableCount = toolsWithSchemas.filter(t => t.evolution.isStable).length;
+    const stableCount = toolsWithSchemas.filter((t) => t.evolution.isStable).length;
     const unstableCount = toolsWithSchemas.length - stableCount;
-    const avgConfidence = toolsWithSchemas.reduce((sum, t) => sum + t.evolution.stabilityConfidence, 0) / toolsWithSchemas.length;
+    const avgConfidence = toolsWithSchemas.reduce((sum, t) => sum + t.evolution.stabilityConfidence, 0) /
+        toolsWithSchemas.length;
     lines.push('| Metric | Value |');
     lines.push('|--------|-------|');
     lines.push(`| Tools Analyzed | ${toolsWithSchemas.length} |`);
@@ -1269,7 +1275,7 @@ function generateSchemaStabilitySection(schemaEvolution) {
     lines.push('| Tool | Grade | Stability | Confidence | Samples | Issues |');
     lines.push('|------|-------|-----------|------------|---------|--------|');
     // Sort by grade (worst first, then by name)
-    const gradeOrder = { 'F': 0, 'D': 1, 'C': 2, 'B': 3, 'A': 4, 'N/A': 5 };
+    const gradeOrder = { F: 0, D: 1, C: 2, B: 3, A: 4, 'N/A': 5 };
     const sortedTools = [...toolsWithSchemas].sort((a, b) => {
         const gradeCompare = gradeOrder[a.grade] - gradeOrder[b.grade];
         if (gradeCompare !== 0)
@@ -1284,13 +1290,15 @@ function generateSchemaStabilitySection(schemaEvolution) {
         const confidenceDisplay = `${Math.round(evolution.stabilityConfidence * 100)}%`;
         const issues = evolution.inconsistentFields.length > 0
             ? evolution.inconsistentFields.slice(0, 2).join(', ') +
-                (evolution.inconsistentFields.length > 2 ? ` +${evolution.inconsistentFields.length - 2}` : '')
+                (evolution.inconsistentFields.length > 2
+                    ? ` +${evolution.inconsistentFields.length - 2}`
+                    : '')
             : '-';
         lines.push(`| \`${escapeTableCell(name)}\` | ${gradeEmoji} ${grade} | ${stabilityStatus} | ${confidenceDisplay} | ${evolution.sampleCount} | ${escapeTableCell(issues)} |`);
     }
     lines.push('');
     // Detailed breakdown for unstable tools
-    const unstableTools = sortedTools.filter(t => !t.evolution.isStable && t.evolution.inconsistentFields.length > 0);
+    const unstableTools = sortedTools.filter((t) => !t.evolution.isStable && t.evolution.inconsistentFields.length > 0);
     if (unstableTools.length > 0) {
         lines.push('<details>');
         lines.push('<summary>Unstable Schema Details</summary>');
@@ -1327,12 +1335,18 @@ function generateSchemaStabilitySection(schemaEvolution) {
  */
 function getGradeEmoji(grade) {
     switch (grade) {
-        case 'A': return '🟢';
-        case 'B': return '🟢';
-        case 'C': return '🟡';
-        case 'D': return '🟠';
-        case 'F': return '🔴';
-        case 'N/A': return '⚪';
+        case 'A':
+            return '🟢';
+        case 'B':
+            return '🟢';
+        case 'C':
+            return '🟡';
+        case 'D':
+            return '🟠';
+        case 'F':
+            return '🔴';
+        case 'N/A':
+            return '⚪';
     }
 }
 /**
@@ -1360,7 +1374,8 @@ function generateErrorAnalysisSection(summaries) {
     const allCategories = new Set();
     const transientCount = toolsWithErrors.reduce((sum, t) => sum + t.summary.transientErrors, 0);
     for (const { summary } of toolsWithErrors) {
-        for (const cat of summary.categoryCounts.keys()) {
+        const counts = normalizeCategoryCounts(summary.categoryCounts);
+        for (const cat of counts.keys()) {
             allCategories.add(cat);
         }
     }
@@ -1374,7 +1389,8 @@ function generateErrorAnalysisSection(summaries) {
     // Overall error breakdown by category
     const globalCategoryCounts = new Map();
     for (const { summary } of toolsWithErrors) {
-        for (const [cat, count] of summary.categoryCounts) {
+        const counts = normalizeCategoryCounts(summary.categoryCounts);
+        for (const [cat, count] of counts) {
             globalCategoryCounts.set(cat, (globalCategoryCounts.get(cat) ?? 0) + count);
         }
     }
@@ -1384,10 +1400,10 @@ function generateErrorAnalysisSection(summaries) {
         lines.push('| Category | Count | Description |');
         lines.push('|----------|-------|-------------|');
         // Sort by count descending
-        const sortedCategories = Array.from(globalCategoryCounts.entries())
-            .sort((a, b) => b[1] - a[1]);
+        const sortedCategories = Array.from(globalCategoryCounts.entries()).sort((a, b) => b[1] - a[1]);
         for (const [category, count] of sortedCategories) {
-            const label = ERROR_ANALYSIS.CATEGORY_LABELS[category] ?? category;
+            const label = ERROR_ANALYSIS.CATEGORY_LABELS[category] ??
+                category;
             const emoji = getCategoryEmoji(category);
             lines.push(`| ${emoji} ${label} | ${count} | ${escapeTableCell(formatCategoryDescription(category))} |`);
         }
@@ -1406,14 +1422,12 @@ function generateErrorAnalysisSection(summaries) {
             ? (ERROR_ANALYSIS.CATEGORY_LABELS[topCategory] ?? topCategory)
             : '-';
         const topRemediation = summary.topRemediations[0] ?? '-';
-        const truncatedRemediation = topRemediation.length > 50
-            ? `${topRemediation.slice(0, 47)}...`
-            : topRemediation;
+        const truncatedRemediation = topRemediation.length > 50 ? `${topRemediation.slice(0, 47)}...` : topRemediation;
         lines.push(`| \`${escapeTableCell(name)}\` | ${summary.totalErrors} | ${summary.transientErrors} | ${topCategoryLabel} | ${escapeTableCell(truncatedRemediation)} |`);
     }
     lines.push('');
     // Detailed remediation suggestions (collapsed)
-    const toolsWithRemediations = sortedTools.filter(t => t.summary.topRemediations.length > 0);
+    const toolsWithRemediations = sortedTools.filter((t) => t.summary.topRemediations.length > 0);
     if (toolsWithRemediations.length > 0) {
         lines.push('<details>');
         lines.push('<summary>Remediation Suggestions</summary>');
@@ -1463,13 +1477,20 @@ function generateErrorAnalysisSection(summaries) {
  */
 function getCategoryEmoji(category) {
     switch (category) {
-        case 'client_error_validation': return '⚠️';
-        case 'client_error_auth': return '🔐';
-        case 'client_error_not_found': return '🔍';
-        case 'client_error_conflict': return '💥';
-        case 'client_error_rate_limit': return '⏱️';
-        case 'server_error': return '🔥';
-        default: return '❓';
+        case 'client_error_validation':
+            return '⚠️';
+        case 'client_error_auth':
+            return '🔐';
+        case 'client_error_not_found':
+            return '🔍';
+        case 'client_error_conflict':
+            return '💥';
+        case 'client_error_rate_limit':
+            return '⏱️';
+        case 'server_error':
+            return '🔥';
+        default:
+            return '❓';
     }
 }
 /**
@@ -1493,13 +1514,30 @@ function formatCategoryDescription(category) {
             return 'Unknown error category';
     }
 }
+/**
+ * Get the top category from a category counts map.
+ */
+function normalizeCategoryCounts(counts) {
+    if (!counts) {
+        return new Map();
+    }
+    if (counts instanceof Map) {
+        return counts;
+    }
+    if (typeof counts !== 'object') {
+        return new Map();
+    }
+    const entries = Object.entries(counts).filter((entry) => typeof entry[1] === 'number');
+    return new Map(entries);
+}
 /**
  * Get the top category from a category counts map.
  */
 function getTopCategory(counts) {
+    const normalized = normalizeCategoryCounts(counts);
     let topCategory;
     let topCount = 0;
-    for (const [category, count] of counts) {
+    for (const [category, count] of normalized) {
         if (count > topCount) {
             topCount = count;
             topCategory = category;
@@ -1601,7 +1639,10 @@ function formatIssueTypeLabel(type) {
         case 'no_examples':
             return 'No Examples';
         default:
-            return type.split('_').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+            return type
+                .split('_')
+                .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+                .join(' ');
     }
 }
 /**
@@ -1617,10 +1658,10 @@ function generateToolExamples(profile, maxExamples, maxExampleLength = EXAMPLE_O
         return [];
     }
     // Find successful interactions
-    const successful = profile.interactions.filter(i => {
+    const successful = profile.interactions.filter((i) => {
         if (i.error || i.response?.isError)
             return false;
-        const textContent = i.response?.content?.find(c => c.type === 'text');
+        const textContent = i.response?.content?.find((c) => c.type === 'text');
         if (textContent && 'text' in textContent) {
             if (looksLikeError(String(textContent.text)))
                 return false;
@@ -1640,7 +1681,7 @@ function generateToolExamples(profile, maxExamples, maxExampleLength = EXAMPLE_O
         if (seenArgsHashes.has(argsHash))
             continue;
         seenArgsHashes.add(argsHash);
-        const textContent = interaction.response?.content?.find(c => c.type === 'text');
+        const textContent = interaction.response?.content?.find((c) => c.type === 'text');
         if (!textContent || !('text' in textContent))
             continue;
         const responseText = String(textContent.text);
@@ -1696,7 +1737,7 @@ function generateToolErrorPatterns(profile) {
             continue;
         }
         const errorText = interaction.error || '';
-        const textContent = interaction.response?.content?.find(c => c.type === 'text');
+        const textContent = interaction.response?.content?.find((c) => c.type === 'text');
         const responseText = textContent && 'text' in textContent ? String(textContent.text) : '';
         const isError = interaction.error || interaction.response?.isError || looksLikeError(responseText);
         if (!isError)
@@ -1706,7 +1747,8 @@ function generateToolErrorPatterns(profile) {
             continue;
         const category = categorizeError(errorContent);
         const existing = errorCategories.get(category) || [];
-        if (existing.length < 2) { // Max 2 examples per category
+        if (existing.length < 2) {
+            // Max 2 examples per category
             const truncated = errorContent.length > 100 ? `${errorContent.slice(0, 97)}...` : errorContent;
             existing.push(truncated);
         }
@@ -1758,7 +1800,7 @@ function generateErrorSummarySection(profiles) {
                 continue;
             }
             const errorText = interaction.error || '';
-            const textContent = interaction.response?.content?.find(c => c.type === 'text');
+            const textContent = interaction.response?.content?.find((c) => c.type === 'text');
             const responseText = textContent && 'text' in textContent ? String(textContent.text) : '';
             const isError = interaction.error || interaction.response?.isError || looksLikeError(responseText);
             if (!isError)
@@ -1771,7 +1813,8 @@ function generateErrorSummarySection(profiles) {
             existing.count++;
             existing.tools.add(profile.name);
             if (!existing.example) {
-                existing.example = errorContent.length > 80 ? `${errorContent.slice(0, 77)}...` : errorContent;
+                existing.example =
+                    errorContent.length > 80 ? `${errorContent.slice(0, 77)}...` : errorContent;
             }
             categoryCounts.set(category, existing);
         }
@@ -1786,7 +1829,10 @@ function generateErrorSummarySection(profiles) {
     lines.push('| Category | Count | Affected Tools |');
     lines.push('|----------|-------|----------------|');
     for (const [category, data] of categoryCounts) {
-        const toolList = Array.from(data.tools).slice(0, 3).map(t => `\`${t}\``).join(', ');
+        const toolList = Array.from(data.tools)
+            .slice(0, 3)
+            .map((t) => `\`${t}\``)
+            .join(', ');
         const more = data.tools.size > 3 ? ` +${data.tools.size - 3} more` : '';
         lines.push(`| ${category} | ${data.count} | ${toolList}${more} |`);
     }
@@ -1813,7 +1859,7 @@ function analyzeToolsForExternalDependencies(profiles, tools) {
                 continue;
             }
             const errorText = interaction.error || '';
-            const textContent = interaction.response?.content?.find(c => c.type === 'text');
+            const textContent = interaction.response?.content?.find((c) => c.type === 'text');
             const responseText = textContent && 'text' in textContent ? String(textContent.text) : '';
             const isError = interaction.error || interaction.response?.isError || looksLikeError(responseText);
             if (!isError)
@@ -1843,7 +1889,7 @@ function analyzeToolsForExternalDependencies(profiles, tools) {
             });
         }
         if (patterns.length > 0) {
-            const tool = tools.find(t => t.name === profile.name);
+            const tool = tools.find((t) => t.name === profile.name);
             errorInputs.push({
                 toolName: profile.name,
                 toolDescription: tool?.description,
@@ -1962,7 +2008,9 @@ function collectAssertionFailures(profile) {
         for (const result of interaction.assertionResults ?? []) {
             if (result.passed)
                 continue;
-            const message = result.message ? `${result.type}: ${result.message}` : `${result.type} failed`;
+            const message = result.message
+                ? `${result.type}: ${result.message}`
+                : `${result.type} failed`;
             failures.add(message);
         }
     }

package/dist/docs/report.js

@@ -1,14 +1,13 @@
 import { Ajv2020 as Ajv } from 'ajv/dist/2020.js';
 import { readFileSync } from 'fs';
+import { isAbsolute } from 'path';
 import { fileURLToPath } from 'url';
 import { REPORT_SCHEMAS } from '../constants.js';
 /**
  * Generate a JSON report of the interview.
  */
 export function generateJsonReport(result, options = {}) {
-    const report = options.schemaUrl
-        ? { $schema: options.schemaUrl, ...result }
-        : { ...result };
+    const report = options.schemaUrl ? { $schema: options.schemaUrl, ...result } : { ...result };
     const jsonReadyReport = JSON.parse(JSON.stringify(report));
     if (options.validate) {
         const schemaPath = resolveSchemaPath(options.schemaPath);
@@ -18,7 +17,11 @@ export function generateJsonReport(result, options = {}) {
 }
 function resolveSchemaPath(schemaPath) {
     if (schemaPath) {
-        return schemaPath;
+        if (isAbsolute(schemaPath)) {
+            return schemaPath;
+        }
+        const base = new URL('../../', import.meta.url);
+        return fileURLToPath(new URL(schemaPath, base));
     }
     const url = new URL(`../../${REPORT_SCHEMAS.CHECK_REPORT_SCHEMA_FILE}`, import.meta.url);
     return fileURLToPath(url);
@@ -38,7 +41,7 @@ function validateReportAgainstSchema(report, schemaPath) {
     const validate = ajv.compile(schema);
     if (!validate(report)) {
         const errorText = ajv.errorsText(validate.errors, { separator: '\n' });
-        throw new Error(`Check report schema validation failed:\n${errorText}`);
+        throw new Error(`Report schema validation failed:\n${errorText}`);
     }
 }
 //# sourceMappingURL=report.js.map

package/dist/interview/insights.d.ts

@@ -0,0 +1,17 @@
+import type { InterviewResult } from './types.js';
+import type { SemanticInference } from '../validation/semantic-types.js';
+import type { ResponseSchemaEvolution } from '../baseline/response-schema-tracker.js';
+import type { ErrorAnalysisSummary } from '../baseline/error-analyzer.js';
+import type { DocumentationScore } from '../baseline/documentation-scorer.js';
+export interface InterviewInsights {
+    semanticInferences?: Record<string, SemanticInference[]>;
+    schemaEvolution?: Record<string, ResponseSchemaEvolution>;
+    errorAnalysisSummaries?: Record<string, ErrorAnalysisSummary>;
+    documentationScore?: DocumentationScore;
+}
+/**
+ * Build derived insights from an interview result.
+ * These insights are used for documentation and JSON report enrichment.
+ */
+export declare function buildInterviewInsights(result: InterviewResult): InterviewInsights;
+//# sourceMappingURL=insights.d.ts.map