@aiready/context-analyzer 0.4.2 → 0.4.4

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/context-analyzer@0.4.2 build /Users/pengcao/projects/aiready/packages/context-analyzer
+> @aiready/context-analyzer@0.4.4 build /Users/pengcao/projects/aiready/packages/context-analyzer
 > tsup src/index.ts src/cli.ts --format cjs,esm --dts
 
 CLI Building entry: src/cli.ts, src/index.ts
@@ -9,16 +9,16 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-ESM dist/cli.mjs            15.74 KB
+ESM dist/cli.mjs            18.45 KB
 ESM dist/index.mjs          164.00 B
-ESM dist/chunk-HDFXSEFW.mjs 19.11 KB
-ESM ⚡️ Build success in 33ms
-CJS dist/cli.js   35.91 KB
-CJS dist/index.js 20.26 KB
-CJS ⚡️ Build success in 33ms
+ESM dist/chunk-45P4RDYP.mjs 19.24 KB
+ESM ⚡️ Build success in 22ms
+CJS dist/index.js 20.38 KB
+CJS dist/cli.js   39.03 KB
+CJS ⚡️ Build success in 22ms
 DTS Build start
-DTS ⚡️ Build success in 646ms
+DTS ⚡️ Build success in 608ms
 DTS dist/cli.d.ts    20.00 B
-DTS dist/index.d.ts  2.37 KB
+DTS dist/index.d.ts  2.44 KB
 DTS dist/cli.d.mts   20.00 B
-DTS dist/index.d.mts 2.37 KB
+DTS dist/index.d.mts 2.44 KB

package/README.md

@@ -75,8 +75,62 @@ aiready-context ./src --focus depth
 # Set thresholds
 aiready-context ./src --max-depth 5 --max-context 10000 --min-cohesion 0.6
 
