@aiready/cli 0.14.2 → 0.14.4

package/src/commands/scan.ts

@@ -9,28 +9,20 @@ import {
   loadMergedConfig,
   handleJSONOutput,
   handleCLIError,
-  getElapsedTime,
   resolveOutputPath,
-  formatScore,
-  formatToolScore,
-  calculateTokenBudget,
-  estimateCostFromBudget,
-  getModelPreset,
-  getRating,
-  getRatingDisplay,
   getRepoMetadata,
-  Severity,
-  IssueType,
+  calculateTokenBudget,
   ToolName,
-  ToolRegistry,
   emitIssuesAsAnnotations,
 } from '@aiready/core';
 import { analyzeUnified, scoreUnified, type ScoringResult } from '../index';
+import { getReportTimestamp, warnIfGraphCapExceeded } from '../utils/helpers';
 import {
-  getReportTimestamp,
-  warnIfGraphCapExceeded,
-  truncateArray,
-} from '../utils/helpers';
+  printScanSummary,
+  printBusinessImpact,
+  printScoring,
+  mapToUnifiedReport,
+} from './report-formatter';
 import { uploadAction } from './upload';
 
 interface ScanOptions {
@@ -53,6 +45,14 @@ interface ScanOptions {
   server?: string;
 }
 
+/**
+ * CLI action handler for the "scan" command.
+ * Runs a comprehensive AI-readiness analysis across multiple tools,
+ * including pattern detection, context analysis, and naming consistency.
+ *
+ * @param directory - The directory to analyze (defaults to ".")
+ * @param options - CLI options from commander
+ */
 export async function scanAction(directory: string, options: ScanOptions) {
   console.log(chalk.blue('🚀 Starting AIReady unified analysis...\n'));
 
@@ -151,7 +151,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
     )) as any;
 
     // Apply smart defaults for pattern detection if requested
-    let finalOptions = { ...baseOptions };
+    const finalOptions = { ...baseOptions };
     if (
       baseOptions.tools.includes(ToolName.PatternDetect) ||
       baseOptions.tools.includes('patterns')
@@ -211,13 +211,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
       suppressToolConfig: true,
     });
 
-    console.log(chalk.cyan('\n=== AIReady Run Summary ==='));
-    console.log(
-      `  Total issues (all tools): ${chalk.bold(String(results.summary.totalIssues || 0))}`
-    );
-    console.log(
-      `  Execution time: ${chalk.bold(((Date.now() - startTime) / 1000).toFixed(2) + 's')}`
-    );
+    printScanSummary(results, startTime);
 
     let scoringResult: ScoringResult | undefined;
     if (options.score || finalOptions.scoring?.showBreakdown) {
@@ -230,9 +224,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
         },
       });
 
-      console.log(chalk.bold('\n📊 AI Readiness Overall Score'));
-      console.log(`  ${formatScore(scoringResult)}`);
-      console.log(chalk.dim(`  (Scoring Profile: ${scoringProfile})`));
+      printScoring(scoringResult, scoringProfile);
 
       // Trend comparison logic
       if (options.compareTo) {
@@ -315,19 +307,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
           modelId: modelId,
         });
 
