@aiready/agent-grounding 0.13.22 → 0.14.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @aiready/agent-grounding@0.13.22 build /Users/pengcao/projects/aiready/packages/agent-grounding
+> @aiready/agent-grounding@0.14.0 build /Users/pengcao/projects/aiready/packages/agent-grounding
 > tsup src/index.ts src/cli.ts --format cjs,esm --dts
 
 CLI Building entry: src/cli.ts, src/index.ts
@@ -8,15 +8,15 @@ CLI tsup v8.5.1
 CLI Target: es2020
 CJS Build start
 ESM Build start
-CJS dist/cli.js   14.19 KB
-CJS dist/index.js 11.11 KB
-CJS ⚡️ Build success in 33ms
-ESM dist/cli.mjs            4.15 KB
-ESM dist/chunk-OFAWUHBZ.mjs 8.68 KB
 ESM dist/index.mjs          1.18 KB
-ESM ⚡️ Build success in 34ms
+ESM dist/chunk-FCCOCULS.mjs 8.61 KB
+ESM dist/cli.mjs            4.15 KB
+ESM ⚡️ Build success in 316ms
+CJS dist/index.js 11.04 KB
+CJS dist/cli.js   14.11 KB
+CJS ⚡️ Build success in 317ms
 DTS Build start
-DTS ⚡️ Build success in 1736ms
+DTS ⚡️ Build success in 5500ms
 DTS dist/cli.d.ts    20.00 B
 DTS dist/index.d.ts  2.52 KB
 DTS dist/cli.d.mts   20.00 B

package/.turbo/turbo-test.log

@@ -1,17 +1,17 @@
 
-> @aiready/agent-grounding@0.13.21 test /Users/pengcao/projects/aiready/packages/agent-grounding
+> @aiready/agent-grounding@0.13.23 test /Users/pengcao/projects/aiready/packages/agent-grounding
 > vitest run
 
 
  RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/agent-grounding
 
- ✓ src/__tests__/provider.test.ts (2 tests) 19ms
  ✓ src/__tests__/scoring.test.ts (2 tests) 2ms
- ✓ src/__tests__/analyzer.test.ts (3 tests) 771ms
-       ✓ should detect deep directories and vague file names  502ms
+ ✓ src/__tests__/provider.test.ts (2 tests) 3ms
+ ✓ src/__tests__/analyzer.test.ts (3 tests) 644ms
+       ✓ should detect missing READMEs in directories  370ms
 
  Test Files  3 passed (3)
       Tests  7 passed (7)
-   Start at  19:39:17
-   Duration  3.68s (transform 2.30s, setup 0ms, import 7.17s, tests 792ms, environment 0ms)
+   Start at  15:17:50
+   Duration  3.62s (transform 2.55s, setup 0ms, import 6.72s, tests 649ms, environment 0ms)
 

package/dist/chunk-FCCOCULS.mjs

