@aiready/agent-grounding 0.1.1

package/src/analyzer.ts

@@ -0,0 +1,334 @@
+/**
+ * Scanner for agent-grounding dimensions.
+ * 
+ * Measures 5 dimensions:
+ * 1. Structure clarity — how deep are directory trees?
+ * 2. Self-documentation — do file names reveal purpose?
+ * 3. Entry points — does a fresh README + barrel exports exist?
+ * 4. API clarity — are public exports typed?
+ * 5. Domain consistency — is the same concept named the same everywhere?
+ */
+
+import { readdirSync, statSync, existsSync, readFileSync } from 'fs';
+import { join, extname, basename } from 'path';
+import { parse } from '@typescript-eslint/typescript-estree';
+import type { TSESTree } from '@typescript-eslint/types';
+import type { AgentGroundingOptions, AgentGroundingIssue, AgentGroundingReport } from './types';
+import { calculateAgentGrounding } from '@aiready/core';
+
+// File names that don't describe purpose — an agent can't determine what to find here
+const VAGUE_FILE_NAMES = new Set([
+  'utils', 'helpers', 'helper', 'misc', 'common', 'shared', 'tools',
+  'util', 'lib', 'libs', 'stuff', 'functions', 'methods', 'handlers',
+  'data', 'temp', 'tmp', 'test-utils', 'test-helpers', 'mocks',
+]);
+
+const SUPPORTED_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx']);
+const DEFAULT_EXCLUDES = ['node_modules', 'dist', '.git', 'coverage', '.turbo', 'build'];
+
+// ---------------------------------------------------------------------------
+// File/dir collection
+// ---------------------------------------------------------------------------
+
+interface DirEntry {
+  path: string;
+  depth: number;
+}
+
+function collectEntries(
+  dir: string,
+  options: AgentGroundingOptions,
+  depth = 0,
+  dirs: DirEntry[] = [],
+  files: string[] = [],
+): { dirs: DirEntry[]; files: string[] } {
+  if (depth > (options.maxDepth ?? 20)) return { dirs, files };
+  const excludes = [...DEFAULT_EXCLUDES, ...(options.exclude ?? [])];
+
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return { dirs, files };
+  }
+
+  for (const entry of entries) {
+    if (excludes.some(ex => entry === ex || entry.includes(ex))) continue;
+    const full = join(dir, entry);
+    let stat;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      dirs.push({ path: full, depth });
+      collectEntries(full, options, depth + 1, dirs, files);
+    } else if (stat.isFile() && SUPPORTED_EXTENSIONS.has(extname(full))) {
+      if (!options.include || options.include.some(p => full.includes(p))) {
+        files.push(full);
+      }
+    }
+  }
+
+  return { dirs, files };
+}
+
+// ---------------------------------------------------------------------------
+// Per-file analysis
+// ---------------------------------------------------------------------------
+
+interface FileAnalysis {
+  isBarrel: boolean;
+  exportedNames: string[];
+  untypedExports: number;
+  totalExports: number;
+  domainTerms: string[];
+}
+
+function analyzeFile(filePath: string): FileAnalysis {
+  let code: string;
+  try {
+    code = readFileSync(filePath, 'utf-8');
+  } catch {
+    return { isBarrel: false, exportedNames: [], untypedExports: 0, totalExports: 0, domainTerms: [] };
+  }
+
+  let ast: TSESTree.Program;
+  try {
+    ast = parse(code, {
+      jsx: filePath.endsWith('.tsx') || filePath.endsWith('.jsx'),
+      range: false,
+      loc: false,
+    });
+  } catch {
+    return { isBarrel: false, exportedNames: [], untypedExports: 0, totalExports: 0, domainTerms: [] };
+  }
+
+  let isBarrel = false;
+  let exportedNames: string[] = [];
+  let untypedExports = 0;
+  let totalExports = 0;
+
+  // Extract "domain terms" from exported identifier names (camelCase split)
+  const domainTerms: string[] = [];
+
+  for (const node of ast.body) {
+    if (node.type === 'ExportAllDeclaration') {
+      isBarrel = true;
+      continue;
+    }
+    if (node.type === 'ExportNamedDeclaration') {
+      totalExports++;
+      const decl = (node as any).declaration;
+      if (decl) {
+        const name = decl.id?.name ?? decl.declarations?.[0]?.id?.name;
+        if (name) {
+          exportedNames.push(name);
+          // Split camelCase into terms
+          domainTerms.push(...name.replace(/([A-Z])/g, ' $1').toLowerCase().split(/\s+/).filter(Boolean));
+
+          // Check if it's typed (TS function/variable with annotation)
+          const hasType =
+            decl.returnType != null ||
+            decl.declarations?.[0]?.id?.typeAnnotation != null ||
+            decl.typeParameters != null;
+          if (!hasType) untypedExports++;
+        }
+      } else if (node.specifiers && node.specifiers.length > 0) {
+        // Named re-exports from another module — this is barrel-like
+        isBarrel = true;
+      }
+    }
+    if (node.type === 'ExportDefaultDeclaration') {
+      totalExports++;
+    }
+  }
+
+  return { isBarrel, exportedNames, untypedExports, totalExports, domainTerms };
+}
+
+// ---------------------------------------------------------------------------
+// Domain vocabulary consistency check
+// ---------------------------------------------------------------------------
+
+function detectInconsistentTerms(allTerms: string[]): { inconsistent: number; vocabularySize: number } {
+  const termFreq = new Map<string, number>();
+  for (const term of allTerms) {
+    if (term.length >= 3) {
+      termFreq.set(term, (termFreq.get(term) ?? 0) + 1);
+    }
+  }
+  // Very simplistic: terms that appear exactly once are "orphan concepts" —
+  // they may be inconsistently named variants of common terms.
+  const orphans = [...termFreq.values()].filter(count => count === 1).length;
+  const common = [...termFreq.values()].filter(count => count >= 3).length;
+  const vocabularySize = termFreq.size;
+  // Inconsistency ratio: many orphan terms relative to common terms
+  const inconsistent = Math.max(0, orphans - common * 2);
+  return { inconsistent, vocabularySize };
+}
+
+// ---------------------------------------------------------------------------
+// Main analyzer
+// ---------------------------------------------------------------------------
+
+export async function analyzeAgentGrounding(
+  options: AgentGroundingOptions,
+): Promise<AgentGroundingReport> {
+  const rootDir = options.rootDir;
+  const maxRecommendedDepth = options.maxRecommendedDepth ?? 4;
+  const readmeStaleDays = options.readmeStaleDays ?? 90;
+
+  const { dirs, files } = collectEntries(rootDir, options);
+
+  // Structure clarity
+  const deepDirectories = dirs.filter(d => d.depth > maxRecommendedDepth).length;
+
+  // Self-documentation — vague file names
+  const additionalVague = new Set((options.additionalVagueNames ?? []).map(n => n.toLowerCase()));
+  let vagueFileNames = 0;
+  for (const f of files) {
+    const base = basename(f, extname(f)).toLowerCase();
+    if (VAGUE_FILE_NAMES.has(base) || additionalVague.has(base)) {
+      vagueFileNames++;
+    }
+  }
+
+  // README presence and freshness
+  const readmePath = join(rootDir, 'README.md');
+  const hasRootReadme = existsSync(readmePath);
+  let readmeIsFresh = false;
+  if (hasRootReadme) {
+    try {
+      const stat = statSync(readmePath);
+      const ageDays = (Date.now() - stat.mtimeMs) / (1000 * 60 * 60 * 24);
+      readmeIsFresh = ageDays < readmeStaleDays;
+    } catch { }
+  }
+
+  // File analysis
+  const allDomainTerms: string[] = [];
+  let barrelExports = 0;
+  let untypedExports = 0;
+  let totalExports = 0;
+
+  for (const f of files) {
+    const analysis = analyzeFile(f);
+    if (analysis.isBarrel) barrelExports++;
+    untypedExports += analysis.untypedExports;
+    totalExports += analysis.totalExports;
+    allDomainTerms.push(...analysis.domainTerms);
+  }
+
+  // Domain vocabulary consistency
+  const { inconsistent: inconsistentDomainTerms, vocabularySize: domainVocabularySize } =
+    detectInconsistentTerms(allDomainTerms);
+
+  // Calculate grounding score using core math
+  const groundingResult = calculateAgentGrounding({
+    deepDirectories,
+    totalDirectories: dirs.length,
+    vagueFileNames,
+    totalFiles: files.length,
+    hasRootReadme,
+    readmeIsFresh,
+    barrelExports,
+    untypedExports,
+    totalExports: Math.max(1, totalExports),
+    inconsistentDomainTerms,
+    domainVocabularySize: Math.max(1, domainVocabularySize),
+  });
+
+  // Build issues list
+  const issues: AgentGroundingIssue[] = [];
+
+  if (groundingResult.dimensions.structureClarityScore < 70) {
+    issues.push({
+      type: 'agent-navigation-failure',
+      dimension: 'structure-clarity',
+      severity: 'major',
+      message: `${deepDirectories} directories exceed recommended depth of ${maxRecommendedDepth} — agents struggle to navigate deep trees.`,
+      location: { file: rootDir, line: 0 },
+      suggestion: `Flatten nested directories to ${maxRecommendedDepth} levels or fewer.`,
+    });
+  }
+
+  if (groundingResult.dimensions.selfDocumentationScore < 70) {
+    issues.push({
+      type: 'agent-navigation-failure',
+      dimension: 'self-documentation',
+      severity: 'major',
+      message: `${vagueFileNames} files use vague names (utils, helpers, misc) — an agent cannot determine their purpose from the name alone.`,
+      location: { file: rootDir, line: 0 },
+      suggestion: 'Rename to domain-specific names: e.g., userAuthUtils → tokenValidator.',
+    });
+  }
+
+  if (!hasRootReadme) {
+    issues.push({
+      type: 'agent-navigation-failure',
+      dimension: 'entry-point',
+      severity: 'critical',
+      message: 'No root README.md found — agents have no orientation document to start from.',
+      location: { file: join(rootDir, 'README.md'), line: 0 },
+      suggestion: 'Add a README.md explaining the project structure, entry points, and key conventions.',
+    });
+  } else if (!readmeIsFresh) {
+    issues.push({
+      type: 'agent-navigation-failure',
+      dimension: 'entry-point',
+      severity: 'minor',
+      message: `README.md is stale (>${readmeStaleDays} days without updates) — agents may be misled by outdated context.`,
+      location: { file: readmePath, line: 0 },
+      suggestion: 'Update README.md to reflect the current codebase structure.',
+    });
+  }
+
+  if (groundingResult.dimensions.apiClarityScore < 70) {
+    issues.push({
+      type: 'agent-navigation-failure',
+      dimension: 'api-clarity',
+      severity: 'major',
+      message: `${untypedExports} of ${totalExports} public exports lack TypeScript type annotations — agents cannot infer the API contract.`,
+      location: { file: rootDir, line: 0 },
+      suggestion: 'Add explicit return type and parameter annotations to all exported functions.',
+    });
+  }
+
+  if (groundingResult.dimensions.domainConsistencyScore < 70) {
+    issues.push({
+      type: 'agent-navigation-failure',
+      dimension: 'domain-consistency',
+      severity: 'major',
+      message: `${inconsistentDomainTerms} domain terms appear to be used inconsistently — agents get confused when one concept has multiple names.`,
+      location: { file: rootDir, line: 0 },
+      suggestion: 'Establish a domain glossary and enforce one term per concept across the codebase.',
+    });
+  }
+
+  return {
+    summary: {
+      filesAnalyzed: files.length,
+      directoriesAnalyzed: dirs.length,
+      score: groundingResult.score,
+      rating: groundingResult.rating,
+      dimensions: groundingResult.dimensions,
+    },
+    issues,
+    rawData: {
+      deepDirectories,
+      totalDirectories: dirs.length,
+      vagueFileNames,
+      totalFiles: files.length,
+      hasRootReadme,
+      readmeIsFresh,
+      barrelExports,
+      untypedExports,
+      totalExports,
+      inconsistentDomainTerms,
+      domainVocabularySize,
+    },
+    recommendations: groundingResult.recommendations,
+  };
+}