-        console.log(chalk.bold('\n💰 Business Impact Analysis (Monthly)'));
-        console.log(
-          `  Potential Savings: ${chalk.green(chalk.bold('$' + roi.monthlySavings.toLocaleString()))}`
-        );
-        console.log(
-          `  Productivity Gain: ${chalk.cyan(chalk.bold(roi.productivityGainHours + 'h'))} (est. dev time)`
-        );
-        console.log(
-          `  Context Efficiency: ${chalk.yellow((unifiedBudget.efficiencyRatio * 100).toFixed(0) + '%')}`
-        );
-        console.log(
-          `  Annual Value: ${chalk.bold('$' + roi.annualValue.toLocaleString())} (ROI Prediction)`
-        );
+        printBusinessImpact(roi, unifiedBudget);
 
         (results.summary as any).businessImpact = {
           estimatedMonthlyWaste: roi.monthlySavings,
@@ -338,43 +318,6 @@ export async function scanAction(directory: string, options: ScanOptions) {
         (scoringResult as any).tokenBudget = unifiedBudget;
         (scoringResult as any).businessROI = roi;
       }
-
-      if (scoringResult.breakdown) {
-        console.log(chalk.bold('\nTool breakdown:'));
-        scoringResult.breakdown.forEach((tool) => {
-          const rating = getRating(tool.score);
-          const emoji = getRatingDisplay(rating).emoji;
-          console.log(
-            `  - ${tool.toolName}: ${tool.score}/100 (${rating}) ${emoji}`
-          );
-        });
-
-        // Top Actionable Recommendations
-        const allRecs = scoringResult.breakdown
-          .flatMap((t) =>
-            (t.recommendations || []).map((r) => ({ ...r, tool: t.toolName }))
-          )
-          .sort((a, b) => b.estimatedImpact - a.estimatedImpact)
-          .slice(0, 3);
-
-        if (allRecs.length > 0) {
-          console.log(chalk.bold('\n🎯 Top Actionable Recommendations:'));
-          allRecs.forEach((rec, i) => {
-            const priorityIcon =
-              rec.priority === 'high'
-                ? '🔴'
-                : rec.priority === 'medium'
-                  ? '🟡'
-                  : '🔵';
-            console.log(
-              `  ${i + 1}. ${priorityIcon} ${chalk.bold(rec.action)}`
-            );
-            console.log(
-              `     Impact: ${chalk.green(`+${rec.estimatedImpact} points`)} to ${rec.tool}`
-            );
-          });
-        }
-      }
     }
 
     console.log(
@@ -395,43 +338,6 @@ export async function scanAction(directory: string, options: ScanOptions) {
       )
     );
 
