@aiready/cli 0.14.3 → 0.14.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/cli",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "description": "Unified CLI for AIReady analysis tools",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -11,17 +11,17 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^14.0.0",
-    "@aiready/agent-grounding": "0.13.2",
-    "@aiready/consistency": "0.20.2",
-    "@aiready/context-analyzer": "0.21.6",
-    "@aiready/core": "0.23.2",
-    "@aiready/doc-drift": "0.13.2",
-    "@aiready/change-amplification": "0.13.2",
-    "@aiready/deps": "0.13.2",
-    "@aiready/testability": "0.6.2",
-    "@aiready/pattern-detect": "0.16.2",
-    "@aiready/visualizer": "0.6.2",
-    "@aiready/ai-signal-clarity": "0.13.2"
+    "@aiready/context-analyzer": "0.21.7",
+    "@aiready/agent-grounding": "0.13.3",
+    "@aiready/core": "0.23.3",
+    "@aiready/deps": "0.13.3",
+    "@aiready/ai-signal-clarity": "0.13.3",
+    "@aiready/doc-drift": "0.13.3",
+    "@aiready/testability": "0.6.3",
+    "@aiready/visualizer": "0.6.3",
+    "@aiready/change-amplification": "0.13.3",
+    "@aiready/consistency": "0.20.3",
+    "@aiready/pattern-detect": "0.16.3"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/__tests__/cli.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { analyzeUnified } from '../index';
 import { ToolRegistry, ToolName, SpokeOutputSchema } from '@aiready/core';
 

package/src/__tests__/config-shape.test.ts

@@ -76,7 +76,6 @@ describe('CLI Configuration Shape', () => {
       rootDir: '/test',
       tools: [ToolName.PatternDetect],
       useSmartDefaults: true,
-      // @ts-expect-error - testing internal key stripping
       batchSize: 50,
     });
 

