@bryan-thompson/inspector-assessment 1.34.2 → 1.35.0

package/client/lib/lib/assessment/summarizer/AssessmentSummarizer.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Assessment Summarizer
+ *
+ * Generates tiered output for large assessment results to fit within
+ * LLM context windows. Creates executive summaries and per-tool digests.
+ *
+ * Issue #136: Tiered output strategy for large assessments
+ *
+ * @module assessment/summarizer/AssessmentSummarizer
+ */
+import type { MCPDirectoryAssessment } from "../resultTypes.js";
+import { type ExecutiveSummary, type ToolSummariesCollection, type SummarizerConfig } from "./types.js";
+/**
+ * Generates tiered summaries from assessment results.
+ *
+ * @example
+ * ```typescript
+ * const summarizer = new AssessmentSummarizer();
+ * const executive = summarizer.generateExecutiveSummary(results);
+ * const toolSummaries = summarizer.generateToolSummaries(results);
+ * ```
+ */
+export declare class AssessmentSummarizer {
+    private config;
+    constructor(config?: SummarizerConfig);
+    /**
+     * Generate executive summary (Tier 1) from assessment results.
+     * Targets ~5K tokens for guaranteed LLM context fit.
+     *
+     * @param results - Full assessment results
+     * @returns Executive summary
+     */
+    generateExecutiveSummary(results: MCPDirectoryAssessment): ExecutiveSummary;
+    /**
+     * Extract per-module status and scores.
+     */
+    private extractModulesSummary;
+    /**
+     * Extract critical findings counts from all modules.
+     */
+    private extractCriticalFindings;
+    /**
+     * Calculate tool risk distribution from security test results.
+     */
+    private calculateToolRiskDistribution;
+    /**
+     * Calculate risk level based on vulnerability count.
+     */
+    private calculateToolRiskLevel;
+    /**
+     * Aggregate recommendations from all modules.
+     */
+    private aggregateRecommendations;
+    /**
+     * Calculate overall score from module scores.
+     */
+    private calculateOverallScore;
+    /**
+     * Generate tool summaries (Tier 2) from assessment results.
+     * Targets ~500 tokens per tool for efficient LLM processing.
+     *
+     * @param results - Full assessment results
+     * @returns Collection of tool summaries
+     */
+    generateToolSummaries(results: MCPDirectoryAssessment): ToolSummariesCollection;
+    /**
+     * Extract all unique tool names from assessment results.
+     */
+    private extractToolNames;
+    /**
+     * Generate summary for a single tool.
+     */
+    private generateSingleToolSummary;
+    /**
+     * Get all security tests for a specific tool.
+     */
+    private getToolTests;
+    /**
+     * Extract top vulnerability patterns from tests.
+     */
+    private extractTopPatterns;
+    /**
+     * Calculate pass rate for tests.
+     */
+    private calculatePassRate;
+    /**
+     * Get annotation info for a tool.
+     */
+    private getToolAnnotationInfo;
+    /**
+     * Generate recommendations for a specific tool.
+     */
+    private generateToolRecommendations;
+    /**
+     * Calculate aggregate statistics across all tool summaries.
+     */
+    private calculateAggregate;
+    /**
+     * Extract full detail data for a specific tool.
+     * Used when generating Tier 3 per-tool detail files.
+     *
+     * @param toolName - Tool name to extract
+     * @param results - Full assessment results
+     * @returns Tool-specific detail data
+     */
+    extractToolDetail(toolName: string, results: MCPDirectoryAssessment): Record<string, unknown>;
+    /**
+     * Get all tool names for Tier 3 file generation.
+     */
+    getAllToolNames(results: MCPDirectoryAssessment): string[];
+}
+//# sourceMappingURL=AssessmentSummarizer.d.ts.map

