@aiready/agent-grounding 0.13.19 → 0.13.21

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as _aiready_core from '@aiready/core';
-import { Issue, IssueType, ScanOptions, ToolScoringOutput } from '@aiready/core';
+import { Issue, IssueType, ScanOptions } from '@aiready/core';
 
 /**
  * Agent Grounding Tool Provider
@@ -67,11 +67,7 @@ declare function analyzeAgentGrounding(options: AgentGroundingOptions): Promise<
 
 /**
  * Convert agent grounding report into a ToolScoringOutput.
- *
- * @param report - The detailed agent grounding report.
- * @returns Standardized scoring and risk factor breakdown.
- * @lastUpdated 2026-03-18
  */
-declare function calculateGroundingScore(report: AgentGroundingReport): ToolScoringOutput;
+declare function calculateGroundingScore(report: AgentGroundingReport): any;
 
 export { type AgentGroundingIssue, type AgentGroundingOptions, AgentGroundingProvider, type AgentGroundingReport, analyzeAgentGrounding, calculateGroundingScore };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _aiready_core from '@aiready/core';
-import { Issue, IssueType, ScanOptions, ToolScoringOutput } from '@aiready/core';
+import { Issue, IssueType, ScanOptions } from '@aiready/core';
 
 /**
  * Agent Grounding Tool Provider
@@ -67,11 +67,7 @@ declare function analyzeAgentGrounding(options: AgentGroundingOptions): Promise<
 
 /**
  * Convert agent grounding report into a ToolScoringOutput.
- *
- * @param report - The detailed agent grounding report.
- * @returns Standardized scoring and risk factor breakdown.
- * @lastUpdated 2026-03-18
  */
-declare function calculateGroundingScore(report: AgentGroundingReport): ToolScoringOutput;
+declare function calculateGroundingScore(report: AgentGroundingReport): any;
 
 export { type AgentGroundingIssue, type AgentGroundingOptions, AgentGroundingProvider, type AgentGroundingReport, analyzeAgentGrounding, calculateGroundingScore };

package/dist/index.js

@@ -34,68 +34,45 @@ var import_core3 = require("@aiready/core");
 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");
