@aiready/agent-grounding 0.1.4 → 0.1.6

package/src/cli.ts

@@ -7,15 +7,23 @@ import type { AgentGroundingOptions } from './types';
 import chalk from 'chalk';
 import { writeFileSync, mkdirSync, existsSync } from 'fs';
 import { dirname } from 'path';
-import { loadConfig, mergeConfigWithDefaults, resolveOutputPath } from '@aiready/core';
+import {
+  loadConfig,
+  mergeConfigWithDefaults,
+  resolveOutputPath,
+} from '@aiready/core';
 
 const program = new Command();
 
 program
   .name('aiready-agent-grounding')
-  .description('Measure how well an AI agent can navigate your codebase autonomously')
+  .description(
+    'Measure how well an AI agent can navigate your codebase autonomously'
+  )
   .version('0.1.0')
-  .addHelpText('after', `
+  .addHelpText(
+    'after',
+    `
 GROUNDING DIMENSIONS:
   Structure Clarity     Deep directory trees slow and confuse agents
   Self-Documentation    Vague file names (utils, helpers) hide intent
@@ -27,10 +35,19 @@ EXAMPLES:
   aiready-agent-grounding .                        # Full analysis
   aiready-agent-grounding src/ --output json       # JSON report
   aiready-agent-grounding . --max-depth 3          # Stricter depth limit
-`)
+`
+  )
   .argument('<directory>', 'Directory to analyze')
-  .option('--max-depth <n>', 'Max recommended directory depth (default: 4)', '4')
-  .option('--readme-stale-days <n>', 'Days after which README is considered stale (default: 90)', '90')
+  .option(
+    '--max-depth <n>',
+    'Max recommended directory depth (default: 4)',
+    '4'
+  )
+  .option(
+    '--readme-stale-days <n>',
+    'Days after which README is considered stale (default: 90)',
+    '90'
+  )
   .option('--include <patterns>', 'File patterns to include (comma-separated)')
   .option('--exclude <patterns>', 'File patterns to exclude (comma-separated)')
   .option('-o, --output <format>', 'Output format: console|json', 'console')
@@ -47,8 +64,12 @@ EXAMPLES:
 
     const finalOptions: AgentGroundingOptions = {
       rootDir: directory,
-      maxRecommendedDepth: parseInt(options.maxDepth ?? '4', 10) || mergedConfig.maxRecommendedDepth,
-      readmeStaleDays: parseInt(options.readmeStaleDays ?? '90', 10) || mergedConfig.readmeStaleDays,
+      maxRecommendedDepth:
+        parseInt(options.maxDepth ?? '4', 10) ||
+        mergedConfig.maxRecommendedDepth,
+      readmeStaleDays:
+        parseInt(options.readmeStaleDays ?? '90', 10) ||
+        mergedConfig.readmeStaleDays,
       include: options.include?.split(','),
       exclude: options.exclude?.split(','),
     };
@@ -62,7 +83,7 @@ EXAMPLES:
       const outputPath = resolveOutputPath(
         options.outputFile,
         `agent-grounding-report-${new Date().toISOString().split('T')[0]}.json`,
-        directory,
+        directory
       );
       const dir = dirname(outputPath);
       if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