package/client/lib/lib/assessment/summarizer/AssessmentSummarizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssessmentSummarizer.d.ts","sourceRoot":"","sources":["../../../../src/lib/assessment/summarizer/AssessmentSummarizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,sBAAsB,EAEvB,MAAM,gBAAgB,CAAC;AAIxB,OAAO,EACL,KAAK,gBAAgB,EAErB,KAAK,uBAAuB,EAE5B,KAAK,gBAAgB,EAEtB,MAAM,SAAS,CAAC;AAMjB;;;;;;;;;GASG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAA6B;gBAE/B,MAAM,GAAE,gBAAqB;IAQzC;;;;;;OAMG;IACH,wBAAwB,CAAC,OAAO,EAAE,sBAAsB,GAAG,gBAAgB;IA2B3E;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA8C7B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;OAEG;IACH,OAAO,CAAC,6BAA6B;IAmDrC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAO9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA8BhC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA2B7B;;;;;;OAMG;IACH,qBAAqB,CACnB,OAAO,EAAE,sBAAsB,GAC9B,uBAAuB;IAoC1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA8BxB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAgCjC;;OAEG;IACH,OAAO,CAAC,YAAY;IAQpB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgB1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA8B7B;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAgCnC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA2B1B;;;;;;;OAOG;IACH,iBAAiB,CACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,sBAAsB,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IA2B1B;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,EAAE;CAG3D"}

package/client/lib/lib/assessment/summarizer/AssessmentSummarizer.js

