@aiready/agent-grounding 0.1.5 → 0.1.8

package/dist/cli.mjs

@@ -2,16 +2,24 @@
 import {
   analyzeAgentGrounding,
   calculateGroundingScore
-} from "./chunk-OOB3JMXQ.mjs";
+} from "./chunk-NXIMJNCK.mjs";
 
 // src/cli.ts
 import { Command } from "commander";
 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";
 var 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", `
+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
@@ -23,7 +31,16 @@ 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) => {
+`
+).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("\u{1F9ED} Analyzing agent grounding...\n"));
   const startTime = Date.now();
   const config = await loadConfig(directory);
@@ -65,10 +82,14 @@ function scoreColor(score) {
   return chalk.bgRed.white;
 }
 function displayConsoleReport(report, scoring, elapsed) {
-  const { summary, rawData, issues, recommendations } = report;
+  const { summary, issues, recommendations } = report;
   console.log(chalk.bold("\n\u{1F9ED} 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")}
 `);
   console.log(chalk.bold("\u{1F4D0} Dimension Scores\n"));
@@ -81,22 +102,33 @@ function displayConsoleReport(report, scoring, elapsed) {
   ];
   for (const [name, val] of dims) {
     const bar = "\u2588".repeat(Math.round(val / 10)).padEnd(10, "\u2591");
-    console.log(`  ${String(name).padEnd(22)} ${scoreColor(val)(bar)} ${val}/100`);
+    console.log(
+      `  ${String(name).padEnd(22)} ${scoreColor(val)(bar)} ${val}/100`
+    );
   }
   if (issues.length > 0) {
     console.log(chalk.bold("\n\u26A0\uFE0F  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("\u2192")} ${chalk.italic(issue.suggestion)}`);
+      if (issue.suggestion)
+        console.log(
+          `         ${chalk.dim("\u2192")} ${chalk.italic(issue.suggestion)}`
+        );
       console.log();
     }
   } else {
-    console.log(chalk.green("\n\u2728 No grounding issues found \u2014 agents can navigate freely!\n"));
+    console.log(
+      chalk.green(
+        "\n\u2728 No grounding issues found \u2014 agents can navigate freely!\n"
+      )
+    );
   }
   if (recommendations.length > 0) {
     console.log(chalk.bold("\u{1F4A1} Recommendations\n"));
-    recommendations.forEach((rec, i) => console.log(`${i + 1}. ${rec}`));
+    recommendations.forEach(
+      (rec, i) => console.log(`${i + 1}. ${rec}`)
+    );
   }
   console.log();
 }

package/dist/index.js

@@ -26,69 +26,22 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/analyzer.ts
+var import_core = require("@aiready/core");
 var import_fs = require("fs");
 var import_path = require("path");
 var import_typescript_estree = require("@typescript-eslint/typescript-estree");
