@aiready/cli 0.14.8 → 0.14.10

package/src/commands/scan.ts

@@ -57,7 +57,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
   console.log(chalk.blue('🚀 Starting AIReady unified analysis...\n'));
 
   const startTime = Date.now();
-  const resolvedDir = resolvePath(process.cwd(), directory || '.');
+  const resolvedDir = resolvePath(process.cwd(), directory ?? '.');
   const repoMetadata = getRepoMetadata(resolvedDir);
 
   try {
@@ -159,7 +159,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
       const { getSmartDefaults } = await import('@aiready/pattern-detect');
       const patternSmartDefaults = await getSmartDefaults(
         resolvedDir,
-        finalOptions.toolConfigs?.[ToolName.PatternDetect] || {}
+        finalOptions.toolConfigs?.[ToolName.PatternDetect] ?? {}
       );
 
       // Merge smart defaults into toolConfigs instead of root level
@@ -173,7 +173,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
     console.log(chalk.cyan('\n=== AIReady Run Preview ==='));
     console.log(
       chalk.white('Tools to run:'),
-      (finalOptions.tools || []).join(', ')
+      (finalOptions.tools ?? []).join(', ')
     );
 
     // Dynamic progress callback
@@ -202,7 +202,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
 
     // Determine scoring profile for project-type-aware weighting
     const scoringProfile =
-      options.profile || baseOptions.scoring?.profile || 'default';
+      options.profile ?? baseOptions.scoring?.profile ?? 'default';
 
     const results = await analyzeUnified({
       ...finalOptions,
@@ -233,7 +233,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
             readFileSync(resolvePath(process.cwd(), options.compareTo), 'utf8')
           );
           const prevScore =
-            prevReport.scoring?.overall || prevReport.scoring?.score;
+            prevReport.scoring?.overall ?? prevReport.scoring?.score;
           if (typeof prevScore === 'number') {
             const diff = scoringResult.overall - prevScore;
             const diffStr = diff > 0 ? `+${diff}` : String(diff);
@@ -262,19 +262,19 @@ export async function scanAction(directory: string, options: ScanOptions) {
       }
 
       // Token Budget & Cost Logic
-      const totalWastedDuplication = (scoringResult.breakdown || []).reduce(
-        (sum, s) =>
-          sum + (s.tokenBudget?.wastedTokens.bySource.duplication || 0),
+      const totalWastedDuplication = (scoringResult.breakdown ?? []).reduce(
+        (sum: number, s: any) =>
+          sum + (s.tokenBudget?.wastedTokens?.bySource?.duplication ?? 0),
         0
       );
-      const totalWastedFragmentation = (scoringResult.breakdown || []).reduce(
-        (sum, s) =>
-          sum + (s.tokenBudget?.wastedTokens.bySource.fragmentation || 0),
+      const totalWastedFragmentation = (scoringResult.breakdown ?? []).reduce(
+        (sum: number, s: any) =>
+          sum + (s.tokenBudget?.wastedTokens?.bySource?.fragmentation ?? 0),
         0
       );
       const totalContext = Math.max(
-        ...(scoringResult.breakdown || []).map(
-          (s) => s.tokenBudget?.totalContextTokens || 0
+        ...(scoringResult.breakdown ?? []).map(
+          (s: any) => s.tokenBudget?.totalContextTokens ?? 0
         ),
         0
       );
@@ -300,7 +300,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
           }
         }
 
-        const modelId = options.model || 'claude-3-5-sonnet';
+        const modelId = options.model ?? 'gpt-5.4-mini';
         const roi = (await import('@aiready/core')).calculateBusinessROI({
           tokenWaste: unifiedBudget.wastedTokens.total,
           issues: allIssues,
@@ -345,9 +345,9 @@ export async function scanAction(directory: string, options: ScanOptions) {
 
     // Output persistence
     const outputFormat =
-      options.output || finalOptions.output?.format || 'console';
+      options.output ?? finalOptions.output?.format ?? 'console';
     const outputPath = resolveOutputPath(
-      options.outputFile || finalOptions.output?.file,
+      options.outputFile ?? finalOptions.output?.file,
       `aiready-report-${getReportTimestamp()}.json`,
       resolvedDir
     );
@@ -380,8 +380,8 @@ export async function scanAction(directory: string, options: ScanOptions) {
       const threshold = options.threshold
         ? parseInt(options.threshold)
         : undefined;
-      const failOnLevel = options.failOn || 'critical';
-      const isCI = options.ci || process.env.CI === 'true';
+      const failOnLevel = options.failOn ?? 'critical';
+      const isCI = options.ci ?? process.env.CI === 'true';
 
       let shouldFail = false;
       let failReason = '';

package/src/commands/upload.ts

@@ -13,10 +13,10 @@ export async function uploadAction(file: string, options: UploadOptions) {
   const startTime = Date.now();
   const filePath = resolvePath(process.cwd(), file);
   const serverUrl =
-    options.server ||
-    process.env.AIREADY_SERVER ||
+    options.server ??
+    process.env.AIREADY_SERVER ??
     'https://dev.platform.getaiready.dev';
-  const apiKey = options.apiKey || process.env.AIREADY_API_KEY;
+  const apiKey = options.apiKey ?? process.env.AIREADY_API_KEY;
 
   if (!apiKey) {
     console.error(chalk.red('❌ API Key is required for upload.'));
@@ -49,7 +49,7 @@ export async function uploadAction(file: string, options: UploadOptions) {
 
     // Prepare upload payload
     // 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 repoId = options.repoId ?? reportData.repository?.repoId;
 
     const response = await fetch(`${serverUrl}/api/analysis/upload`, {
       method: 'POST',
@@ -70,13 +70,13 @@ export async function uploadAction(file: string, options: UploadOptions) {
       uploadResult = await response.json();
     } else {
       const text = await response.text();
-      uploadResult = { error: text || response.statusText };
+      uploadResult = { error: text ?? response.statusText };
     }
 
     if (!response.ok) {
       console.error(
         chalk.red(
-          `❌ Upload failed: ${uploadResult.error || response.statusText}`
+          `❌ Upload failed: ${uploadResult.error ?? response.statusText}`
         )
       );
 

package/src/commands/visualize.ts

@@ -30,7 +30,7 @@ export async function visualizeAction(
   options: VisualizeOptions
 ) {
   try {
-    const dirPath = resolvePath(process.cwd(), directory || '.');
+    const dirPath = resolvePath(process.cwd(), directory ?? '.');
     let reportPath = options.report
       ? resolvePath(dirPath, options.report)
       : null;
@@ -87,7 +87,7 @@ export async function visualizeAction(
     const graph = GraphBuilder.buildFromReport(report, dirPath);
 
     // Check if --dev mode is requested and available
-    let useDevMode = options.dev || false;
+    let useDevMode = options.dev ?? false;
     let devServerStarted = false;
 
     if (useDevMode) {
@@ -230,7 +230,7 @@ export async function visualizeAction(
     console.log('Generating HTML...');
     const html = generateHTML(graph as any);
     const defaultOutput = 'visualization.html';
-    const outPath = resolvePath(dirPath, options.output || defaultOutput);
+    const outPath = resolvePath(dirPath, options.output ?? defaultOutput);
     writeFileSync(outPath, html, 'utf8');
     console.log(chalk.green(`✅ Visualization written to: ${outPath}`));
 
@@ -250,7 +250,7 @@ export async function visualizeAction(
 
           const server = http.createServer(async (req, res) => {
             try {
-              const urlPath = req.url || '/';
+              const urlPath = req.url ?? '/';
               if (urlPath === '/' || urlPath === '/index.html') {
                 const content = await fsp.readFile(outPath, 'utf8');
                 res.writeHead(200, {

package/src/index.ts

@@ -57,6 +57,12 @@ export interface UnifiedAnalysisOptions extends ScanOptions {
     total?: number;
     message?: string;
   }) => void;
+  /** Files or directories to include in scan */
+  include?: string[];
+  /** Files or directories to exclude from scan */
+  exclude?: string[];
+  /** Batch size for comparisons */
+  batchSize?: number;
 }
 
 /**
@@ -147,8 +153,12 @@ function sanitizeToolConfig(config: any): any {
 }
 
 /**
- * AIReady Unified Analysis
+ * AIReady Unified Analysis.
  * Orchestrates all registered tools via the ToolRegistry.
+ *
+ * @param options - Unified analysis configuration including tools and rootDir.
+ * @returns Promise resolving to the consolidated analysis result.
+ * @lastUpdated 2026-03-18
  */
 export async function analyzeUnified(
   options: UnifiedAnalysisOptions
@@ -157,7 +167,7 @@ export async function analyzeUnified(
   await initializeParsers();
 
   const startTime = Date.now();
-  const requestedTools = options.tools || [
+  const requestedTools = options.tools ?? [
     'patterns',
     'context',
     'consistency',
@@ -182,7 +192,7 @@ export async function analyzeUnified(
     // Dynamic Loading: If provider not found, attempt to import the package
     if (!provider) {
       const packageName =
-        TOOL_PACKAGE_MAP[toolName] ||
+        TOOL_PACKAGE_MAP[toolName] ??
         (toolName.startsWith('@aiready/') ? toolName : `@aiready/${toolName}`);
       try {
         await import(packageName);
@@ -297,34 +307,16 @@ export async function analyzeUnified(
 
       // Track total files analyzed across all tools
       const toolFiles =
-        output.summary?.totalFiles || output.summary?.filesAnalyzed || 0;
+        output.summary?.totalFiles ?? output.summary?.filesAnalyzed ?? 0;
       if (toolFiles > result.summary.totalFiles) {
         result.summary.totalFiles = toolFiles;
       }
 
       const issueCount = output.results.reduce(
-        (sum: number, file: any) => sum + (file.issues?.length || 0),
+        (sum: number, file: any) => sum + (file.issues?.length ?? 0),
         0
       );
       result.summary.totalIssues += issueCount;
-
-      // Robust backward compatibility fallbacks
-      // 1. Add all aliases as keys (e.g., 'patterns', 'context', 'consistency')
-      if (provider.alias && Array.isArray(provider.alias)) {
-        for (const alias of provider.alias) {
-          if (!result[alias]) {
-            (result as any)[alias] = output;
-          }
-        }
-      }
-
-      // 2. Add camelCase version of canonical ID (e.g., 'patternDetect', 'contextAnalyzer')
-      const camelCaseId = provider.id.replace(/-([a-z])/g, (g) =>
-        g[1].toUpperCase()
-      );
-      if (camelCaseId !== provider.id && !result[camelCaseId]) {
-        (result as any)[camelCaseId] = output;
-      }
     } catch (err) {
       console.error(`❌ Error running tool '${provider.id}':`, err);
     }
@@ -343,12 +335,38 @@ export async function analyzeUnified(
   });
 
   result.summary.executionTime = Date.now() - startTime;
+
+  // Add backward compatibility key mappings (kebab-case -> camelCase and aliases)
+  const keyMappings: Record<string, string[]> = {
+    'pattern-detect': ['patternDetect', 'patterns'],
+    'context-analyzer': ['contextAnalyzer', 'context'],
+    'naming-consistency': ['namingConsistency', 'consistency'],
+    'ai-signal-clarity': ['aiSignalClarity'],
+    'agent-grounding': ['agentGrounding'],
+    'testability-index': ['testabilityIndex', 'testability'],
+    'doc-drift': ['docDrift'],
+    'dependency-health': ['dependencyHealth', 'deps'],
+    'change-amplification': ['changeAmplification'],
+  };
+
+  for (const [kebabKey, aliases] of Object.entries(keyMappings)) {
+    if (result[kebabKey]) {
+      for (const alias of aliases) {
+        result[alias] = result[kebabKey];
+      }
+    }
+  }
+
   return result;
 }
 
 /**
- * AIReady Unified Scoring
+ * AIReady Unified Scoring.
  * Calculates scores for all analyzed tools.
+ *
+ * @param results - The consolidated results from a unified analysis.
+ * @param options - Analysis options for weighting and budget calculation.
+ * @returns Promise resolving to the final scoring result.
  */
 export async function scoreUnified(
   results: UnifiedAnalysisResult,
@@ -370,7 +388,7 @@ export async function scoreUnified(
       if (!toolScore.tokenBudget) {
         if (toolId === ToolName.PatternDetect && (output as any).duplicates) {
           const wastedTokens = (output as any).duplicates.reduce(
-            (sum: number, d: any) => sum + (d.tokenCost || 0),
+            (sum: number, d: any) => sum + (d.tokenCost ?? 0),
             0
           );
           toolScore.tokenBudget = calculateTokenBudget({
@@ -386,7 +404,7 @@ export async function scoreUnified(
             totalContextTokens: output.summary.totalTokens,
             wastedTokens: {
               duplication: 0,
-              fragmentation: output.summary.totalPotentialSavings || 0,
+              fragmentation: output.summary.totalPotentialSavings ?? 0,
               chattiness: 0,
             },
           });
@@ -419,7 +437,10 @@ export async function scoreUnified(
 }
 
 /**
- * Generate human-readable summary of unified results
+ * Generate human-readable summary of unified results.
+ *
+ * @param result - The consolidated analysis result object.
+ * @returns Formatted summary string.
  */
 export function generateUnifiedSummary(result: UnifiedAnalysisResult): string {
   const { summary } = result;
@@ -433,7 +454,7 @@ export function generateUnifiedSummary(result: UnifiedAnalysisResult): string {
     const toolResult = result[provider.id];
     if (toolResult) {
       const issueCount = toolResult.results.reduce(
-        (sum: number, r: any) => sum + (r.issues?.length || 0),
+        (sum: number, r: any) => sum + (r.issues?.length ?? 0),
         0
       );
       output += `• ${provider.id}: ${issueCount} issues\n`;

package/src/utils/helpers.ts

@@ -22,7 +22,10 @@ export function getReportTimestamp(): string {
 }
 
 /**
- * Warn if graph caps may be exceeded
+ * Warn if graph caps may be exceeded for visualization.
+ *
+ * @param report - The combined analysis report.
+ * @param dirPath - Root directory to look for configuration.
  */
 export async function warnIfGraphCapExceeded(report: any, dirPath: string) {
   try {
@@ -90,7 +93,11 @@ export async function warnIfGraphCapExceeded(report: any, dirPath: string) {
 }
 
 /**
- * Generate markdown report for consistency command
+ * Generate markdown report for consistency command.
+ *
+ * @param report - The consistency report object.
+ * @param elapsedTime - Time taken for analysis in seconds.
+ * @returns Formatted markdown string.
  */
 export function generateMarkdownReport(
   report: any,
@@ -117,7 +124,11 @@ export function generateMarkdownReport(
 }
 
 /**
- * Truncate array for display (show first N items with "... +N more")
+ * Truncate array for display (show first N items with "... +N more").
+ *
+ * @param arr - The array to truncate.
+ * @param cap - Maximum number of items to show before truncating.
+ * @returns Formatted string for display.
  */
 export function truncateArray(arr: any[] | undefined, cap = 8): string {
   if (!Array.isArray(arr)) return '';
@@ -128,6 +139,10 @@ export function truncateArray(arr: any[] | undefined, cap = 8): string {
 
 /**
  * Build a common ToolScoringOutput payload from a tool report.
+ *
+ * @param toolName - Identifier for the tool.
+ * @param report - Minimal report structure containing score and recommendations.
+ * @returns Standardized scoring output.
  */
 export function buildToolScoringOutput(
   toolName: string,
@@ -152,6 +167,10 @@ export function buildToolScoringOutput(
 
 /**
  * Load config and apply tool-level defaults.
+ *
+ * @param directory - Directory to search for config.
+ * @param defaults - Tool-specific default values.
+ * @returns Merged configuration with tool defaults.
  */
 export async function loadMergedToolConfig<T extends Record<string, unknown>>(
   directory: string,
@@ -164,6 +183,11 @@ export async function loadMergedToolConfig<T extends Record<string, unknown>>(
 
 /**
  * Shared base scan options used by CLI tool commands.
+ *
+ * @param directory - Root directory for scanning.
+ * @param options - CLI commander options object.
+ * @param extras - Additional tool-specific options.
+ * @returns Combined scan options for the analyzer.
  */
 export function buildCommonScanOptions(
   directory: string,
@@ -180,6 +204,9 @@ export function buildCommonScanOptions(
 
 /**
  * Execute a config-driven tool command with shared CLI plumbing.
+ *
+ * @param params - Execution parameters including analyze and score callbacks.
+ * @returns Promise resolving to the tool report and its scoring output.
  */
 export async function runConfiguredToolCommand<TReport, TScoring>(params: {
   directory: string;