/**
 * Documentation quality scoring for MCP tools.
 *
 * Calculates documentation quality metrics including:
 * - Description coverage (percentage of tools with descriptions)
 * - Description quality (depth, clarity, actionable language)
 * - Parameter documentation (percentage of params documented)
 * - Example coverage (percentage of tools with examples)
 *
 * Overall score: 0-100 with grade A-F.
 */
import type { MCPTool } from '../transport/types.js';
/**
 * Issue severity levels for documentation problems.
 */
export type DocumentationIssueSeverity = 'error' | 'warning' | 'info';
/**
 * Types of documentation issues that can be detected.
 */
export type DocumentationIssueType = 'missing_description' | 'short_description' | 'missing_param_description' | 'no_examples';
/**
 * A specific documentation issue found during scoring.
 */
export interface DocumentationIssue {
    /** Tool name where issue was found */
    tool: string;
    /** Type of issue */
    type: DocumentationIssueType;
    /** Severity level */
    severity: DocumentationIssueSeverity;
    /** Human-readable message describing the issue */
    message: string;
    /** Parameter name (for parameter-specific issues) */
    paramName?: string;
}
/**
 * Component scores that make up the overall documentation score.
 */
export interface DocumentationComponents {
    /** Percentage of tools with descriptions (0-100) */
    descriptionCoverage: number;
    /** Quality score for descriptions (0-100) */
    descriptionQuality: number;
    /** Percentage of parameters with descriptions (0-100) */
    parameterDocumentation: number;
    /** Percentage of tools with examples (0-100) */
    exampleCoverage: number;
}
/**
 * Documentation grade (A-F).
 */
export type DocumentationGrade = 'A' | 'B' | 'C' | 'D' | 'F';
/**
 * Complete documentation quality score for a set of tools.
 */
export interface DocumentationScore {
    /** Overall score (0-100) */
    overallScore: number;
    /** Grade (A-F) */
    grade: DocumentationGrade;
    /** Component scores */
    components: DocumentationComponents;
    /** Specific issues found */
    issues: DocumentationIssue[];
    /** Improvement suggestions */
    suggestions: string[];
    /** Number of tools scored */
    toolCount: number;
}
/**
 * Score for a single tool's documentation.
 */
export interface ToolDocumentationScore {
    /** Tool name */
    tool: string;
    /** Individual score (0-100) */
    score: number;
    /** Issues found for this tool */
    issues: DocumentationIssue[];
}
/**
 * Change in documentation score between baselines.
 */
export interface DocumentationScoreChange {
    /** Previous overall score */
    previousScore: number;
    /** Current overall score */
    currentScore: number;
    /** Score change (positive = improved) */
    change: number;
    /** Previous grade */
    previousGrade: DocumentationGrade;
    /** Current grade */
    currentGrade: DocumentationGrade;
    /** Whether documentation improved */
    improved: boolean;
    /** Whether documentation degraded */
    degraded: boolean;
    /** Issues that were fixed */
    issuesFixed: number;
    /** New issues introduced */
    newIssues: number;
    /** Human-readable summary */
    summary: string;
}
/**
 * Serializable documentation score summary for baseline storage.
 */
export interface DocumentationScoreSummary {
    /** Overall score (0-100) */
    overallScore: number;
    /** Grade (A-F) */
    grade: string;
    /** Number of issues found */
    issueCount: number;
    /** Number of tools scored */
    toolCount: number;
}
/**
 * Score documentation quality for a set of tools.
 *
 * @param tools - Array of MCP tools to score
 * @returns Complete documentation score with components, issues, and suggestions
 */
export declare function scoreDocumentation(tools: MCPTool[]): DocumentationScore;
/**
 * Score a single tool's documentation quality.
 *
 * @param tool - MCP tool to score
 * @returns Tool score with issues
 */
export declare function scoreToolDocumentation(tool: MCPTool): ToolDocumentationScore;
/**
 * Calculate description coverage score.
 * Percentage of tools that have non-empty descriptions.
 */
export declare function calculateDescriptionCoverage(tools: MCPTool[]): number;
/**
 * Calculate description quality score.
 * Assesses length, imperative mood, behavior description, and examples.
 */
export declare function calculateDescriptionQuality(tools: MCPTool[]): number;
/**
 * Calculate parameter documentation score.
 * Percentage of parameters across all tools that have descriptions.
 */
export declare function calculateParameterDocumentation(tools: MCPTool[]): number;
/**
 * Calculate example coverage score.
 * Percentage of tools that have schema-level or property-level examples.
 */
export declare function calculateExampleCoverage(tools: MCPTool[]): number;
/**
 * Check if a tool has any examples defined in its schema.
 */
export declare function hasExamples(tool: MCPTool): boolean;
/**
 * Convert a numeric score to a letter grade.
 */
export declare function scoreToGrade(score: number): DocumentationGrade;
/**
 * Generate improvement suggestions based on issues found.
 */
export declare function generateSuggestions(issues: DocumentationIssue[], tools: MCPTool[]): string[];
/**
 * Compare documentation scores between baselines.
 *
 * @param previous - Previous documentation score (or summary)
 * @param current - Current documentation score
 * @returns Change analysis
 */
export declare function compareDocumentationScores(previous: DocumentationScore | DocumentationScoreSummary | undefined, current: DocumentationScore): DocumentationScoreChange;
/**
 * Format documentation score as a human-readable string.
 */
export declare function formatDocumentationScore(score: DocumentationScore): string;
/**
 * Format documentation score as a compact one-line summary.
 */
export declare function formatDocumentationScoreCompact(score: DocumentationScore): string;
/**
 * Format documentation score change as a human-readable string.
 */
export declare function formatDocumentationScoreChange(change: DocumentationScoreChange): string;
/**
 * Convert documentation score to a serializable summary for baseline storage.
 */
export declare function toDocumentationScoreSummary(score: DocumentationScore): DocumentationScoreSummary;
/**
 * Get the text indicator for a documentation grade.
 */
export declare function getGradeIndicator(grade: DocumentationGrade): string;
/**
 * Get the badge color for a documentation grade.
 */
export declare function getGradeBadgeColor(grade: DocumentationGrade): 'green' | 'yellow' | 'orange' | 'red';
/**
 * Check if a documentation score meets a minimum threshold.
 */
export declare function meetsDocumentationThreshold(score: DocumentationScore, minScore: number): boolean;
/**
 * Check if documentation score meets a minimum grade.
 */
export declare function meetsDocumentationGrade(score: DocumentationScore, minGrade: DocumentationGrade): boolean;
//# sourceMappingURL=documentation-scorer.d.ts.map