-    // Normalized report mapping
-    const mapToUnifiedReport = (
-      res: any,
-      scoring: ScoringResult | undefined
-    ) => {
-      const allResults: any[] = [];
-      const totalFilesSet = new Set<string>();
-      let criticalCount = 0;
-      let majorCount = 0;
-
-      res.summary.toolsRun.forEach((toolId: string) => {
-        const spokeRes = res[toolId];
-        if (!spokeRes || !spokeRes.results) return;
-
-        spokeRes.results.forEach((r: any) => {
-          totalFilesSet.add(r.fileName);
-          allResults.push(r);
-          r.issues?.forEach((i: any) => {
-            if (i.severity === Severity.Critical) criticalCount++;
-            if (i.severity === Severity.Major) majorCount++;
-          });
-        });
-      });
-
-      return {
-        ...res,
-        results: allResults,
-        summary: {
-          ...res.summary,
-          totalFiles: totalFilesSet.size,
-          criticalIssues: criticalCount,
-          majorIssues: majorCount,
-        },
-        scoring,
-      };
-    };
-
     const outputData = {
       ...mapToUnifiedReport(results, scoringResult),
       repository: repoMetadata,
@@ -469,20 +375,20 @@ export async function scanAction(directory: string, options: ScanOptions) {
     }
     await warnIfGraphCapExceeded(outputData, resolvedDir);
 
-    // CI/CD Gatekeeper logic
-    const isCI = options.ci || process.env.CI === 'true';
-    if (isCI && scoringResult) {
+    // Score Check & Gatekeeper logic
+    if (scoringResult) {
       const threshold = options.threshold
         ? parseInt(options.threshold)
         : undefined;
       const failOnLevel = options.failOn || 'critical';
+      const isCI = options.ci || process.env.CI === 'true';
 
       let shouldFail = false;
       let failReason = '';
 
-      // Emit annotations for all issues found
+      // Emit annotations only in CI
       const report = mapToUnifiedReport(results, scoringResult);
-      if (report.results && report.results.length > 0) {
+      if (isCI && report.results && report.results.length > 0) {
         console.log(
           chalk.cyan(
             `\n📝 Emitting GitHub Action annotations for ${report.results.length} issues...`
@@ -495,6 +401,9 @@ export async function scanAction(directory: string, options: ScanOptions) {
         shouldFail = true;
         failReason = `Score ${scoringResult.overall} < threshold ${threshold}`;
       }
+
+      // If failOnLevel is set (default 'critical'), check for issues
+      // But only fail if not 'none'
       if (failOnLevel !== 'none') {
         if (failOnLevel === 'critical' && report.summary.criticalIssues > 0) {
           shouldFail = true;
@@ -509,10 +418,10 @@ export async function scanAction(directory: string, options: ScanOptions) {
       }
 
       if (shouldFail) {
-        console.log(chalk.red(`\n🚫 PR BLOCKED: ${failReason}`));
+        console.log(chalk.red(`\n🚫 SCAN FAILED: ${failReason}`));
         process.exit(1);
       } else {
-        console.log(chalk.green('\n✅ PR PASSED'));
+        console.log(chalk.green('\n✅ SCAN PASSED'));
       }
     }
   } catch (error) {

package/src/commands/shared/configured-tool-action.ts

@@ -0,0 +1,35 @@
+import type { ToolScoringOutput } from '@aiready/core';
+import { runConfiguredToolCommand } from '../../utils/helpers';
+
+export interface ConfiguredToolActionConfig<TReport> {
+  defaults: Record<string, unknown>;
+  analyze: (scanOptions: any) => Promise<TReport>;
+  getExtras: (
+    options: any,
+    merged: Record<string, unknown>
+  ) => Record<string, unknown>;
+  score: (report: TReport) => ToolScoringOutput;
+  render: (report: TReport, scoring: ToolScoringOutput) => void;
+}
+
+export async function runConfiguredToolAction<TReport>(
+  directory: string,
+  options: any,
+  config: ConfiguredToolActionConfig<TReport>
+): Promise<ToolScoringOutput | undefined> {
+  const { report, scoring } = await runConfiguredToolCommand({
+    directory,
+    options,
+    defaults: config.defaults,
+    analyze: config.analyze,
+    getExtras: config.getExtras,
+    score: config.score,
+  });
+
+  if (options.output === 'json') {
+    return scoring;
+  }
+
+  config.render(report, scoring);
+  return scoring;
+}

package/src/commands/shared/standard-tool-actions.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared implementations for standard config-driven CLI actions.
+ */
+
+import chalk from 'chalk';
+import type { ToolScoringOutput } from '@aiready/core';
+import { buildToolScoringOutput } from '../../utils/helpers';
+import { runConfiguredToolAction } from './configured-tool-action';
+
+export async function docDriftAction(
+  directory: string,
+  options: any
+): Promise<ToolScoringOutput | undefined> {
+  const { analyzeDocDrift } = await import('@aiready/doc-drift');
+
+  return runConfiguredToolAction(directory, options, {
+    defaults: { staleMonths: 6 },
+    analyze: analyzeDocDrift as any,
+    getExtras: (cmdOptions, merged) => ({
+      staleMonths: cmdOptions.staleMonths ?? merged.staleMonths ?? 6,
+    }),
+    score: (toolReport): ToolScoringOutput =>
+      buildToolScoringOutput('doc-drift', toolReport as any),
+    render: (report: any, scoring) => {
+      const { summary } = report;
+      const ratingColors: Record<string, (s: string) => string> = {
+        minimal: chalk.green,
+        low: chalk.cyan,
+        moderate: chalk.yellow,
+        high: chalk.red,
+        severe: chalk.bgRed.white,
+      };
+      const color = ratingColors[summary.rating] ?? chalk.white;
+      console.log(
+        `  📝 Documentation Drift:  ${chalk.bold(100 - scoring.score + '/100 health')} (${color(summary.rating)} risk)`
+      );
+      if (report.issues.length > 0) {
+        console.log(
+          chalk.dim(`     Found ${report.issues.length} drift issues.`)
+        );
+      } else {
+        console.log(chalk.dim(`     No documentation drift detected.`));
+      }
+    },
+  });
+}
+
+export async function depsHealthAction(
+  directory: string,
+  options: any
+): Promise<ToolScoringOutput | undefined> {
+  const { analyzeDeps } = await import('@aiready/deps');
+
+  return runConfiguredToolAction(directory, options, {
+    defaults: { trainingCutoffYear: 2023 },
+    analyze: analyzeDeps as any,
+    getExtras: (cmdOptions, merged) => ({
+      trainingCutoffYear:
+        cmdOptions.trainingCutoffYear ?? merged.trainingCutoffYear ?? 2023,
+    }),
+    score: (toolReport): ToolScoringOutput =>
+      buildToolScoringOutput('dependency-health', toolReport as any),
+    render: (report: any, scoring) => {
+      const { summary } = report;
+      const ratingColors: Record<string, (s: string) => string> = {
+        excellent: chalk.green,
+        good: chalk.blueBright,
+        moderate: chalk.yellow,
+        poor: chalk.red,
+        hazardous: chalk.bgRed.white,
+      };
+      const color = ratingColors[summary.rating] ?? chalk.white;
+      console.log(
+        `  📦 Dependency Health:  ${chalk.bold(scoring.score + '/100 health')} (${color(summary.rating)})`
+      );
+      if (report.issues.length > 0) {
+        console.log(
+          chalk.dim(`     Found ${report.issues.length} dependency issues.`)
+        );
+      } else {
+        console.log(
+          chalk.dim(`     Dependencies look healthy for AI assistance.`)
+        );
+      }
+    },
+  });
+}
+
+export async function aiSignalClarityAction(
+  directory: string,
+  options: any
+): Promise<ToolScoringOutput | undefined> {
+  const { analyzeAiSignalClarity, calculateAiSignalClarityScore } =
+    await import('@aiready/ai-signal-clarity');
+
+  return runConfiguredToolAction(directory, options, {
+    defaults: { minSeverity: 'info' },
+    analyze: analyzeAiSignalClarity as any,
+    getExtras: (cmdOptions, merged) => ({
+      minSeverity: cmdOptions.minSeverity ?? merged.minSeverity ?? 'info',
+    }),
+    score: (toolReport) => calculateAiSignalClarityScore(toolReport as any),
+    render: (report: any, scoring) => {
+      const { summary } = report;
+      const ratingColors: Record<string, (s: string) => string> = {
+        minimal: chalk.green,
+        low: chalk.cyan,
+        moderate: chalk.yellow,
+        high: chalk.red,
+        severe: chalk.bgRed.white,
+      };
+      const color = ratingColors[summary.rating] ?? chalk.white;
+      console.log(
+        `  🧠 AI Signal Clarity:  ${chalk.bold(scoring.score + '/100')} (${color(summary.rating)})`
+      );
+      console.log(`     Top Risk: ${chalk.italic(summary.topRisk)}`);
+      if (summary.totalSignals > 0) {
+        console.log(
+          chalk.dim(
+            `     ${summary.criticalSignals} critical  ${summary.majorSignals} major  ${summary.minorSignals} minor signals`
+          )
+        );
+      }
+    },
+  });
+}

package/src/commands/upload.ts

@@ -51,7 +51,7 @@ export async function uploadAction(file: string, options: UploadOptions) {
     // Note: repoId is optional if the metadata contains it, but for now we'll require it or infer from metadata
     const repoId = options.repoId || reportData.repository?.repoId;
 
-    const res = await fetch(`${serverUrl}/api/analysis/upload`, {
+    const response = await fetch(`${serverUrl}/api/analysis/upload`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
@@ -63,19 +63,21 @@ export async function uploadAction(file: string, options: UploadOptions) {
       }),
     });
 
-    const contentType = res.headers.get('content-type');
-    let result: any = {};
+    const contentType = response.headers.get('content-type');
+    let uploadResult: any = {};
 
     if (contentType?.includes('application/json')) {
-      result = await res.json();
+      uploadResult = await response.json();
     } else {
-      const text = await res.text();
-      result = { error: text || res.statusText };
+      const text = await response.text();
+      uploadResult = { error: text || response.statusText };
     }
 
-    if (!res.ok) {
+    if (!response.ok) {
       console.error(
-        chalk.red(`❌ Upload failed: ${result.error || res.statusText}`)
+        chalk.red(
+          `❌ Upload failed: ${uploadResult.error || response.statusText}`
+        )
       );
 
       // Special case for redirects or HTML error pages
@@ -85,7 +87,7 @@ export async function uploadAction(file: string, options: UploadOptions) {
             '   Note: Received an HTML response. This often indicates a redirect (e.g., to a login page) or a server error.'
           )
         );
-        if (result.error?.includes('Redirecting')) {
+        if (uploadResult.error?.includes('Redirecting')) {
           console.log(
             chalk.dim(
               '   Detected redirect. Check if the API endpoint requires authentication or has changed.'
@@ -94,7 +96,7 @@ export async function uploadAction(file: string, options: UploadOptions) {
         }
       }
 
-      if (res.status === 401) {
+      if (response.status === 401) {
         console.log(
           chalk.dim('   Hint: Your API key may be invalid or expired.')
         );
@@ -106,9 +108,9 @@ export async function uploadAction(file: string, options: UploadOptions) {
     console.log(chalk.green(`\n✅ Upload successful! (${duration}s)`));
     console.log(chalk.cyan(`   View results: ${serverUrl}/dashboard`));
 
-    if (result.analysis) {
-      console.log(chalk.dim(`   Analysis ID: ${result.analysis.id}`));
-      console.log(chalk.dim(`   Score: ${result.analysis.aiScore}/100`));
+    if (uploadResult.analysis) {
+      console.log(chalk.dim(`   Analysis ID: ${uploadResult.analysis.id}`));
+      console.log(chalk.dim(`   Score: ${uploadResult.analysis.aiScore}/100`));
     }
   } catch (error) {
     handleCLIError(error, 'Upload');

package/src/commands/visualize.ts

@@ -7,8 +7,7 @@ import { writeFileSync, readFileSync, existsSync, copyFileSync } from 'fs';
 import { resolve as resolvePath } from 'path';
 import { spawn } from 'child_process';
 import { handleCLIError } from '@aiready/core';
-import { generateHTML } from '@aiready/core';
-import { findLatestScanReport } from '../utils/helpers';
+import { generateHTML, findLatestReport } from '@aiready/core';
 
 interface VisualizeOptions {
   report?: string;
@@ -18,6 +17,14 @@ interface VisualizeOptions {
   dev?: boolean;
 }
 
+/**
+ * CLI action handler for the "visualize" command.
+ * Generates an interactive dependency graph visualization of the project
+ * to help understand code structure and AI context usage.
+ *
+ * @param directory - The directory to analyze and visualize
+ * @param options - CLI options from commander
+ */
 export async function visualizeAction(
   directory: string,
   options: VisualizeOptions
@@ -30,7 +37,7 @@ export async function visualizeAction(
 
     // If report not provided or not found, try to find latest scan report
     if (!reportPath || !existsSync(reportPath)) {
-      const latestScan = findLatestScanReport(dirPath);
+      const latestScan = findLatestReport(dirPath);
       if (latestScan) {
         reportPath = latestScan;
         console.log(
@@ -221,7 +228,7 @@ export async function visualizeAction(
 
     // Generate static HTML (default behavior or fallback from failed --dev)
     console.log('Generating HTML...');
-    const html = generateHTML(graph);
+    const html = generateHTML(graph as any);
     const defaultOutput = 'visualization.html';
     const outPath = resolvePath(dirPath, options.output || defaultOutput);
     writeFileSync(outPath, html, 'utf8');

package/src/index.ts

@@ -3,15 +3,12 @@ import {
   ToolName,
   calculateOverallScore,
   calculateTokenBudget,
-  GLOBAL_SCAN_OPTIONS,
   GLOBAL_INFRA_OPTIONS,
   COMMON_FINE_TUNING_OPTIONS,
   initializeParsers,
 } from '@aiready/core';
 import type {
-  AnalysisResult,
   ScanOptions,
-  SpokeOutput,
   ToolScoringOutput,
   ScoringResult,
 } from '@aiready/core';
@@ -29,16 +26,30 @@ import '@aiready/change-amplification';
 
 export type { ToolScoringOutput, ScoringResult };
 
+/**
+ * Options for running a unified AI-readiness analysis across multiple tools.
+ * Extends base ScanOptions with CLI-specific configurations.
+ */
 export interface UnifiedAnalysisOptions extends ScanOptions {
+  /** Root directory for analysis */
   rootDir: string;
+  /** List of tools to run (e.g. ['patterns', 'context']) */
   tools?: string[];
+  /** Overrides for specific tool configurations */
   toolConfigs?: Record<string, any>;
+  /** Minimum similarity threshold for pattern detection (0-1) */
   minSimilarity?: number;
+  /** Minimum number of lines for a pattern to be considered */
   minLines?: number;
+  /** Maximum number of candidates to check per code block */
   maxCandidatesPerBlock?: number;
+  /** Minimum number of shared tokens for a match */
   minSharedTokens?: number;
+  /** Whether to use optimized defaults based on project size/language */
   useSmartDefaults?: boolean;
+  /** Specific options for naming consistency analysis */
   consistency?: any;
+  /** Optional callback for tracking analysis progress */
   progressCallback?: (event: {
     tool: string;
     data?: any;
@@ -48,6 +59,10 @@ export interface UnifiedAnalysisOptions extends ScanOptions {
   }) => void;
 }
 
+/**
+ * The consolidated result of a unified analysis across all requested tools.
+ * Contains tool-specific outputs, scoring, and a high-level summary.
+ */
 export interface UnifiedAnalysisResult {
   // Dynamic keys based on ToolName
   [key: string]: any;