-function analyzeFile(filePath) {
+async function analyzeFile(filePath) {
+  const result = {
+    isBarrel: false,
+    exportedNames: [],
+    untypedExports: 0,
+    totalExports: 0,
+    domainTerms: []
+  };
+  const parser = await (0, import_core.getParser)(filePath);
+  if (!parser) return result;
   let code;
   try {
     code = (0, import_fs.readFileSync)(filePath, "utf-8");
   } catch {
-    return {
-      isBarrel: false,
-      exportedNames: [],
-      untypedExports: 0,
-      totalExports: 0,
-      domainTerms: []
-    };
+    return result;
   }
-  let ast;
   try {
-    ast = (0, import_typescript_estree.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;
-  const exportedNames = [];
-  let untypedExports = 0;
-  let totalExports = 0;
-  const domainTerms = [];
-  for (const node of ast.body) {
-    if (node.type === "ExportAllDeclaration") {
-      isBarrel = true;
-      continue;
-    }
-    if (node.type === "ExportNamedDeclaration") {
-      totalExports++;
-      const decl = node.declaration;
-      if (decl) {
-        const name = decl.id?.name ?? decl.declarations?.[0]?.id?.name;
-        if (name) {
-          exportedNames.push(name);
-          domainTerms.push(
+    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)
           );
-          const hasType = decl.returnType != null || decl.declarations?.[0]?.id?.typeAnnotation != null || decl.typeParameters != null;
-          if (!hasType) untypedExports++;
+          if (exp.isTyped === false) {
+            result.untypedExports++;
+          }
         }
-      } else if (node.specifiers && node.specifiers.length > 0) {
-        isBarrel = true;
       }
+      if (parseResult.exports.length > 5) result.isBarrel = true;
     }
-    if (node.type === "ExportDefaultDeclaration") {
-      totalExports++;
-    }
+  } catch (error) {
+    console.warn(`Agent Grounding: Failed to parse ${filePath}: ${error}`);
   }
-  return { isBarrel, exportedNames, untypedExports, totalExports, domainTerms };
+  return result;
 }
 function detectInconsistentTerms(allTerms) {
   const termFreq = /* @__PURE__ */ new Map();
@@ -164,7 +141,7 @@ async function analyzeAgentGrounding(options) {
       "analyzing files",
       options.onProgress
     );
-    const analysis = analyzeFile(f);
+    const analysis = await analyzeFile(f);
     if (analysis.isBarrel) barrelExports++;
     untypedExports += analysis.untypedExports;
     totalExports += analysis.totalExports;
@@ -227,11 +204,11 @@ async function analyzeAgentGrounding(options) {
       suggestion: "Update README.md to reflect the current codebase structure."
     });
   }
-  if (groundingResult.dimensions.apiClarityScore < 70) {
+  if (untypedExports > 0) {
     issues.push({
       type: import_core.IssueType.AgentNavigationFailure,
       dimension: "api-clarity",
-      severity: import_core.Severity.Major,
+      severity: groundingResult.dimensions.apiClarityScore < 70 ? import_core.Severity.Major : import_core.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."
@@ -277,50 +254,28 @@ async function analyzeAgentGrounding(options) {
 var import_core2 = require("@aiready/core");
 function calculateGroundingScore(report) {
   const { summary, rawData, recommendations } = report;
-  const 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 = recommendations.map(
-    (action) => ({
-      action,
-      estimatedImpact: 6,
-      priority: summary.score < 50 ? "high" : "medium"
-    })
-  );
-  return {
+  return (0, import_core2.buildStandardToolScore)({
     toolName: import_core2.ToolName.AgentGrounding,
     score: summary.score,
-    rawMetrics: {
-      ...rawData,
-      rating: summary.rating
+    rawData,
+    dimensions: {
+      structureClarityScore: summary.dimensions.structureClarityScore,
+      selfDocumentationScore: summary.dimensions.selfDocumentationScore,
+      entryPointScore: summary.dimensions.entryPointScore,
+      apiClarityScore: summary.dimensions.apiClarityScore,
+      domainConsistencyScore: summary.dimensions.domainConsistencyScore
     },
-    factors,
-    recommendations: recs
-  };
+    dimensionNames: {
+      structureClarityScore: "Structure Clarity",
+      selfDocumentationScore: "Self-Documentation",
+      entryPointScore: "Entry Points",
+      apiClarityScore: "API Clarity",
+      domainConsistencyScore: "Domain Consistency"
+    },
+    recommendations,
+    recommendationImpact: 6,
+    rating: summary.rating
+  });
 }
 
 // src/provider.ts

package/dist/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/agent-grounding",
-  "version": "0.13.19",
+  "version": "0.13.21",
   "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.20"
+    "@aiready/core": "0.23.22"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/__tests__/scoring.test.ts

@@ -43,7 +43,7 @@ describe('Agent Grounding Scoring', () => {
     expect(scoring.factors.length).toBe(5);
 
     const apiClarityFactor = scoring.factors.find(
-      (f) => f.name === 'API Clarity'
+      (f: any) => f.name === 'API Clarity'
     );
     expect(apiClarityFactor?.impact).toBe(0); // 50 - 50
     expect(apiClarityFactor?.description).toContain(

package/src/analyzer.ts

@@ -16,11 +16,10 @@ import {
   Severity,
   IssueType,
   emitProgress,
+  getParser,
 } 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,
@@ -39,59 +38,41 @@ interface FileAnalysis {
   domainTerms: string[];
 }
 
-function analyzeFile(filePath: string): FileAnalysis {
+async function analyzeFile(filePath: string): Promise<FileAnalysis> {
+  const result: FileAnalysis = {
+    isBarrel: false,
+    exportedNames: [],
+    untypedExports: 0,
+    totalExports: 0,
+    domainTerms: [],
+  };
+
+  const parser = await getParser(filePath);
+  if (!parser) return result;
+
   let code: string;
   try {
     code = readFileSync(filePath, 'utf-8');
   } catch {
-    return {
-      isBarrel: false,
-      exportedNames: [],
-      untypedExports: 0,
-      totalExports: 0,
-      domainTerms: [],
-    };
+    return result;
   }
 
-  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;
-  const 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(
+    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);
+          // Domain consistency terms
+          result.domainTerms.push(
             ...name
               .replace(/([A-Z])/g, ' $1')
               .toLowerCase()
@@ -99,24 +80,21 @@ function analyzeFile(filePath: string): FileAnalysis {
               .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++;
+          // Check if it's untyped
+          if (exp.isTyped === false) {
+            result.untypedExports++;
+          }
         }
-      } else if (node.specifiers && node.specifiers.length > 0) {
-        // Named re-exports from another module — this is barrel-like
-        isBarrel = true;
       }
+
+      // Barrel detection heuristic: if it has many exports
+      if (parseResult.exports.length > 5) result.isBarrel = true;
     }
-    if (node.type === 'ExportDefaultDeclaration') {
-      totalExports++;
-    }
+  } catch (error) {
+    console.warn(`Agent Grounding: Failed to parse ${filePath}: ${error}`);
   }
 
-  return { isBarrel, exportedNames, untypedExports, totalExports, domainTerms };
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -220,7 +198,7 @@ export async function analyzeAgentGrounding(
       options.onProgress
     );
 
-    const analysis = analyzeFile(f);
+    const analysis = await analyzeFile(f);
     if (analysis.isBarrel) barrelExports++;
     untypedExports += analysis.untypedExports;
     totalExports += analysis.totalExports;
@@ -296,11 +274,14 @@ export async function analyzeAgentGrounding(
     });
   }
 
-  if (groundingResult.dimensions.apiClarityScore < 70) {
+  if (untypedExports > 0) {
     issues.push({
       type: IssueType.AgentNavigationFailure,
       dimension: 'api-clarity',
-      severity: Severity.Major,
+      severity:
+        groundingResult.dimensions.apiClarityScore < 70
+          ? Severity.Major
+          : Severity.Minor,
       message: `${untypedExports} of ${totalExports} public exports lack TypeScript type annotations — agents cannot infer the API contract.`,
       location: { file: rootDir, line: 0 },
       suggestion:

package/src/cli.ts

@@ -11,6 +11,7 @@ import {
   loadConfig,
   mergeConfigWithDefaults,
   resolveOutputPath,
+  displayStandardConsoleReport,
 } from '@aiready/core';
 
 const program = new Command();
@@ -90,76 +91,43 @@ EXAMPLES:
       writeFileSync(outputPath, JSON.stringify(payload, null, 2));
       console.log(chalk.green(`✓ Report saved to ${outputPath}`));
     } else {
-      displayConsoleReport(report, scoring, elapsed);
+      displayStandardConsoleReport({
+        title: '🧭 Agent Grounding Analysis',
+        score: scoring.summary.score,
+        rating: scoring.summary.rating,
+        dimensions: [
+          {
+            name: 'Structure Clarity',
+            value: scoring.summary.dimensions.structureClarityScore,
+          },
+          {
+            name: 'Self-Documentation',
+            value: scoring.summary.dimensions.selfDocumentationScore,
+          },
+          {
+            name: 'Entry Points',
+            value: scoring.summary.dimensions.entryPointScore,
+          },
+          {
+            name: 'API Clarity',
+            value: scoring.summary.dimensions.apiClarityScore,
+          },
+          {
+            name: 'Domain Consistency',
+            value: scoring.summary.dimensions.domainConsistencyScore,
+          },
+        ],
+        stats: [
+          { label: 'Files', value: scoring.summary.filesAnalyzed },
+          { label: 'Directories', value: scoring.summary.directoriesAnalyzed },
+        ],
+        issues: report.issues,
+        recommendations: report.recommendations,
+        elapsedTime: elapsed,
+        noIssuesMessage:
+          '✨ No grounding issues found — agents can navigate freely!',
+      });
     }
   });
 
 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, 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/scoring.ts

@@ -1,66 +1,32 @@
-import { type ToolScoringOutput, ToolName } from '@aiready/core';
+import { ToolName, buildStandardToolScore } from '@aiready/core';
 import type { AgentGroundingReport } from './types';
 
 /**
  * Convert agent grounding report into a ToolScoringOutput.
- *
- * @param report - The detailed agent grounding report.
- * @returns Standardized scoring and risk factor breakdown.
- * @lastUpdated 2026-03-18
  */
-export function calculateGroundingScore(
-  report: AgentGroundingReport
-): ToolScoringOutput {
+export function calculateGroundingScore(report: AgentGroundingReport): any {
   const { summary, rawData, 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 {
+  return buildStandardToolScore({
     toolName: ToolName.AgentGrounding,
     score: summary.score,
-    rawMetrics: {
-      ...rawData,
-      rating: summary.rating,
+    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',
     },
-    factors,
-    recommendations: recs,
-  };
+    recommendations,
+    recommendationImpact: 6,
+    rating: summary.rating,
+  });
 }