@@ -0,0 +1,439 @@
+/**
+ * Assessment Summarizer
+ *
+ * Generates tiered output for large assessment results to fit within
+ * LLM context windows. Creates executive summaries and per-tool digests.
+ *
+ * Issue #136: Tiered output strategy for large assessments
+ *
+ * @module assessment/summarizer/AssessmentSummarizer
+ */
+import { calculateModuleScore } from "../../moduleScoring.js";
+import { estimateTokens } from "./tokenEstimator.js";
+import { DEFAULT_SUMMARIZER_CONFIG, } from "./types.js";
+// ============================================================================
+// Assessment Summarizer Class
+// ============================================================================
+/**
+ * Generates tiered summaries from assessment results.
+ *
+ * @example
+ * ```typescript
+ * const summarizer = new AssessmentSummarizer();
+ * const executive = summarizer.generateExecutiveSummary(results);
+ * const toolSummaries = summarizer.generateToolSummaries(results);
+ * ```
+ */
+export class AssessmentSummarizer {
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_SUMMARIZER_CONFIG, ...config };
+    }
+    // ==========================================================================
+    // Tier 1: Executive Summary
+    // ==========================================================================
+    /**
+     * Generate executive summary (Tier 1) from assessment results.
+     * Targets ~5K tokens for guaranteed LLM context fit.
+     *
+     * @param results - Full assessment results
+     * @returns Executive summary
+     */
+    generateExecutiveSummary(results) {
+        const modulesSummary = this.extractModulesSummary(results);
+        const criticalFindings = this.extractCriticalFindings(results);
+        const toolRiskDistribution = this.calculateToolRiskDistribution(results);
+        const recommendations = this.aggregateRecommendations(results);
+        const summary = {
+            serverName: results.serverName,
+            overallStatus: results.overallStatus,
+            overallScore: this.calculateOverallScore(results),
+            toolCount: results.functionality?.totalTools ?? 0,
+            testCount: results.totalTestsRun ?? 0,
+            executionTime: results.executionTime ?? 0,
+            modulesSummary,
+            criticalFindings,
+            toolRiskDistribution,
+            recommendations: recommendations.slice(0, this.config.maxRecommendations),
+            estimatedTokens: 0, // Will be calculated after construction
+            generatedAt: new Date().toISOString(),
+        };
+        // Calculate actual token estimate
+        summary.estimatedTokens = estimateTokens(summary);
+        return summary;
+    }
+    /**
+     * Extract per-module status and scores.
+     */
+    extractModulesSummary(results) {
+        const summary = {};
+        const moduleKeys = [
+            "functionality",
+            "security",
+            "errorHandling",
+            "aupCompliance",
+            "toolAnnotations",
+            "temporal",
+            "resources",
+            "prompts",
+            "crossCapability",
+            "protocolCompliance",
+            "developerExperience",
+            "prohibitedLibraries",
+            "manifestValidation",
+            "authentication",
+            "portability",
+            "externalAPIScanner",
+            // Legacy keys for backwards compatibility
+            "mcpSpecCompliance",
+            "documentation",
+            "usability",
+        ];
+        for (const key of moduleKeys) {
+            const module = results[key];
+            if (module && module.status) {
+                const score = calculateModuleScore(module) ?? 50;
+                summary[key] = {
+                    status: module.status,
+                    score,
+                };
+            }
+        }
+        return summary;
+    }
+    /**
+     * Extract critical findings counts from all modules.
+     */
+    extractCriticalFindings(results) {
+        return {
+            securityVulnerabilities: results.security?.vulnerabilities?.length ?? 0,
+            aupViolations: results.aupCompliance?.violations?.length ?? 0,
+            brokenTools: results.functionality?.brokenTools?.length ?? 0,
+            missingAnnotations: results.toolAnnotations?.missingAnnotationsCount ?? 0,
+        };
+    }
+    /**
+     * Calculate tool risk distribution from security test results.
+     */
+    calculateToolRiskDistribution(results) {
+        const distribution = { high: 0, medium: 0, low: 0, safe: 0 };
+        const tests = results.security?.promptInjectionTests ?? [];
+        const toolVulnCounts = new Map();
+        // Count vulnerabilities per tool
+        for (const test of tests) {
+            if (test.vulnerable && test.toolName) {
+                const current = toolVulnCounts.get(test.toolName) ?? 0;
+                toolVulnCounts.set(test.toolName, current + 1);
+            }
+        }
+        // Get all tool names
+        const allTools = new Set();
+        for (const test of tests) {
+            if (test.toolName) {
+                allTools.add(test.toolName);
+            }
+        }
+        // Categorize each tool
+        for (const toolName of allTools) {
+            const vulnCount = toolVulnCounts.get(toolName) ?? 0;
+            const riskLevel = this.calculateToolRiskLevel(vulnCount);
+            switch (riskLevel) {
+                case "HIGH":
+                    distribution.high++;
+                    break;
+                case "MEDIUM":
+                    distribution.medium++;
+                    break;
+                case "LOW":
+                    distribution.low++;
+                    break;
+                case "SAFE":
+                    distribution.safe++;
+                    break;
+            }
+        }
+        return distribution;
+    }
+    /**
+     * Calculate risk level based on vulnerability count.
+     */
+    calculateToolRiskLevel(vulnCount) {
+        if (vulnCount >= 5)
+            return "HIGH";
+        if (vulnCount >= 2)
+            return "MEDIUM";
+        if (vulnCount >= 1)
+            return "LOW";
+        return "SAFE";
+    }
+    /**
+     * Aggregate recommendations from all modules.
+     */
+    aggregateRecommendations(results) {
+        const recommendations = [];
+        // Top-level recommendations
+        if (results.recommendations) {
+            recommendations.push(...results.recommendations);
+        }
+        // Module-specific recommendations
+        const modulesWithRecs = [
+            results.errorHandling,
+            results.aupCompliance,
+            results.toolAnnotations,
+            results.developerExperience,
+            results.documentation,
+            results.usability,
+            results.prohibitedLibraries,
+            results.portability,
+        ];
+        for (const module of modulesWithRecs) {
+            if (module?.recommendations) {
+                recommendations.push(...module.recommendations);
+            }
+        }
+        // Deduplicate
+        return [...new Set(recommendations)];
+    }
+    /**
+     * Calculate overall score from module scores.
+     */
+    calculateOverallScore(results) {
+        const scores = [];
+        const coreModules = [
+            results.functionality,
+            results.security,
+            results.errorHandling,
+        ];
+        for (const module of coreModules) {
+            const score = calculateModuleScore(module);
+            if (score !== null) {
+                scores.push(score);
+            }
+        }
+        if (scores.length === 0) {
+            return results.overallStatus === "PASS" ? 100 : 0;
+        }
+        return Math.round(scores.reduce((a, b) => a + b, 0) / scores.length);
+    }
+    // ==========================================================================
+    // Tier 2: Tool Summaries
+    // ==========================================================================
+    /**
+     * Generate tool summaries (Tier 2) from assessment results.
+     * Targets ~500 tokens per tool for efficient LLM processing.
+     *
+     * @param results - Full assessment results
+     * @returns Collection of tool summaries
+     */
+    generateToolSummaries(results) {
+        const tools = [];
+        // Get all unique tool names from security tests
+        const toolNames = this.extractToolNames(results);
+        for (const toolName of toolNames) {
+            const summary = this.generateSingleToolSummary(toolName, results);
+            tools.push(summary);
+        }
+        // Sort by risk level (highest first)
+        tools.sort((a, b) => {
+            const riskOrder = {
+                HIGH: 0,
+                MEDIUM: 1,
+                LOW: 2,
+                SAFE: 3,
+            };
+            return riskOrder[a.riskLevel] - riskOrder[b.riskLevel];
+        });
+        const aggregate = this.calculateAggregate(tools);
+        const collection = {
+            tools,
+            totalTools: tools.length,
+            aggregate,
+            estimatedTokens: 0,
+            generatedAt: new Date().toISOString(),
+        };
+        collection.estimatedTokens = estimateTokens(collection);
+        return collection;
+    }
+    /**
+     * Extract all unique tool names from assessment results.
+     */
+    extractToolNames(results) {
+        const toolNames = new Set();
+        // From security tests
+        const tests = results.security?.promptInjectionTests ?? [];
+        for (const test of tests) {
+            if (test.toolName) {
+                toolNames.add(test.toolName);
+            }
+        }
+        // From functionality results
+        const funcResults = results.functionality?.toolResults ?? [];
+        for (const result of funcResults) {
+            if (result.toolName) {
+                toolNames.add(result.toolName);
+            }
+        }
+        // From annotation results
+        const annotationResults = results.toolAnnotations?.toolResults ?? [];
+        for (const result of annotationResults) {
+            if (result.toolName) {
+                toolNames.add(result.toolName);
+            }
+        }
+        return [...toolNames].sort();
+    }
+    /**
+     * Generate summary for a single tool.
+     */
+    generateSingleToolSummary(toolName, results) {
+        const tests = this.getToolTests(toolName, results);
+        const vulnCount = tests.filter((t) => t.vulnerable).length;
+        const patterns = this.extractTopPatterns(tests);
+        const passRate = this.calculatePassRate(tests);
+        const annotationInfo = this.getToolAnnotationInfo(toolName, results);
+        const summary = {
+            toolName,
+            riskLevel: this.calculateToolRiskLevel(vulnCount),
+            vulnerabilityCount: vulnCount,
+            topPatterns: patterns.slice(0, this.config.maxPatternsPerTool),
+            testCount: tests.length,
+            passRate,
+            recommendations: this.generateToolRecommendations(toolName, vulnCount, annotationInfo),
+            estimatedTokens: 0,
+            hasAnnotations: annotationInfo.hasAnnotations,
+            annotationStatus: annotationInfo.status,
+        };
+        summary.estimatedTokens = estimateTokens(summary);
+        return summary;
+    }
+    /**
+     * Get all security tests for a specific tool.
+     */
+    getToolTests(toolName, results) {
+        const tests = results.security?.promptInjectionTests ?? [];
+        return tests.filter((t) => t.toolName === toolName);
+    }
+    /**
+     * Extract top vulnerability patterns from tests.
+     */
+    extractTopPatterns(tests) {
+        const patternCounts = new Map();
+        for (const test of tests) {
+            if (test.vulnerable && test.testName) {
+                const current = patternCounts.get(test.testName) ?? 0;
+                patternCounts.set(test.testName, current + 1);
+            }
+        }
+        // Sort by count and return names
+        return [...patternCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .map(([name]) => name);
+    }
+    /**
+     * Calculate pass rate for tests.
+     */
+    calculatePassRate(tests) {
+        if (tests.length === 0)
+            return 100;
+        const passed = tests.filter((t) => !t.vulnerable).length;
+        return Math.round((passed / tests.length) * 100);
+    }
+    /**
+     * Get annotation info for a tool.
+     */
+    getToolAnnotationInfo(toolName, results) {
+        const annotationResults = results.toolAnnotations?.toolResults ?? [];
+        const toolResult = annotationResults.find((r) => r.toolName === toolName);
+        if (!toolResult) {
+            return { hasAnnotations: false, status: "MISSING" };
+        }
+        const hasAnnotations = toolResult.annotations?.readOnlyHint !== undefined ||
+            toolResult.annotations?.destructiveHint !== undefined;
+        let status;
+        if (!hasAnnotations) {
+            status = "MISSING";
+        }
+        else if (toolResult.alignmentStatus === "ALIGNED") {
+            status = "ALIGNED";
+        }
+        else if (toolResult.alignmentStatus === "MISALIGNED") {
+            status = "MISALIGNED";
+        }
+        return { hasAnnotations, status };
+    }
+    /**
+     * Generate recommendations for a specific tool.
+     */
+    generateToolRecommendations(toolName, vulnCount, annotationInfo) {
+        const recommendations = [];
+        if (vulnCount >= 5) {
+            recommendations.push(`Critical: ${toolName} has ${vulnCount} vulnerabilities - requires immediate security review`);
+        }
+        else if (vulnCount >= 2) {
+            recommendations.push(`${toolName} has ${vulnCount} vulnerabilities - review input validation`);
+        }
+        else if (vulnCount >= 1) {
+            recommendations.push(`${toolName} has a vulnerability - investigate and patch`);
+        }
+        if (!annotationInfo.hasAnnotations) {
+            recommendations.push(`Add readOnlyHint/destructiveHint annotations to ${toolName}`);
+        }
+        else if (annotationInfo.status === "MISALIGNED") {
+            recommendations.push(`Review annotation alignment for ${toolName}`);
+        }
+        return recommendations;
+    }
+    /**
+     * Calculate aggregate statistics across all tool summaries.
+     */
+    calculateAggregate(tools) {
+        const totalVulns = tools.reduce((sum, t) => sum + t.vulnerabilityCount, 0);
+        const avgPassRate = tools.length > 0
+            ? Math.round(tools.reduce((sum, t) => sum + t.passRate, 0) / tools.length)
+            : 100;
+        const misaligned = tools.filter((t) => t.annotationStatus === "MISALIGNED").length;
+        return {
+            totalVulnerabilities: totalVulns,
+            averagePassRate: avgPassRate,
+            misalignedAnnotations: misaligned,
+        };
+    }
+    // ==========================================================================
+    // Tier 3: Per-Tool Details (extraction helpers)
+    // ==========================================================================
+    /**
+     * Extract full detail data for a specific tool.
+     * Used when generating Tier 3 per-tool detail files.
+     *
+     * @param toolName - Tool name to extract
+     * @param results - Full assessment results
+     * @returns Tool-specific detail data
+     */
+    extractToolDetail(toolName, results) {
+        const securityTests = this.getToolTests(toolName, results);
+        const functionalityResult = results.functionality?.toolResults?.find((r) => r.toolName === toolName);
+        const annotationResult = results.toolAnnotations?.toolResults?.find((r) => r.toolName === toolName);
+        return {
+            toolName,
+            extractedAt: new Date().toISOString(),
+            security: {
+                tests: securityTests,
+                vulnerableCount: securityTests.filter((t) => t.vulnerable).length,
+                totalTests: securityTests.length,
+            },
+            functionality: functionalityResult ?? null,
+            annotations: annotationResult ?? null,
+            estimatedTokens: estimateTokens({
+                security: { tests: securityTests },
+                functionality: functionalityResult,
+                annotations: annotationResult,
+            }),
+        };
+    }
+    /**
+     * Get all tool names for Tier 3 file generation.
+     */
+    getAllToolNames(results) {
+        return this.extractToolNames(results);
+    }
+}