package/src/cli.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { analyzeAgentGrounding } from './analyzer';
+import { calculateGroundingScore } from './scoring';
+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';
+
+const program = new Command();
+
+program
+  .name('aiready-agent-grounding')
+  .description('Measure how well an AI agent can navigate your codebase autonomously')
+  .version('0.1.0')
+  .addHelpText('after', `
+GROUNDING DIMENSIONS:
+  Structure Clarity     Deep directory trees slow and confuse agents
+  Self-Documentation    Vague file names (utils, helpers) hide intent
+  Entry Points          README presence, freshness, and barrel exports
+  API Clarity           Untyped exports prevent API contract inference
+  Domain Consistency    Inconsistent naming forces agents to guess
+
+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('--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')
+  .option('--output-file <path>', 'Output file path (for json)')
+  .action(async (directory, options) => {
+    console.log(chalk.blue('🧭 Analyzing agent grounding...\n'));
+    const startTime = Date.now();
+
+    const config = await loadConfig(directory);
+    const mergedConfig = mergeConfigWithDefaults(config, {
+      maxRecommendedDepth: 4,
+      readmeStaleDays: 90,
+    });
+
+    const finalOptions: AgentGroundingOptions = {
+      rootDir: directory,
+      maxRecommendedDepth: parseInt(options.maxDepth ?? '4', 10) || mergedConfig.maxRecommendedDepth,
+      readmeStaleDays: parseInt(options.readmeStaleDays ?? '90', 10) || mergedConfig.readmeStaleDays,
+      include: options.include?.split(','),
+      exclude: options.exclude?.split(','),
+    };
+
+    const report = await analyzeAgentGrounding(finalOptions);
+    const scoring = calculateGroundingScore(report);
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+
+    if (options.output === 'json') {
+      const payload = { report, score: scoring };
+      const outputPath = resolveOutputPath(
+        options.outputFile,
+        `agent-grounding-report-${new Date().toISOString().split('T')[0]}.json`,
+        directory,
+      );
+      const dir = dirname(outputPath);
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      writeFileSync(outputPath, JSON.stringify(payload, null, 2));
+      console.log(chalk.green(`✓ Report saved to ${outputPath}`));
+    } else {
+      displayConsoleReport(report, scoring, elapsed);
+    }
+  });
+
+program.parse();
+
+function scoreColor(score: number) {
+  if (score >= 85) return chalk.green;
+  if (score >= 70) return chalk.cyan;
+  if (score >= 50) return chalk.yellow;
+  if (score >= 30) return chalk.red;
+  return chalk.bgRed.white;
+}
+
+function displayConsoleReport(report: any, scoring: any, elapsed: string) {
+  const { summary, rawData, 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(`Analysis:    ${chalk.gray(elapsed + 's')}\n`);
+
+  console.log(chalk.bold('📐 Dimension Scores\n'));
+  const dims = [
+    ['Structure Clarity', summary.dimensions.structureClarityScore],
+    ['Self-Documentation', summary.dimensions.selfDocumentationScore],
+    ['Entry Points', summary.dimensions.entryPointScore],
+    ['API Clarity', summary.dimensions.apiClarityScore],
+    ['Domain Consistency', summary.dimensions.domainConsistencyScore],
+  ];
+  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`);
+  }
+
+  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;
+      console.log(`${sev(issue.severity.toUpperCase())}  ${issue.message}`);
+      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'));
+  }
+
+  if (recommendations.length > 0) {
+    console.log(chalk.bold('💡 Recommendations\n'));
+    recommendations.forEach((rec: string, i: number) => console.log(`${i + 1}. ${rec}`));
+  }
+  console.log();
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { analyzeAgentGrounding } from './analyzer';
+export { calculateGroundingScore } from './scoring';
+export type {
+  AgentGroundingOptions,
+  AgentGroundingReport,
+  AgentGroundingIssue,
+} from './types';

