@aiready/agent-grounding 0.1.1

package/dist/index.js

@@ -0,0 +1,333 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  analyzeAgentGrounding: () => analyzeAgentGrounding,
+  calculateGroundingScore: () => calculateGroundingScore
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/analyzer.ts
+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: [] };
+  }
+  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;
+  let 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(...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++;
+        }
+      } else if (node.specifiers && node.specifiers.length > 0) {
+        isBarrel = true;
+      }
+    }
+    if (node.type === "ExportDefaultDeclaration") {
+      totalExports++;
+    }
+  }
+  return { isBarrel, exportedNames, untypedExports, totalExports, domainTerms };
+}
+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 { dirs, files } = collectEntries(rootDir, options);
+  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)) {
+      vagueFileNames++;
+    }
+  }
+  const readmePath = (0, import_path.join)(rootDir, "README.md");
+  const hasRootReadme = (0, import_fs.existsSync)(readmePath);
+  let readmeIsFresh = false;
+  if (hasRootReadme) {
+    try {
+      const stat = (0, import_fs.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;
+  for (const f of 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 groundingResult = (0, import_core.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: "agent-navigation-failure",
+      dimension: "structure-clarity",
+      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: "agent-navigation-failure",
+      dimension: "self-documentation",
+      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: "agent-navigation-failure",
+      dimension: "entry-point",
+      severity: "critical",
+      message: "No root README.md found \u2014 agents have no orientation document to start from.",
+      location: { file: (0, import_path.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) \u2014 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 \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: "agent-navigation-failure",
+      dimension: "domain-consistency",
+      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
+function calculateGroundingScore(report) {
+  const { summary, rawData, issues, 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 {
+    toolName: "agent-grounding",
+    score: summary.score,
+    rawMetrics: {
+      ...rawData,
+      rating: summary.rating
+    },
+    factors,
+    recommendations: recs
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  analyzeAgentGrounding,
+  calculateGroundingScore
+});

package/dist/index.mjs

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

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@aiready/agent-grounding",
+  "version": "0.1.1",
+  "description": "Measures how well an AI agent can navigate a codebase autonomously without human assistance",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "aiready-agent-grounding": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "keywords": [
+    "aiready",
+    "agent-grounding",
+    "ai-navigation",
+    "code-structure",
+    "copilot",
+    "claude",
+    "chatgpt",
+    "ai-assisted-development",
+    "autonomous-agents",
+    "codebase-navigation"
+  ],
+  "author": "AIReady Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/caopengau/aiready-agent-grounding.git"
+  },
+  "homepage": "https://github.com/caopengau/aiready-agent-grounding",
+  "dependencies": {
+    "@typescript-eslint/types": "^8.53.0",
+    "@typescript-eslint/typescript-estree": "^8.53.0",
+    "chalk": "^5.3.0",
+    "commander": "^14.0.0",
+    "glob": "^11.0.0",
+    "@aiready/core": "0.9.28"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rm -rf dist",
+    "release": "pnpm build && pnpm publish --no-git-checks"
+  }
+}

package/src/__tests__/analyzer.test.ts

@@ -0,0 +1,77 @@
+import { analyzeAgentGrounding } from '../analyzer';
+import { join } from 'path';
+import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+
+describe('Agent Grounding Analyzer', () => {
+  const tmpDir = join(tmpdir(), 'aiready-ag-tests');
+
+  beforeAll(() => {
+    mkdirSync(tmpDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function createTestFile(name: string, content: string): string {
+    const filePath = join(tmpDir, name);
+    // Ensure dir exists
+    const dir = join(filePath, '..');
+    mkdirSync(dir, { recursive: true });
+
+    writeFileSync(filePath, content, 'utf8');
+    return filePath;
+  }
+
+  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/utils.ts', 'export const y = 2;');
+
+      const report = await analyzeAgentGrounding({
+        rootDir: tmpDir,
+        maxRecommendedDepth: 3,
+        additionalVagueNames: ['utils', 'helpers']
+      });
+
+      expect(report.issues.length).toBeGreaterThanOrEqual(1);
+
+      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);
+    });
+  });
+
+  describe('Missing READMEs', () => {
+    it('should detect missing READMEs in directories', async () => {
+      // tmpDir has no README
+      const report = await analyzeAgentGrounding({ rootDir: tmpDir });
+
+      const issues = report.issues;
+      const readmeIssues = issues.filter(i => i.dimension === 'entry-point' || i.message.includes('README'));
+
+      expect(readmeIssues.length).toBeGreaterThan(0);
+    });
+  });
+
+  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; }');
+
+      const report = await analyzeAgentGrounding({ rootDir: tmpDir });
+
+      const issues = report.issues;
+      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);
+    });
+  });
+});