package/client/lib/lib/assessment/summarizer/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Assessment Summarizer Module
+ *
+ * Generates tiered output for large assessment results to fit within
+ * LLM context windows.
+ *
+ * Issue #136: Tiered output strategy for large assessments
+ *
+ * @module assessment/summarizer
+ */
+export type { OutputFormat, ToolRiskLevel, ExecutiveSummary, ToolSummary, ToolSummariesCollection, ToolDetailReference, TieredOutput, SummarizerConfig, } from "./types.js";
+export { DEFAULT_SUMMARIZER_CONFIG } from "./types.js";
+export { estimateTokens, estimateJsonFileTokens, shouldAutoTier, formatTokenEstimate, estimateSectionTokens, getTopSections, } from "./tokenEstimator.js";
+export { AssessmentSummarizer } from "./AssessmentSummarizer.js";
+//# sourceMappingURL=index.d.ts.map

package/client/lib/lib/assessment/summarizer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/assessment/summarizer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,uBAAuB,EACvB,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAGpD,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}

package/client/lib/lib/assessment/summarizer/index.js

@@ -0,0 +1,15 @@
+/**
+ * Assessment Summarizer Module
+ *
+ * Generates tiered output for large assessment results to fit within
+ * LLM context windows.
+ *
+ * Issue #136: Tiered output strategy for large assessments
+ *
+ * @module assessment/summarizer
+ */
+export { DEFAULT_SUMMARIZER_CONFIG } from "./types.js";
+// Token estimation utilities
+export { estimateTokens, estimateJsonFileTokens, shouldAutoTier, formatTokenEstimate, estimateSectionTokens, getTopSections, } from "./tokenEstimator.js";
+// Main summarizer class
+export { AssessmentSummarizer } from "./AssessmentSummarizer.js";

