@aiready/agent-grounding 0.1.5 → 0.1.8

package/dist/chunk-ZOE5BFWE.mjs

@@ -0,0 +1,339 @@
+// src/analyzer.ts
+import { readdirSync, statSync, existsSync, readFileSync } from "fs";
+import { join, extname, basename } from "path";
+import { parse } from "@typescript-eslint/typescript-estree";
+import { calculateAgentGrounding } from "@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 = 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 };
+}
+function analyzeFile(filePath) {
+  let code;
+  try {
+    code = readFileSync(filePath, "utf-8");
+  } catch {
+    return {
+      isBarrel: false,
+      exportedNames: [],
+      untypedExports: 0,
+      totalExports: 0,
+      domainTerms: []
+    };
+  }
+  let ast;
+  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 = [];
+  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 = 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;
+  let processed = 0;
+  for (const f of files) {
+    processed++;
+    options.onProgress?.(processed, files.length, `agent-grounding: analyzing ${f.substring(rootDir.length + 1)}`);
+    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 = 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: 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, 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
+  };
+}
+
+export {
+  analyzeAgentGrounding,
+  calculateGroundingScore
+};

package/dist/cli.js

@@ -27,69 +27,22 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var import_commander = require("commander");
 
 // 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 {
@@ -99,10 +52,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 = [];
@@ -118,7 +77,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++;
         }
@@ -149,13 +110,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++;
     }
   }
@@ -174,14 +146,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,
@@ -283,7 +265,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",
@@ -311,11 +293,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,
@@ -334,7 +318,11 @@ var import_fs2 = require("fs");
 var import_path2 = require("path");
 var import_core2 = require("@aiready/core");
 var program = new import_commander.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
@@ -346,7 +334,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(import_chalk.default.blue("\u{1F9ED} Analyzing agent grounding...\n"));
   const startTime = Date.now();
   const config = await (0, import_core2.loadConfig)(directory);
@@ -388,10 +385,14 @@ function scoreColor(score) {
   return import_chalk.default.bgRed.white;
 }
 function displayConsoleReport(report, scoring, elapsed) {
-  const { summary, rawData, issues, recommendations } = report;
+  const { summary, issues, recommendations } = report;
   console.log(import_chalk.default.bold("\n\u{1F9ED} Agent Grounding Analysis\n"));
-  console.log(`Score:       ${scoreColor(summary.score)(summary.score + "/100")} (${summary.rating.toUpperCase()})`);
-  console.log(`Files:       ${import_chalk.default.cyan(summary.filesAnalyzed)}   Directories: ${import_chalk.default.cyan(summary.directoriesAnalyzed)}`);
+  console.log(
+    `Score:       ${scoreColor(summary.score)(summary.score + "/100")} (${summary.rating.toUpperCase()})`
+  );
+  console.log(
+    `Files:       ${import_chalk.default.cyan(summary.filesAnalyzed)}   Directories: ${import_chalk.default.cyan(summary.directoriesAnalyzed)}`
+  );
   console.log(`Analysis:    ${import_chalk.default.gray(elapsed + "s")}
 `);
   console.log(import_chalk.default.bold("\u{1F4D0} Dimension Scores\n"));
@@ -404,22 +405,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(import_chalk.default.bold("\n\u26A0\uFE0F  Issues Found\n"));
     for (const issue of issues) {
       const sev = issue.severity === "critical" ? import_chalk.default.red : issue.severity === "major" ? import_chalk.default.yellow : import_chalk.default.blue;
       console.log(`${sev(issue.severity.toUpperCase())}  ${issue.message}`);
-      if (issue.suggestion) console.log(`         ${import_chalk.default.dim("\u2192")} ${import_chalk.default.italic(issue.suggestion)}`);
+      if (issue.suggestion)
+        console.log(
+          `         ${import_chalk.default.dim("\u2192")} ${import_chalk.default.italic(issue.suggestion)}`
+        );
       console.log();
     }
   } else {
-    console.log(import_chalk.default.green("\n\u2728 No grounding issues found \u2014 agents can navigate freely!\n"));
+    console.log(
+      import_chalk.default.green(
+        "\n\u2728 No grounding issues found \u2014 agents can navigate freely!\n"
+      )
+    );
   }
   if (recommendations.length > 0) {
     console.log(import_chalk.default.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();
 }