@aiready/core 0.9.33 → 0.9.35

package/dist/client.d.mts

@@ -131,6 +131,8 @@ interface ScanOptions {
     include?: string[];
     exclude?: string[];
     maxDepth?: number;
+    onProgress?: (processed: number, total: number, message: string) => void;
+    includeTests?: boolean;
 }
 interface AIReadyConfig {
     scan?: {

package/dist/client.d.ts

@@ -131,6 +131,8 @@ interface ScanOptions {
     include?: string[];
     exclude?: string[];
     maxDepth?: number;
+    onProgress?: (processed: number, total: number, message: string) => void;
+    includeTests?: boolean;
 }
 interface AIReadyConfig {
     scan?: {

package/dist/index.d.mts

@@ -2,6 +2,7 @@ import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, Comprehension
 export { AnalysisResult, BusinessReport, CONTEXT_TIER_THRESHOLDS, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, SIZE_ADJUSTED_THRESHOLDS, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString } from './client.mjs';
 
 declare const DEFAULT_EXCLUDE: string[];
+declare const VAGUE_FILE_NAMES: Set<string>;
 /**
  * Scan files in a directory using glob patterns
  *
@@ -12,6 +13,14 @@ declare const DEFAULT_EXCLUDE: string[];
  * @returns Array of absolute file paths matching the patterns
  */
 declare function scanFiles(options: ScanOptions): Promise<string[]>;
+/**
+ * Scan for both files and directories, respecting ignore rules.
+ * Useful for tools that need to analyze directory structure.
+ */
+declare function scanEntries(options: ScanOptions): Promise<{
+    files: string[];
+    dirs: string[];
+}>;
 declare function readFileContent(filePath: string): Promise<string>;
 declare function getFileExtension(filePath: string): string;
 declare function isSourceFile(filePath: string): boolean;
@@ -826,4 +835,13 @@ declare function exportHistory(rootDir: string, format?: 'json' | 'csv'): string
  */
 declare function clearHistory(rootDir: string): void;
 
-export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, type RemediationVelocity, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, type TestabilityIndex, ToolScoringOutput, TypeScriptParser, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, clearHistory, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, getDebtBreakdown, getElapsedTime, getFileExtension, getHistorySummary, getModelPreset, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanFiles };
+/**
+ * Get git commit timestamps for each line in a file
+ */
+declare function getFileCommitTimestamps(file: string): Record<number, number>;
+/**
+ * Get the latest commit timestamp for a line range
+ */
+declare function getLineRangeLastModifiedCached(lineStamps: Record<number, number>, startLine: number, endLine: number): number;
+
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, type RemediationVelocity, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, type TestabilityIndex, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, clearHistory, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, getDebtBreakdown, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { ScanOptions, AIReadyConfig, CostConfig, ModelContextTier, Comprehension
 export { AnalysisResult, BusinessReport, CONTEXT_TIER_THRESHOLDS, CommonASTNode, DEFAULT_TOOL_WEIGHTS, ExportInfo, GraphData, GraphEdge, GraphIssueSeverity, GraphMetadata, GraphNode, ImportInfo, Issue, IssueType, LANGUAGE_EXTENSIONS, LanguageConfig, Location, Metrics, ParseError, ParseStatistics, Report, SIZE_ADJUSTED_THRESHOLDS, ScoringConfig, ScoringResult, SourceLocation, SourceRange, TOOL_NAME_MAP, calculateOverallScore, formatScore, formatToolScore, generateHTML, getProjectSizeTier, getRating, getRatingDisplay, getRatingWithContext, getRecommendedThreshold, getToolWeight, normalizeToolName, parseWeightString } from './client.js';
 
 declare const DEFAULT_EXCLUDE: string[];
+declare const VAGUE_FILE_NAMES: Set<string>;
 /**
  * Scan files in a directory using glob patterns
  *
@@ -12,6 +13,14 @@ declare const DEFAULT_EXCLUDE: string[];
  * @returns Array of absolute file paths matching the patterns
  */
 declare function scanFiles(options: ScanOptions): Promise<string[]>;
+/**
+ * Scan for both files and directories, respecting ignore rules.
+ * Useful for tools that need to analyze directory structure.
+ */
+declare function scanEntries(options: ScanOptions): Promise<{
+    files: string[];
+    dirs: string[];
+}>;
 declare function readFileContent(filePath: string): Promise<string>;
 declare function getFileExtension(filePath: string): string;
 declare function isSourceFile(filePath: string): boolean;
@@ -826,4 +835,13 @@ declare function exportHistory(rootDir: string, format?: 'json' | 'csv'): string
  */
 declare function clearHistory(rootDir: string): void;
 
-export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, type RemediationVelocity, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, type TestabilityIndex, ToolScoringOutput, TypeScriptParser, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, clearHistory, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, getDebtBreakdown, getElapsedTime, getFileExtension, getHistorySummary, getModelPreset, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanFiles };
+/**
+ * Get git commit timestamps for each line in a file
+ */
+declare function getFileCommitTimestamps(file: string): Record<number, number>;
+/**
+ * Get the latest commit timestamp for a line range
+ */
+declare function getLineRangeLastModifiedCached(lineStamps: Record<number, number>, startLine: number, endLine: number): number;
+
+export { AIReadyConfig, type ASTNode, AcceptancePrediction, type AgentGroundingScore, type AiSignalClarity, type AiSignalClaritySignal, type CLIOptions, type ChangeAmplificationScore, type CognitiveLoad, ComprehensionDifficulty, type ConceptCohesion, CostConfig, DEFAULT_COST_CONFIG, DEFAULT_EXCLUDE, type DebtBreakdown, type DependencyHealthScore, type DocDriftRisk, type ExportWithImports, type FileImport, type FileWithDomain, type KnowledgeConcentrationRisk, Language, LanguageParser, type LoadFactor, MODEL_PRICING_PRESETS, ModelContextTier, type ModelPricingPreset, NamingConvention, ParseResult, ParserFactory, type PatternEntropy, ProductivityImpact, PythonParser, type RemediationVelocity, ScanOptions, type ScoreHistoryEntry, type ScoreTrend, type SemanticDistance, type TechnicalDebtInterest, type TestabilityIndex, ToolScoringOutput, TypeScriptParser, VAGUE_FILE_NAMES, calculateAgentGrounding, calculateAiSignalClarity, calculateChangeAmplification, calculateCognitiveLoad, calculateComprehensionDifficulty, calculateConceptCohesion, calculateDependencyHealth, calculateDocDrift, calculateExtendedFutureProofScore, calculateFutureProofScore, calculateImportSimilarity, calculateKnowledgeConcentration, calculateMonthlyCost, calculatePatternEntropy, calculateProductivityImpact, calculateRemediationVelocity, calculateScoreTrend, calculateSemanticDistance, calculateTechnicalDebtInterest, calculateTestabilityIndex, clearHistory, estimateTokens, exportHistory, extractFunctions, extractImports, formatAcceptanceRate, formatCost, formatHours, getDebtBreakdown, getElapsedTime, getFileCommitTimestamps, getFileExtension, getHistorySummary, getLineRangeLastModifiedCached, getModelPreset, getParser, getSupportedLanguages, handleCLIError, handleJSONOutput, isFileSupported, isSourceFile, loadConfig, loadMergedConfig, loadScoreHistory, mergeConfigWithDefaults, parseCode, parseFileExports, predictAcceptanceRate, readFileContent, resolveOutputPath, saveScoreEntry, scanEntries, scanFiles };

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,20 +235,35 @@ async function scanFiles(options) {
       ignoreFromFile = [];
     }
   }
+  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, ...DEFAULT_EXCLUDE])
+    .../* @__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;
@@ -233,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");
 }
@@ -457,9 +548,14 @@ async function loadConfig(rootDir) {
           return config;
         } catch (error) {
           const errorMessage = error instanceof Error ? error.message : String(error);
-          throw new Error(
+          const e = new Error(
             `Failed to load config from ${configPath}: ${errorMessage}`
           );
+          try {
+            e.cause = error instanceof Error ? error : void 0;
+          } catch {
+          }
+          throw e;
         }
       }
     }
@@ -2806,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,
@@ -2821,6 +2950,7 @@ function clearHistory(rootDir) {
   SIZE_ADJUSTED_THRESHOLDS,
   TOOL_NAME_MAP,
   TypeScriptParser,
+  VAGUE_FILE_NAMES,
   calculateAgentGrounding,
   calculateAiSignalClarity,
   calculateChangeAmplification,
@@ -2855,8 +2985,10 @@ function clearHistory(rootDir) {
   generateHTML,
   getDebtBreakdown,
   getElapsedTime,
+  getFileCommitTimestamps,
   getFileExtension,
   getHistorySummary,
+  getLineRangeLastModifiedCached,
   getModelPreset,
   getParser,
   getProjectSizeTier,
@@ -2882,5 +3014,6 @@ function clearHistory(rootDir) {
   readFileContent,
   resolveOutputPath,
   saveScoreEntry,
+  scanEntries,
   scanFiles
 });

package/dist/index.mjs

@@ -24,7 +24,7 @@ import {
 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,20 +112,35 @@ async function scanFiles(options) {
       ignoreFromFile = [];
     }
   }
+  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, ...DEFAULT_EXCLUDE])
+    .../* @__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;
@@ -114,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");
 }
@@ -306,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",
@@ -338,13 +425,18 @@ async function loadConfig(rootDir) {
           return config;
         } catch (error) {
           const errorMessage = error instanceof Error ? error.message : String(error);
-          throw new Error(
+          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;
     }
@@ -377,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) {
@@ -386,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 });
   }
@@ -404,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 });
     }
@@ -2258,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");
 }
@@ -2277,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 });
   }
@@ -2329,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,
@@ -2343,6 +2468,7 @@ export {
   SIZE_ADJUSTED_THRESHOLDS,
   TOOL_NAME_MAP,
   TypeScriptParser,
+  VAGUE_FILE_NAMES,
   calculateAgentGrounding,
   calculateAiSignalClarity,
   calculateChangeAmplification,
@@ -2377,8 +2503,10 @@ export {
   generateHTML,
   getDebtBreakdown,
   getElapsedTime,
+  getFileCommitTimestamps,
   getFileExtension,
   getHistorySummary,
+  getLineRangeLastModifiedCached,
   getModelPreset,
   getParser,
   getProjectSizeTier,
@@ -2404,5 +2532,6 @@ export {
   readFileContent,
   resolveOutputPath,
   saveScoreEntry,
+  scanEntries,
   scanFiles
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/core",
-  "version": "0.9.33",
+  "version": "0.9.35",
   "description": "Shared utilities for AIReady analysis tools",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",