@aiready/core 0.9.32 → 0.9.35

package/dist/index.mjs

@@ -18,13 +18,13 @@ import {
   getToolWeight,
   normalizeToolName,
   parseWeightString
-} from "./chunk-CWRCDSKZ.mjs";
+} from "./chunk-HFLFBA6F.mjs";
 
 // src/utils/file-scanner.ts
 import { glob } from "glob";
 import { readFile } from "fs/promises";
 import { existsSync } from "fs";
-import { join, relative } from "path";
+import { join, relative, dirname } from "path";
 import ignorePkg from "ignore";
 var DEFAULT_EXCLUDE = [
   // Dependencies
@@ -40,6 +40,8 @@ var DEFAULT_EXCLUDE = [
   "**/cdk.out/**",
   // Framework-specific build dirs
   "**/.next/**",
+  "**/.sst/**",
+  "**/.open-next/**",
   "**/.nuxt/**",
   "**/.vuepress/**",
   "**/.cache/**",
@@ -71,6 +73,28 @@ var DEFAULT_EXCLUDE = [
   "**/*.log",
   "**/.DS_Store"
 ];
+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"
+]);
 async function scanFiles(options) {
   const {
     rootDir,
@@ -88,18 +112,35 @@ async function scanFiles(options) {
       ignoreFromFile = [];
     }
   }
-  const finalExclude = [.../* @__PURE__ */ new Set([...exclude || [], ...ignoreFromFile, ...DEFAULT_EXCLUDE])];
+  const TEST_PATTERNS = ["**/*.test.*", "**/*.spec.*", "**/__tests__/**", "**/test/**", "**/tests/**"];
+  const baseExclude = options.includeTests ? DEFAULT_EXCLUDE.filter((p) => !TEST_PATTERNS.includes(p)) : DEFAULT_EXCLUDE;
+  const finalExclude = [
+    .../* @__PURE__ */ new Set([...exclude || [], ...ignoreFromFile, ...baseExclude])
+  ];
   const files = await glob(include, {
     cwd: rootDir,
     ignore: finalExclude,
     absolute: true
   });
-  const gitignorePath = join(rootDir || ".", ".gitignore");
-  if (existsSync(gitignorePath)) {
+  const gitignoreFiles = await glob("**/.gitignore", {
+    cwd: rootDir,
+    ignore: finalExclude,
+    absolute: true
+  });
+  if (gitignoreFiles.length > 0) {
     try {
-      const gitTxt = await readFile(gitignorePath, "utf-8");
       const ig = ignorePkg();
-      ig.add(gitTxt);
+      for (const gitignorePath of gitignoreFiles) {
+        const gitTxt = await readFile(gitignorePath, "utf-8");
+        const gitignoreDir = dirname(gitignorePath);
+        const relativePrefix = relative(rootDir || ".", gitignoreDir).replace(/\\/g, "/");
+        const patterns = gitTxt.split(/\r?\n/).map((s) => s.trim()).filter(Boolean).filter((l) => !l.startsWith("#"));
+        if (relativePrefix === "." || relativePrefix === "") {
+          ig.add(patterns);
+        } else {
+          ig.add(patterns.map((p) => p.startsWith("/") ? `${relativePrefix}${p}` : `${relativePrefix}/**/${p}`));
+        }
+      }
       const filtered = files.filter((f) => {
         let rel = relative(rootDir || ".", f).replace(/\\/g, "/");
         if (rel === "") rel = f;
@@ -112,6 +153,54 @@ async function scanFiles(options) {
   }
   return files;
 }
+async function scanEntries(options) {
+  const files = await scanFiles(options);
+  const { rootDir, include = ["**/*"], exclude, includeTests } = options;
+  const ignoreFilePath = join(rootDir || ".", ".aireadyignore");
+  let ignoreFromFile = [];
+  if (existsSync(ignoreFilePath)) {
+    try {
+      const txt = await readFile(ignoreFilePath, "utf-8");
+      ignoreFromFile = txt.split(/\r?\n/).map((s) => s.trim()).filter(Boolean).filter((l) => !l.startsWith("#")).filter((l) => !l.startsWith("!"));
+    } catch (e) {
+      ignoreFromFile = [];
+    }
+  }
+  const TEST_PATTERNS = ["**/*.test.*", "**/*.spec.*", "**/__tests__/**", "**/test/**", "**/tests/**"];
+  const baseExclude = includeTests ? DEFAULT_EXCLUDE.filter((p) => !TEST_PATTERNS.includes(p)) : DEFAULT_EXCLUDE;
+  const finalExclude = [.../* @__PURE__ */ new Set([...exclude || [], ...ignoreFromFile, ...baseExclude])];
+  const dirs = await glob("**/", {
+    cwd: rootDir,
+    ignore: finalExclude,
+    absolute: true
+  });
+  const gitignoreFiles = await glob("**/.gitignore", {
+    cwd: rootDir,
+    ignore: finalExclude,
+    absolute: true
+  });
+  if (gitignoreFiles.length > 0) {
+    const ig = ignorePkg();
+    for (const gitignorePath of gitignoreFiles) {
+      const gitTxt = await readFile(gitignorePath, "utf-8");
+      const gitignoreDir = dirname(gitignorePath);
+      const relativePrefix = relative(rootDir || ".", gitignoreDir).replace(/\\/g, "/");
+      const patterns = gitTxt.split(/\r?\n/).map((s) => s.trim()).filter(Boolean).filter((l) => !l.startsWith("#"));
+      if (relativePrefix === "." || relativePrefix === "") {
+        ig.add(patterns);
+      } else {
+        ig.add(patterns.map((p) => p.startsWith("/") ? `${relativePrefix}${p}` : `${relativePrefix}/**/${p}`));
+      }
+    }
+    const filteredDirs = dirs.filter((d) => {
+      let rel = relative(rootDir || ".", d).replace(/\\/g, "/").replace(/\/$/, "");
+      if (rel === "") return true;
+      return !ig.ignores(rel);
+    });
+    return { files, dirs: filteredDirs };
+  }
+  return { files, dirs };
+}
 async function readFileContent(filePath) {
   return readFile(filePath, "utf-8");
 }
@@ -304,7 +393,7 @@ function estimateTokens(text) {
 
 // src/utils/config.ts
 import { readFileSync, existsSync as existsSync2 } from "fs";
-import { join as join2, resolve, dirname } from "path";
+import { join as join2, resolve, dirname as dirname2 } from "path";
 import { pathToFileURL } from "url";
 var CONFIG_FILES = [
   "aiready.json",
@@ -336,11 +425,18 @@ async function loadConfig(rootDir) {
           return config;
         } catch (error) {
           const errorMessage = error instanceof Error ? error.message : String(error);
-          throw new Error(`Failed to load config from ${configPath}: ${errorMessage}`);
+          const e = new Error(
+            `Failed to load config from ${configPath}: ${errorMessage}`
+          );
+          try {
+            e.cause = error instanceof Error ? error : void 0;
+          } catch {
+          }
+          throw e;
         }
       }
     }
-    const parent = dirname(currentDir);
+    const parent = dirname2(currentDir);
     if (parent === currentDir) {
       break;
     }
@@ -373,7 +469,7 @@ function mergeConfigWithDefaults(userConfig, defaults) {
 
 // src/utils/cli-helpers.ts
 import { writeFileSync, mkdirSync, existsSync as existsSync3 } from "fs";
-import { join as join3, dirname as dirname2 } from "path";
+import { join as join3, dirname as dirname3 } from "path";
 function resolveOutputPath(userPath, defaultFilename, workingDir = process.cwd()) {
   let outputPath;
   if (userPath) {
@@ -382,7 +478,7 @@ function resolveOutputPath(userPath, defaultFilename, workingDir = process.cwd()
     const aireadyDir = join3(workingDir, ".aiready");
     outputPath = join3(aireadyDir, defaultFilename);
   }
-  const parentDir = dirname2(outputPath);
+  const parentDir = dirname3(outputPath);
   if (!existsSync3(parentDir)) {
     mkdirSync(parentDir, { recursive: true });
   }
@@ -400,7 +496,7 @@ async function loadMergedConfig(directory, defaults, cliOptions) {
 }
 function handleJSONOutput(data, outputFile, successMessage) {
   if (outputFile) {
-    const dir = dirname2(outputFile);
+    const dir = dirname3(outputFile);
     if (!existsSync3(dir)) {
       mkdirSync(dir, { recursive: true });
     }
@@ -476,7 +572,7 @@ var MODEL_PRICING_PRESETS = {
     contextTier: "frontier",
     typicalQueriesPerDevPerDay: 150
   },
-  "copilot": {
+  copilot: {
     name: "GitHub Copilot (subscription)",
     // Amortized per-request cost for a $19/month plan at 80 queries/day
     pricePer1KInputTokens: 1e-4,
@@ -542,9 +638,18 @@ function calculateProductivityImpact(issues, hourlyRate = DEFAULT_HOURLY_RATE) {
     hourlyRate,
     totalCost: Math.round(totalCost),
     bySeverity: {
-      critical: { hours: Math.round(hours.critical * 10) / 10, cost: Math.round(hours.critical * hourlyRate) },
-      major: { hours: Math.round(hours.major * 10) / 10, cost: Math.round(hours.major * hourlyRate) },
-      minor: { hours: Math.round(hours.minor * 10) / 10, cost: Math.round(hours.minor * hourlyRate) }
+      critical: {
+        hours: Math.round(hours.critical * 10) / 10,
+        cost: Math.round(hours.critical * hourlyRate)
+      },
+      major: {
+        hours: Math.round(hours.major * 10) / 10,
+        cost: Math.round(hours.major * hourlyRate)
+      },
+      minor: {
+        hours: Math.round(hours.minor * 10) / 10,
+        cost: Math.round(hours.minor * hourlyRate)
+      }
     }
   };
 }
@@ -602,12 +707,18 @@ function calculateComprehensionDifficulty(contextBudget, importDepth, fragmentat
   const criticalBudget = tierThresholds.criticalTokens;
   const idealDepth = tierThresholds.idealDepth;
   const budgetRange = criticalBudget - idealBudget;
-  const budgetFactor = Math.min(100, Math.max(
-    0,
-    (contextBudget - idealBudget) / budgetRange * 100
-  ));
-  const depthFactor = Math.min(100, Math.max(0, (importDepth - idealDepth) * 10));
-  const fragmentationFactor = Math.min(100, Math.max(0, (fragmentation - 0.3) * 250));
+  const budgetFactor = Math.min(
+    100,
+    Math.max(0, (contextBudget - idealBudget) / budgetRange * 100)
+  );
+  const depthFactor = Math.min(
+    100,
+    Math.max(0, (importDepth - idealDepth) * 10)
+  );
+  const fragmentationFactor = Math.min(
+    100,
+    Math.max(0, (fragmentation - 0.3) * 250)
+  );
   const consistencyFactor = Math.min(100, Math.max(0, 100 - consistencyScore));
   const fileFactor = Math.min(100, Math.max(0, (totalFiles - 50) / 5));
   const score = Math.round(
@@ -687,8 +798,12 @@ function calculateScoreTrend(history) {
   const now = /* @__PURE__ */ new Date();
   const thirtyDaysAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1e3);
   const ninetyDaysAgo = new Date(now.getTime() - 90 * 24 * 60 * 60 * 1e3);
-  const last30Days = history.filter((e) => new Date(e.timestamp) >= thirtyDaysAgo);
-  const last90Days = history.filter((e) => new Date(e.timestamp) >= ninetyDaysAgo);
+  const last30Days = history.filter(
+    (e) => new Date(e.timestamp) >= thirtyDaysAgo
+  );
+  const last90Days = history.filter(
+    (e) => new Date(e.timestamp) >= ninetyDaysAgo
+  );
   const currentScore = history[history.length - 1].overallScore;
   const thirtyDaysAgoScore = last30Days[0]?.overallScore || currentScore;
   const ninetyDaysAgoScore = last90Days[0]?.overallScore || thirtyDaysAgoScore;
@@ -701,7 +816,10 @@ function calculateScoreTrend(history) {
   if (change30Days > 3) direction = "improving";
   else if (change30Days < -3) direction = "degrading";
   else direction = "stable";
-  const projectedScore = Math.max(0, Math.min(100, currentScore + velocity * 4));
+  const projectedScore = Math.max(
+    0,
+    Math.min(100, currentScore + velocity * 4)
+  );
   return {
     direction,
     change30Days,
@@ -762,9 +880,13 @@ function calculateKnowledgeConcentration(files, authorData) {
       recommendations: ["No files to analyze"]
     };
   }
-  const orphanFiles = files.filter((f) => f.exports < 2 && f.imports < 2).length;
+  const orphanFiles = files.filter(
+    (f) => f.exports < 2 && f.imports < 2
+  ).length;
   const avgExports = files.reduce((sum, f) => sum + f.exports, 0) / files.length;
-  const uniqueConceptFiles = files.filter((f) => f.exports > avgExports * 2).length;
+  const uniqueConceptFiles = files.filter(
+    (f) => f.exports > avgExports * 2
+  ).length;
   const totalExports = files.reduce((sum, f) => sum + f.exports, 0);
   const concentrationRatio = totalExports > 0 ? uniqueConceptFiles / files.length : 0;
   let singleAuthorFiles = 0;
@@ -776,7 +898,10 @@ function calculateKnowledgeConcentration(files, authorData) {
   const orphanRisk = orphanFiles / files.length * 30;
   const uniqueRisk = concentrationRatio * 40;
   const singleAuthorRisk = authorData ? singleAuthorFiles / files.length * 30 : 0;
-  const score = Math.min(100, Math.round(orphanRisk + uniqueRisk + singleAuthorRisk));
+  const score = Math.min(
+    100,
+    Math.round(orphanRisk + uniqueRisk + singleAuthorRisk)
+  );
   let rating;
   if (score < 20) rating = "low";
   else if (score < 40) rating = "moderate";
@@ -784,13 +909,19 @@ function calculateKnowledgeConcentration(files, authorData) {
   else rating = "critical";
   const recommendations = [];
   if (orphanFiles > files.length * 0.2) {
-    recommendations.push(`Reduce ${orphanFiles} orphan files by connecting them to main modules`);
+    recommendations.push(
+      `Reduce ${orphanFiles} orphan files by connecting them to main modules`
+    );
   }
   if (uniqueConceptFiles > files.length * 0.1) {
-    recommendations.push("Distribute high-export files into more focused modules");
+    recommendations.push(
+      "Distribute high-export files into more focused modules"
+    );
   }
   if (authorData && singleAuthorFiles > files.length * 0.3) {
-    recommendations.push("Increase knowledge sharing to reduce single-author dependencies");
+    recommendations.push(
+      "Increase knowledge sharing to reduce single-author dependencies"
+    );
   }
   return {
     score,
@@ -944,7 +1075,10 @@ var TypeScriptParser = class {
           specifiers,
           isTypeOnly,
           loc: node.loc ? {
-            start: { line: node.loc.start.line, column: node.loc.start.column },
+            start: {
+              line: node.loc.start.line,
+              column: node.loc.start.column
+            },
             end: { line: node.loc.end.line, column: node.loc.end.column }
           } : void 0
         });
@@ -955,11 +1089,16 @@ var TypeScriptParser = class {
   extractExports(ast, imports) {
     const exports = [];
     const importedNames = new Set(
-      imports.flatMap((imp) => imp.specifiers.filter((s) => s !== "*" && s !== "default"))
+      imports.flatMap(
+        (imp) => imp.specifiers.filter((s) => s !== "*" && s !== "default")
+      )
     );
     for (const node of ast.body) {
       if (node.type === "ExportNamedDeclaration" && node.declaration) {
-        const extracted = this.extractFromDeclaration(node.declaration, importedNames);
+        const extracted = this.extractFromDeclaration(
+          node.declaration,
+          importedNames
+        );
         exports.push(...extracted);
       } else if (node.type === "ExportDefaultDeclaration") {
         let name = "default";
@@ -975,7 +1114,10 @@ var TypeScriptParser = class {
           name,
           type,
           loc: node.loc ? {
-            start: { line: node.loc.start.line, column: node.loc.start.column },
+            start: {
+              line: node.loc.start.line,
+              column: node.loc.start.column
+            },
             end: { line: node.loc.end.line, column: node.loc.end.column }
           } : void 0
         });
@@ -997,7 +1139,10 @@ var TypeScriptParser = class {
             line: declaration.loc.start.line,
             column: declaration.loc.start.column
           },
-          end: { line: declaration.loc.end.line, column: declaration.loc.end.column }
+          end: {
+            line: declaration.loc.end.line,
+            column: declaration.loc.end.column
+          }
         } : void 0
       });
     } else if (declaration.type === "ClassDeclaration" && declaration.id) {
@@ -1009,7 +1154,10 @@ var TypeScriptParser = class {
             line: declaration.loc.start.line,
             column: declaration.loc.start.column
           },
-          end: { line: declaration.loc.end.line, column: declaration.loc.end.column }
+          end: {
+            line: declaration.loc.end.line,
+            column: declaration.loc.end.column
+          }
         } : void 0
       });
     } else if (declaration.type === "VariableDeclaration") {
@@ -1040,7 +1188,10 @@ var TypeScriptParser = class {
             line: declaration.loc.start.line,
             column: declaration.loc.start.column
           },
-          end: { line: declaration.loc.end.line, column: declaration.loc.end.column }
+          end: {
+            line: declaration.loc.end.line,
+            column: declaration.loc.end.column
+          }
         } : void 0
       });
     } else if (declaration.type === "TSInterfaceDeclaration") {
@@ -1052,7 +1203,10 @@ var TypeScriptParser = class {
             line: declaration.loc.start.line,
             column: declaration.loc.start.column
           },
-          end: { line: declaration.loc.end.line, column: declaration.loc.end.column }
+          end: {
+            line: declaration.loc.end.line,
+            column: declaration.loc.end.column
+          }
         } : void 0
       });
     }
@@ -1077,7 +1231,9 @@ var PythonParser = class {
     try {
       this.initialized = true;
     } catch (error) {
-      throw new Error(`Failed to initialize Python parser: ${error.message}`);
+      throw new Error(
+        `Failed to initialize Python parser: ${error.message}`
+      );
     }
   }
   parse(code, filePath) {
@@ -1088,7 +1244,9 @@ var PythonParser = class {
         exports,
         imports,
         language: "python" /* Python */,
-        warnings: ["Python parsing is currently using regex-based extraction. Tree-sitter support coming soon."]
+        warnings: [
+          "Python parsing is currently using regex-based extraction. Tree-sitter support coming soon."
+        ]
       };
     } catch (error) {
       throw new ParseError(
@@ -1183,7 +1341,7 @@ var PythonParser = class {
   }
   /**
    * Regex-based export extraction (temporary implementation)
-   * 
+   *
    * Python doesn't have explicit exports like JavaScript.
    * We extract:
    * - Functions defined at module level (def)
@@ -1351,7 +1509,13 @@ function getSupportedLanguages() {
 
 // src/future-proof-metrics.ts
 function calculateCognitiveLoad(params) {
-  const { linesOfCode, exportCount, importCount, uniqueConcepts, cyclomaticComplexity = 1 } = params;
+  const {
+    linesOfCode,
+    exportCount,
+    importCount,
+    uniqueConcepts,
+    cyclomaticComplexity = 1
+  } = params;
   const sizeFactor = {
     name: "Size Complexity",
     score: Math.min(100, Math.max(0, (linesOfCode - 50) / 10)),
@@ -1377,7 +1541,12 @@ function calculateCognitiveLoad(params) {
     weight: 0.2,
     description: `${uniqueConcepts} unique concepts`
   };
-  const factors = [sizeFactor, interfaceFactor, dependencyFactor, conceptFactor];
+  const factors = [
+    sizeFactor,
+    interfaceFactor,
+    dependencyFactor,
+    conceptFactor
+  ];
   const score = factors.reduce((sum, f) => sum + f.score * f.weight, 0);
   let rating;
   if (score < 20) rating = "trivial";
@@ -1400,7 +1569,10 @@ function calculateCognitiveLoad(params) {
 function calculateSemanticDistance(params) {
   const { file1, file2, file1Domain, file2Domain, sharedDependencies } = params;
   const domainDistance = file1Domain === file2Domain ? 0 : file1Domain && file2Domain ? 0.5 : 0.8;
-  const importOverlap = sharedDependencies.length / Math.max(1, Math.min(params.file1Imports.length, params.file2Imports.length));
+  const importOverlap = sharedDependencies.length / Math.max(
+    1,
+    Math.min(params.file1Imports.length, params.file2Imports.length)
+  );
   const importDistance = 1 - importOverlap;
   const distance = domainDistance * 0.4 + importDistance * 0.3 + (sharedDependencies.length > 0 ? 0 : 0.3);
   let relationship;
@@ -1408,7 +1580,9 @@ function calculateSemanticDistance(params) {
   else if (file1Domain === file2Domain) relationship = "same-domain";
   else if (sharedDependencies.length > 0) relationship = "cross-domain";
   else relationship = "unrelated";
-  const pathItems = [file1Domain, ...sharedDependencies, file2Domain].filter((s) => typeof s === "string" && s.length > 0);
+  const pathItems = [file1Domain, ...sharedDependencies, file2Domain].filter(
+    (s) => typeof s === "string" && s.length > 0
+  );
   return {
     between: [file1, file2],
     distance: Math.round(distance * 100) / 100,
@@ -1423,7 +1597,11 @@ function calculatePatternEntropy(files) {
       domain: "unknown",
       entropy: 0,
       rating: "crystalline",
-      distribution: { locationCount: 0, dominantLocation: "", giniCoefficient: 0 },
+      distribution: {
+        locationCount: 0,
+        dominantLocation: "",
+        giniCoefficient: 0
+      },
       recommendations: ["No files to analyze"]
     };
   }
@@ -1463,10 +1641,14 @@ function calculatePatternEntropy(files) {
   else rating = "chaotic";
   const recommendations = [];
   if (normalizedEntropy > 0.5) {
-    recommendations.push(`Consolidate ${files.length} files into fewer directories by domain`);
+    recommendations.push(
+      `Consolidate ${files.length} files into fewer directories by domain`
+    );
   }
   if (dirGroups.size > 5) {
-    recommendations.push("Consider barrel exports to reduce directory navigation");
+    recommendations.push(
+      "Consider barrel exports to reduce directory navigation"
+    );
   }
   if (gini > 0.5) {
     recommendations.push("Redistribute files more evenly across directories");
@@ -1491,7 +1673,11 @@ function calculateConceptCohesion(params) {
     return {
       score: 1,
       rating: "excellent",
-      analysis: { uniqueDomains: 0, domainConcentration: 0, exportPurposeClarity: 1 }
+      analysis: {
+        uniqueDomains: 0,
+        domainConcentration: 0,
+        exportPurposeClarity: 1
+      }
     };
   }
   const allDomains = [];
@@ -1597,7 +1783,10 @@ function calculateAiSignalClarity(params) {
       recommendations: []
     };
   }
-  const overloadRatio = Math.min(1, overloadedSymbols / Math.max(1, totalSymbols));
+  const overloadRatio = Math.min(
+    1,
+    overloadedSymbols / Math.max(1, totalSymbols)
+  );
   const overloadSignal = {
     name: "Symbol Overloading",
     count: overloadedSymbols,
@@ -1621,7 +1810,10 @@ function calculateAiSignalClarity(params) {
     // 20% weight
     description: `${booleanTraps} boolean trap parameters \u2014 AI inverts intent`
   };
-  const sideEffectRatio = Math.min(1, implicitSideEffects / Math.max(1, totalExports));
+  const sideEffectRatio = Math.min(
+    1,
+    implicitSideEffects / Math.max(1, totalExports)
+  );
   const sideEffectSignal = {
     name: "Implicit Side Effects",
     count: implicitSideEffects,
@@ -1629,7 +1821,10 @@ function calculateAiSignalClarity(params) {
     // 15% weight
     description: `${implicitSideEffects} functions with implicit side effects \u2014 AI misses contracts`
   };
-  const callbackRatio = Math.min(1, deepCallbacks / Math.max(1, totalSymbols * 0.1));
+  const callbackRatio = Math.min(
+    1,
+    deepCallbacks / Math.max(1, totalSymbols * 0.1)
+  );
   const callbackSignal = {
     name: "Callback Nesting",
     count: deepCallbacks,
@@ -1637,7 +1832,10 @@ function calculateAiSignalClarity(params) {
     // 10% weight
     description: `${deepCallbacks} deep callback chains \u2014 AI loses control flow context`
   };
-  const ambiguousRatio = Math.min(1, ambiguousNames / Math.max(1, totalSymbols));
+  const ambiguousRatio = Math.min(
+    1,
+    ambiguousNames / Math.max(1, totalSymbols)
+  );
   const ambiguousSignal = {
     name: "Ambiguous Names",
     count: ambiguousNames,
@@ -1645,7 +1843,10 @@ function calculateAiSignalClarity(params) {
     // 10% weight
     description: `${ambiguousNames} non-descriptive identifiers \u2014 AI guesses wrong intent`
   };
-  const undocRatio = Math.min(1, undocumentedExports / Math.max(1, totalExports));
+  const undocRatio = Math.min(
+    1,
+    undocumentedExports / Math.max(1, totalExports)
+  );
   const undocSignal = {
     name: "Undocumented Exports",
     count: undocumentedExports,
@@ -1662,30 +1863,45 @@ function calculateAiSignalClarity(params) {
     ambiguousSignal,
     undocSignal
   ];
-  const score = Math.min(100, signals.reduce((sum, s) => sum + s.riskContribution, 0));
+  const score = Math.min(
+    100,
+    signals.reduce((sum, s) => sum + s.riskContribution, 0)
+  );
   let rating;
   if (score < 10) rating = "minimal";
   else if (score < 25) rating = "low";
   else if (score < 50) rating = "moderate";
   else if (score < 75) rating = "high";
   else rating = "severe";
-  const topSignal = signals.reduce((a, b) => a.riskContribution > b.riskContribution ? a : b);
+  const topSignal = signals.reduce(
+    (a, b) => a.riskContribution > b.riskContribution ? a : b
+  );
   const topRisk = topSignal.riskContribution > 0 ? topSignal.description : "No significant AI signal claritys detected";
   const recommendations = [];
   if (overloadSignal.riskContribution > 5) {
-    recommendations.push(`Rename ${overloadedSymbols} overloaded symbols to unique, intent-revealing names`);
+    recommendations.push(
+      `Rename ${overloadedSymbols} overloaded symbols to unique, intent-revealing names`
+    );
   }
   if (magicSignal.riskContribution > 5) {
-    recommendations.push(`Extract ${magicLiterals} magic literals into named constants`);
+    recommendations.push(
+      `Extract ${magicLiterals} magic literals into named constants`
+    );
   }
   if (trapSignal.riskContribution > 5) {
-    recommendations.push(`Replace ${booleanTraps} boolean traps with named options objects`);
+    recommendations.push(
+      `Replace ${booleanTraps} boolean traps with named options objects`
+    );
   }
   if (undocSignal.riskContribution > 5) {
-    recommendations.push(`Add JSDoc/docstrings to ${undocumentedExports} undocumented public functions`);
+    recommendations.push(
+      `Add JSDoc/docstrings to ${undocumentedExports} undocumented public functions`
+    );
   }
   if (sideEffectSignal.riskContribution > 5) {
-    recommendations.push("Mark functions with side effects explicitly in their names or docs");
+    recommendations.push(
+      "Mark functions with side effects explicitly in their names or docs"
+    );
   }
   return {
     score: Math.round(score),
@@ -1710,7 +1926,10 @@ function calculateAgentGrounding(params) {
     domainVocabularySize
   } = params;
   const deepDirRatio = totalDirectories > 0 ? deepDirectories / totalDirectories : 0;
-  const structureClarityScore = Math.max(0, Math.round(100 - deepDirRatio * 80));
+  const structureClarityScore = Math.max(
+    0,
+    Math.round(100 - deepDirRatio * 80)
+  );
   const vagueRatio = totalFiles > 0 ? vagueFileNames / totalFiles : 0;
   const selfDocumentationScore = Math.max(0, Math.round(100 - vagueRatio * 90));
   let entryPointScore = 60;
@@ -1722,7 +1941,10 @@ function calculateAgentGrounding(params) {
   const untypedRatio = totalExports > 0 ? untypedExports / totalExports : 0;
   const apiClarityScore = Math.max(0, Math.round(100 - untypedRatio * 70));
   const inconsistencyRatio = domainVocabularySize > 0 ? inconsistentDomainTerms / domainVocabularySize : 0;
-  const domainConsistencyScore = Math.max(0, Math.round(100 - inconsistencyRatio * 80));
+  const domainConsistencyScore = Math.max(
+    0,
+    Math.round(100 - inconsistencyRatio * 80)
+  );
   const score = Math.round(
     structureClarityScore * 0.2 + selfDocumentationScore * 0.25 + entryPointScore * 0.2 + apiClarityScore * 0.15 + domainConsistencyScore * 0.2
   );
@@ -1734,21 +1956,33 @@ function calculateAgentGrounding(params) {
   else rating = "disorienting";
   const recommendations = [];
   if (structureClarityScore < 70) {
-    recommendations.push(`Flatten ${deepDirectories} overly-deep directories to improve agent navigation`);
+    recommendations.push(
+      `Flatten ${deepDirectories} overly-deep directories to improve agent navigation`
+    );
   }
   if (selfDocumentationScore < 70) {
-    recommendations.push(`Rename ${vagueFileNames} vague files (utils, helpers, misc) to domain-specific names`);
+    recommendations.push(
+      `Rename ${vagueFileNames} vague files (utils, helpers, misc) to domain-specific names`
+    );
   }
   if (!hasRootReadme) {
-    recommendations.push("Add a root README.md so agents understand the project context immediately");
+    recommendations.push(
+      "Add a root README.md so agents understand the project context immediately"
+    );
   } else if (!readmeIsFresh) {
-    recommendations.push("Update README.md \u2014 stale entry-point documentation disorients agents");
+    recommendations.push(
+      "Update README.md \u2014 stale entry-point documentation disorients agents"
+    );
   }
   if (apiClarityScore < 70) {
-    recommendations.push(`Add TypeScript types to ${untypedExports} untyped exports to improve API discoverability`);
+    recommendations.push(
+      `Add TypeScript types to ${untypedExports} untyped exports to improve API discoverability`
+    );
   }
   if (domainConsistencyScore < 70) {
-    recommendations.push(`Unify ${inconsistentDomainTerms} inconsistent domain terms \u2014 agents need one word per concept`);
+    recommendations.push(
+      `Unify ${inconsistentDomainTerms} inconsistent domain terms \u2014 agents need one word per concept`
+    );
   }
   return {
     score,
@@ -1781,7 +2015,9 @@ function calculateTestabilityIndex(params) {
   const purityRatio = totalFunctions > 0 ? pureFunctions / totalFunctions : 0.5;
   const purityScore = Math.round(purityRatio * 100);
   const injectionRatio = totalClasses > 0 ? injectionPatterns / totalClasses : 0.5;
-  const dependencyInjectionScore = Math.round(Math.min(100, injectionRatio * 100));
+  const dependencyInjectionScore = Math.round(
+    Math.min(100, injectionRatio * 100)
+  );
   const bloatedRatio = totalInterfaces > 0 ? bloatedInterfaces / totalInterfaces : 0;
   const interfaceFocusScore = Math.max(0, Math.round(100 - bloatedRatio * 80));
   const mutationRatio = totalFunctions > 0 ? externalStateMutations / totalFunctions : 0;
@@ -1797,25 +2033,36 @@ function calculateTestabilityIndex(params) {
   else rating = "unverifiable";
   let aiChangeSafetyRating;
   if (rawCoverageRatio >= 0.5 && score >= 70) aiChangeSafetyRating = "safe";
-  else if (rawCoverageRatio >= 0.2 && score >= 50) aiChangeSafetyRating = "moderate-risk";
+  else if (rawCoverageRatio >= 0.2 && score >= 50)
+    aiChangeSafetyRating = "moderate-risk";
   else if (rawCoverageRatio > 0) aiChangeSafetyRating = "high-risk";
   else aiChangeSafetyRating = "blind-risk";
   const recommendations = [];
   if (!hasTestFramework) {
-    recommendations.push("Add a testing framework (Jest, Vitest, pytest) \u2014 AI changes cannot be verified without tests");
+    recommendations.push(
+      "Add a testing framework (Jest, Vitest, pytest) \u2014 AI changes cannot be verified without tests"
+    );
   }
   if (rawCoverageRatio < 0.3) {
     const neededTests = Math.round(sourceFiles * 0.3 - testFiles);
-    recommendations.push(`Add ~${neededTests} test files to reach 30% coverage ratio \u2014 minimum for safe AI assistance`);
+    recommendations.push(
+      `Add ~${neededTests} test files to reach 30% coverage ratio \u2014 minimum for safe AI assistance`
+    );
   }
   if (purityScore < 50) {
-    recommendations.push("Extract pure functions from side-effectful code \u2014 pure functions are trivially AI-testable");
+    recommendations.push(
+      "Extract pure functions from side-effectful code \u2014 pure functions are trivially AI-testable"
+    );
   }
   if (dependencyInjectionScore < 50 && totalClasses > 0) {
-    recommendations.push("Adopt dependency injection \u2014 makes classes mockable and AI-generated code verifiable");
+    recommendations.push(
+      "Adopt dependency injection \u2014 makes classes mockable and AI-generated code verifiable"
+    );
   }
   if (externalStateMutations > totalFunctions * 0.3) {
-    recommendations.push("Reduce direct state mutations \u2014 return values instead to improve observability");
+    recommendations.push(
+      "Reduce direct state mutations \u2014 return values instead to improve observability"
+    );
   }
   return {
     score,
@@ -1832,7 +2079,12 @@ function calculateTestabilityIndex(params) {
   };
 }
 function calculateDocDrift(params) {
-  const { uncommentedExports, totalExports, outdatedComments, undocumentedComplexity } = params;
+  const {
+    uncommentedExports,
+    totalExports,
+    outdatedComments,
+    undocumentedComplexity
+  } = params;
   const uncommentedRatio = totalExports > 0 ? uncommentedExports / totalExports : 0;
   const outdatedScore = Math.min(100, outdatedComments * 15);
   const uncommentedScore = Math.min(100, uncommentedRatio * 100);
@@ -1849,13 +2101,19 @@ function calculateDocDrift(params) {
   else rating = "severe";
   const recommendations = [];
   if (outdatedComments > 0) {
-    recommendations.push(`Update or remove ${outdatedComments} outdated comments that contradict the code.`);
+    recommendations.push(
+      `Update or remove ${outdatedComments} outdated comments that contradict the code.`
+    );
   }
   if (uncommentedRatio > 0.3) {
-    recommendations.push(`Add JSDoc to ${uncommentedExports} uncommented exports.`);
+    recommendations.push(
+      `Add JSDoc to ${uncommentedExports} uncommented exports.`
+    );
   }
   if (undocumentedComplexity > 0) {
-    recommendations.push(`Explain the business logic for ${undocumentedComplexity} highly complex functions.`);
+    recommendations.push(
+      `Explain the business logic for ${undocumentedComplexity} highly complex functions.`
+    );
   }
   return {
     score: finalScore,
@@ -1869,7 +2127,12 @@ function calculateDocDrift(params) {
   };
 }
 function calculateDependencyHealth(params) {
-  const { totalPackages, outdatedPackages, deprecatedPackages, trainingCutoffSkew } = params;
+  const {
+    totalPackages,
+    outdatedPackages,
+    deprecatedPackages,
+    trainingCutoffSkew
+  } = params;
   const outdatedRatio = totalPackages > 0 ? outdatedPackages / totalPackages : 0;
   const deprecatedRatio = totalPackages > 0 ? deprecatedPackages / totalPackages : 0;
   const outdatedScore = Math.max(0, 100 - outdatedRatio * 200);
@@ -1884,19 +2147,27 @@ function calculateDependencyHealth(params) {
   else if (score >= 30) rating = "poor";
   else rating = "hazardous";
   let aiKnowledgeConfidence;
-  if (trainingCutoffSkew < 0.2 && deprecatedPackages === 0) aiKnowledgeConfidence = "high";
-  else if (trainingCutoffSkew < 0.5 && deprecatedPackages <= 2) aiKnowledgeConfidence = "moderate";
+  if (trainingCutoffSkew < 0.2 && deprecatedPackages === 0)
+    aiKnowledgeConfidence = "high";
+  else if (trainingCutoffSkew < 0.5 && deprecatedPackages <= 2)
+    aiKnowledgeConfidence = "moderate";
   else if (trainingCutoffSkew < 0.8) aiKnowledgeConfidence = "low";
   else aiKnowledgeConfidence = "blind";
   const recommendations = [];
   if (deprecatedPackages > 0) {
-    recommendations.push(`Replace ${deprecatedPackages} deprecated packages, as AI will struggle to find modern solutions.`);
+    recommendations.push(
+      `Replace ${deprecatedPackages} deprecated packages, as AI will struggle to find modern solutions.`
+    );
   }
   if (outdatedRatio > 0.2) {
-    recommendations.push(`Update ${outdatedPackages} outdated packages to keep APIs aligned with AI training data.`);
+    recommendations.push(
+      `Update ${outdatedPackages} outdated packages to keep APIs aligned with AI training data.`
+    );
   }
   if (trainingCutoffSkew > 0.5) {
-    recommendations.push("High training cutoff skew detected. AI may hallucinate APIs that were introduced recently.");
+    recommendations.push(
+      "High training cutoff skew detected. AI may hallucinate APIs that were introduced recently."
+    );
   }
   return {
     score,
@@ -1937,10 +2208,14 @@ function calculateChangeAmplification(params) {
   else if (score < 90) rating = "contained";
   const recommendations = [];
   if (score < 70 && hotspots.length > 0) {
-    recommendations.push(`Refactor top hotspot '${hotspots[0].file}' to reduce coupling (fan-out: ${hotspots[0].fanOut}, fan-in: ${hotspots[0].fanIn}).`);
+    recommendations.push(
+      `Refactor top hotspot '${hotspots[0].file}' to reduce coupling (fan-out: ${hotspots[0].fanOut}, fan-in: ${hotspots[0].fanIn}).`
+    );
   }
   if (maxAmplification > 30) {
-    recommendations.push(`Break down key bottlenecks with amplification factor > 30.`);
+    recommendations.push(
+      `Break down key bottlenecks with amplification factor > 30.`
+    );
   }
   return {
     score: Math.round(score),
@@ -2022,7 +2297,11 @@ function calculateExtendedFutureProofScore(params) {
     recommendations.push({ action: rec, estimatedImpact: 8, priority: "high" });
   }
   for (const rec of params.agentGrounding.recommendations) {
-    recommendations.push({ action: rec, estimatedImpact: 6, priority: "medium" });
+    recommendations.push({
+      action: rec,
+      estimatedImpact: 6,
+      priority: "medium"
+    });
   }
   for (const rec of params.testability.recommendations) {
     const priority = params.testability.aiChangeSafetyRating === "blind-risk" ? "high" : "medium";
@@ -2033,12 +2312,20 @@ function calculateExtendedFutureProofScore(params) {
   }
   if (params.docDrift) {
     for (const rec of params.docDrift.recommendations) {
-      recommendations.push({ action: rec, estimatedImpact: 8, priority: "high" });
+      recommendations.push({
+        action: rec,
+        estimatedImpact: 8,
+        priority: "high"
+      });
     }
   }
   if (params.dependencyHealth) {
     for (const rec of params.dependencyHealth.recommendations) {
-      recommendations.push({ action: rec, estimatedImpact: 7, priority: "medium" });
+      recommendations.push({
+        action: rec,
+        estimatedImpact: 7,
+        priority: "medium"
+      });
     }
   }
   const semanticDistanceAvg = params.semanticDistances && params.semanticDistances.length > 0 ? params.semanticDistances.reduce((s, d) => s + d.distance, 0) / params.semanticDistances.length : 0;
@@ -2063,7 +2350,7 @@ function calculateExtendedFutureProofScore(params) {
 
 // src/utils/history.ts
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync4, mkdirSync as mkdirSync2 } from "fs";
-import { join as join4, dirname as dirname3 } from "path";
+import { join as join4, dirname as dirname4 } from "path";
 function getHistoryPath(rootDir) {
   return join4(rootDir, ".aiready", "history.json");
 }
@@ -2082,7 +2369,7 @@ function loadScoreHistory(rootDir) {
 }
 function saveScoreEntry(rootDir, entry) {
   const historyPath = getHistoryPath(rootDir);
-  const historyDir = dirname3(historyPath);
+  const historyDir = dirname4(historyPath);
   if (!existsSync4(historyDir)) {
     mkdirSync2(historyDir, { recursive: true });
   }
@@ -2134,6 +2421,39 @@ function clearHistory(rootDir) {
     writeFileSync2(historyPath, JSON.stringify([]));
   }
 }
+
+// src/utils/history-git.ts
+import { execSync } from "child_process";
+function getFileCommitTimestamps(file) {
+  const lineStamps = {};
+  try {
+    const output = execSync(`git blame -t "${file}"`, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const lines = output.split("\n");
+    for (const line of lines) {
+      if (!line) continue;
+      const match = line.match(/^\S+\s+\(.*?(\d{10,})\s+[-+]\d+\s+(\d+)\)/);
+      if (match) {
+        const ts = parseInt(match[1], 10);
+        const ln = parseInt(match[2], 10);
+        lineStamps[ln] = ts;
+      }
+    }
+  } catch {
+  }
+  return lineStamps;
+}
+function getLineRangeLastModifiedCached(lineStamps, startLine, endLine) {
+  let latest = 0;
+  for (let i = startLine; i <= endLine; i++) {
+    if (lineStamps[i] && lineStamps[i] > latest) {
+      latest = lineStamps[i];
+    }
+  }
+  return latest;
+}
 export {
   CONTEXT_TIER_THRESHOLDS,
   DEFAULT_COST_CONFIG,
@@ -2148,6 +2468,7 @@ export {
   SIZE_ADJUSTED_THRESHOLDS,
   TOOL_NAME_MAP,
   TypeScriptParser,
+  VAGUE_FILE_NAMES,
   calculateAgentGrounding,
   calculateAiSignalClarity,
   calculateChangeAmplification,
@@ -2182,8 +2503,10 @@ export {
   generateHTML,
   getDebtBreakdown,
   getElapsedTime,
+  getFileCommitTimestamps,
   getFileExtension,
   getHistorySummary,
+  getLineRangeLastModifiedCached,
   getModelPreset,
   getParser,
   getProjectSizeTier,
@@ -2209,5 +2532,6 @@ export {
   readFileContent,
   resolveOutputPath,
   saveScoreEntry,
+  scanEntries,
   scanFiles
 };