package/client/lib/lib/assessment/summarizer/tokenEstimator.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Token Estimation Utilities
+ *
+ * Provides token counting and threshold detection for tiered output strategy.
+ * Uses industry-standard approximation of ~4 characters per token.
+ *
+ * Issue #136: Tiered output strategy for large assessments
+ *
+ * @module assessment/summarizer/tokenEstimator
+ */
+import type { MCPDirectoryAssessment } from "../resultTypes.js";
+/**
+ * Estimate the number of tokens for any content.
+ *
+ * Uses the industry-standard approximation of ~4 characters per token.
+ * For JSON content, applies a buffer for formatting overhead.
+ *
+ * @param content - Content to estimate (string, object, or array)
+ * @returns Estimated token count
+ *
+ * @example
+ * ```typescript
+ * // String content
+ * estimateTokens("Hello world"); // ~3 tokens
+ *
+ * // Object content (will be JSON stringified)
+ * estimateTokens({ name: "test", value: 123 }); // ~10 tokens
+ *
+ * // Large assessment results
+ * estimateTokens(assessmentResults); // ~50,000+ tokens
+ * ```
+ */
+export declare function estimateTokens(content: unknown): number;
+/**
+ * Estimate tokens for a JSON file that would be written.
+ * Accounts for pretty-printing with indent=2.
+ *
+ * @param content - Content that would be JSON.stringify'd
+ * @returns Estimated token count
+ */
+export declare function estimateJsonFileTokens(content: unknown): number;
+/**
+ * Determine if assessment results should automatically use tiered output.
+ *
+ * Returns true when estimated token count exceeds the threshold,
+ * indicating the full output would not fit in typical LLM context windows.
+ *
+ * @param results - Full assessment results
+ * @param threshold - Token threshold (default: 100,000)
+ * @returns true if results should be tiered
+ *
+ * @example
+ * ```typescript
+ * const results = await runAssessment(server);
+ *
+ * if (shouldAutoTier(results)) {
+ *   // Use tiered output
+ *   saveTieredResults(serverName, results, options);
+ * } else {
+ *   // Use standard full output
+ *   saveResults(serverName, results, options);
+ * }
+ * ```
+ */
+export declare function shouldAutoTier(results: MCPDirectoryAssessment, threshold?: number): boolean;
+/**
+ * Get a human-readable token estimate with size category.
+ *
+ * @param tokenCount - Number of tokens
+ * @returns Object with formatted token count and size category
+ *
+ * @example
+ * ```typescript
+ * formatTokenEstimate(5000);
+ * // { tokens: "5,000", category: "small", fitsContext: true }
+ *
+ * formatTokenEstimate(500000);
+ * // { tokens: "500,000", category: "very-large", fitsContext: false }
+ * ```
+ */
+export declare function formatTokenEstimate(tokenCount: number): {
+    tokens: string;
+    category: "small" | "medium" | "large" | "very-large" | "oversized";
+    fitsContext: boolean;
+    recommendation: string;
+};
+/**
+ * Estimate tokens for each major section of assessment results.
+ * Useful for understanding which modules contribute most to output size.
+ *
+ * @param results - Assessment results to analyze
+ * @returns Map of section name to estimated token count
+ */
+export declare function estimateSectionTokens(results: MCPDirectoryAssessment): Record<string, number>;
+/**
+ * Get the top N largest sections by token count.
+ *
+ * @param results - Assessment results
+ * @param topN - Number of sections to return (default: 5)
+ * @returns Array of [sectionName, tokenCount] sorted by size descending
+ */
+export declare function getTopSections(results: MCPDirectoryAssessment, topN?: number): Array<[string, number]>;
+//# sourceMappingURL=tokenEstimator.d.ts.map