package/src/scoring.ts

@@ -0,0 +1,58 @@
+import { calculateAgentGrounding } from '@aiready/core';
+import type { ToolScoringOutput } from '@aiready/core';
+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;
+
+  const factors: ToolScoringOutput['factors'] = [
+    {
+      name: 'Structure Clarity',
+      impact: Math.round(summary.dimensions.structureClarityScore - 50),
+      description: `${rawData.deepDirectories} of ${rawData.totalDirectories} dirs exceed recommended depth`,
+    },
+    {
+      name: 'Self-Documentation',
+      impact: Math.round(summary.dimensions.selfDocumentationScore - 50),
+      description: `${rawData.vagueFileNames} of ${rawData.totalFiles} files have vague names`,
+    },
+    {
+      name: 'Entry Points',
+      impact: Math.round(summary.dimensions.entryPointScore - 50),
+      description: rawData.hasRootReadme
+        ? rawData.readmeIsFresh ? 'README present and fresh' : 'README present but stale'
+        : 'No root README',
+    },
+    {
+      name: 'API Clarity',
+      impact: Math.round(summary.dimensions.apiClarityScore - 50),
+      description: `${rawData.untypedExports} of ${rawData.totalExports} exports lack type annotations`,
+    },
+    {
+      name: 'Domain Consistency',
+      impact: Math.round(summary.dimensions.domainConsistencyScore - 50),
+      description: `${rawData.inconsistentDomainTerms} inconsistent domain terms detected`,
+    },
+  ];
+
+  const recs: ToolScoringOutput['recommendations'] = recommendations.map(action => ({
+    action,
+    estimatedImpact: 6,
+    priority: summary.score < 50 ? 'high' : 'medium',
+  }));
+
+  return {
+    toolName: 'agent-grounding',
+    score: summary.score,
+    rawMetrics: {
+      ...rawData,
+      rating: summary.rating,
+    },
+    factors,
+    recommendations: recs,
+  };
+}

