@aiready/cli 0.9.35 → 0.9.38

package/src/commands/agent-grounding.ts

@@ -0,0 +1,47 @@
+/**
+ * Agent grounding command for unified CLI
+ */
+
+import chalk from 'chalk';
+import { loadConfig, mergeConfigWithDefaults } from '@aiready/core';
+import type { ToolScoringOutput } from '@aiready/core';
+
+export async function agentGroundingAction(
+  directory: string,
+  options: any,
+): Promise<ToolScoringOutput | undefined> {
+  const { analyzeAgentGrounding, calculateGroundingScore } = await import('@aiready/agent-grounding');
+
+  const config = await loadConfig(directory);
+  const merged = mergeConfigWithDefaults(config, {
+    maxRecommendedDepth: 4,
+    readmeStaleDays: 90,
+  });
+
+  const report = await analyzeAgentGrounding({
+    rootDir: directory,
+    maxRecommendedDepth: options.maxDepth ?? merged.maxRecommendedDepth,
+    readmeStaleDays: options.readmeStaleDays ?? merged.readmeStaleDays,
+    include: options.include,
+    exclude: options.exclude,
+  });
+
+  const scoring = calculateGroundingScore(report);
+
+  if (options.output === 'json') {
+    return scoring;
+  }
+
+  const scoreColor = (s: number) =>
+    s >= 85 ? chalk.green : s >= 70 ? chalk.cyan : s >= 50 ? chalk.yellow : chalk.red;
+
+  console.log(`  🧭 Agent Grounding:     ${chalk.bold(scoring.score + '/100')} (${report.summary.rating})`);
+  const dims = report.summary.dimensions;
+  const worstDim = Object.entries(dims).sort(([, a], [, b]) => a - b)[0];
+  if (worstDim && worstDim[1] < 70) {
+    const name = worstDim[0].replace(/([A-Z])/g, ' $1').replace('Score', '').trim();
+    console.log(chalk.dim(`     Weakest dimension: ${name} (${worstDim[1]}/100)`));
+  }
+
+  return scoring;
+}

package/src/commands/deps-health.ts

@@ -0,0 +1,56 @@
+/**
+ * Dependency health command for unified CLI
+ */
+
+import chalk from 'chalk';
+import { loadConfig, mergeConfigWithDefaults } from '@aiready/core';
+import type { ToolScoringOutput } from '@aiready/core';
+
+export async function depsHealthAction(
+  directory: string,
+  options: any,
+): Promise<ToolScoringOutput | undefined> {
+  const { analyzeDeps } = await import('@aiready/deps');
+
+  const config = await loadConfig(directory);
+  const merged = mergeConfigWithDefaults(config, {
+    trainingCutoffYear: 2023,
+  });
+
+  const report = await analyzeDeps({
+    rootDir: directory,
+    include: options.include,
+    exclude: options.exclude,
+    trainingCutoffYear: options.trainingCutoffYear ?? merged.trainingCutoffYear ?? 2023,
+  });
+
+  const scoring: ToolScoringOutput = {
+    toolName: 'dependency-health',
+    score: report.summary.score,
+    rawMetrics: report.rawData,
+    factors: [],
+    recommendations: report.recommendations.map((action: string) => ({ action, estimatedImpact: 5, priority: 'medium' }))
+  };
+
+  if (options.output === 'json') {
+    return scoring;
+  }
+
+  const { summary } = report;
+  const ratingColors: Record<string, Function> = {
+    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.`));
+  }
+
+  return scoring;
+}

package/src/commands/doc-drift.ts

@@ -0,0 +1,56 @@
+/**
+ * Doc drift risk command for unified CLI
+ */
+
+import chalk from 'chalk';
+import { loadConfig, mergeConfigWithDefaults } from '@aiready/core';
+import type { ToolScoringOutput } from '@aiready/core';
+
+export async function docDriftAction(
+  directory: string,
+  options: any,
+): Promise<ToolScoringOutput | undefined> {
+  const { analyzeDocDrift } = await import('@aiready/doc-drift');
+
+  const config = await loadConfig(directory);
+  const merged = mergeConfigWithDefaults(config, {
+    staleMonths: 6,
+  });
+
+  const report = await analyzeDocDrift({
+    rootDir: directory,
+    include: options.include,
+    exclude: options.exclude,
+    staleMonths: options.staleMonths ?? merged.staleMonths ?? 6,
+  });
+
+  const scoring: ToolScoringOutput = {
+    toolName: 'doc-drift',
+    score: report.summary.score,
+    rawMetrics: report.rawData,
+    factors: [],
+    recommendations: report.recommendations.map((action: string) => ({ action, estimatedImpact: 5, priority: 'medium' }))
+  };
+
+  if (options.output === 'json') {
+    return scoring;
+  }
+
+  const { summary } = report;
+  const ratingColors: Record<string, Function> = {
+    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.`));
+  }
+
+  return scoring;
+}

