@revealui/mcp 0.0.1-pre.0 → 0.1.0

package/dist/scripts/lib/validators/documentation-validator.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Unified Documentation Validator
+ *
+ * Consolidates logic from:
+ * - analyze/docs.ts (JSDoc coverage, quality metrics)
+ * - validate/validate-docs.ts (JSDoc, references)
+ * - validate/validate-docs-comprehensive.ts (script refs, links, patterns)
+ * - analyze/audit-docs.ts (false claim detection)
+ *
+ * Provides modular validators for comprehensive documentation validation.
+ *
+ * @dependencies
+ * - node:fs - Synchronous file system checks
+ * - node:fs/promises - File system operations for reading documentation
+ * - node:path - Path manipulation utilities
+ */
+export interface ValidationIssue {
+    file: string;
+    line?: number;
+    column?: number;
+    severity: 'critical' | 'high' | 'medium' | 'low' | 'info' | 'error' | 'warning';
+    category: ValidationCategory;
+    message: string;
+    suggestedFix?: string;
+    actual?: string;
+    expected?: string;
+}
+export type ValidationCategory = 'broken-link' | 'nonexistent-script' | 'nonexistent-directory' | 'outdated-package' | 'incorrect-path' | 'deprecated-reference' | 'version-mismatch' | 'naming-inconsistency' | 'false-claim' | 'missing-jsdoc' | 'incomplete-jsdoc';
+export interface JSDocCoverage {
+    totalExports: number;
+    documentedExports: number;
+    coverage: number;
+    undocumented: Array<{
+        file: string;
+        exports: string[];
+    }>;
+}
+export interface QualityMetrics {
+    totalFiles: number;
+    totalSize: number;
+    avgFileSize: number;
+    largestFile: {
+        path: string;
+        size: number;
+    };
+    oldestFile: {
+        path: string;
+        mtime: Date;
+    };
+    newestFile: {
+        path: string;
+        mtime: Date;
+    };
+    filesByExtension: Record<string, number>;
+    filesByAge: {
+        lastWeek: number;
+        lastMonth: number;
+        lastQuarter: number;
+        older: number;
+    };
+}
+export interface ValidationResult {
+    totalFiles: number;
+    totalIssues: number;
+    bySeverity: Record<string, number>;
+    byCategory: Record<string, number>;
+    issues: ValidationIssue[];
+    accuracyScore: number;
+}
+export interface DocValidationOptions {
+    projectRoot: string;
+    validateLinks?: boolean;
+    validateJSDoc?: boolean;
+    validateScriptRefs?: boolean;
+    validateFalseClaims?: boolean;
+    validateDeprecated?: boolean;
+    validateNaming?: boolean;
+}
+/**
+ * Find all markdown and documentation files in the project.
+ * Scans common documentation locations and optionally source files.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param includeSource - Whether to include source files (*.ts, *.tsx) for JSDoc validation
+ * @returns Array of relative file paths to documentation files
+ *
+ * @example
+ * ```typescript
+ * // Find only markdown files
+ * const mdFiles = await findDocumentationFiles('/app')
+ * console.log(`Found ${mdFiles.length} markdown files`)
+ *
+ * // Include source files for JSDoc analysis
+ * const allFiles = await findDocumentationFiles('/app', true)
+ * ```
+ */
+export declare function findDocumentationFiles(projectRoot: string, includeSource?: boolean): Promise<string[]>;
+/**
+ * Validate links in markdown content for broken references.
+ * Checks relative file links (ignoring HTTP/HTTPS and anchor-only links).
+ *
+ * @param content - Markdown file content to validate
+ * @param filePath - Relative path to the markdown file (for error reporting)
+ * @param projectRoot - Root directory of the project
+ * @returns Array of validation issues for broken links
+ *
+ * @example
+ * ```typescript
+ * const content = await readFile('README.md', 'utf-8')
+ * const issues = await validateLinks(content, 'README.md', process.cwd())
+ *
+ * issues.forEach(issue => {
+ *   console.log(`${issue.file}:${issue.line} - ${issue.message}`)
+ * })
+ * ```
+ */
+export declare function validateLinks(content: string, filePath: string, projectRoot: string): Promise<ValidationIssue[]>;
+/**
+ * Validate JSDoc coverage in source files
+ */
+export declare function validateJSDoc(filePath: string, projectRoot: string): Promise<ValidationIssue[]>;
+/**
+ * Calculate JSDoc coverage across project source directories.
+ * Analyzes exported functions and classes for JSDoc documentation.
+ *
+ * @param sourceDirs - Array of source directories to scan (e.g., ['packages', 'apps'])
+ * @param projectRoot - Root directory of the project
+ * @returns JSDoc coverage statistics including percentage and undocumented exports
+ *
+ * @example
+ * ```typescript
+ * const coverage = await calculateJSDocCoverage(
+ *   ['packages', 'apps'],
+ *   process.cwd()
+ * )
+ *
+ * console.log(`JSDoc Coverage: ${coverage.coverage}%`)
+ * console.log(`Total exports: ${coverage.totalExports}`)
+ * console.log(`Documented: ${coverage.documentedExports}`)
+ * console.log(`Undocumented: ${coverage.undocumented.length}`)
+ *
+ * coverage.undocumented.forEach(item => {
+ *   console.log(`Missing JSDoc in ${item.file}:`)
+ *   item.exports.forEach(exp => console.log(`  - ${exp}`))
+ * })
+ * ```
+ */
+export declare function calculateJSDocCoverage(sourceDirs: string[], projectRoot: string): Promise<JSDocCoverage>;
+/**
+ * Validate script references in documentation
+ */
+export declare function validateScriptRefs(content: string, filePath: string, projectRoot: string): Promise<ValidationIssue[]>;
+/**
+ * Validate for false claims in documentation
+ */
+export declare function validateFalseClaims(content: string, filePath: string): Promise<ValidationIssue[]>;
+/**
+ * Validate for deprecated references
+ */
+export declare function validateDeprecated(content: string, filePath: string): Promise<ValidationIssue[]>;
+/**
+ * Calculate quality metrics for documentation
+ */
+export declare function calculateQualityMetrics(files: string[], projectRoot: string): Promise<QualityMetrics>;
+/**
+ * Comprehensive documentation validator for validating markdown files,
+ * JSDoc coverage, links, script references, and documentation quality.
+ *
+ * Consolidates functionality from:
+ * - analyze/docs.ts
+ * - validate/validate-docs.ts
+ * - validate/validate-docs-comprehensive.ts
+ * - analyze/audit-docs.ts
+ *
+ * @example
+ * ```typescript
+ * const validator = new DocumentationValidator('/path/to/project')
+ *
+ * // Validate everything
+ * const result = await validator.validate()
+ * console.log(`Found ${result.issues.length} issues`)
+ * console.log(`By category:`, result.byCategory)
+ *
+ * // Validate only links
+ * const linkResult = await validator.validate({
+ *   validateLinks: true,
+ *   validateJSDoc: false,
+ *   validateScriptRefs: false
+ * })
+ *
+ * // Get JSDoc coverage metrics
+ * const coverage = await validator.getJSDocCoverage()
+ * console.log(`JSDoc coverage: ${coverage.coverage}%`)
+ * ```
+ */
+export declare class DocumentationValidator {
+    private projectRoot;
+    /**
+     * Create a new DocumentationValidator instance.
+     *
+     * @param projectRoot - Root directory of the project
+     */
+    constructor(projectRoot: string);
+    /**
+     * Validate all aspects of documentation with comprehensive checks.
+     * Scans markdown files and optionally source code for various issues.
+     *
+     * @param options - Validation options (all checks enabled by default)
+     * @returns Validation result with issues grouped by category and severity
+     *
+     * @example
+     * ```typescript
+     * const validator = new DocumentationValidator(process.cwd())
+     *
+     * // Full validation
+     * const result = await validator.validate()
+     *
+     * // Selective validation
+     * const result = await validator.validate({
+     *   validateLinks: true,
+     *   validateJSDoc: false,
+     *   validateScriptRefs: true,
+     *   validateFalseClaims: true
+     * })
+     *
+     * // Print results
+     * console.log(`Total issues: ${result.issues.length}`)
+     * console.log(`Errors: ${result.bySeverity.error}`)
+     * console.log(`Warnings: ${result.bySeverity.warning}`)
+     * ```
+     */
+    validate(options?: Partial<DocValidationOptions>): Promise<ValidationResult>;
+    /**
+     * Get JSDoc coverage across the project
+     */
+    getJSDocCoverage(): Promise<JSDocCoverage>;
+    /**
+     * Get quality metrics for documentation
+     */
+    getQualityMetrics(): Promise<QualityMetrics>;
+}
+//# sourceMappingURL=documentation-validator.d.ts.map

package/dist/scripts/lib/validators/documentation-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation-validator.d.ts","sourceRoot":"","sources":["../../../../../../scripts/lib/validators/documentation-validator.ts"],"names":[],"mappings":"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"}