-# Export to JSON
-aiready-context ./src --output json --output-file report.json
+# Export to JSON (saved to .aiready/ by default)
+aiready-context ./src --output json
+
+# Or specify custom path
+aiready-context ./src --output json --output-file custom-report.json
+```
+
+> **📁 Output Files:** By default, all output files are saved to the `.aiready/` directory in your project root. You can override this with `--output-file`.
+
+## 🎛️ Tuning Guide
+
+**Smart defaults automatically adjust based on your repository size** to show ~10 most serious issues.
+
+### Getting More/Fewer Results
+
+**Want to catch MORE potential issues?** (More sensitive, shows smaller problems)
+
+```bash
+# Lower thresholds to be more strict:
+aiready-context ./src --max-depth 3 --max-context 5000 --min-cohesion 0.7 --max-fragmentation 0.4
+```
+
+**Want to see FEWER issues?** (Less noise, focus on critical problems only)
+
+```bash
+# Raise thresholds to be more lenient:
+aiready-context ./src --max-depth 10 --max-context 30000 --min-cohesion 0.4 --max-fragmentation 0.8
+```
+
+### Threshold Parameters Explained
+
+| Parameter | Default (Auto) | Lower = More Strict | Higher = Less Strict |
+|-----------|---------------|-------------------|---------------------|
+| `--max-depth` | 4-10* | Catches shallower imports | Only very deep chains |
+| `--max-context` | 8k-40k* | Catches smaller files | Only huge files |
+| `--min-cohesion` | 0.35-0.5* | Stricter about mixed concerns | More lenient |
+| `--max-fragmentation` | 0.5-0.8* | Catches less scattered code | Only severely scattered |
+
+\* Auto-adjusted based on your repository size (100 files vs 2000+ files)
+
+### Common Tuning Scenarios
+
+**Small codebase getting too many warnings?**
+```bash
+aiready-context ./src --max-depth 6 --min-cohesion 0.5
+```
+
+**Large codebase showing too few issues?**
+```bash
+aiready-context ./src --max-depth 5 --max-context 15000
+```
+
+**Focus on critical issues only:**
+```bash
+aiready-context ./src --max-depth 8 --max-context 25000 --min-cohesion 0.3
+```
 
 # Generate HTML report
 aiready-context ./src --output html --output-file report.html

package/dist/chunk-45P4RDYP.mjs

@@ -0,0 +1,607 @@
+// src/index.ts
+import { scanFiles, readFileContent } from "@aiready/core";
+
+// src/analyzer.ts
+import { estimateTokens } from "@aiready/core";
+function buildDependencyGraph(files) {
+  const nodes = /* @__PURE__ */ new Map();
+  const edges = /* @__PURE__ */ new Map();
+  for (const { file, content } of files) {
+    const imports = extractImportsFromContent(content);
+    const exports = extractExports(content);
+    const tokenCost = estimateTokens(content);
+    const linesOfCode = content.split("\n").length;
+    nodes.set(file, {
+      file,
+      imports,
+      exports,
+      tokenCost,
+      linesOfCode
+    });
+    edges.set(file, new Set(imports));
+  }
+  return { nodes, edges };
+}
+function extractImportsFromContent(content) {
+  const imports = [];
+  const patterns = [
+    /import\s+.*?\s+from\s+['"](.+?)['"]/g,
+    // import ... from '...'
+    /import\s+['"](.+?)['"]/g,
+    // import '...'
+    /require\(['"](.+?)['"]\)/g
+    // require('...')
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      const importPath = match[1];
+      if (importPath && !importPath.startsWith("@") && !importPath.startsWith("node:")) {
+        imports.push(importPath);
+      }
+    }
+  }
+  return [...new Set(imports)];
+}
+function calculateImportDepth(file, graph, visited = /* @__PURE__ */ new Set(), depth = 0) {
+  if (visited.has(file)) {
+    return depth;
+  }
+  const dependencies = graph.edges.get(file);
+  if (!dependencies || dependencies.size === 0) {
+    return depth;
+  }
+  visited.add(file);
+  let maxDepth = depth;
+  for (const dep of dependencies) {
+    const depDepth = calculateImportDepth(dep, graph, visited, depth + 1);
+    maxDepth = Math.max(maxDepth, depDepth);
+  }
+  visited.delete(file);
+  return maxDepth;
+}
+function getTransitiveDependencies(file, graph, visited = /* @__PURE__ */ new Set()) {
+  if (visited.has(file)) {
+    return [];
+  }
+  visited.add(file);
+  const dependencies = graph.edges.get(file);
+  if (!dependencies || dependencies.size === 0) {
+    return [];
+  }
+  const allDeps = [];
+  for (const dep of dependencies) {
+    allDeps.push(dep);
+    allDeps.push(...getTransitiveDependencies(dep, graph, visited));
+  }
+  return [...new Set(allDeps)];
+}
+function calculateContextBudget(file, graph) {
+  const node = graph.nodes.get(file);
+  if (!node) return 0;
+  let totalTokens = node.tokenCost;
+  const deps = getTransitiveDependencies(file, graph);
+  for (const dep of deps) {
+    const depNode = graph.nodes.get(dep);
+    if (depNode) {
+      totalTokens += depNode.tokenCost;
+    }
+  }
+  return totalTokens;
+}
+function detectCircularDependencies(graph) {
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const recursionStack = /* @__PURE__ */ new Set();
+  function dfs(file, path) {
+    if (recursionStack.has(file)) {
+      const cycleStart = path.indexOf(file);
+      if (cycleStart !== -1) {
+        cycles.push([...path.slice(cycleStart), file]);
+      }
+      return;
+    }
+    if (visited.has(file)) {
+      return;
+    }
+    visited.add(file);
+    recursionStack.add(file);
+    path.push(file);
+    const dependencies = graph.edges.get(file);
+    if (dependencies) {
+      for (const dep of dependencies) {
+        dfs(dep, [...path]);
+      }
+    }
+    recursionStack.delete(file);
+  }
+  for (const file of graph.nodes.keys()) {
+    if (!visited.has(file)) {
+      dfs(file, []);
+    }
+  }
+  return cycles;
+}
+function calculateCohesion(exports) {
+  if (exports.length === 0) return 1;
+  if (exports.length === 1) return 1;
+  const domains = exports.map((e) => e.inferredDomain || "unknown");
+  const domainCounts = /* @__PURE__ */ new Map();
+  for (const domain of domains) {
+    domainCounts.set(domain, (domainCounts.get(domain) || 0) + 1);
+  }
+  const total = domains.length;
+  let entropy = 0;
+  for (const count of domainCounts.values()) {
+    const p = count / total;
+    if (p > 0) {
+      entropy -= p * Math.log2(p);
+    }
+  }
+  const maxEntropy = Math.log2(total);
+  return maxEntropy > 0 ? 1 - entropy / maxEntropy : 1;
+}
+function calculateFragmentation(files, domain) {
+  if (files.length <= 1) return 0;
+  const directories = new Set(files.map((f) => f.split("/").slice(0, -1).join("/")));
+  return (directories.size - 1) / (files.length - 1);
+}
+function detectModuleClusters(graph) {
+  const domainMap = /* @__PURE__ */ new Map();
+  for (const [file, node] of graph.nodes.entries()) {
+    const domains = node.exports.map((e) => e.inferredDomain || "unknown");
+    const primaryDomain = domains[0] || "unknown";
+    if (!domainMap.has(primaryDomain)) {
+      domainMap.set(primaryDomain, []);
+    }
+    domainMap.get(primaryDomain).push(file);
+  }
+  const clusters = [];
+  for (const [domain, files] of domainMap.entries()) {
+    if (files.length < 2) continue;
+    const totalTokens = files.reduce((sum, file) => {
+      const node = graph.nodes.get(file);
+      return sum + (node?.tokenCost || 0);
+    }, 0);
+    const fragmentationScore = calculateFragmentation(files, domain);
+    const avgCohesion = files.reduce((sum, file) => {
+      const node = graph.nodes.get(file);
+      return sum + (node ? calculateCohesion(node.exports) : 0);
+    }, 0) / files.length;
+    const targetFiles = Math.max(1, Math.ceil(files.length / 3));
+    const consolidationPlan = generateConsolidationPlan(
+      domain,
+      files,
+      targetFiles
+    );
+    clusters.push({
+      domain,
+      files,
+      totalTokens,
+      fragmentationScore,
+      avgCohesion,
+      suggestedStructure: {
+        targetFiles,
+        consolidationPlan
+      }
+    });
+  }
+  return clusters.sort((a, b) => b.fragmentationScore - a.fragmentationScore);
+}
+function extractExports(content) {
+  const exports = [];
+  const patterns = [
+    /export\s+function\s+(\w+)/g,
+    /export\s+class\s+(\w+)/g,
+    /export\s+const\s+(\w+)/g,
+    /export\s+type\s+(\w+)/g,
+    /export\s+interface\s+(\w+)/g,
+    /export\s+default/g
+  ];
+  const types = [
+    "function",
+    "class",
+    "const",
+    "type",
+    "interface",
+    "default"
+  ];
+  patterns.forEach((pattern, index) => {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      const name = match[1] || "default";
+      const type = types[index];
+      const inferredDomain = inferDomain(name);
+      exports.push({ name, type, inferredDomain });
+    }
+  });
+  return exports;
+}
+function inferDomain(name) {
+  const lower = name.toLowerCase();
+  const domainKeywords = [
+    "user",
+    "auth",
+    "order",
+    "product",
+    "payment",
+    "cart",
+    "invoice",
+    "customer",
+    "admin",
+    "api",
+    "util",
+    "helper",
+    "config",
+    "service",
+    "repository",
+    "controller",
+    "model",
+    "view"
+  ];
+  for (const keyword of domainKeywords) {
+    if (lower.includes(keyword)) {
+      return keyword;
+    }
+  }
+  return "unknown";
+}
+function generateConsolidationPlan(domain, files, targetFiles) {
+  const plan = [];
+  if (files.length <= targetFiles) {
+    return [`No consolidation needed for ${domain}`];
+  }
+  plan.push(
+    `Consolidate ${files.length} ${domain} files into ${targetFiles} cohesive file(s):`
+  );
+  const dirGroups = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const dir = file.split("/").slice(0, -1).join("/");
+    if (!dirGroups.has(dir)) {
+      dirGroups.set(dir, []);
+    }
+    dirGroups.get(dir).push(file);
+  }
+  plan.push(`1. Create unified ${domain} module file`);
+  plan.push(
+    `2. Move related functionality from ${files.length} scattered files`
+  );
+  plan.push(`3. Update imports in dependent files`);
+  plan.push(
+    `4. Remove old files after consolidation (verify with tests first)`
+  );
+  return plan;
+}
+
+// src/index.ts
+async function getSmartDefaults(directory, userOptions) {
+  const files = await scanFiles({
+    rootDir: directory,
+    include: userOptions.include,
+    exclude: userOptions.exclude
+  });
+  const estimatedBlocks = files.length;
+  let maxDepth;
+  let maxContextBudget;
+  let minCohesion;
+  let maxFragmentation;
+  if (estimatedBlocks < 100) {
+    maxDepth = 4;
+    maxContextBudget = 8e3;
+    minCohesion = 0.5;
+    maxFragmentation = 0.5;
+  } else if (estimatedBlocks < 500) {
+    maxDepth = 5;
+    maxContextBudget = 15e3;
+    minCohesion = 0.45;
+    maxFragmentation = 0.6;
+  } else if (estimatedBlocks < 2e3) {
+    maxDepth = 7;
+    maxContextBudget = 25e3;
+    minCohesion = 0.4;
+    maxFragmentation = 0.7;
+  } else {
+    maxDepth = 10;
+    maxContextBudget = 4e4;
+    minCohesion = 0.35;
+    maxFragmentation = 0.8;
+  }
+  return {
+    maxDepth,
+    maxContextBudget,
+    minCohesion,
+    maxFragmentation,
+    focus: "all",
+    includeNodeModules: false,
+    rootDir: userOptions.rootDir || directory,
+    include: userOptions.include,
+    exclude: userOptions.exclude
+  };
+}
+async function analyzeContext(options) {
+  const {
+    maxDepth = 5,
+    maxContextBudget = 1e4,
+    minCohesion = 0.6,
+    maxFragmentation = 0.5,
+    focus = "all",
+    includeNodeModules = false,
+    ...scanOptions
+  } = options;
+  const files = await scanFiles({
+    ...scanOptions,
+    exclude: includeNodeModules ? scanOptions.exclude : [...scanOptions.exclude || [], "**/node_modules/**"]
+  });
+  const fileContents = await Promise.all(
+    files.map(async (file) => ({
+      file,
+      content: await readFileContent(file)
+    }))
+  );
+  const graph = buildDependencyGraph(fileContents);
+  const circularDeps = detectCircularDependencies(graph);
+  const clusters = detectModuleClusters(graph);
+  const fragmentationMap = /* @__PURE__ */ new Map();
+  for (const cluster of clusters) {
+    for (const file of cluster.files) {
+      fragmentationMap.set(file, cluster.fragmentationScore);
+    }
+  }
+  const results = [];
+  for (const { file } of fileContents) {
+    const node = graph.nodes.get(file);
+    if (!node) continue;
+    const importDepth = focus === "depth" || focus === "all" ? calculateImportDepth(file, graph) : 0;
+    const dependencyList = focus === "depth" || focus === "all" ? getTransitiveDependencies(file, graph) : [];
+    const contextBudget = focus === "all" ? calculateContextBudget(file, graph) : node.tokenCost;
+    const cohesionScore = focus === "cohesion" || focus === "all" ? calculateCohesion(node.exports) : 1;
+    const fragmentationScore = fragmentationMap.get(file) || 0;
+    const relatedFiles = [];
+    for (const cluster of clusters) {
+      if (cluster.files.includes(file)) {
+        relatedFiles.push(...cluster.files.filter((f) => f !== file));
+        break;
+      }
+    }
+    const { severity, issues, recommendations, potentialSavings } = analyzeIssues({
+      file,
+      importDepth,
+      contextBudget,
+      cohesionScore,
+      fragmentationScore,
+      maxDepth,
+      maxContextBudget,
+      minCohesion,
+      maxFragmentation,
+      circularDeps
+    });
+    const domains = [
+      ...new Set(node.exports.map((e) => e.inferredDomain || "unknown"))
+    ];
+    results.push({
+      file,
+      tokenCost: node.tokenCost,
+      linesOfCode: node.linesOfCode,
+      importDepth,
+      dependencyCount: dependencyList.length,
+      dependencyList,
+      circularDeps: circularDeps.filter((cycle) => cycle.includes(file)),
+      cohesionScore,
+      domains,
+      exportCount: node.exports.length,
+      contextBudget,
+      fragmentationScore,
+      relatedFiles,
+      severity,
+      issues,
+      recommendations,
+      potentialSavings
+    });
+  }
+  const issuesOnly = results.filter((r) => r.severity !== "info");
+  const sorted = issuesOnly.sort((a, b) => {
+    const severityOrder = { critical: 0, major: 1, minor: 2, info: 3 };
+    const severityDiff = severityOrder[a.severity] - severityOrder[b.severity];
+    if (severityDiff !== 0) return severityDiff;
+    return b.contextBudget - a.contextBudget;
+  });
+  return sorted.length > 0 ? sorted : results;
+}
+function generateSummary(results) {
+  if (results.length === 0) {
+    return {
+      totalFiles: 0,
+      totalTokens: 0,
+      avgContextBudget: 0,
+      maxContextBudget: 0,
+      avgImportDepth: 0,
+      maxImportDepth: 0,
+      deepFiles: [],
+      avgFragmentation: 0,
+      fragmentedModules: [],
+      avgCohesion: 0,
+      lowCohesionFiles: [],
+      criticalIssues: 0,
+      majorIssues: 0,
+      minorIssues: 0,
+      totalPotentialSavings: 0,
+      topExpensiveFiles: []
+    };
+  }
+  const totalFiles = results.length;
+  const totalTokens = results.reduce((sum, r) => sum + r.tokenCost, 0);
+  const totalContextBudget = results.reduce(
+    (sum, r) => sum + r.contextBudget,
+    0
+  );
+  const avgContextBudget = totalContextBudget / totalFiles;
+  const maxContextBudget = Math.max(...results.map((r) => r.contextBudget));
+  const avgImportDepth = results.reduce((sum, r) => sum + r.importDepth, 0) / totalFiles;
+  const maxImportDepth = Math.max(...results.map((r) => r.importDepth));
+  const deepFiles = results.filter((r) => r.importDepth >= 5).map((r) => ({ file: r.file, depth: r.importDepth })).sort((a, b) => b.depth - a.depth).slice(0, 10);
+  const avgFragmentation = results.reduce((sum, r) => sum + r.fragmentationScore, 0) / totalFiles;
+  const moduleMap = /* @__PURE__ */ new Map();
+  for (const result of results) {
+    for (const domain of result.domains) {
+      if (!moduleMap.has(domain)) {
+        moduleMap.set(domain, []);
+      }
+      moduleMap.get(domain).push(result);
+    }
+  }
+  const fragmentedModules = [];
+  for (const [domain, files] of moduleMap.entries()) {
+    if (files.length < 2) continue;
+    const fragmentationScore = files.reduce((sum, f) => sum + f.fragmentationScore, 0) / files.length;
+    if (fragmentationScore < 0.3) continue;
+    const totalTokens2 = files.reduce((sum, f) => sum + f.tokenCost, 0);
+    const avgCohesion2 = files.reduce((sum, f) => sum + f.cohesionScore, 0) / files.length;
+    const targetFiles = Math.max(1, Math.ceil(files.length / 3));
+    fragmentedModules.push({
+      domain,
+      files: files.map((f) => f.file),
+      totalTokens: totalTokens2,
+      fragmentationScore,
+      avgCohesion: avgCohesion2,
+      suggestedStructure: {
+        targetFiles,
+        consolidationPlan: [
+          `Consolidate ${files.length} ${domain} files into ${targetFiles} cohesive file(s)`,
+          `Current token cost: ${totalTokens2.toLocaleString()}`,
+          `Estimated savings: ${Math.floor(totalTokens2 * 0.3).toLocaleString()} tokens (30%)`
+        ]
+      }
+    });
+  }
+  fragmentedModules.sort((a, b) => b.fragmentationScore - a.fragmentationScore);
+  const avgCohesion = results.reduce((sum, r) => sum + r.cohesionScore, 0) / totalFiles;
+  const lowCohesionFiles = results.filter((r) => r.cohesionScore < 0.6).map((r) => ({ file: r.file, score: r.cohesionScore })).sort((a, b) => a.score - b.score).slice(0, 10);
+  const criticalIssues = results.filter((r) => r.severity === "critical").length;
+  const majorIssues = results.filter((r) => r.severity === "major").length;
+  const minorIssues = results.filter((r) => r.severity === "minor").length;
+  const totalPotentialSavings = results.reduce(
+    (sum, r) => sum + r.potentialSavings,
+    0
+  );
+  const topExpensiveFiles = results.sort((a, b) => b.contextBudget - a.contextBudget).slice(0, 10).map((r) => ({
+    file: r.file,
+    contextBudget: r.contextBudget,
+    severity: r.severity
+  }));
+  return {
+    totalFiles,
+    totalTokens,
+    avgContextBudget,
+    maxContextBudget,
+    avgImportDepth,
+    maxImportDepth,
+    deepFiles,
+    avgFragmentation,
+    fragmentedModules: fragmentedModules.slice(0, 10),
+    avgCohesion,
+    lowCohesionFiles,
+    criticalIssues,
+    majorIssues,
+    minorIssues,
+    totalPotentialSavings,
+    topExpensiveFiles
+  };
+}
+function analyzeIssues(params) {
+  const {
+    file,
+    importDepth,
+    contextBudget,
+    cohesionScore,
+    fragmentationScore,
+    maxDepth,
+    maxContextBudget,
+    minCohesion,
+    maxFragmentation,
+    circularDeps
+  } = params;
+  const issues = [];
+  const recommendations = [];
+  let severity = "info";
+  let potentialSavings = 0;
+  if (circularDeps.length > 0) {
+    severity = "critical";
+    issues.push(
+      `Part of ${circularDeps.length} circular dependency chain(s)`
+    );
+    recommendations.push("Break circular dependencies by extracting interfaces or using dependency injection");
+    potentialSavings += contextBudget * 0.2;
+  }
+  if (importDepth > maxDepth * 1.5) {
+    severity = severity === "critical" ? "critical" : "critical";
+    issues.push(`Import depth ${importDepth} exceeds limit by 50%`);
+    recommendations.push("Flatten dependency tree or use facade pattern");
+    potentialSavings += contextBudget * 0.3;
+  } else if (importDepth > maxDepth) {
+    severity = severity === "critical" ? "critical" : "major";
+    issues.push(`Import depth ${importDepth} exceeds recommended maximum ${maxDepth}`);
+    recommendations.push("Consider reducing dependency depth");
+    potentialSavings += contextBudget * 0.15;
+  }
+  if (contextBudget > maxContextBudget * 1.5) {
+    severity = severity === "critical" ? "critical" : "critical";
+    issues.push(`Context budget ${contextBudget.toLocaleString()} tokens is 50% over limit`);
+    recommendations.push("Split into smaller modules or reduce dependency tree");
+    potentialSavings += contextBudget * 0.4;
+  } else if (contextBudget > maxContextBudget) {
+    severity = severity === "critical" || severity === "major" ? severity : "major";
+    issues.push(`Context budget ${contextBudget.toLocaleString()} exceeds ${maxContextBudget.toLocaleString()}`);
+    recommendations.push("Reduce file size or dependencies");
+    potentialSavings += contextBudget * 0.2;
+  }
+  if (cohesionScore < minCohesion * 0.5) {
+    severity = severity === "critical" ? "critical" : "major";
+    issues.push(`Very low cohesion (${(cohesionScore * 100).toFixed(0)}%) - mixed concerns`);
+    recommendations.push("Split file by domain - separate unrelated functionality");
+    potentialSavings += contextBudget * 0.25;
+  } else if (cohesionScore < minCohesion) {
+    severity = severity === "critical" || severity === "major" ? severity : "minor";
+    issues.push(`Low cohesion (${(cohesionScore * 100).toFixed(0)}%)`);
+    recommendations.push("Consider grouping related exports together");
+    potentialSavings += contextBudget * 0.1;
+  }
+  if (fragmentationScore > maxFragmentation) {
+    severity = severity === "critical" || severity === "major" ? severity : "minor";
+    issues.push(`High fragmentation (${(fragmentationScore * 100).toFixed(0)}%) - scattered implementation`);
+    recommendations.push("Consolidate with related files in same domain");
+    potentialSavings += contextBudget * 0.3;
+  }
+  if (issues.length === 0) {
+    issues.push("No significant issues detected");
+    recommendations.push("File is well-structured for AI context usage");
+  }
+  if (isBuildArtifact(file)) {
+    issues.push("Detected build artifact (bundled/output file)");
+    recommendations.push("Exclude build outputs (e.g., cdk.out, dist, build, .next) from analysis");
+    severity = downgradeSeverity(severity);
+    potentialSavings = 0;
+  }
+  return { severity, issues, recommendations, potentialSavings: Math.floor(potentialSavings) };
+}
+function isBuildArtifact(filePath) {
+  const lower = filePath.toLowerCase();
+  return lower.includes("/node_modules/") || lower.includes("/dist/") || lower.includes("/build/") || lower.includes("/out/") || lower.includes("/output/") || lower.includes("/cdk.out/") || lower.includes("/.next/") || /\/asset\.[^/]+\//.test(lower);
+}
+function downgradeSeverity(s) {
+  switch (s) {
+    case "critical":
+      return "minor";
+    case "major":
+      return "minor";
+    case "minor":
+      return "info";
+    default:
+      return "info";
+  }
+}
+
+export {
+  getSmartDefaults,
+  analyzeContext,
+  generateSummary
+};

package/dist/cli.js

@@ -382,12 +382,14 @@ async function analyzeContext(options) {
       potentialSavings
     });
   }
-  return results.sort((a, b) => {
+  const issuesOnly = results.filter((r) => r.severity !== "info");
+  const sorted = issuesOnly.sort((a, b) => {
     const severityOrder = { critical: 0, major: 1, minor: 2, info: 3 };
     const severityDiff = severityOrder[a.severity] - severityOrder[b.severity];
     if (severityDiff !== 0) return severityDiff;
     return b.contextBudget - a.contextBudget;
   });
+  return sorted.length > 0 ? sorted : results;
 }
 function generateSummary(results) {
   if (results.length === 0) {
@@ -641,24 +643,66 @@ program.name("aiready-context").description("Analyze AI context window cost and
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         analysisTime: elapsedTime
       };
-      (0, import_core3.handleJSONOutput)(jsonOutput, options.outputFile, `
-\u2713 JSON report saved to ${options.outputFile}`);
+      const outputPath = (0, import_core3.resolveOutputPath)(
+        options.outputFile,
+        `context-report-${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}.json`,
+        directory
+      );
+      (0, import_core3.handleJSONOutput)(jsonOutput, outputPath, `
+\u2713 JSON report saved to ${outputPath}`);
       return;
     }
     if (options.output === "html") {
       const html = generateHTMLReport(summary, results);
-      const outputPath = options.outputFile || (0, import_path.join)(process.cwd(), "context-report.html");
+      const outputPath = (0, import_core3.resolveOutputPath)(
+        options.outputFile,
+        `context-report-${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}.html`,
+        directory
+      );
+      const dir = (0, import_path.dirname)(outputPath);
+      if (!(0, import_fs.existsSync)(dir)) {
+        (0, import_fs.mkdirSync)(dir, { recursive: true });
+      }
       (0, import_fs.writeFileSync)(outputPath, html);
       console.log(import_chalk.default.green(`
 \u2713 HTML report saved to ${outputPath}`));
       return;
     }
     displayConsoleReport(summary, results, elapsedTime, finalOptions.maxResults);
+    displayTuningGuidance(results, finalOptions);
   } catch (error) {
     (0, import_core3.handleCLIError)(error, "Analysis");
   }
 });
 program.parse();
+function displayTuningGuidance(results, options) {
+  const issueCount = results.filter((r) => r.severity !== "info").length;
+  if (issueCount === 0) {
+    console.log(import_chalk.default.green("\n\u2728 No issues found! Your code is well-structured for AI context usage.\n"));
+    return;
+  }
+  console.log(import_chalk.default.cyan("\n\u2501".repeat(60)));
+  console.log(import_chalk.default.bold.white("  TUNING GUIDANCE"));
+  console.log(import_chalk.default.cyan("\u2501".repeat(60) + "\n"));
+  if (issueCount < 5) {
+    console.log(import_chalk.default.yellow("\u{1F4CA} Showing few issues. To catch more potential problems:\n"));
+    console.log(import_chalk.default.dim("   \u2022 Lower --max-depth (currently: " + options.maxDepth + ") to catch shallower import chains"));
+    console.log(import_chalk.default.dim("   \u2022 Lower --max-context (currently: " + options.maxContextBudget.toLocaleString() + ") to catch smaller files"));
+    console.log(import_chalk.default.dim("   \u2022 Raise --min-cohesion (currently: " + (options.minCohesion * 100).toFixed(0) + "%) to be stricter about mixed concerns"));
+    console.log(import_chalk.default.dim("   \u2022 Lower --max-fragmentation (currently: " + (options.maxFragmentation * 100).toFixed(0) + "%) to catch scattered code\n"));
+  } else if (issueCount > 20) {
+    console.log(import_chalk.default.yellow("\u{1F4CA} Showing many issues. To focus on most critical problems:\n"));
+    console.log(import_chalk.default.dim("   \u2022 Raise --max-depth (currently: " + options.maxDepth + ") to only catch very deep chains"));
+    console.log(import_chalk.default.dim("   \u2022 Raise --max-context (currently: " + options.maxContextBudget.toLocaleString() + ") to focus on largest files"));
+    console.log(import_chalk.default.dim("   \u2022 Lower --min-cohesion (currently: " + (options.minCohesion * 100).toFixed(0) + "%) to only flag severe mixed concerns"));
+    console.log(import_chalk.default.dim("   \u2022 Raise --max-fragmentation (currently: " + (options.maxFragmentation * 100).toFixed(0) + "%) to only flag highly scattered code\n"));
+  } else {
+    console.log(import_chalk.default.green("\u{1F4CA} Good balance of issues detected (showing " + issueCount + " issues)\n"));
+    console.log(import_chalk.default.dim("   \u{1F4A1} Tip: Adjust thresholds if needed:"));
+    console.log(import_chalk.default.dim("      aiready-context . --max-depth N --max-context N --min-cohesion 0.X\n"));
+  }
+  console.log(import_chalk.default.dim("   \u{1F4D6} See README for detailed tuning guide\n"));
+}
 function displayConsoleReport(summary, results, elapsedTime, maxResults = 10) {
   const terminalWidth = process.stdout.columns || 80;
   const dividerWidth = Math.min(60, terminalWidth - 2);

package/dist/cli.mjs

@@ -2,14 +2,14 @@
 import {
   analyzeContext,
   generateSummary
-} from "./chunk-HDFXSEFW.mjs";
+} from "./chunk-45P4RDYP.mjs";
 
 // src/cli.ts
 import { Command } from "commander";
 import chalk from "chalk";
-import { writeFileSync, existsSync, readFileSync } from "fs";
-import { join } from "path";
-import { loadMergedConfig, handleJSONOutput, handleCLIError, getElapsedTime } from "@aiready/core";
+import { writeFileSync, existsSync, readFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { loadMergedConfig, handleJSONOutput, handleCLIError, getElapsedTime, resolveOutputPath } from "@aiready/core";
 import prompts from "prompts";
 var program = new Command();
 program.name("aiready-context").description("Analyze AI context window cost and code structure").version("0.1.0").addHelpText("after", "\nCONFIGURATION:\n  Supports config files: aiready.json, aiready.config.json, .aiready.json, .aireadyrc.json, aiready.config.js, .aireadyrc.js\n  CLI options override config file settings").argument("<directory>", "Directory to analyze").option("--max-depth <number>", "Maximum acceptable import depth").option(
@@ -64,24 +64,66 @@ program.name("aiready-context").description("Analyze AI context window cost and
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         analysisTime: elapsedTime
       };
-      handleJSONOutput(jsonOutput, options.outputFile, `
-\u2713 JSON report saved to ${options.outputFile}`);
+      const outputPath = resolveOutputPath(
+        options.outputFile,
+        `context-report-${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}.json`,
+        directory
+      );
+      handleJSONOutput(jsonOutput, outputPath, `
+\u2713 JSON report saved to ${outputPath}`);
       return;
     }
     if (options.output === "html") {
       const html = generateHTMLReport(summary, results);
-      const outputPath = options.outputFile || join(process.cwd(), "context-report.html");
+      const outputPath = resolveOutputPath(
+        options.outputFile,
+        `context-report-${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}.html`,
+        directory
+      );
+      const dir = dirname(outputPath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
       writeFileSync(outputPath, html);
       console.log(chalk.green(`
 \u2713 HTML report saved to ${outputPath}`));
       return;
     }
     displayConsoleReport(summary, results, elapsedTime, finalOptions.maxResults);
+    displayTuningGuidance(results, finalOptions);
   } catch (error) {
     handleCLIError(error, "Analysis");
   }
 });
 program.parse();
+function displayTuningGuidance(results, options) {
+  const issueCount = results.filter((r) => r.severity !== "info").length;
+  if (issueCount === 0) {
+    console.log(chalk.green("\n\u2728 No issues found! Your code is well-structured for AI context usage.\n"));
+    return;
+  }
+  console.log(chalk.cyan("\n\u2501".repeat(60)));
+  console.log(chalk.bold.white("  TUNING GUIDANCE"));
+  console.log(chalk.cyan("\u2501".repeat(60) + "\n"));
+  if (issueCount < 5) {
+    console.log(chalk.yellow("\u{1F4CA} Showing few issues. To catch more potential problems:\n"));
+    console.log(chalk.dim("   \u2022 Lower --max-depth (currently: " + options.maxDepth + ") to catch shallower import chains"));
+    console.log(chalk.dim("   \u2022 Lower --max-context (currently: " + options.maxContextBudget.toLocaleString() + ") to catch smaller files"));
+    console.log(chalk.dim("   \u2022 Raise --min-cohesion (currently: " + (options.minCohesion * 100).toFixed(0) + "%) to be stricter about mixed concerns"));
+    console.log(chalk.dim("   \u2022 Lower --max-fragmentation (currently: " + (options.maxFragmentation * 100).toFixed(0) + "%) to catch scattered code\n"));
+  } else if (issueCount > 20) {
+    console.log(chalk.yellow("\u{1F4CA} Showing many issues. To focus on most critical problems:\n"));
+    console.log(chalk.dim("   \u2022 Raise --max-depth (currently: " + options.maxDepth + ") to only catch very deep chains"));
+    console.log(chalk.dim("   \u2022 Raise --max-context (currently: " + options.maxContextBudget.toLocaleString() + ") to focus on largest files"));
+    console.log(chalk.dim("   \u2022 Lower --min-cohesion (currently: " + (options.minCohesion * 100).toFixed(0) + "%) to only flag severe mixed concerns"));
+    console.log(chalk.dim("   \u2022 Raise --max-fragmentation (currently: " + (options.maxFragmentation * 100).toFixed(0) + "%) to only flag highly scattered code\n"));
+  } else {
+    console.log(chalk.green("\u{1F4CA} Good balance of issues detected (showing " + issueCount + " issues)\n"));
+    console.log(chalk.dim("   \u{1F4A1} Tip: Adjust thresholds if needed:"));
+    console.log(chalk.dim("      aiready-context . --max-depth N --max-context N --min-cohesion 0.X\n"));
+  }
+  console.log(chalk.dim("   \u{1F4D6} See README for detailed tuning guide\n"));
+}
 function displayConsoleReport(summary, results, elapsedTime, maxResults = 10) {
   const terminalWidth = process.stdout.columns || 80;
   const dividerWidth = Math.min(60, terminalWidth - 2);

package/dist/index.d.mts

@@ -69,6 +69,7 @@ interface ContextSummary {
 
 /**
  * Generate smart defaults for context analysis based on repository size
+ * Automatically tunes thresholds to target ~10 most serious issues
  */
 declare function getSmartDefaults(directory: string, userOptions: Partial<ContextAnalyzerOptions>): Promise<ContextAnalyzerOptions>;
 /**

package/dist/index.d.ts

@@ -69,6 +69,7 @@ interface ContextSummary {
 
 /**
  * Generate smart defaults for context analysis based on repository size
+ * Automatically tunes thresholds to target ~10 most serious issues
  */
 declare function getSmartDefaults(directory: string, userOptions: Partial<ContextAnalyzerOptions>): Promise<ContextAnalyzerOptions>;
 /**

package/dist/index.js

@@ -312,25 +312,25 @@ async function getSmartDefaults(directory, userOptions) {
   let minCohesion;
   let maxFragmentation;
   if (estimatedBlocks < 100) {
-    maxDepth = 3;
-    maxContextBudget = 5e3;
-    minCohesion = 0.7;
-    maxFragmentation = 0.3;
-  } else if (estimatedBlocks < 500) {
     maxDepth = 4;
     maxContextBudget = 8e3;
-    minCohesion = 0.65;
-    maxFragmentation = 0.4;
-  } else if (estimatedBlocks < 2e3) {
-    maxDepth = 5;
-    maxContextBudget = 12e3;
-    minCohesion = 0.6;
+    minCohesion = 0.5;
     maxFragmentation = 0.5;
-  } else {
-    maxDepth = 6;
-    maxContextBudget = 2e4;
-    minCohesion = 0.55;
+  } else if (estimatedBlocks < 500) {
+    maxDepth = 5;
+    maxContextBudget = 15e3;
+    minCohesion = 0.45;
     maxFragmentation = 0.6;
+  } else if (estimatedBlocks < 2e3) {
+    maxDepth = 7;
+    maxContextBudget = 25e3;
+    minCohesion = 0.4;
+    maxFragmentation = 0.7;
+  } else {
+    maxDepth = 10;
+    maxContextBudget = 4e4;
+    minCohesion = 0.35;
+    maxFragmentation = 0.8;
   }
   return {
     maxDepth,
@@ -424,12 +424,14 @@ async function analyzeContext(options) {
       potentialSavings
     });
   }
-  return results.sort((a, b) => {
+  const issuesOnly = results.filter((r) => r.severity !== "info");
+  const sorted = issuesOnly.sort((a, b) => {
     const severityOrder = { critical: 0, major: 1, minor: 2, info: 3 };
     const severityDiff = severityOrder[a.severity] - severityOrder[b.severity];
     if (severityDiff !== 0) return severityDiff;
     return b.contextBudget - a.contextBudget;
   });
+  return sorted.length > 0 ? sorted : results;
 }
 function generateSummary(results) {
   if (results.length === 0) {

package/dist/index.mjs

@@ -2,7 +2,7 @@ import {
   analyzeContext,
   generateSummary,
   getSmartDefaults
-} from "./chunk-HDFXSEFW.mjs";
+} from "./chunk-45P4RDYP.mjs";
 export {
   analyzeContext,
   generateSummary,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/context-analyzer",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "AI context window cost analysis - detect fragmented code, deep import chains, and expensive context budgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -50,7 +50,7 @@
     "commander": "^12.1.0",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
-    "@aiready/core": "0.5.1"
+    "@aiready/core": "0.5.4"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/src/cli.ts

@@ -3,9 +3,9 @@
 import { Command } from 'commander';
 import { analyzeContext, generateSummary } from './index';
 import chalk from 'chalk';
-import { writeFileSync, existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { loadMergedConfig, handleJSONOutput, handleCLIError, getElapsedTime } from '@aiready/core';
+import { writeFileSync, existsSync, readFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { loadMergedConfig, handleJSONOutput, handleCLIError, getElapsedTime, resolveOutputPath } from '@aiready/core';
 import prompts from 'prompts';
 
 const program = new Command();
@@ -91,14 +91,29 @@ program
           analysisTime: elapsedTime,
         };
 
-        handleJSONOutput(jsonOutput, options.outputFile, `\n✓ JSON report saved to ${options.outputFile}`);
+        const outputPath = resolveOutputPath(
+          options.outputFile,
+          `context-report-${new Date().toISOString().split('T')[0]}.json`,
+          directory
+        );
+        
+        handleJSONOutput(jsonOutput, outputPath, `\n✓ JSON report saved to ${outputPath}`);
         return;
       }
 
       if (options.output === 'html') {
         const html = generateHTMLReport(summary, results);
-        const outputPath =
-          options.outputFile || join(process.cwd(), 'context-report.html');
+        const outputPath = resolveOutputPath(
+          options.outputFile,
+          `context-report-${new Date().toISOString().split('T')[0]}.html`,
+          directory
+        );
+        
+        const dir = dirname(outputPath);
+        if (!existsSync(dir)) {
+          mkdirSync(dir, { recursive: true });
+        }
+        
         writeFileSync(outputPath, html);
         console.log(chalk.green(`\n✓ HTML report saved to ${outputPath}`));
         return;
@@ -106,6 +121,9 @@ program
 
       // Console output
       displayConsoleReport(summary, results, elapsedTime, finalOptions.maxResults);
+      
+      // Show tuning guidance after results
+      displayTuningGuidance(results, finalOptions);
     } catch (error) {
       handleCLIError(error, 'Analysis');
     }
@@ -113,6 +131,45 @@ program
 
 program.parse();
 
+/**
+ * Display tuning guidance to help users adjust thresholds
+ */
+function displayTuningGuidance(
+  results: Awaited<ReturnType<typeof analyzeContext>>,
+  options: any
+): void {
+  const issueCount = results.filter(r => r.severity !== 'info').length;
+  
+  if (issueCount === 0) {
+    console.log(chalk.green('\n✨ No issues found! Your code is well-structured for AI context usage.\n'));
+    return;
+  }
+  
+  console.log(chalk.cyan('\n━'.repeat(60)));
+  console.log(chalk.bold.white('  TUNING GUIDANCE'));
+  console.log(chalk.cyan('━'.repeat(60) + '\n'));
+  
+  if (issueCount < 5) {
+    console.log(chalk.yellow('📊 Showing few issues. To catch more potential problems:\n'));
+    console.log(chalk.dim('   • Lower --max-depth (currently: ' + options.maxDepth + ') to catch shallower import chains'));
+    console.log(chalk.dim('   • Lower --max-context (currently: ' + options.maxContextBudget.toLocaleString() + ') to catch smaller files'));
+    console.log(chalk.dim('   • Raise --min-cohesion (currently: ' + (options.minCohesion * 100).toFixed(0) + '%) to be stricter about mixed concerns'));
+    console.log(chalk.dim('   • Lower --max-fragmentation (currently: ' + (options.maxFragmentation * 100).toFixed(0) + '%) to catch scattered code\n'));
+  } else if (issueCount > 20) {
+    console.log(chalk.yellow('📊 Showing many issues. To focus on most critical problems:\n'));
+    console.log(chalk.dim('   • Raise --max-depth (currently: ' + options.maxDepth + ') to only catch very deep chains'));
+    console.log(chalk.dim('   • Raise --max-context (currently: ' + options.maxContextBudget.toLocaleString() + ') to focus on largest files'));
+    console.log(chalk.dim('   • Lower --min-cohesion (currently: ' + (options.minCohesion * 100).toFixed(0) + '%) to only flag severe mixed concerns'));
+    console.log(chalk.dim('   • Raise --max-fragmentation (currently: ' + (options.maxFragmentation * 100).toFixed(0) + '%) to only flag highly scattered code\n'));
+  } else {
+    console.log(chalk.green('📊 Good balance of issues detected (showing ' + issueCount + ' issues)\n'));
+    console.log(chalk.dim('   💡 Tip: Adjust thresholds if needed:'));
+    console.log(chalk.dim('      aiready-context . --max-depth N --max-context N --min-cohesion 0.X\n'));
+  }
+  
+  console.log(chalk.dim('   📖 See README for detailed tuning guide\n'));
+}
+
 /**
  * Display formatted console report
  */

package/src/index.ts

@@ -21,6 +21,7 @@ export type { ContextAnalyzerOptions, ContextAnalysisResult, ContextSummary, Mod
 
 /**
  * Generate smart defaults for context analysis based on repository size
+ * Automatically tunes thresholds to target ~10 most serious issues
  */
 async function getSmartDefaults(
   directory: string,
@@ -36,35 +37,37 @@ async function getSmartDefaults(
   const estimatedBlocks = files.length;
 
   // Smart defaults based on repository size
+  // Adjusted to be stricter (higher thresholds) to catch only serious issues
+  // This targets ~10 most critical issues instead of showing all files
   let maxDepth: number;
   let maxContextBudget: number;
   let minCohesion: number;
   let maxFragmentation: number;
 
   if (estimatedBlocks < 100) {
-    // Small project
-    maxDepth = 3;
-    maxContextBudget = 5000;
-    minCohesion = 0.7;
-    maxFragmentation = 0.3;
-  } else if (estimatedBlocks < 500) {
-    // Medium project
+    // Small project - be more lenient
     maxDepth = 4;
     maxContextBudget = 8000;
-    minCohesion = 0.65;
-    maxFragmentation = 0.4;
-  } else if (estimatedBlocks < 2000) {
-    // Large project
-    maxDepth = 5;
-    maxContextBudget = 12000;
-    minCohesion = 0.6;
+    minCohesion = 0.5;
     maxFragmentation = 0.5;
-  } else {
-    // Enterprise project
-    maxDepth = 6;
-    maxContextBudget = 20000;
-    minCohesion = 0.55;
+  } else if (estimatedBlocks < 500) {
+    // Medium project - moderate strictness
+    maxDepth = 5;
+    maxContextBudget = 15000;
+    minCohesion = 0.45;
     maxFragmentation = 0.6;
+  } else if (estimatedBlocks < 2000) {
+    // Large project - stricter to focus on worst issues
+    maxDepth = 7;
+    maxContextBudget = 25000;
+    minCohesion = 0.4;
+    maxFragmentation = 0.7;
+  } else {
+    // Enterprise project - very strict to show only critical issues
+    maxDepth = 10;
+    maxContextBudget = 40000;
+    minCohesion = 0.35;
+    maxFragmentation = 0.8;
   }
 
   return {
@@ -205,13 +208,20 @@ export async function analyzeContext(
     });
   }
 
+  // Filter to only files with actual issues (not just info)
+  // This reduces output noise and focuses on actionable problems
+  const issuesOnly = results.filter(r => r.severity !== 'info');
+  
   // Sort by severity and context budget
-  return results.sort((a, b) => {
+  const sorted = issuesOnly.sort((a, b) => {
     const severityOrder = { critical: 0, major: 1, minor: 2, info: 3 };
     const severityDiff = severityOrder[a.severity] - severityOrder[b.severity];
     if (severityDiff !== 0) return severityDiff;
     return b.contextBudget - a.contextBudget;
   });
+  
+  // If we have issues, return them; otherwise return all results
+  return sorted.length > 0 ? sorted : results;
 }
 
 /**