@aiready/core 0.9.20 → 0.9.23

package/dist/index.d.ts

@@ -1,274 +1,5 @@
-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;
-}
-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;
-    };
-}
-
-/**
- * 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;
-}
+import { ScanOptions, AIReadyConfig, LanguageParser, Language, ParseResult, NamingConvention } from './client.js';
+export { AnalysisResult, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, ToolScoringOutput, calculateOverallScore, formatScore, formatToolScore, generateHTML, getRating, getRatingDisplay, getToolWeight, normalizeToolName, parseWeightString } from './client.js';
 
 declare const DEFAULT_EXCLUDE: string[];
 /**
@@ -381,116 +112,6 @@ declare function handleCLIError(error: unknown, commandName: string): never;
  */
 declare function getElapsedTime(startTime: number): string;
 
-/**
- * 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;
-
 /**
  * Parser Factory - Manages language-specific parsers
  *
@@ -619,4 +240,4 @@ declare class PythonParser implements LanguageParser {
     private extractExportsRegex;
 }
 
-export { type AIReadyConfig, type ASTNode, type AnalysisResult, type CLIOptions, type CommonASTNode, DEFAULT_EXCLUDE, DEFAULT_TOOL_WEIGHTS, type ExportInfo, type ExportWithImports, type FileImport, type ImportInfo, type Issue, type IssueType, LANGUAGE_EXTENSIONS, Language, type LanguageConfig, type LanguageParser, type Location, type Metrics, type NamingConvention, ParseError, type ParseResult, type ParseStatistics, ParserFactory, PythonParser, type Report, type ScanOptions, type ScoringConfig, type ScoringResult, type SourceLocation, type SourceRange, TOOL_NAME_MAP, type ToolScoringOutput, TypeScriptParser, calculateImportSimilarity, calculateOverallScore, estimateTokens, extractFunctions, extractImports, formatScore, formatToolScore, getElapsedTime, getFileExtension, getParser, getRating, getRatingDisplay, getSupportedLanguages, getToolWeight, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, mergeConfigWithDefaults, normalizeToolName, parseCode, parseFileExports, parseWeightString, readFileContent, resolveOutputPath, scanFiles };
+export { AIReadyConfig, type ASTNode, type CLIOptions, DEFAULT_EXCLUDE, type ExportWithImports, type FileImport, Language, LanguageParser, NamingConvention, ParseResult, ParserFactory, PythonParser, ScanOptions, TypeScriptParser, calculateImportSimilarity, estimateTokens, extractFunctions, extractImports, getElapsedTime, getFileExtension, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, mergeConfigWithDefaults, parseCode, parseFileExports, readFileContent, resolveOutputPath, scanFiles };

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   extractImports: () => extractImports,
   formatScore: () => formatScore,
   formatToolScore: () => formatToolScore,
+  generateHTML: () => generateHTML,
   getElapsedTime: () => getElapsedTime,
   getFileExtension: () => getFileExtension,
   getParser: () => getParser,
@@ -472,6 +473,172 @@ function getElapsedTime(startTime) {
   return ((Date.now() - startTime) / 1e3).toFixed(2);
 }
 
+// src/utils/visualization.ts
+function generateHTML(graph) {
+  const payload = JSON.stringify(graph, null, 2);
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AIReady Visualization</title>
+    <style>
+      html,body { height: 100%; margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0f172a; color: #e2e8f0 }
+      #container { display:flex; height:100vh }
+      #panel { width: 320px; padding: 16px; background: #071130; box-shadow: -2px 0 8px rgba(0,0,0,0.3); overflow:auto }
+      #canvasWrap { flex:1; display:flex; align-items:center; justify-content:center }
+      canvas { background: #0b1220; border-radius:8px }
+      .stat { margin-bottom:12px }
+    </style>
+  </head>
+  <body>
+    <div id="container">
+      <div id="canvasWrap"><canvas id="canvas" width="1200" height="800"></canvas></div>
+      <div id="panel">
+        <h2>AIReady Visualization</h2>
+        <div class="stat"><strong>Files:</strong> <span id="stat-files"></span></div>
+        <div class="stat"><strong>Dependencies:</strong> <span id="stat-deps"></span></div>
+        <div class="stat"><strong>Legend</strong></div>
+        <div style="font-size:13px;line-height:1.3;color:#cbd5e1;margin-top:8px">
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ff4d4f;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Critical</strong>: highest severity issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ff9900;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Major</strong>: important issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#ffd666;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Minor</strong>: low priority issues.</div>
+          <div style="margin-bottom:8px"><span style="display:inline-block;width:12px;height:12px;background:#91d5ff;margin-right:8px;border:1px solid rgba(255,255,255,0.06)"></span><strong>Info</strong>: informational notes.</div>
+          <div style="margin-top:10px;color:#94a3b8"><strong>Node size</strong>: larger = higher token cost, more issues or dependency weight.</div>
+          <div style="margin-top:6px;color:#94a3b8"><strong>Proximity</strong>: nodes that are spatially close are more contextually related; relatedness is represented by distance and size rather than explicit edges.</div>
+          <div style="margin-top:6px;color:#94a3b8"><strong>Edge colors</strong>: <span style="color:#fb7e81">Similarity</span>, <span style="color:#84c1ff">Dependency</span>, <span style="color:#ffa500">Reference</span>, default <span style="color:#334155">Other</span>.</div>
+        </div>
+      </div>
+    </div>
+
+    <script>
+      const graphData = ${payload};
+      document.getElementById('stat-files').textContent = graphData.metadata.totalFiles;
+      document.getElementById('stat-deps').textContent = graphData.metadata.totalDependencies;
+
+      const canvas = document.getElementById('canvas');
+      const ctx = canvas.getContext('2d');
+
+      const nodes = graphData.nodes.map((n, i) => ({
+        ...n,
+        x: canvas.width / 2 + Math.cos(i / graphData.nodes.length * Math.PI * 2) * (Math.min(canvas.width, canvas.height) / 3),
+        y: canvas.height / 2 + Math.sin(i / graphData.nodes.length * Math.PI * 2) * (Math.min(canvas.width, canvas.height) / 3),
+      }));
+
+      function draw() {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+        graphData.edges.forEach(edge => {
+          const s = nodes.find(n => n.id === edge.source);
+          const t = nodes.find(n => n.id === edge.target);
+          if (!s || !t) return;
+          if (edge.type === 'related') return;
+          if (edge.type === 'similarity') {
+            ctx.strokeStyle = '#fb7e81';
+            ctx.lineWidth = 1.2;
+          } else if (edge.type === 'dependency') {
+            ctx.strokeStyle = '#84c1ff';
+            ctx.lineWidth = 1.0;
+          } else if (edge.type === 'reference') {
+            ctx.strokeStyle = '#ffa500';
+            ctx.lineWidth = 0.9;
+          } else {
+            ctx.strokeStyle = '#334155';
+            ctx.lineWidth = 0.8;
+          }
+          ctx.beginPath();
+          ctx.moveTo(s.x, s.y);
+          ctx.lineTo(t.x, t.y);
+          ctx.stroke();
+        });
+
+        const groups = {};
+        nodes.forEach(n => {
+          const g = n.group || '__default';
+          if (!groups[g]) groups[g] = { minX: n.x, minY: n.y, maxX: n.x, maxY: n.y };
+          groups[g].minX = Math.min(groups[g].minX, n.x);
+          groups[g].minY = Math.min(groups[g].minY, n.y);
+          groups[g].maxX = Math.max(groups[g].maxX, n.x);
+          groups[g].maxY = Math.max(groups[g].maxY, n.y);
+        });
+
+        const groupRelations = {};
+        graphData.edges.forEach(edge => {
+          const sNode = nodes.find(n => n.id === edge.source);
+          const tNode = nodes.find(n => n.id === edge.target);
+          if (!sNode || !tNode) return;
+          const g1 = sNode.group || '__default';
+          const g2 = tNode.group || '__default';
+          if (g1 === g2) return;
+          const key = g1 < g2 ? g1 + '::' + g2 : g2 + '::' + g1;
+          groupRelations[key] = (groupRelations[key] || 0) + 1;
+        });
+
+        Object.keys(groupRelations).forEach(k => {
+          const count = groupRelations[k];
+          const [ga, gb] = k.split('::');
+          if (!groups[ga] || !groups[gb]) return;
+          const ax = (groups[ga].minX + groups[ga].maxX) / 2;
+          const ay = (groups[ga].minY + groups[ga].maxY) / 2;
+          const bx = (groups[gb].minX + groups[gb].maxX) / 2;
+          const by = (groups[gb].minY + groups[gb].maxY) / 2;
+          ctx.beginPath();
+          ctx.strokeStyle = 'rgba(148,163,184,0.25)';
+          ctx.lineWidth = Math.min(6, 0.6 + Math.sqrt(count));
+          ctx.moveTo(ax, ay);
+          ctx.lineTo(bx, by);
+          ctx.stroke();
+        });
+
+        Object.keys(groups).forEach(g => {
+          if (g === '__default') return;
+          const box = groups[g];
+          const pad = 16;
+          const x = box.minX - pad;
+          const y = box.minY - pad;
+          const w = (box.maxX - box.minX) + pad * 2;
+          const h = (box.maxY - box.minY) + pad * 2;
+          ctx.save();
+          ctx.fillStyle = 'rgba(30,64,175,0.04)';
+          ctx.strokeStyle = 'rgba(30,64,175,0.12)';
+          ctx.lineWidth = 1.2;
+          const r = 8;
+          ctx.beginPath();
+          ctx.moveTo(x + r, y);
+          ctx.arcTo(x + w, y, x + w, y + h, r);
+          ctx.arcTo(x + w, y + h, x, y + h, r);
+          ctx.arcTo(x, y + h, x, y, r);
+          ctx.arcTo(x, y, x + w, y, r);
+          ctx.closePath();
+          ctx.fill();
+          ctx.stroke();
+          ctx.restore();
+          ctx.fillStyle = '#94a3b8';
+          ctx.font = '11px sans-serif';
+          ctx.fillText(g, x + 8, y + 14);
+        });
+
+        nodes.forEach(n => {
+          const sizeVal = (n.size || n.value || 1);
+          const r = 6 + (sizeVal / 2);
+          ctx.beginPath();
+          ctx.fillStyle = n.color || '#60a5fa';
+          ctx.arc(n.x, n.y, r, 0, Math.PI * 2);
+          ctx.fill();
+
+          ctx.fillStyle = '#e2e8f0';
+          ctx.font = '11px sans-serif';
+          ctx.textAlign = 'center';
+          ctx.fillText(n.label || n.id.split('/').slice(-1)[0], n.x, n.y + r + 12);
+        });
+      }
+
+      draw();
+    </script>
+  </body>
+</html>`;
+}
+
 // src/scoring.ts
 var DEFAULT_TOOL_WEIGHTS = {
   "pattern-detect": 40,
@@ -1113,6 +1280,7 @@ function getSupportedLanguages() {
   extractImports,
   formatScore,
   formatToolScore,
+  generateHTML,
   getElapsedTime,
   getFileExtension,
   getParser,