-var import_core = require("@aiready/core");
-var VAGUE_FILE_NAMES = /* @__PURE__ */ new Set([
-  "utils",
-  "helpers",
-  "helper",
-  "misc",
-  "common",
-  "shared",
-  "tools",
-  "util",
-  "lib",
-  "libs",
-  "stuff",
-  "functions",
-  "methods",
-  "handlers",
-  "data",
-  "temp",
-  "tmp",
-  "test-utils",
-  "test-helpers",
-  "mocks"
-]);
-var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
-var DEFAULT_EXCLUDES = ["node_modules", "dist", ".git", "coverage", ".turbo", "build"];
-function collectEntries(dir, options, depth = 0, dirs = [], files = []) {
-  if (depth > (options.maxDepth ?? 20)) return { dirs, files };
-  const excludes = [...DEFAULT_EXCLUDES, ...options.exclude ?? []];
-  let entries;
-  try {
-    entries = (0, import_fs.readdirSync)(dir);
-  } catch {
-    return { dirs, files };
-  }
-  for (const entry of entries) {
-    if (excludes.some((ex) => entry === ex || entry.includes(ex))) continue;
-    const full = (0, import_path.join)(dir, entry);
-    let stat;
-    try {
-      stat = (0, import_fs.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((0, import_path.extname)(full))) {
-      if (!options.include || options.include.some((p) => full.includes(p))) {
-        files.push(full);
-      }
-    }
-  }
-  return { dirs, files };
-}
 function analyzeFile(filePath) {
   let code;
   try {
     code = (0, import_fs.readFileSync)(filePath, "utf-8");
   } catch {
-    return { isBarrel: false, exportedNames: [], untypedExports: 0, totalExports: 0, domainTerms: [] };
+    return {
+      isBarrel: false,
+      exportedNames: [],
+      untypedExports: 0,
+      totalExports: 0,
+      domainTerms: []
+    };
   }
   let ast;
   try {
@@ -98,10 +51,16 @@ function analyzeFile(filePath) {
       loc: false
     });
   } catch {
-    return { isBarrel: false, exportedNames: [], untypedExports: 0, totalExports: 0, domainTerms: [] };
+    return {
+      isBarrel: false,
+      exportedNames: [],
+      untypedExports: 0,
+      totalExports: 0,
+      domainTerms: []
+    };
   }
   let isBarrel = false;
-  let exportedNames = [];
+  const exportedNames = [];
   let untypedExports = 0;
   let totalExports = 0;
   const domainTerms = [];
@@ -117,7 +76,9 @@ function analyzeFile(filePath) {
         const name = decl.id?.name ?? decl.declarations?.[0]?.id?.name;
         if (name) {
           exportedNames.push(name);
-          domainTerms.push(...name.replace(/([A-Z])/g, " $1").toLowerCase().split(/\s+/).filter(Boolean));
+          domainTerms.push(
+            ...name.replace(/([A-Z])/g, " $1").toLowerCase().split(/\s+/).filter(Boolean)
+          );
           const hasType = decl.returnType != null || decl.declarations?.[0]?.id?.typeAnnotation != null || decl.typeParameters != null;
           if (!hasType) untypedExports++;
         }
@@ -148,13 +109,24 @@ async function analyzeAgentGrounding(options) {
   const rootDir = options.rootDir;
   const maxRecommendedDepth = options.maxRecommendedDepth ?? 4;
   const readmeStaleDays = options.readmeStaleDays ?? 90;
-  const { dirs, files } = collectEntries(rootDir, options);
-  const deepDirectories = dirs.filter((d) => d.depth > maxRecommendedDepth).length;
-  const additionalVague = new Set((options.additionalVagueNames ?? []).map((n) => n.toLowerCase()));
+  const { files, dirs: rawDirs } = await (0, import_core.scanEntries)({
+    ...options,
+    include: options.include || ["**/*.{ts,tsx,js,jsx}"]
+  });
+  const dirs = rawDirs.map((d) => ({
+    path: d,
+    depth: (0, import_path.relative)(rootDir, d).split(/[/\\]/).filter(Boolean).length
+  }));
+  const deepDirectories = dirs.filter(
+    (d) => d.depth > maxRecommendedDepth
+  ).length;
+  const additionalVague = new Set(
+    (options.additionalVagueNames ?? []).map((n) => n.toLowerCase())
+  );
   let vagueFileNames = 0;
   for (const f of files) {
     const base = (0, import_path.basename)(f, (0, import_path.extname)(f)).toLowerCase();
-    if (VAGUE_FILE_NAMES.has(base) || additionalVague.has(base)) {
+    if (import_core.VAGUE_FILE_NAMES.has(base) || additionalVague.has(base)) {
       vagueFileNames++;
     }
   }
@@ -173,14 +145,24 @@ async function analyzeAgentGrounding(options) {
   let barrelExports = 0;
   let untypedExports = 0;
   let totalExports = 0;
+  let processed = 0;
   for (const f of files) {
+    processed++;
+    options.onProgress?.(
+      processed,
+      files.length,
+      `agent-grounding: analyzing files`
+    );
     const analysis = analyzeFile(f);
     if (analysis.isBarrel) barrelExports++;
     untypedExports += analysis.untypedExports;
     totalExports += analysis.totalExports;
     allDomainTerms.push(...analysis.domainTerms);
   }
-  const { inconsistent: inconsistentDomainTerms, vocabularySize: domainVocabularySize } = detectInconsistentTerms(allDomainTerms);
+  const {
+    inconsistent: inconsistentDomainTerms,
+    vocabularySize: domainVocabularySize
+  } = detectInconsistentTerms(allDomainTerms);
   const groundingResult = (0, import_core.calculateAgentGrounding)({
     deepDirectories,
     totalDirectories: dirs.length,
@@ -282,7 +264,7 @@ async function analyzeAgentGrounding(options) {
 
 // src/scoring.ts
 function calculateGroundingScore(report) {
-  const { summary, rawData, issues, recommendations } = report;
+  const { summary, rawData, recommendations } = report;
   const factors = [
     {
       name: "Structure Clarity",
@@ -310,11 +292,13 @@ function calculateGroundingScore(report) {
       description: `${rawData.inconsistentDomainTerms} inconsistent domain terms detected`
     }
   ];
-  const recs = recommendations.map((action) => ({
-    action,
-    estimatedImpact: 6,
-    priority: summary.score < 50 ? "high" : "medium"
-  }));
+  const recs = recommendations.map(
+    (action) => ({
+      action,
+      estimatedImpact: 6,
+      priority: summary.score < 50 ? "high" : "medium"
+    })
+  );
   return {
     toolName: "agent-grounding",
     score: summary.score,

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   analyzeAgentGrounding,
   calculateGroundingScore
-} from "./chunk-OOB3JMXQ.mjs";
+} from "./chunk-NXIMJNCK.mjs";
 export {
   analyzeAgentGrounding,
   calculateGroundingScore

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/agent-grounding",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Measures how well an AI agent can navigate a codebase autonomously without human assistance",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -39,8 +39,8 @@
     "@typescript-eslint/typescript-estree": "^8.53.0",
     "chalk": "^5.3.0",
     "commander": "^14.0.0",
-    "glob": "^11.0.0",
-    "@aiready/core": "0.9.32"
+    "glob": "^13.0.0",
+    "@aiready/core": "0.9.35"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/__tests__/analyzer.test.ts

@@ -28,23 +28,33 @@ describe('Agent Grounding Analyzer', () => {
   describe('Deep Directories and Vague Files', () => {
     it('should detect deep directories and vague file names', async () => {
       // Mock files deep in the tree and with vague names
-      createTestFile('src/components/common/utils/helpers/deep/very/deep.ts', 'export const x = 1;');
+      createTestFile(
+        'src/components/common/utils/helpers/deep/very/deep.ts',
+        'export const x = 1;'
+      );
       createTestFile('src/utils.ts', 'export const y = 2;');
 
       const report = await analyzeAgentGrounding({
         rootDir: tmpDir,
         maxRecommendedDepth: 3,
-        additionalVagueNames: ['utils', 'helpers']
+        additionalVagueNames: ['utils', 'helpers'],
       });
 
       expect(report.issues.length).toBeGreaterThanOrEqual(1);
 
-      const deepIssues = report.issues.filter(i => i.dimension === 'structure-clarity' && i.message.includes('exceed'));
+      const deepIssues = report.issues.filter(
+        (i) =>
+          i.dimension === 'structure-clarity' && i.message.includes('exceed')
+      );
       // The deep.ts file contributes to the aggregate depth count
       expect(deepIssues.length).toBeGreaterThan(0);
 
-      const vagueIssues = report.issues.filter(i => i.dimension === 'self-documentation');
-      expect(vagueIssues.some(i => i.message.includes('vague names'))).toBe(true);
+      const vagueIssues = report.issues.filter(
+        (i) => i.dimension === 'self-documentation'
+      );
+      expect(vagueIssues.some((i) => i.message.includes('vague names'))).toBe(
+        true
+      );
     });
   });
 
@@ -54,7 +64,9 @@ describe('Agent Grounding Analyzer', () => {
       const report = await analyzeAgentGrounding({ rootDir: tmpDir });
 
       const issues = report.issues;
-      const readmeIssues = issues.filter(i => i.dimension === 'entry-point' || i.message.includes('README'));
+      const readmeIssues = issues.filter(
+        (i) => i.dimension === 'entry-point' || i.message.includes('README')
+      );
 
       expect(readmeIssues.length).toBeGreaterThan(0);
     });
@@ -62,16 +74,24 @@ describe('Agent Grounding Analyzer', () => {
 
   describe('Untyped Exports', () => {
     it('should detect JS files or untyped exports', async () => {
-      createTestFile('src/untyped.js', 'export function doSomething(a, b) { return a + b; }');
-      createTestFile('src/typed.ts', 'export function doSomething(a: number, b: number): number { return a + b; }');
+      createTestFile(
+        'src/untyped.js',
+        'export function doSomething(a, b) { return a + b; }'
+      );
+      createTestFile(
+        'src/typed.ts',
+        'export function doSomething(a: number, b: number): number { return a + b; }'
+      );
 
       const report = await analyzeAgentGrounding({ rootDir: tmpDir });
 
       const issues = report.issues;
-      const untypedIssues = issues.filter(i => i.dimension === 'api-clarity');
+      const untypedIssues = issues.filter((i) => i.dimension === 'api-clarity');
 
       // The JS file untyped export contributes to the aggregate count
-      expect(untypedIssues.some(i => i.message.includes('lack TypeScript type'))).toBe(true);
+      expect(
+        untypedIssues.some((i) => i.message.includes('lack TypeScript type'))
+      ).toBe(true);
     });
   });
 });

package/src/analyzer.ts

@@ -1,6 +1,6 @@
 /**
  * Scanner for agent-grounding dimensions.
- * 
+ *
  * Measures 5 dimensions:
  * 1. Structure clarity — how deep are directory trees?
  * 2. Self-documentation — do file names reveal purpose?
@@ -9,70 +9,20 @@
  * 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 {
+  scanEntries,
+  calculateAgentGrounding,
+  VAGUE_FILE_NAMES,
+} from '@aiready/core';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join, extname, basename, relative } 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 };
-}
+import type {
+  AgentGroundingOptions,
+  AgentGroundingIssue,
+  AgentGroundingReport,
+} from './types';
 
 // ---------------------------------------------------------------------------
 // Per-file analysis
@@ -91,7 +41,13 @@ function analyzeFile(filePath: string): FileAnalysis {
   try {
     code = readFileSync(filePath, 'utf-8');
   } catch {
-    return { isBarrel: false, exportedNames: [], untypedExports: 0, totalExports: 0, domainTerms: [] };
+    return {
+      isBarrel: false,
+      exportedNames: [],
+      untypedExports: 0,
+      totalExports: 0,
+      domainTerms: [],
+    };
   }
 
   let ast: TSESTree.Program;
@@ -102,11 +58,17 @@ function analyzeFile(filePath: string): FileAnalysis {
       loc: false,
     });
   } catch {
-    return { isBarrel: false, exportedNames: [], untypedExports: 0, totalExports: 0, domainTerms: [] };
+    return {
+      isBarrel: false,
+      exportedNames: [],
+      untypedExports: 0,
+      totalExports: 0,
+      domainTerms: [],
+    };
   }
 
   let isBarrel = false;
-  let exportedNames: string[] = [];
+  const exportedNames: string[] = [];
   let untypedExports = 0;
   let totalExports = 0;
 
@@ -126,7 +88,13 @@ function analyzeFile(filePath: string): FileAnalysis {
         if (name) {
           exportedNames.push(name);
           // Split camelCase into terms
-          domainTerms.push(...name.replace(/([A-Z])/g, ' $1').toLowerCase().split(/\s+/).filter(Boolean));
+          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 =
@@ -152,7 +120,10 @@ function analyzeFile(filePath: string): FileAnalysis {
 // Domain vocabulary consistency check
 // ---------------------------------------------------------------------------
 
-function detectInconsistentTerms(allTerms: string[]): { inconsistent: number; vocabularySize: number } {
+function detectInconsistentTerms(allTerms: string[]): {
+  inconsistent: number;
+  vocabularySize: number;
+} {
   const termFreq = new Map<string, number>();
   for (const term of allTerms) {
     if (term.length >= 3) {
@@ -161,8 +132,8 @@ function detectInconsistentTerms(allTerms: string[]): { inconsistent: number; vo
   }
   // 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 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);
@@ -174,19 +145,32 @@ function detectInconsistentTerms(allTerms: string[]): { inconsistent: number; vo
 // ---------------------------------------------------------------------------
 
 export async function analyzeAgentGrounding(
-  options: AgentGroundingOptions,
+  options: AgentGroundingOptions
 ): Promise<AgentGroundingReport> {
   const rootDir = options.rootDir;
   const maxRecommendedDepth = options.maxRecommendedDepth ?? 4;
   const readmeStaleDays = options.readmeStaleDays ?? 90;
 
-  const { dirs, files } = collectEntries(rootDir, options);
+  // Use core scanEntries which respects .gitignore recursively
+  const { files, dirs: rawDirs } = await scanEntries({
+    ...options,
+    include: options.include || ['**/*.{ts,tsx,js,jsx}'],
+  });
+
+  const dirs = rawDirs.map((d: string) => ({
+    path: d,
+    depth: relative(rootDir, d).split(/[/\\]/).filter(Boolean).length,
+  }));
 
   // Structure clarity
-  const deepDirectories = dirs.filter(d => d.depth > maxRecommendedDepth).length;
+  const deepDirectories = dirs.filter(
+    (d: { path: string; depth: number }) => d.depth > maxRecommendedDepth
+  ).length;
 
   // Self-documentation — vague file names
-  const additionalVague = new Set((options.additionalVagueNames ?? []).map(n => n.toLowerCase()));
+  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();
@@ -204,7 +188,9 @@ export async function analyzeAgentGrounding(
       const stat = statSync(readmePath);
       const ageDays = (Date.now() - stat.mtimeMs) / (1000 * 60 * 60 * 24);
       readmeIsFresh = ageDays < readmeStaleDays;
-    } catch { }
+    } catch {
+      /* ignore stat errors */
+    }
   }
 
   // File analysis
@@ -213,7 +199,15 @@ export async function analyzeAgentGrounding(
   let untypedExports = 0;
   let totalExports = 0;
 
+  let processed = 0;
   for (const f of files) {
+    processed++;
+    options.onProgress?.(
+      processed,
+      files.length,
+      `agent-grounding: analyzing files`
+    );
+
     const analysis = analyzeFile(f);
     if (analysis.isBarrel) barrelExports++;
     untypedExports += analysis.untypedExports;
@@ -222,8 +216,10 @@ export async function analyzeAgentGrounding(
   }
 
   // Domain vocabulary consistency
-  const { inconsistent: inconsistentDomainTerms, vocabularySize: domainVocabularySize } =
-    detectInconsistentTerms(allDomainTerms);
+  const {
+    inconsistent: inconsistentDomainTerms,
+    vocabularySize: domainVocabularySize,
+  } = detectInconsistentTerms(allDomainTerms);
 
   // Calculate grounding score using core math
   const groundingResult = calculateAgentGrounding({
@@ -261,7 +257,8 @@ export async function analyzeAgentGrounding(
       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.',
+      suggestion:
+        'Rename to domain-specific names: e.g., userAuthUtils → tokenValidator.',
     });
   }
 
@@ -270,9 +267,11 @@ export async function analyzeAgentGrounding(
       type: 'agent-navigation-failure',
       dimension: 'entry-point',
       severity: 'critical',
-      message: 'No root README.md found — agents have no orientation document to start from.',
+      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.',
+      suggestion:
+        'Add a README.md explaining the project structure, entry points, and key conventions.',
     });
   } else if (!readmeIsFresh) {
     issues.push({
@@ -292,7 +291,8 @@ export async function analyzeAgentGrounding(
       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.',
+      suggestion:
+        'Add explicit return type and parameter annotations to all exported functions.',
     });
   }
 
@@ -303,7 +303,8 @@ export async function analyzeAgentGrounding(
       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.',
+      suggestion:
+        'Establish a domain glossary and enforce one term per concept across the codebase.',
     });
   }