package/src/commands/hallucination-risk.ts

@@ -0,0 +1,51 @@
+/**
+ * Hallucination risk command for unified CLI
+ */
+
+import chalk from 'chalk';
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { resolveOutputPath, loadConfig, mergeConfigWithDefaults } from '@aiready/core';
+import type { ToolScoringOutput } from '@aiready/core';
+
+export async function hallucinationRiskAction(
+  directory: string,
+  options: any,
+): Promise<ToolScoringOutput | undefined> {
+  const { analyzeHallucinationRisk, calculateHallucinationScore } = await import('@aiready/hallucination-risk');
+
+  const config = await loadConfig(directory);
+  const merged = mergeConfigWithDefaults(config, {
+    minSeverity: 'info',
+  });
+
+  const report = await analyzeHallucinationRisk({
+    rootDir: directory,
+    minSeverity: options.minSeverity ?? merged.minSeverity ?? 'info',
+    include: options.include,
+    exclude: options.exclude,
+  });
+
+  const scoring = calculateHallucinationScore(report);
+
+  if (options.output === 'json') {
+    return scoring;
+  }
+
+  const { summary } = report;
+  const ratingColors: Record<string, Function> = {
+    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(`  🧠 Hallucination Risk:  ${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`));
+  }
+
+  return scoring;
+}

package/src/commands/index.ts

@@ -6,4 +6,7 @@ export { scanAction, scanHelpText } from './scan';
 export { patternsAction, patternsHelpText } from './patterns';
 export { contextAction } from './context';
 export { consistencyAction } from './consistency';
-export { visualizeAction, visualizeHelpText, visualiseHelpText } from './visualize';
+export { visualizeAction, visualizeHelpText, visualiseHelpText } from './visualize';
+export { hallucinationRiskAction } from './hallucination-risk';
+export { agentGroundingAction } from './agent-grounding';
+export { testabilityAction } from './testability';

package/src/commands/scan.ts

@@ -3,14 +3,14 @@
  */
 
 import chalk from 'chalk';