package/src/types.ts

@@ -0,0 +1,47 @@
+import type { ScanOptions, Issue } from '@aiready/core';
+
+export interface AgentGroundingOptions extends ScanOptions {
+  /** Max directory depth before flagging as "too deep" */
+  maxRecommendedDepth?: number;
+  /** README staleness threshold in days */
+  readmeStaleDays?: number;
+  /** File names considered "vague" (in addition to built-in list) */
+  additionalVagueNames?: string[];
+}
+
+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';
+}
+
+export interface AgentGroundingReport {
+  summary: {
+    filesAnalyzed: number;
+    directoriesAnalyzed: number;
+    score: number;
+    rating: 'excellent' | 'good' | 'moderate' | 'poor' | 'disorienting';
+    dimensions: {
+      structureClarityScore: number;
+      selfDocumentationScore: number;
+      entryPointScore: number;
+      apiClarityScore: number;
+      domainConsistencyScore: number;
+    };
+  };
+  issues: AgentGroundingIssue[];
+  rawData: {
+    deepDirectories: number;
+    totalDirectories: number;
+    vagueFileNames: number;
+    totalFiles: number;
+    hasRootReadme: boolean;
+    readmeIsFresh: boolean;
+    barrelExports: number;
+    untypedExports: number;
+    totalExports: number;
+    inconsistentDomainTerms: number;
+    domainVocabularySize: number;
+  };
+  recommendations: string[];
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../core/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}