@aiready/core 0.9.32 → 0.9.35

package/dist/index.js

@@ -43,6 +43,7 @@ __export(index_exports, {
   SIZE_ADJUSTED_THRESHOLDS: () => SIZE_ADJUSTED_THRESHOLDS,
   TOOL_NAME_MAP: () => TOOL_NAME_MAP,
   TypeScriptParser: () => TypeScriptParser,
+  VAGUE_FILE_NAMES: () => VAGUE_FILE_NAMES,
   calculateAgentGrounding: () => calculateAgentGrounding,
   calculateAiSignalClarity: () => calculateAiSignalClarity,
   calculateChangeAmplification: () => calculateChangeAmplification,
@@ -77,8 +78,10 @@ __export(index_exports, {
   generateHTML: () => generateHTML,
   getDebtBreakdown: () => getDebtBreakdown,
   getElapsedTime: () => getElapsedTime,
+  getFileCommitTimestamps: () => getFileCommitTimestamps,
   getFileExtension: () => getFileExtension,
   getHistorySummary: () => getHistorySummary,
+  getLineRangeLastModifiedCached: () => getLineRangeLastModifiedCached,
   getModelPreset: () => getModelPreset,
   getParser: () => getParser,
   getProjectSizeTier: () => getProjectSizeTier,
@@ -104,6 +107,7 @@ __export(index_exports, {
   readFileContent: () => readFileContent,
   resolveOutputPath: () => resolveOutputPath,
   saveScoreEntry: () => saveScoreEntry,
+  scanEntries: () => scanEntries,
   scanFiles: () => scanFiles
 });
 module.exports = __toCommonJS(index_exports);
@@ -159,6 +163,8 @@ var DEFAULT_EXCLUDE = [
   "**/cdk.out/**",
   // Framework-specific build dirs
   "**/.next/**",
+  "**/.sst/**",
+  "**/.open-next/**",
   "**/.nuxt/**",
   "**/.vuepress/**",
   "**/.cache/**",
@@ -190,6 +196,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,
@@ -207,18 +235,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 (0, import_glob.glob)(include, {
     cwd: rootDir,
     ignore: finalExclude,
     absolute: true
   });
-  const gitignorePath = (0, import_path.join)(rootDir || ".", ".gitignore");
-  if ((0, import_fs.existsSync)(gitignorePath)) {
+  const gitignoreFiles = await (0, import_glob.glob)("**/.gitignore", {
+    cwd: rootDir,
+    ignore: finalExclude,
+    absolute: true
+  });
+  if (gitignoreFiles.length > 0) {
     try {
-      const gitTxt = await (0, import_promises.readFile)(gitignorePath, "utf-8");
       const ig = (0, import_ignore.default)();
-      ig.add(gitTxt);
+      for (const gitignorePath of gitignoreFiles) {
+        const gitTxt = await (0, import_promises.readFile)(gitignorePath, "utf-8");
+        const gitignoreDir = (0, import_path.dirname)(gitignorePath);
+        const relativePrefix = (0, import_path.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 = (0, import_path.relative)(rootDir || ".", f).replace(/\\/g, "/");
         if (rel === "") rel = f;
@@ -231,6 +276,54 @@ async function scanFiles(options) {
   }
   return files;
 }
+async function scanEntries(options) {
+  const files = await scanFiles(options);
+  const { rootDir, include = ["**/*"], exclude, includeTests } = options;
+  const ignoreFilePath = (0, import_path.join)(rootDir || ".", ".aireadyignore");
+  let ignoreFromFile = [];
+  if ((0, import_fs.existsSync)(ignoreFilePath)) {
+    try {
+      const txt = await (0, import_promises.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 (0, import_glob.glob)("**/", {
+    cwd: rootDir,
+    ignore: finalExclude,
+    absolute: true
+  });
+  const gitignoreFiles = await (0, import_glob.glob)("**/.gitignore", {
+    cwd: rootDir,
+    ignore: finalExclude,
+    absolute: true
+  });
+  if (gitignoreFiles.length > 0) {
+    const ig = (0, import_ignore.default)();
+    for (const gitignorePath of gitignoreFiles) {
+      const gitTxt = await (0, import_promises.readFile)(gitignorePath, "utf-8");
+      const gitignoreDir = (0, import_path.dirname)(gitignorePath);
+      const relativePrefix = (0, import_path.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 = (0, import_path.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 (0, import_promises.readFile)(filePath, "utf-8");
 }
@@ -455,7 +548,14 @@ 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;
         }
       }
     }
@@ -707,26 +807,26 @@ function generateHTML(graph) {
 var DEFAULT_TOOL_WEIGHTS = {
   "pattern-detect": 22,
   "context-analyzer": 19,
-  "consistency": 14,
+  consistency: 14,
   "ai-signal-clarity": 11,
   "agent-grounding": 10,
-  "testability": 10,
+  testability: 10,
   "doc-drift": 8,
-  "deps": 6
+  deps: 6
 };
 var TOOL_NAME_MAP = {
-  "patterns": "pattern-detect",
-  "context": "context-analyzer",
-  "consistency": "consistency",
+  patterns: "pattern-detect",
+  context: "context-analyzer",
+  consistency: "consistency",
   "AI signal clarity": "ai-signal-clarity",
   "ai-signal-clarity": "ai-signal-clarity",
-  "grounding": "agent-grounding",
+  grounding: "agent-grounding",
   "agent-grounding": "agent-grounding",
-  "testability": "testability",
-  "tests": "testability",
+  testability: "testability",
+  tests: "testability",
   "doc-drift": "doc-drift",
-  "docs": "doc-drift",
-  "deps": "deps"
+  docs: "doc-drift",
+  deps: "deps"
 };
 var CONTEXT_TIER_THRESHOLDS = {
   compact: { idealTokens: 3e3, criticalTokens: 1e4, idealDepth: 4 },
@@ -735,15 +835,15 @@ var CONTEXT_TIER_THRESHOLDS = {
   frontier: { idealTokens: 5e4, criticalTokens: 15e4, idealDepth: 10 }
 };
 var SIZE_ADJUSTED_THRESHOLDS = {
-  "xs": 80,
+  xs: 80,
   // < 50 files
-  "small": 75,
+  small: 75,
   // 50-200 files
-  "medium": 70,
+  medium: 70,
   // 200-500 files
-  "large": 65,
+  large: 65,
   // 500-2000 files
-  "enterprise": 58
+  enterprise: 58
   // 2000+ files
 };
 function getProjectSizeTier(fileCount) {
@@ -816,10 +916,12 @@ function calculateOverallScore(toolOutputs, config, cliWeights) {
   }
   const overall = Math.round(weightedSum / totalWeight);
   const rating = getRating(overall);
-  const formulaParts = Array.from(toolOutputs.entries()).map(([name, output]) => {
-    const w = weights.get(name) || 10;
-    return `(${output.score} \xD7 ${w})`;
-  });
+  const formulaParts = Array.from(toolOutputs.entries()).map(
+    ([name, output]) => {
+      const w = weights.get(name) || 10;
+      return `(${output.score} \xD7 ${w})`;
+    }
+  );
   const formulaStr = `[${formulaParts.join(" + ")}] / ${totalWeight} = ${overall}`;
   return {
     overall,
@@ -951,7 +1053,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,
@@ -1017,9 +1119,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)
+      }
     }
   };
 }
@@ -1077,12 +1188,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(
@@ -1162,8 +1279,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;
@@ -1176,7 +1297,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,
@@ -1237,9 +1361,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;
@@ -1251,7 +1379,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";
@@ -1259,13 +1390,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,
@@ -1419,7 +1556,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
         });
@@ -1430,11 +1570,16 @@ var TypeScriptParser = class {
   extractExports(ast, imports) {
     const exports2 = [];
     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
+        );
         exports2.push(...extracted);
       } else if (node.type === "ExportDefaultDeclaration") {
         let name = "default";
@@ -1450,7 +1595,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
         });
@@ -1472,7 +1620,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) {
@@ -1484,7 +1635,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") {
@@ -1515,7 +1669,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") {
@@ -1527,7 +1684,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
       });
     }
@@ -1552,7 +1712,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) {
@@ -1563,7 +1725,9 @@ var PythonParser = class {
         exports: exports2,
         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(
@@ -1658,7 +1822,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)
@@ -1826,7 +1990,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)),
@@ -1852,7 +2022,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";
@@ -1875,7 +2050,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;
@@ -1883,7 +2061,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,
@@ -1898,7 +2078,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"]
     };
   }
@@ -1938,10 +2122,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");
@@ -1966,7 +2154,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 = [];
@@ -2072,7 +2264,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,
@@ -2096,7 +2291,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,
@@ -2104,7 +2302,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,
@@ -2112,7 +2313,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,
@@ -2120,7 +2324,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,
@@ -2137,30 +2344,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),
@@ -2185,7 +2407,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;
@@ -2197,7 +2422,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
   );
@@ -2209,21 +2437,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,
@@ -2256,7 +2496,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;
@@ -2272,25 +2514,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,
@@ -2307,7 +2560,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);
@@ -2324,13 +2582,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,
@@ -2344,7 +2608,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);
@@ -2359,19 +2628,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,
@@ -2412,10 +2689,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),
@@ -2497,7 +2778,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";
@@ -2508,12 +2793,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;
@@ -2609,6 +2902,39 @@ function clearHistory(rootDir) {
     (0, import_fs4.writeFileSync)(historyPath, JSON.stringify([]));
   }
 }
+
+// src/utils/history-git.ts
+var import_child_process = require("child_process");
+function getFileCommitTimestamps(file) {
+  const lineStamps = {};
+  try {
+    const output = (0, import_child_process.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;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CONTEXT_TIER_THRESHOLDS,
@@ -2624,6 +2950,7 @@ function clearHistory(rootDir) {
   SIZE_ADJUSTED_THRESHOLDS,
   TOOL_NAME_MAP,
   TypeScriptParser,
+  VAGUE_FILE_NAMES,
   calculateAgentGrounding,
   calculateAiSignalClarity,
   calculateChangeAmplification,
@@ -2658,8 +2985,10 @@ function clearHistory(rootDir) {
   generateHTML,
   getDebtBreakdown,
   getElapsedTime,
+  getFileCommitTimestamps,
   getFileExtension,
   getHistorySummary,
+  getLineRangeLastModifiedCached,
   getModelPreset,
   getParser,
   getProjectSizeTier,
@@ -2685,5 +3014,6 @@ function clearHistory(rootDir) {
   readFileContent,
   resolveOutputPath,
   saveScoreEntry,
+  scanEntries,
   scanFiles
 });