-import { writeFileSync } from 'fs';
+import { writeFileSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { resolve as resolvePath } from 'path';
-import { 
-  loadMergedConfig, 
-  handleJSONOutput, 
-  handleCLIError, 
-  getElapsedTime, 
+import {
+  loadMergedConfig,
+  handleJSONOutput,
+  handleCLIError,
+  getElapsedTime,
   resolveOutputPath,
   calculateOverallScore,
   formatScore,
@@ -25,6 +25,8 @@ import { getReportTimestamp, warnIfGraphCapExceeded, truncateArray } from '../ut
 
 interface ScanOptions {
   tools?: string;
+  profile?: string;
+  compareTo?: string;
   include?: string;
   exclude?: string;
   output?: string;
@@ -47,7 +49,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
   try {
     // Define defaults
     const defaults = {
-      tools: ['patterns', 'context', 'consistency'],
+      tools: ['patterns', 'context', 'consistency', 'hallucination', 'grounding', 'testability', 'doc-drift', 'deps-health'],
       include: undefined,
       exclude: undefined,
       output: {
@@ -56,9 +58,29 @@ export async function scanAction(directory: string, options: ScanOptions) {
       },
     };
 
+    let profileTools = options.tools ? options.tools.split(',').map((t: string) => t.trim()) : undefined;
+    if (options.profile) {
+      switch (options.profile.toLowerCase()) {
+        case 'agentic':
+          profileTools = ['hallucination', 'grounding', 'testability'];
+          break;
+        case 'cost':
+          profileTools = ['patterns', 'context'];
+          break;
+        case 'security':
+          profileTools = ['consistency', 'testability'];
+          break;
+        case 'onboarding':
+          profileTools = ['context', 'consistency', 'grounding'];
+          break;
+        default:
+          console.log(chalk.yellow(`\n⚠️  Unknown profile '${options.profile}'. Using specified tools or defaults.`));
+      }
+    }
+
     // Load and merge config with CLI options
     const baseOptions = await loadMergedConfig(resolvedDir, defaults, {
-      tools: options.tools ? options.tools.split(',').map((t: string) => t.trim()) as ('patterns' | 'context' | 'consistency')[] : undefined,
+      tools: profileTools as any,
       include: options.include?.split(','),
       exclude: options.exclude?.split(','),
     }) as any;
@@ -210,7 +232,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
               const sample = issues.find((it: any) => it.severity === 'critical' || it.severity === 'major') || issues[0];
               const sampleMsg = sample ? ` — ${sample.message}` : '';
 
-              console.log(`   ${idx + 1}. ${file} — ${issues.length} issue(s) (critical:${counts.critical||0} major:${counts.major||0} minor:${counts.minor||0} info:${counts.info||0})${sampleMsg}`);
+              console.log(`   ${idx + 1}. ${file} — ${issues.length} issue(s) (critical:${counts.critical || 0} major:${counts.major || 0} minor:${counts.minor || 0} info:${counts.info || 0})${sampleMsg}`);
             });
 
             const remaining = files.length - topFiles.length;
@@ -218,6 +240,20 @@ export async function scanAction(directory: string, options: ScanOptions) {
               console.log(chalk.dim(`   ... and ${remaining} more files with issues (use --output json for full details)`));
             }
           }
+        } else if (event.tool === 'doc-drift') {
+          const dr = event.data as any;
+          console.log(`  Issues found: ${chalk.bold(String(dr.issues?.length || 0))}`);
+          if (dr.rawData) {
+            console.log(`  Signature Mismatches: ${chalk.bold(dr.rawData.outdatedComments || 0)}`);
+            console.log(`  Undocumented Complexity: ${chalk.bold(dr.rawData.undocumentedComplexity || 0)}`);
+          }
+        } else if (event.tool === 'deps-health') {
+          const dr = event.data as any;
+          console.log(`  Packages Analyzed: ${chalk.bold(String(dr.summary?.packagesAnalyzed || 0))}`);
+          if (dr.rawData) {
+            console.log(`  Deprecated Packages: ${chalk.bold(dr.rawData.deprecatedPackages || 0)}`);
+            console.log(`  AI Cutoff Skew Score: ${chalk.bold(dr.rawData.trainingCutoffSkew?.toFixed(1) || 0)}`);
+          }
         }
       } catch (err) {
         // don't crash the run for progress printing errors
@@ -282,6 +318,61 @@ export async function scanAction(directory: string, options: ScanOptions) {
         }
       }
 
+      // Hallucination risk score
+      if (results.hallucination) {
+        const { calculateHallucinationScore } = await import('@aiready/hallucination-risk');
+        try {
+          const hrScore = calculateHallucinationScore(results.hallucination);
+          toolScores.set('hallucination-risk', hrScore);
+        } catch (err) {
+          // ignore
+        }
+      }
+
+      // Agent grounding score
+      if (results.grounding) {
+        const { calculateGroundingScore } = await import('@aiready/agent-grounding');
+        try {
+          const agScore = calculateGroundingScore(results.grounding);
+          toolScores.set('agent-grounding', agScore);
+        } catch (err) {
+          // ignore
+        }
+      }
+
+      // Testability score
+      if (results.testability) {
+        const { calculateTestabilityScore } = await import('@aiready/testability');
+        try {
+          const tbScore = calculateTestabilityScore(results.testability);
+          toolScores.set('testability', tbScore);
+        } catch (err) {
+          // ignore
+        }
+      }
+
+      // Documentation Drift score
+      if (results.docDrift) {
+        toolScores.set('doc-drift', {
+          toolName: 'doc-drift',
+          score: results.docDrift.summary.score,
+          rawMetrics: results.docDrift.rawData,
+          factors: [],
+          recommendations: results.docDrift.recommendations.map((action: string) => ({ action, estimatedImpact: 5, priority: 'medium' }))
+        });
+      }
+
+      // Dependency Health score
+      if (results.deps) {
+        toolScores.set('dependency-health', {
+          toolName: 'dependency-health',
+          score: results.deps.summary.score,
+          rawMetrics: results.deps.rawData,
+          factors: [],
+          recommendations: results.deps.recommendations.map((action: string) => ({ action, estimatedImpact: 5, priority: 'medium' }))
+        });
+      }
+
       // Parse CLI weight overrides (if any)
       const cliWeights = parseWeightString((options as any).weights);
 
@@ -292,6 +383,40 @@ export async function scanAction(directory: string, options: ScanOptions) {
         console.log(chalk.bold('\n📊 AI Readiness Overall Score'));
         console.log(`  ${formatScore(scoringResult)}`);
 
+        // Check if we need to compare to a previous report
+        if (options.compareTo) {
+          try {
+            const prevReportStr = readFileSync(resolvePath(process.cwd(), options.compareTo), 'utf8');
+            const prevReport = JSON.parse(prevReportStr);
+            const prevScore = prevReport.scoring?.score || prevReport.scoring?.overallScore;
+
+            if (typeof prevScore === 'number') {
+              const diff = scoringResult.overall - prevScore;
+              const diffStr = diff > 0 ? `+${diff}` : String(diff);
+              console.log();
+              if (diff > 0) {
+                console.log(chalk.green(`  📈 Trend: ${diffStr} compared to ${options.compareTo} (${prevScore} → ${scoringResult.overall})`));
+              } else if (diff < 0) {
+                console.log(chalk.red(`  📉 Trend: ${diffStr} compared to ${options.compareTo} (${prevScore} → ${scoringResult.overall})`));
+                // Trend gating: if we regressed and CI is on or threshold is present, we could lower the threshold effectively,
+                // but for now, we just highlight the regression.
+              } else {
+                console.log(chalk.blue(`  ➖ Trend: No change compared to ${options.compareTo} (${prevScore} → ${scoringResult.overall})`));
+              }
+
+              // Add trend info to scoringResult for programmatic use
+              (scoringResult as any).trend = {
+                previousScore: prevScore,
+                difference: diff
+              };
+            } else {
+              console.log(chalk.yellow(`\n  ⚠️  Previous report at ${options.compareTo} does not contain an overall score.`));
+            }
+          } catch (e) {
+            console.log(chalk.yellow(`\n  ⚠️  Could not read or parse previous report at ${options.compareTo}.`));
+          }
+        }
+
         // Show concise breakdown; detailed breakdown only if config requests it
         if (scoringResult.breakdown && scoringResult.breakdown.length > 0) {
           console.log(chalk.bold('\nTool breakdown:'));
@@ -322,7 +447,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
       const outputPath = resolveOutputPath(userOutputFile, defaultFilename, resolvedDir);
       const outputData = { ...results, scoring: scoringResult };
       handleJSONOutput(outputData, outputPath, `✅ Report saved to ${outputPath}`);
-      
+
       // Warn if graph caps may be exceeded
       warnIfGraphCapExceeded(outputData, resolvedDir);
     }
@@ -332,28 +457,28 @@ export async function scanAction(directory: string, options: ScanOptions) {
     if (isCI && scoringResult) {
       const threshold = options.threshold ? parseInt(options.threshold) : undefined;
       const failOnLevel = options.failOn || 'critical';
-      
+
       // Output GitHub Actions annotations
       if (process.env.GITHUB_ACTIONS === 'true') {
         console.log(`\n::group::AI Readiness Score`);
-        console.log(`score=${scoringResult.overallScore}`);
+        console.log(`score=${scoringResult.overall}`);
         if (scoringResult.breakdown) {
           scoringResult.breakdown.forEach(tool => {
             console.log(`${tool.toolName}=${tool.score}`);
           });
         }
         console.log('::endgroup::');
-        
+
         // Output annotation for score
-        if (threshold && scoringResult.overallScore < threshold) {
-          console.log(`::error::AI Readiness Score ${scoringResult.overallScore} is below threshold ${threshold}`);
+        if (threshold && scoringResult.overall < threshold) {
+          console.log(`::error::AI Readiness Score ${scoringResult.overall} is below threshold ${threshold}`);
         } else if (threshold) {
-          console.log(`::notice::AI Readiness Score: ${scoringResult.overallScore}/100 (threshold: ${threshold})`);
+          console.log(`::notice::AI Readiness Score: ${scoringResult.overall}/100 (threshold: ${threshold})`);
         }
-        
+
         // Output annotations for critical issues
         if (results.patterns) {
-          const criticalPatterns = results.patterns.flatMap((p: any) => 
+          const criticalPatterns = results.patterns.flatMap((p: any) =>
             p.issues.filter((i: any) => i.severity === 'critical')
           );
           criticalPatterns.slice(0, 10).forEach((issue: any) => {
@@ -365,21 +490,21 @@ export async function scanAction(directory: string, options: ScanOptions) {
       // Determine if we should fail
       let shouldFail = false;
       let failReason = '';
-      
+
       // Check threshold
-      if (threshold && scoringResult.overallScore < threshold) {
+      if (threshold && scoringResult.overall < threshold) {
         shouldFail = true;
-        failReason = `AI Readiness Score ${scoringResult.overallScore} is below threshold ${threshold}`;
+        failReason = `AI Readiness Score ${scoringResult.overall} is below threshold ${threshold}`;
       }
-      
+
       // Check fail-on severity
       if (failOnLevel !== 'none') {
         const severityLevels = { critical: 4, major: 3, minor: 2, any: 1 };
         const minSeverity = severityLevels[failOnLevel as keyof typeof severityLevels] || 4;
-        
+
         let criticalCount = 0;
         let majorCount = 0;
-        
+
         if (results.patterns) {
           results.patterns.forEach((p: any) => {
             p.issues.forEach((i: any) => {
@@ -402,7 +527,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
             });
           });
         }
-        
+
         if (minSeverity >= 4 && criticalCount > 0) {
           shouldFail = true;
           failReason = `Found ${criticalCount} critical issues`;
@@ -411,7 +536,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
           failReason = `Found ${criticalCount} critical and ${majorCount} major issues`;
         }
       }
-      
+
       // Output result
       if (shouldFail) {
         console.log(chalk.red('\n🚫 PR BLOCKED: AI Readiness Check Failed'));
@@ -424,7 +549,7 @@ export async function scanAction(directory: string, options: ScanOptions) {
       } else {
         console.log(chalk.green('\n✅ PR PASSED: AI Readiness Check'));
         if (threshold) {
-          console.log(chalk.green(`   Score: ${scoringResult.overallScore}/100 (threshold: ${threshold})`));
+          console.log(chalk.green(`   Score: ${scoringResult.overall}/100 (threshold: ${threshold})`));
         }
         console.log(chalk.dim('\n   💡 Track historical trends: https://getaiready.dev — Team plan $99/mo'));
       }
@@ -438,11 +563,20 @@ export const scanHelpText = `
 EXAMPLES:
   $ aiready scan                                    # Analyze all tools
   $ aiready scan --tools patterns,context           # Skip consistency
+  $ aiready scan --profile agentic                  # Optimize for AI agent execution
+  $ aiready scan --profile security                 # Optimize for secure coding (testability)
+  $ aiready scan --compare-to prev-report.json      # Compare trends against previous run
   $ aiready scan --score --threshold 75             # CI/CD with threshold
   $ aiready scan --ci --threshold 70                # GitHub Actions gatekeeper
   $ aiready scan --ci --fail-on major               # Fail on major+ issues
   $ aiready scan --output json --output-file report.json
 
+PROFILES:
+  agentic:      hallucination, grounding, testability
+  cost:         patterns, context
+  security:     consistency, testability
+  onboarding:   context, consistency, grounding
+
 CI/CD INTEGRATION (Gatekeeper Mode):
   Use --ci for GitHub Actions integration:
   - Outputs GitHub Actions annotations for PR checks

package/src/commands/testability.ts

@@ -0,0 +1,60 @@
+/**
+ * Testability command for unified CLI
+ */
+
+import chalk from 'chalk';
+import { loadConfig, mergeConfigWithDefaults } from '@aiready/core';
+import type { ToolScoringOutput } from '@aiready/core';
+
+export async function testabilityAction(
+  directory: string,
+  options: any,
+): Promise<ToolScoringOutput | undefined> {
+  const { analyzeTestability, calculateTestabilityScore } = await import('@aiready/testability');
+
+  const config = await loadConfig(directory);
+  const merged = mergeConfigWithDefaults(config, {
+    minCoverageRatio: 0.3,
+  });
+
+  const report = await analyzeTestability({
+    rootDir: directory,
+    minCoverageRatio: options.minCoverageRatio ?? merged.minCoverageRatio,
+    include: options.include,
+    exclude: options.exclude,
+  });
+
+  const scoring = calculateTestabilityScore(report);
+
+  if (options.output === 'json') {
+    return scoring;
+  }
+
+  const safetyIcons: Record<string, string> = {
+    'safe': '✅',
+    'moderate-risk': '⚠️ ',
+    'high-risk': '🔴',
+    'blind-risk': '💀',
+  };
+  const safetyColors: Record<string, Function> = {
+    'safe': chalk.green,
+    'moderate-risk': chalk.yellow,
+    'high-risk': chalk.red,
+    'blind-risk': chalk.bgRed.white,
+  };
+
+  const safety = report.summary.aiChangeSafetyRating;
+  const icon = safetyIcons[safety] ?? '❓';
+  const color = safetyColors[safety] ?? chalk.white;
+
+  console.log(`  🧪 Testability:         ${chalk.bold(scoring.score + '/100')} (${report.summary.rating})`);
+  console.log(`     AI Change Safety:  ${color(`${icon} ${safety.toUpperCase()}`)}`);
+  console.log(chalk.dim(`     Coverage: ${Math.round(report.summary.coverageRatio * 100)}%  (${report.rawData.testFiles} test / ${report.rawData.sourceFiles} source files)`));
+
+  // Critical blind-risk banner in the unified output
+  if (safety === 'blind-risk') {
+    console.log(chalk.red.bold('\n     ⚠️  NO TESTS — AI changes to this codebase are completely unverifiable!\n'));
+  }
+
+  return scoring;
+}