@@ -0,0 +1,257 @@
+// src/analyzer.ts
+import {
+  scanEntries,
+  calculateAgentGrounding,
+  VAGUE_FILE_NAMES,
+  Severity,
+  IssueType,
+  runBatchAnalysis,
+  getParser
+} from "@aiready/core";
+import { readFileSync, existsSync, statSync } from "fs";
+import { join, extname, basename, relative } from "path";
+async function analyzeFile(filePath) {
+  const result = {
+    isBarrel: false,
+    exportedNames: [],
+    untypedExports: 0,
+    totalExports: 0,
+    domainTerms: []
+  };
+  const parser = await getParser(filePath);
+  if (!parser) return result;
+  let code;
+  try {
+    code = readFileSync(filePath, "utf-8");
+  } catch {
+    return result;
+  }
+  try {
+    await parser.initialize();
+    const parseResult = parser.parse(code, filePath);
+    for (const exp of parseResult.exports) {
+      if (exp.type === "function" || exp.type === "class" || exp.type === "const") {
+        result.totalExports++;
+        const name = exp.name;
+        if (name && name !== "default") {
+          result.exportedNames.push(name);
+          result.domainTerms.push(
+            ...name.replace(/([A-Z])/g, " $1").toLowerCase().split(/\s+/).filter(Boolean)
+          );
+          if (exp.isTyped === false) {
+            result.untypedExports++;
+          }
+        }
+      }
+      if (parseResult.exports.length > 5) result.isBarrel = true;
+    }
+  } catch (error) {
+    console.warn(`Agent Grounding: Failed to parse ${filePath}: ${error}`);
+  }
+  return result;
+}
+function detectInconsistentTerms(allTerms) {
+  const termFreq = /* @__PURE__ */ new Map();
+  for (const term of allTerms) {
+    if (term.length >= 3) {
+      termFreq.set(term, (termFreq.get(term) ?? 0) + 1);
+    }
+  }
+  const orphans = [...termFreq.values()].filter((count) => count === 1).length;
+  const common = [...termFreq.values()].filter((count) => count >= 3).length;
+  const vocabularySize = termFreq.size;
+  const inconsistent = Math.max(0, orphans - common * 2);
+  return { inconsistent, vocabularySize };
+}
+async function analyzeAgentGrounding(options) {
+  const rootDir = options.rootDir;
+  const maxRecommendedDepth = options.maxRecommendedDepth ?? 4;
+  const readmeStaleDays = options.readmeStaleDays ?? 90;
+  const { files, dirs: rawDirs } = await scanEntries({
+    ...options,
+    include: options.include || ["**/*.{ts,tsx,js,jsx}"]
+  });
+  const { files: allFiles } = await scanEntries({
+    ...options,
+    include: ["**/*"]
+  });
+  const dirs = rawDirs.map((d) => ({
+    path: d,
+    depth: 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 allFiles) {
+    const base = basename(f, extname(f)).toLowerCase();
+    if (VAGUE_FILE_NAMES.has(base) || additionalVague.has(base)) {
+      vagueFileNames++;
+    }
+  }
+  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) / (1e3 * 60 * 60 * 24);
+      readmeIsFresh = ageDays < readmeStaleDays;
+    } catch {
+    }
+  }
+  const allDomainTerms = [];
+  let barrelExports = 0;
+  let untypedExports = 0;
+  let totalExports = 0;
+  await runBatchAnalysis(
+    files,
+    "analyzing files",
+    "agent-grounding",
+    options.onProgress,
+    (f) => analyzeFile(f),
+    (analysis) => {
+      if (analysis.isBarrel) barrelExports++;
+      untypedExports += analysis.untypedExports;
+      totalExports += analysis.totalExports;
+      allDomainTerms.push(...analysis.domainTerms);
+    }
+  );
+  const {
+    inconsistent: inconsistentDomainTerms,
+    vocabularySize: domainVocabularySize
+  } = detectInconsistentTerms(allDomainTerms);
+  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)
+  });
+  const issues = [];
+  if (groundingResult.dimensions.structureClarityScore < 70) {
+    issues.push({
+      type: IssueType.AgentNavigationFailure,
+      dimension: "structure-clarity",
+      severity: Severity.Major,
+      message: `${deepDirectories} directories exceed recommended depth of ${maxRecommendedDepth} \u2014 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: IssueType.AgentNavigationFailure,
+      dimension: "self-documentation",
+      severity: Severity.Major,
+      message: `${vagueFileNames} files use vague names (utils, helpers, misc) \u2014 an agent cannot determine their purpose from the name alone.`,
+      location: { file: rootDir, line: 0 },
+      suggestion: "Rename to domain-specific names: e.g., userAuthUtils \u2192 tokenValidator."
+    });
+  }
+  if (!hasRootReadme) {
+    issues.push({
+      type: IssueType.AgentNavigationFailure,
+      dimension: "entry-point",
+      severity: Severity.Critical,
+      message: "No root README.md found \u2014 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: IssueType.AgentNavigationFailure,
+      dimension: "entry-point",
+      severity: Severity.Minor,
+      message: `README.md is stale (>${readmeStaleDays} days without updates) \u2014 agents may be misled by outdated context.`,
+      location: { file: readmePath, line: 0 },
+      suggestion: "Update README.md to reflect the current codebase structure."
+    });
+  }
+  if (untypedExports > 0) {
+    issues.push({
+      type: IssueType.AgentNavigationFailure,
+      dimension: "api-clarity",
+      severity: groundingResult.dimensions.apiClarityScore < 70 ? Severity.Major : Severity.Minor,
+      message: `${untypedExports} of ${totalExports} public exports lack TypeScript type annotations \u2014 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: IssueType.AgentNavigationFailure,
+      dimension: "domain-consistency",
+      severity: Severity.Major,
+      message: `${inconsistentDomainTerms} domain terms appear to be used inconsistently \u2014 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
+  };
+}
+
+// src/scoring.ts
+import { ToolName, buildStandardToolScore } from "@aiready/core";
+function calculateGroundingScore(report) {
+  const { summary, rawData, recommendations } = report;
+  return buildStandardToolScore({
+    toolName: ToolName.AgentGrounding,
+    score: summary.score,
+    rawData,
+    dimensions: {
+      structureClarityScore: summary.dimensions.structureClarityScore,
+      selfDocumentationScore: summary.dimensions.selfDocumentationScore,
+      entryPointScore: summary.dimensions.entryPointScore,
+      apiClarityScore: summary.dimensions.apiClarityScore,
+      domainConsistencyScore: summary.dimensions.domainConsistencyScore
+    },
+    dimensionNames: {
+      structureClarityScore: "Structure Clarity",
+      selfDocumentationScore: "Self-Documentation",
+      entryPointScore: "Entry Points",
+      apiClarityScore: "API Clarity",
+      domainConsistencyScore: "Domain Consistency"
+    },
+    recommendations,
+    recommendationImpact: 6,
+    rating: summary.rating
+  });
+}
+
+export {
+  analyzeAgentGrounding,
+  calculateGroundingScore
+};

package/dist/cli.js

@@ -127,22 +127,19 @@ async function analyzeAgentGrounding(options) {
   let barrelExports = 0;
   let untypedExports = 0;
   let totalExports = 0;
-  let processed = 0;
-  for (const f of files) {
-    processed++;
-    (0, import_core.emitProgress)(
-      processed,
-      files.length,
-      "agent-grounding",
-      "analyzing files",
-      options.onProgress
-    );
-    const analysis = await analyzeFile(f);
-    if (analysis.isBarrel) barrelExports++;
-    untypedExports += analysis.untypedExports;
-    totalExports += analysis.totalExports;
-    allDomainTerms.push(...analysis.domainTerms);
-  }
+  await (0, import_core.runBatchAnalysis)(
+    files,
+    "analyzing files",
+    "agent-grounding",
+    options.onProgress,
+    (f) => analyzeFile(f),
+    (analysis) => {
+      if (analysis.isBarrel) barrelExports++;
+      untypedExports += analysis.untypedExports;
+      totalExports += analysis.totalExports;
+      allDomainTerms.push(...analysis.domainTerms);
+    }
+  );
   const {
     inconsistent: inconsistentDomainTerms,
     vocabularySize: domainVocabularySize

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import {
   analyzeAgentGrounding,
   calculateGroundingScore
-} from "./chunk-OFAWUHBZ.mjs";
+} from "./chunk-FCCOCULS.mjs";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/index.js

@@ -131,22 +131,19 @@ async function analyzeAgentGrounding(options) {
   let barrelExports = 0;
   let untypedExports = 0;
   let totalExports = 0;
-  let processed = 0;
-  for (const f of files) {
-    processed++;
-    (0, import_core.emitProgress)(
-      processed,
-      files.length,
-      "agent-grounding",
-      "analyzing files",
-      options.onProgress
-    );
-    const analysis = await analyzeFile(f);
-    if (analysis.isBarrel) barrelExports++;
-    untypedExports += analysis.untypedExports;
-    totalExports += analysis.totalExports;
-    allDomainTerms.push(...analysis.domainTerms);
-  }
+  await (0, import_core.runBatchAnalysis)(
+    files,
+    "analyzing files",
+    "agent-grounding",
+    options.onProgress,
+    (f) => analyzeFile(f),
+    (analysis) => {
+      if (analysis.isBarrel) barrelExports++;
+      untypedExports += analysis.untypedExports;
+      totalExports += analysis.totalExports;
+      allDomainTerms.push(...analysis.domainTerms);
+    }
+  );
   const {
     inconsistent: inconsistentDomainTerms,
     vocabularySize: domainVocabularySize

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   analyzeAgentGrounding,
   calculateGroundingScore
-} from "./chunk-OFAWUHBZ.mjs";
+} from "./chunk-FCCOCULS.mjs";
 
 // src/index.ts
 import { ToolRegistry } from "@aiready/core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/agent-grounding",
-  "version": "0.13.22",
+  "version": "0.14.0",
   "description": "Measures how well an AI agent can navigate a codebase autonomously without human assistance",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -40,7 +40,7 @@
     "chalk": "^5.3.0",
     "commander": "^14.0.0",
     "glob": "^13.0.0",
-    "@aiready/core": "0.23.23"
+    "@aiready/core": "0.24.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/analyzer.ts

@@ -15,7 +15,7 @@ import {
   VAGUE_FILE_NAMES,
   Severity,
   IssueType,
-  emitProgress,
+  runBatchAnalysis,
   getParser,
 } from '@aiready/core';
 import { readFileSync, existsSync, statSync } from 'fs';
@@ -187,23 +187,19 @@ export async function analyzeAgentGrounding(
   let untypedExports = 0;
   let totalExports = 0;
 
-  let processed = 0;
-  for (const f of files) {
-    processed++;
-    emitProgress(
-      processed,
-      files.length,
-      'agent-grounding',
-      'analyzing files',
-      options.onProgress
-    );
-
-    const analysis = await analyzeFile(f);
-    if (analysis.isBarrel) barrelExports++;
-    untypedExports += analysis.untypedExports;
-    totalExports += analysis.totalExports;
-    allDomainTerms.push(...analysis.domainTerms);
-  }
+  await runBatchAnalysis(
+    files,
+    'analyzing files',
+    'agent-grounding',
+    options.onProgress,
+    (f: string) => analyzeFile(f),
+    (analysis: FileAnalysis) => {
+      if (analysis.isBarrel) barrelExports++;
+      untypedExports += analysis.untypedExports;
+      totalExports += analysis.totalExports;
+      allDomainTerms.push(...analysis.domainTerms);
+    }
+  );
 
   // Domain vocabulary consistency
   const {