@aiready/core 0.9.22 → 0.9.25

package/dist/client.d.mts

@@ -0,0 +1,547 @@
+interface AnalysisResult {
+    fileName: string;
+    issues: Issue[];
+    metrics: Metrics;
+}
+interface Issue {
+    type: IssueType;
+    severity: 'critical' | 'major' | 'minor' | 'info';
+    message: string;
+    location: Location;
+    suggestion?: string;
+}
+type IssueType = 'duplicate-pattern' | 'context-fragmentation' | 'doc-drift' | 'naming-inconsistency' | 'naming-quality' | 'pattern-inconsistency' | 'architecture-inconsistency' | 'dead-code' | 'circular-dependency' | 'missing-types';
+interface Location {
+    file: string;
+    line: number;
+    column?: number;
+    endLine?: number;
+    endColumn?: number;
+}
+interface Metrics {
+    tokenCost?: number;
+    complexityScore?: number;
+    consistencyScore?: number;
+    docFreshnessScore?: number;
+    estimatedMonthlyCost?: number;
+    estimatedDeveloperHours?: number;
+    comprehensionDifficultyIndex?: number;
+}
+/**
+ * Cost estimation configuration
+ */
+interface CostConfig {
+    /** Price per 1K tokens (default: $0.01 for GPT-4) */
+    pricePer1KTokens: number;
+    /** Average AI queries per developer per day */
+    queriesPerDevPerDay: number;
+    /** Number of developers on the team */
+    developerCount: number;
+    /** Days per month (default: 30) */
+    daysPerMonth: number;
+}
+/**
+ * Productivity impact estimates
+ */
+interface ProductivityImpact {
+    /** Estimated hours to fix all issues */
+    totalHours: number;
+    /** Average hourly rate for developers */
+    hourlyRate: number;
+    /** Estimated total fix cost */
+    totalCost: number;
+    /** Breakdown by severity */
+    bySeverity: {
+        critical: {
+            hours: number;
+            cost: number;
+        };
+        major: {
+            hours: number;
+            cost: number;
+        };
+        minor: {
+            hours: number;
+            cost: number;
+        };
+    };
+}
+/**
+ * AI acceptance rate prediction
+ * Based on research correlating code quality to AI suggestion acceptance
+ */
+interface AcceptancePrediction {
+    /** Predicted acceptance rate (0-1) */
+    rate: number;
+    /** Confidence level (0-1) */
+    confidence: number;
+    /** Factors affecting acceptance */
+    factors: {
+        name: string;
+        impact: number;
+    }[];
+}
+/**
+ * Comprehension difficulty score (future-proof abstraction)
+ * Normalized 0-100 scale: lower = easier for AI to understand
+ */
+interface ComprehensionDifficulty {
+    /** Overall difficulty score (0-100) */
+    score: number;
+    /** Factors contributing to difficulty */
+    factors: {
+        name: string;
+        contribution: number;
+        description: string;
+    }[];
+    /** Interpretation */
+    rating: 'trivial' | 'easy' | 'moderate' | 'difficult' | 'expert';
+}
+/**
+ * Extended report with business metrics
+ */
+interface BusinessReport extends Report {
+    businessMetrics: {
+        /** Estimated monthly cost impact of AI context waste */
+        estimatedMonthlyCost: number;
+        /** Estimated developer hours to address issues */
+        estimatedDeveloperHours: number;
+        /** Predicted AI suggestion acceptance rate */
+        aiAcceptanceRate: number;
+        /** Comprehension difficulty assessment */
+        comprehensionDifficulty: ComprehensionDifficulty;
+        /** Timestamp for trend tracking */
+        period?: string;
+    };
+}
+interface ScanOptions {
+    rootDir: string;
+    include?: string[];
+    exclude?: string[];
+    maxDepth?: number;
+}
+interface AIReadyConfig {
+    scan?: {
+        include?: string[];
+        exclude?: string[];
+        tools?: string[];
+    };
+    tools?: {
+        'pattern-detect'?: {
+            enabled?: boolean;
+            scoreWeight?: number;
+            minSimilarity?: number;
+            minLines?: number;
+            batchSize?: number;
+            approx?: boolean;
+            minSharedTokens?: number;
+            maxCandidatesPerBlock?: number;
+            streamResults?: boolean;
+            maxResults?: number;
+        };
+        'context-analyzer'?: {
+            enabled?: boolean;
+            scoreWeight?: number;
+            maxDepth?: number;
+            maxContextBudget?: number;
+            minCohesion?: number;
+            maxFragmentation?: number;
+            focus?: 'fragmentation' | 'cohesion' | 'depth' | 'all';
+            includeNodeModules?: boolean;
+            maxResults?: number;
+            domainKeywords?: string[];
+            domainPatterns?: string[];
+            pathDomainMap?: Record<string, string>;
+        };
+        'consistency'?: {
+            enabled?: boolean;
+            scoreWeight?: number;
+            acceptedAbbreviations?: string[];
+            shortWords?: string[];
+            disableChecks?: ('single-letter' | 'abbreviation' | 'convention-mix' | 'unclear' | 'poor-naming')[];
+        };
+        [toolName: string]: {
+            enabled?: boolean;
+            scoreWeight?: number;
+            [key: string]: any;
+        } | undefined;
+    };
+    scoring?: {
+        threshold?: number;
+        showBreakdown?: boolean;
+        compareBaseline?: string;
+        saveTo?: string;
+    };
+    output?: {
+        format?: 'console' | 'json' | 'html';
+        file?: string;
+    };
+    visualizer?: {
+        groupingDirs?: string[];
+        graph?: {
+            maxNodes?: number;
+            maxEdges?: number;
+        };
+    };
+}
+interface Report {
+    summary: {
+        totalFiles: number;
+        totalIssues: number;
+        criticalIssues: number;
+        majorIssues: number;
+    };
+    results: AnalysisResult[];
+    metrics: {
+        overallScore: number;
+        tokenCostTotal: number;
+        avgConsistency: number;
+    };
+}
+/**
+ * Severity levels for issues
+ */
+type GraphIssueSeverity = 'critical' | 'major' | 'minor' | 'info';
+/**
+ * Base graph node
+ */
+interface GraphNode {
+    id: string;
+    label: string;
+    path?: string;
+    size?: number;
+    value?: number;
+    color?: string;
+    group?: string;
+    x?: number;
+    y?: number;
+}
+/**
+ * Graph edge between nodes
+ */
+interface GraphEdge {
+    source: string | GraphNode;
+    target: string | GraphNode;
+    type?: string;
+    weight?: number;
+}
+/**
+ * Graph metadata
+ */
+interface GraphMetadata {
+    projectName?: string;
+    timestamp: string;
+    totalFiles: number;
+    totalDependencies: number;
+    analysisTypes: string[];
+    criticalIssues: number;
+    majorIssues: number;
+    minorIssues: number;
+    infoIssues: number;
+}
+/**
+ * Complete graph data structure for visualization
+ */
+interface GraphData {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    clusters?: {
+        id: string;
+        name: string;
+        nodeIds: string[];
+    }[];
+    issues?: {
+        id: string;
+        type: string;
+        severity: GraphIssueSeverity;
+        nodeIds: string[];
+        message: string;
+    }[];
+    metadata: GraphMetadata;
+}
+
+/**
+ * Language-agnostic AST and parser interfaces for multi-language support
+ *
+ * This module provides abstractions for parsing different programming languages
+ * while maintaining a consistent interface for analysis tools.
+ */
+/**
+ * Supported programming languages
+ */
+declare enum Language {
+    TypeScript = "typescript",
+    JavaScript = "javascript",
+    Python = "python",
+    Java = "java",
+    Go = "go",
+    Rust = "rust",
+    CSharp = "csharp"
+}
+/**
+ * File extensions mapped to languages
+ */
+declare const LANGUAGE_EXTENSIONS: Record<string, Language>;
+/**
+ * Location information in source code
+ */
+interface SourceLocation {
+    line: number;
+    column: number;
+}
+interface SourceRange {
+    start: SourceLocation;
+    end: SourceLocation;
+}
+/**
+ * Common AST node type (language-agnostic)
+ */
+interface CommonASTNode {
+    type: string;
+    loc?: SourceRange;
+    raw?: any;
+}
+/**
+ * Export information (function, class, variable, etc.)
+ */
+interface ExportInfo {
+    name: string;
+    type: 'function' | 'class' | 'const' | 'type' | 'interface' | 'default' | 'variable';
+    loc?: SourceRange;
+    /** Imports used within this export */
+    imports?: string[];
+    /** Dependencies on other exports in same file */
+    dependencies?: string[];
+    /** TypeScript types referenced */
+    typeReferences?: string[];
+    /** For methods: parent class name */
+    parentClass?: string;
+    /** For functions/methods: parameters */
+    parameters?: string[];
+    /** Visibility (public, private, protected) */
+    visibility?: 'public' | 'private' | 'protected';
+}
+/**
+ * Import information
+ */
+interface ImportInfo {
+    /** Module being imported from */
+    source: string;
+    /** What's being imported */
+    specifiers: string[];
+    /** Is this a type-only import (TypeScript) */
+    isTypeOnly?: boolean;
+    /** Location in source */
+    loc?: SourceRange;
+}
+/**
+ * Parse result containing exports and imports
+ */
+interface ParseResult {
+    exports: ExportInfo[];
+    imports: ImportInfo[];
+    /** Language of the parsed file */
+    language: Language;
+    /** Any parse warnings (non-fatal) */
+    warnings?: string[];
+}
+/**
+ * Naming convention rules per language
+ */
+interface NamingConvention {
+    /** Allowed variable naming patterns */
+    variablePattern: RegExp;
+    /** Allowed function naming patterns */
+    functionPattern: RegExp;
+    /** Allowed class naming patterns */
+    classPattern: RegExp;
+    /** Allowed constant naming patterns */
+    constantPattern: RegExp;
+    /** Language-specific exceptions (e.g., __init__ in Python) */
+    exceptions?: string[];
+}
+/**
+ * Language-specific configuration
+ */
+interface LanguageConfig {
+    language: Language;
+    /** File extensions for this language */
+    extensions: string[];
+    /** Naming conventions */
+    namingConventions: NamingConvention;
+    /** Common abbreviations allowed */
+    allowedAbbreviations?: string[];
+    /** Language-specific keywords to ignore */
+    keywords?: string[];
+}
+/**
+ * Abstract interface for language parsers
+ * Each language implementation should implement this interface
+ */
+interface LanguageParser {
+    /** Language this parser handles */
+    readonly language: Language;
+    /** File extensions this parser supports */
+    readonly extensions: string[];
+    /**
+     * Parse source code and extract structure
+     * @param code - Source code to parse
+     * @param filePath - Path to the file (for context)
+     * @returns Parse result with exports and imports
+     * @throws ParseError if code has syntax errors
+     */
+    parse(code: string, filePath: string): ParseResult;
+    /**
+     * Get naming conventions for this language
+     */
+    getNamingConventions(): NamingConvention;
+    /**
+     * Check if this parser can handle a file
+     * @param filePath - File path to check
+     */
+    canHandle(filePath: string): boolean;
+}
+/**
+ * Parser error with location information
+ */
+declare class ParseError extends Error {
+    readonly filePath: string;
+    readonly loc?: SourceLocation | undefined;
+    constructor(message: string, filePath: string, loc?: SourceLocation | undefined);
+}
+/**
+ * Statistics about parsed code
+ */
+interface ParseStatistics {
+    language: Language;
+    filesAnalyzed: number;
+    totalExports: number;
+    totalImports: number;
+    parseErrors: number;
+    warnings: number;
+}
+
+/**
+ * AI Readiness Scoring System
+ *
+ * Provides dynamic, composable scoring across multiple analysis tools.
+ * Each tool contributes a 0-100 score with configurable weights.
+ */
+interface ToolScoringOutput {
+    /** Unique tool identifier (e.g., "pattern-detect") */
+    toolName: string;
+    /** Normalized 0-100 score for this tool */
+    score: number;
+    /** Raw metrics used to calculate the score */
+    rawMetrics: Record<string, any>;
+    /** Factors that influenced the score */
+    factors: Array<{
+        name: string;
+        impact: number;
+        description: string;
+    }>;
+    /** Actionable recommendations with estimated impact */
+    recommendations: Array<{
+        action: string;
+        estimatedImpact: number;
+        priority: 'high' | 'medium' | 'low';
+    }>;
+}
+interface ScoringResult {
+    /** Overall AI Readiness Score (0-100) */
+    overall: number;
+    /** Rating category */
+    rating: 'Excellent' | 'Good' | 'Fair' | 'Needs Work' | 'Critical';
+    /** Timestamp of score calculation */
+    timestamp: string;
+    /** Tools that contributed to this score */
+    toolsUsed: string[];
+    /** Breakdown by tool */
+    breakdown: ToolScoringOutput[];
+    /** Calculation details */
+    calculation: {
+        formula: string;
+        weights: Record<string, number>;
+        normalized: string;
+    };
+}
+interface ScoringConfig {
+    /** Minimum passing score (exit code 1 if below) */
+    threshold?: number;
+    /** Show detailed breakdown in output */
+    showBreakdown?: boolean;
+    /** Path to baseline JSON for comparison */
+    compareBaseline?: string;
+    /** Auto-save score to this path */
+    saveTo?: string;
+}
+/**
+ * Default weights for known tools.
+ * New tools get weight of 10 if not specified.
+ */
+declare const DEFAULT_TOOL_WEIGHTS: Record<string, number>;
+/**
+ * Tool name normalization map (shorthand -> full name)
+ */
+declare const TOOL_NAME_MAP: Record<string, string>;
+/**
+ * Normalize tool name from shorthand to full name
+ */
+declare function normalizeToolName(shortName: string): string;
+/**
+ * Get tool weight with fallback priority:
+ * 1. CLI override
+ * 2. Tool config scoreWeight
+ * 3. Default weight
+ * 4. 10 (for unknown tools)
+ */
+declare function getToolWeight(toolName: string, toolConfig?: {
+    scoreWeight?: number;
+}, cliOverride?: number): number;
+/**
+ * Parse weight string from CLI (e.g., "patterns:50,context:30")
+ */
+declare function parseWeightString(weightStr?: string): Map<string, number>;
+/**
+ * Calculate overall AI Readiness Score from multiple tool scores.
+ *
+ * Formula: Σ(tool_score × tool_weight) / Σ(active_tool_weights)
+ *
+ * This allows dynamic composition - score adjusts automatically
+ * based on which tools actually ran.
+ */
+declare function calculateOverallScore(toolOutputs: Map<string, ToolScoringOutput>, config?: any, cliWeights?: Map<string, number>): ScoringResult;
+/**
+ * Convert numeric score to rating category
+ */
+declare function getRating(score: number): ScoringResult['rating'];
+/**
+ * Get rating emoji and color for display
+ */
+declare function getRatingDisplay(rating: ScoringResult['rating']): {
+    emoji: string;
+    color: string;
+};
+/**
+ * Format score for display with rating
+ */
+declare function formatScore(result: ScoringResult): string;
+/**
+ * Format individual tool score for display
+ */
+declare function formatToolScore(output: ToolScoringOutput): string;
+
+/**
+ * Visualization utilities for generating HTML from graph data
+ */
+
+/**
+ * Generate HTML visualization from graph data
+ * Creates an interactive HTML page with a canvas-based graph visualization
+ *
+ * @param graph - The graph data to visualize
+ * @returns HTML string representing the interactive visualization
+ */
+declare function generateHTML(graph: GraphData): string;
+
+export { type AIReadyConfig, type AcceptancePrediction, type AnalysisResult, type BusinessReport, type CommonASTNode, type ComprehensionDifficulty, type CostConfig, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type GraphData, type GraphEdge, type GraphIssueSeverity, type GraphMetadata, type GraphNode, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, type ProductivityImpact, type Report, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getRating, getRatingDisplay, getToolWeight, normalizeToolName, parseWeightString };