package/src/__tests__/unified.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { analyzeUnified, scoreUnified, generateUnifiedSummary } from '../index';
-import { ToolRegistry, ToolName } from '@aiready/core';
+import { ToolRegistry } from '@aiready/core';
 
 vi.mock('@aiready/core', async () => {
   const actual = await vi.importActual('@aiready/core');

package/src/commands/__tests__/extra-commands.test.ts

@@ -7,7 +7,6 @@ import { testabilityAction } from '../testability';
 import { depsHealthAction } from '../deps-health';
 import { patternsAction } from '../patterns';
 import { contextAction } from '../context';
-import * as core from '@aiready/core';
 
 vi.mock('@aiready/core', async () => {
   const actual = await vi.importActual('@aiready/core');

package/src/commands/__tests__/init.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { existsSync, readFileSync, unlinkSync, mkdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { initAction } from '../init';
+
+describe('initAction', () => {
+  const testDir = join(process.cwd(), 'temp-test-init');
+  const configPath = join(testDir, 'aiready.json');
+
+  beforeEach(() => {
+    if (!existsSync(testDir)) {
+      mkdirSync(testDir, { recursive: true });
+    }
+    // Mock process.cwd to use our test directory
+    vi.spyOn(process, 'cwd').mockReturnValue(testDir);
+    // Mock console.log to avoid noise
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (existsSync(configPath)) {
+      unlinkSync(configPath);
+    }
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  it('should generate aiready.json without output field by default', async () => {
+    await initAction({});
+
+    expect(existsSync(configPath)).toBe(true);
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    expect(config).not.toHaveProperty('output');
+  });
+
+  it('should generate aiready.json without output field even with --full flag', async () => {
+    await initAction({ full: true });
+
+    expect(existsSync(configPath)).toBe(true);
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    expect(config).not.toHaveProperty('output');
+  });
+
+  it('should include scan, tools, and scoring sections', async () => {
+    await initAction({ full: true });
+
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    expect(config).toHaveProperty('scan');
+    expect(config).toHaveProperty('tools');
+    expect(config).toHaveProperty('scoring');
+    expect(config).toHaveProperty('visualizer');
+  });
+});

package/src/commands/__tests__/scan.test.ts

@@ -3,7 +3,7 @@ import { scanAction } from '../scan';
 import * as core from '@aiready/core';
 import * as index from '../../index';
 import * as upload from '../upload';
-import { writeFileSync, readFileSync, existsSync } from 'fs';
+import { readFileSync } from 'fs';
 import { Severity } from '@aiready/core';
 
 vi.mock('../../index', () => ({

package/src/commands/__tests__/upload.test.ts

@@ -1,6 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { uploadAction } from '../upload';
-import fs from 'fs';
 
 vi.mock('fs', () => ({
   default: {

package/src/commands/bug.ts

@@ -1,5 +1,4 @@
 import chalk from 'chalk';
-import { Command } from 'commander';
 
 import { execSync } from 'child_process';
 
@@ -38,7 +37,7 @@ Type: ${type}
         console.log(chalk.green('✅ Issue Created Successfully!'));
         console.log(chalk.cyan(output));
         return;
-      } catch (error) {
+      } catch {
         console.error(chalk.red('\n❌ Failed to submit via gh CLI.'));
         console.log(
           chalk.yellow(

package/src/commands/init.ts

@@ -113,10 +113,6 @@ export async function initAction(options: {
     },
     ...(options.full
       ? {
-          output: {
-            format: fileExt,
-            file: 'aiready-report.json',
-          },
           visualizer: {
             groupingDirs: ['packages', 'src', 'lib'],
             graph: {

package/src/commands/patterns.ts

@@ -86,7 +86,9 @@ export async function patternsAction(
     const { analyzePatterns, generateSummary, calculatePatternScore } =
       await import('@aiready/pattern-detect');
 
-    const { results, duplicates } = await analyzePatterns(finalOptions);
+    const { results, duplicates } = (await analyzePatterns(
+      finalOptions
+    )) as any;
 
     const elapsedTime = getElapsedTime(startTime);
     const summary = generateSummary(results);

package/src/commands/report-formatter.ts

@@ -0,0 +1,128 @@
+import chalk from 'chalk';
+import {
+  Severity,
+  ScoringResult,
+  formatScore,
+  getRating,
+  getRatingDisplay,
+} from '@aiready/core';
+
+/**
+ * Handle console output for the scan results
+ */
+export function printScanSummary(results: any, startTime: number) {
+  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')}`
+  );
+}
+
+/**
+ * Print business impact analysis
+ */
+export function printBusinessImpact(roi: any, unifiedBudget: any) {
+  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)`
+  );
+}
+
+/**
+ * Print detailed scoring breakdown
+ */
+export function printScoring(
+  scoringResult: ScoringResult,
+  scoringProfile: string
+) {
+  console.log(chalk.bold('\n📊 AI Readiness Overall Score'));
+  console.log(`  ${formatScore(scoringResult)}`);
+  console.log(chalk.dim(`  (Scoring Profile: ${scoringProfile})`));
+
+  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}`
+        );
+      });
+    }
+  }
+}
+
+/**
+ * Normalize report mapping (CLI logic)
+ */
+export function 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 || i.severity === 'critical')
+          criticalCount++;
+        if (i.severity === Severity.Major || i.severity === 'major')
+          majorCount++;
+      });
+    });
+  });
+
+  return {
+    ...res,
+    results: allResults,
+    summary: {
+      ...res.summary,
+      totalFiles: totalFilesSet.size,
+      criticalIssues: criticalCount,
+      majorIssues: majorCount,
+    },
+    scoring,
+  };
+}

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'));
 
@@ -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,

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

@@ -17,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
@@ -220,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;

package/src/utils/helpers.ts

@@ -3,7 +3,7 @@
  */
 
 import { resolve as resolvePath } from 'path';
-import { existsSync, readdirSync, statSync, readFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import chalk from 'chalk';
 import { loadConfig, mergeConfigWithDefaults } from '@aiready/core';
 import type { ToolScoringOutput } from '@aiready/core';