@@ -84,11 +105,15 @@ function scoreColor(score: number) {
 }
 
 function displayConsoleReport(report: any, scoring: any, elapsed: string) {
-  const { summary, rawData, issues, recommendations } = report;
+  const { summary, issues, recommendations } = report;
 
   console.log(chalk.bold('\n🧭 Agent Grounding Analysis\n'));
-  console.log(`Score:       ${scoreColor(summary.score)(summary.score + '/100')} (${summary.rating.toUpperCase()})`);
-  console.log(`Files:       ${chalk.cyan(summary.filesAnalyzed)}   Directories: ${chalk.cyan(summary.directoriesAnalyzed)}`);
+  console.log(
+    `Score:       ${scoreColor(summary.score)(summary.score + '/100')} (${summary.rating.toUpperCase()})`
+  );
+  console.log(
+    `Files:       ${chalk.cyan(summary.filesAnalyzed)}   Directories: ${chalk.cyan(summary.directoriesAnalyzed)}`
+  );
   console.log(`Analysis:    ${chalk.gray(elapsed + 's')}\n`);
 
   console.log(chalk.bold('📐 Dimension Scores\n'));
@@ -101,24 +126,40 @@ function displayConsoleReport(report: any, scoring: any, elapsed: string) {
   ];
   for (const [name, val] of dims) {
     const bar = '█'.repeat(Math.round((val as number) / 10)).padEnd(10, '░');
-    console.log(`  ${String(name).padEnd(22)} ${scoreColor(val as number)(bar)} ${val}/100`);
+    console.log(
+      `  ${String(name).padEnd(22)} ${scoreColor(val as number)(bar)} ${val}/100`
+    );
   }
 
   if (issues.length > 0) {
     console.log(chalk.bold('\n⚠️  Issues Found\n'));
     for (const issue of issues) {
-      const sev = issue.severity === 'critical' ? chalk.red : issue.severity === 'major' ? chalk.yellow : chalk.blue;
+      const sev =
+        issue.severity === 'critical'
+          ? chalk.red
+          : issue.severity === 'major'
+            ? chalk.yellow
+            : chalk.blue;
       console.log(`${sev(issue.severity.toUpperCase())}  ${issue.message}`);
-      if (issue.suggestion) console.log(`         ${chalk.dim('→')} ${chalk.italic(issue.suggestion)}`);
+      if (issue.suggestion)
+        console.log(
+          `         ${chalk.dim('→')} ${chalk.italic(issue.suggestion)}`
+        );
       console.log();
     }
   } else {
-    console.log(chalk.green('\n✨ No grounding issues found — agents can navigate freely!\n'));
+    console.log(
+      chalk.green(
+        '\n✨ No grounding issues found — agents can navigate freely!\n'
+      )
+    );
   }
 
   if (recommendations.length > 0) {
     console.log(chalk.bold('💡 Recommendations\n'));
-    recommendations.forEach((rec: string, i: number) => console.log(`${i + 1}. ${rec}`));
+    recommendations.forEach((rec: string, i: number) =>
+      console.log(`${i + 1}. ${rec}`)
+    );
   }
   console.log();
 }

package/src/scoring.ts

@@ -1,4 +1,3 @@
-import { calculateAgentGrounding } from '@aiready/core';
 import type { ToolScoringOutput } from '@aiready/core';
 import type { AgentGroundingReport } from './types';
 
@@ -6,8 +5,10 @@ import type { AgentGroundingReport } from './types';
  * Convert agent grounding report into a ToolScoringOutput
  * for inclusion in the unified AIReady score.
  */
-export function calculateGroundingScore(report: AgentGroundingReport): ToolScoringOutput {
-  const { summary, rawData, issues, recommendations } = report;
+export function calculateGroundingScore(
+  report: AgentGroundingReport
+): ToolScoringOutput {
+  const { summary, rawData, recommendations } = report;
 
   const factors: ToolScoringOutput['factors'] = [
     {
@@ -24,7 +25,9 @@ export function calculateGroundingScore(report: AgentGroundingReport): ToolScori
       name: 'Entry Points',
       impact: Math.round(summary.dimensions.entryPointScore - 50),
       description: rawData.hasRootReadme
-        ? rawData.readmeIsFresh ? 'README present and fresh' : 'README present but stale'
+        ? rawData.readmeIsFresh
+          ? 'README present and fresh'
+          : 'README present but stale'
         : 'No root README',
     },
     {
@@ -39,11 +42,13 @@ export function calculateGroundingScore(report: AgentGroundingReport): ToolScori
     },
   ];
 
-  const recs: ToolScoringOutput['recommendations'] = recommendations.map(action => ({
-    action,
-    estimatedImpact: 6,
-    priority: summary.score < 50 ? 'high' : 'medium',
-  }));
+  const recs: ToolScoringOutput['recommendations'] = recommendations.map(
+    (action) => ({
+      action,
+      estimatedImpact: 6,
+      priority: summary.score < 50 ? 'high' : 'medium',
+    })
+  );
 
   return {
     toolName: 'agent-grounding',

package/src/types.ts

@@ -12,7 +12,12 @@ export interface AgentGroundingOptions extends ScanOptions {
 export interface AgentGroundingIssue extends Issue {
   type: 'agent-navigation-failure';
   /** Which grounding dimension is affected */
-  dimension: 'structure-clarity' | 'self-documentation' | 'entry-point' | 'api-clarity' | 'domain-consistency';
+  dimension:
+    | 'structure-clarity'
+    | 'self-documentation'
+    | 'entry-point'
+    | 'api-clarity'
+    | 'domain-consistency';
 }
 
 export interface AgentGroundingReport {