@aiready/context-analyzer 0.9.34 → 0.9.36

package/src/index.ts

@@ -1,5 +1,4 @@
 import { scanFiles, readFileContent } from '@aiready/core';
-import type { ScanOptions } from '@aiready/core';
 import {
   buildDependencyGraph,
   calculateImportDepth,
@@ -37,11 +36,13 @@ import {
   getCoUsageData,
   findConsolidationCandidates,
 } from './semantic-analysis';
+// Reference optional imports used by future heuristics to avoid lint warnings
+void calculateFragmentation;
 
-export type { 
-  ContextAnalyzerOptions, 
-  ContextAnalysisResult, 
-  ContextSummary, 
+export type {
+  ContextAnalyzerOptions,
+  ContextAnalysisResult,
+  ContextSummary,
   ModuleCluster,
   DomainAssignment,
   DomainSignals,
@@ -50,10 +51,7 @@ export type {
   FileClassification,
 };
 
-export {
-  classifyFile,
-  adjustFragmentationForClassification,
-};
+export { classifyFile, adjustFragmentationForClassification };
 
 export {
   buildCoUsageMatrix,
@@ -152,14 +150,18 @@ export async function analyzeContext(
     // Only add node_modules to exclude if includeNodeModules is false
     // The DEFAULT_EXCLUDE already includes node_modules, so this is only needed
     // if user overrides the default exclude list
-    exclude: includeNodeModules && scanOptions.exclude
-      ? scanOptions.exclude.filter(pattern => pattern !== '**/node_modules/**')
-      : scanOptions.exclude,
+    exclude:
+      includeNodeModules && scanOptions.exclude
+        ? scanOptions.exclude.filter(
+            (pattern) => pattern !== '**/node_modules/**'
+          )
+        : scanOptions.exclude,
   });
 
   // Separate files by language
-  const pythonFiles = files.filter(f => f.toLowerCase().endsWith('.py'));
-  const tsJsFiles = files.filter(f => !f.toLowerCase().endsWith('.py'));
+  const pythonFiles = files.filter((f) => f.toLowerCase().endsWith('.py'));
+  const tsJsFiles = files.filter((f) => !f.toLowerCase().endsWith('.py'));
+  void tsJsFiles;
 
   // Read all file contents
   const fileContents = await Promise.all(
@@ -170,37 +172,51 @@ export async function analyzeContext(
   );
 
   // Build dependency graph (TS/JS)
-  const graph = buildDependencyGraph(fileContents.filter(f => !f.file.toLowerCase().endsWith('.py')));
+  const graph = buildDependencyGraph(
+    fileContents.filter((f) => !f.file.toLowerCase().endsWith('.py'))
+  );
 
   // Analyze Python files separately (if any)
   let pythonResults: ContextAnalysisResult[] = [];
   if (pythonFiles.length > 0) {
     const { analyzePythonContext } = await import('./analyzers/python-context');
-    const pythonMetrics = await analyzePythonContext(pythonFiles, scanOptions.rootDir || options.rootDir || '.');
-    
+    const pythonMetrics = await analyzePythonContext(
+      pythonFiles,
+      scanOptions.rootDir || options.rootDir || '.'
+    );
+
     // Convert Python metrics to ContextAnalysisResult format
-    pythonResults = pythonMetrics.map(metric => {
-      const { severity, issues, recommendations, potentialSavings } = analyzeIssues({
-        file: metric.file,
-        importDepth: metric.importDepth,
-        contextBudget: metric.contextBudget,
-        cohesionScore: metric.cohesion,
-        fragmentationScore: 0, // Python analyzer doesn't calculate fragmentation yet
-        maxDepth,
-        maxContextBudget,
-        minCohesion,
-        maxFragmentation,
-        circularDeps: metric.metrics.circularDependencies.map(cycle => cycle.split(' → ')),
-      });
+    pythonResults = pythonMetrics.map((metric) => {
+      const { severity, issues, recommendations, potentialSavings } =
+        analyzeIssues({
+          file: metric.file,
+          importDepth: metric.importDepth,
+          contextBudget: metric.contextBudget,
+          cohesionScore: metric.cohesion,
+          fragmentationScore: 0, // Python analyzer doesn't calculate fragmentation yet
+          maxDepth,
+          maxContextBudget,
+          minCohesion,
+          maxFragmentation,
+          circularDeps: metric.metrics.circularDependencies.map((cycle) =>
+            cycle.split(' → ')
+          ),
+        });
 
       return {
         file: metric.file,
-        tokenCost: Math.floor(metric.contextBudget / (1 + metric.imports.length || 1)), // Estimate
+        tokenCost: Math.floor(
+          metric.contextBudget / (1 + metric.imports.length || 1)
+        ), // Estimate
         linesOfCode: metric.metrics.linesOfCode,
         importDepth: metric.importDepth,
         dependencyCount: metric.imports.length,
-        dependencyList: metric.imports.map(imp => imp.resolvedPath || imp.source),
-        circularDeps: metric.metrics.circularDependencies.map(cycle => cycle.split(' → ')),
+        dependencyList: metric.imports.map(
+          (imp) => imp.resolvedPath || imp.source
+        ),
+        circularDeps: metric.metrics.circularDependencies.map((cycle) =>
+          cycle.split(' → ')
+        ),
         cohesionScore: metric.cohesion,
         domains: ['python'], // Generic for now
         exportCount: metric.exports.length,
@@ -253,7 +269,9 @@ export async function analyzeContext(
 
     const cohesionScore =
       focus === 'cohesion' || focus === 'all'
-        ? calculateCohesion(node.exports, file, { coUsageMatrix: graph.coUsageMatrix })
+        ? calculateCohesion(node.exports, file, {
+            coUsageMatrix: graph.coUsageMatrix,
+          })
         : 1;
 
     const fragmentationScore = fragmentationMap.get(file) || 0;
@@ -281,6 +299,11 @@ export async function analyzeContext(
         maxFragmentation,
         circularDeps,
       });
+      // Some returned fields are not needed for the Python mapping here
+      void severity;
+      void issues;
+      void recommendations;
+      void potentialSavings;
 
     // Get domains from exports
     const domains = [
@@ -289,14 +312,14 @@ export async function analyzeContext(
 
     // Classify the file to help distinguish real issues from false positives
     const fileClassification = classifyFile(node, cohesionScore, domains);
-    
+
     // Adjust cohesion based on classification (utility/service/handler files get boosted)
     const adjustedCohesionScore = adjustCohesionForClassification(
       cohesionScore,
       fileClassification,
       node
     );
-    
+
     // Adjust fragmentation based on classification
     const adjustedFragmentationScore = adjustFragmentationForClassification(
       fragmentationScore,
@@ -346,7 +369,10 @@ export async function analyzeContext(
       fileClassification,
       severity: adjustedSeverity,
       issues: adjustedIssues,
-      recommendations: [...finalRecommendations, ...classificationRecommendations.slice(0, 1)],
+      recommendations: [
+        ...finalRecommendations,
+        ...classificationRecommendations.slice(0, 1),
+      ],
       potentialSavings: adjustedSavings,
     });
   }
@@ -457,7 +483,10 @@ export function generateSummary(
     let importPairs = 0;
     for (let i = 0; i < files.length; i++) {
       for (let j = i + 1; j < files.length; j++) {
-        importSimTotal += jaccard(files[i].dependencyList || [], files[j].dependencyList || []);
+        importSimTotal += jaccard(
+          files[i].dependencyList || [],
+          files[j].dependencyList || []
+        );
         importPairs++;
       }
     }
@@ -495,7 +524,9 @@ export function generateSummary(
     .sort((a, b) => a.score - b.score)
     .slice(0, 10);
 
-  const criticalIssues = results.filter((r) => r.severity === 'critical').length;
+  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;
 
@@ -574,10 +605,10 @@ function analyzeIssues(params: {
   // Check circular dependencies (CRITICAL)
   if (circularDeps.length > 0) {
     severity = 'critical';
-    issues.push(
-      `Part of ${circularDeps.length} circular dependency chain(s)`
+    issues.push(`Part of ${circularDeps.length} circular dependency chain(s)`);
+    recommendations.push(
+      'Break circular dependencies by extracting interfaces or using dependency injection'
     );
-    recommendations.push('Break circular dependencies by extracting interfaces or using dependency injection');
     potentialSavings += contextBudget * 0.2; // Estimate 20% savings
   }
 
@@ -589,7 +620,9 @@ function analyzeIssues(params: {
     potentialSavings += contextBudget * 0.3; // Estimate 30% savings
   } else if (importDepth > maxDepth) {
     severity = severity === 'critical' ? 'critical' : 'major';
-    issues.push(`Import depth ${importDepth} exceeds recommended maximum ${maxDepth}`);
+    issues.push(
+      `Import depth ${importDepth} exceeds recommended maximum ${maxDepth}`
+    );
     recommendations.push('Consider reducing dependency depth');
     potentialSavings += contextBudget * 0.15;
   }
@@ -597,12 +630,19 @@ function analyzeIssues(params: {
   // Check context budget
   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');
+    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; // Significant savings possible
   } else if (contextBudget > maxContextBudget) {
-    severity = severity === 'critical' || severity === 'major' ? severity : 'major';
-    issues.push(`Context budget ${contextBudget.toLocaleString()} exceeds ${maxContextBudget.toLocaleString()}`);
+    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;
   }
@@ -610,11 +650,16 @@ function analyzeIssues(params: {
   // Check cohesion
   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');
+    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';
+    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;
@@ -622,8 +667,11 @@ function analyzeIssues(params: {
 
   // Check fragmentation
   if (fragmentationScore > maxFragmentation) {
-    severity = severity === 'critical' || severity === 'major' ? severity : 'minor';
-    issues.push(`High fragmentation (${(fragmentationScore * 100).toFixed(0)}%) - scattered implementation`);
+    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;
   }
@@ -636,13 +684,20 @@ function analyzeIssues(params: {
   // Detect build artifacts and downgrade severity to reduce noise
   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');
+    recommendations.push(
+      'Exclude build outputs (e.g., cdk.out, dist, build, .next) from analysis'
+    );
     severity = downgradeSeverity(severity);
     // Build artifacts do not represent actionable savings
     potentialSavings = 0;
   }
 
-  return { severity, issues, recommendations, potentialSavings: Math.floor(potentialSavings) };
+  return {
+    severity,
+    issues,
+    recommendations,
+    potentialSavings: Math.floor(potentialSavings),
+  };
 }
 
 export { getSmartDefaults };
@@ -664,7 +719,9 @@ function isBuildArtifact(filePath: string): boolean {
   );
 }
 
-function downgradeSeverity(s: ContextAnalysisResult['severity']): ContextAnalysisResult['severity'] {
+function downgradeSeverity(
+  s: ContextAnalysisResult['severity']
+): ContextAnalysisResult['severity'] {
   switch (s) {
     case 'critical':
       return 'minor';

package/src/scoring.ts

@@ -1,21 +1,21 @@
-import { 
-  calculateMonthlyCost, 
+import {
+  calculateMonthlyCost,
   calculateProductivityImpact,
   DEFAULT_COST_CONFIG,
-  type CostConfig 
+  type CostConfig,
 } from '@aiready/core';
 import type { ToolScoringOutput } from '@aiready/core';
 import type { ContextSummary } from './types';
 
 /**
  * Calculate AI Readiness Score for context efficiency (0-100)
- * 
+ *
  * Based on:
  * - Average context budget (tokens needed to understand files)
  * - Import depth (dependency chain length)
  * - Fragmentation score (code organization)
  * - Critical/major issues
- * 
+ *
  * Includes business value metrics:
  * - Estimated monthly cost of context waste
  * - Estimated developer hours to fix
@@ -33,66 +33,70 @@ export function calculateContextScore(
     criticalIssues,
     majorIssues,
   } = summary;
-  
+
   // Context budget scoring (40% weight in final score)
   // Ideal: <5000 tokens avg = 100
   // Acceptable: 5000-10000 = 90-70
   // High: 10000-20000 = 70-40
   // Critical: >20000 = <40
-  const budgetScore = avgContextBudget < 5000 
-    ? 100
-    : Math.max(0, 100 - (avgContextBudget - 5000) / 150);
-  
+  const budgetScore =
+    avgContextBudget < 5000
+      ? 100
+      : Math.max(0, 100 - (avgContextBudget - 5000) / 150);
+
   // Import depth scoring (30% weight)
   // Ideal: <5 avg = 100
   // Acceptable: 5-8 = 80-60
   // Deep: >8 = <60
-  const depthScore = avgImportDepth < 5
-    ? 100
-    : Math.max(0, 100 - (avgImportDepth - 5) * 10);
-  
+  const depthScore =
+    avgImportDepth < 5 ? 100 : Math.max(0, 100 - (avgImportDepth - 5) * 10);
+
   // Fragmentation scoring (30% weight)
   // Well-organized: <0.3 = 100
   // Moderate: 0.3-0.5 = 80-60
   // Fragmented: >0.5 = <60
-  const fragmentationScore = avgFragmentation < 0.3
-    ? 100
-    : Math.max(0, 100 - (avgFragmentation - 0.3) * 200);
-  
+  const fragmentationScore =
+    avgFragmentation < 0.3
+      ? 100
+      : Math.max(0, 100 - (avgFragmentation - 0.3) * 200);
+
   // Issue penalties
   const criticalPenalty = criticalIssues * 10;
   const majorPenalty = majorIssues * 3;
-  
+
   // Max budget penalty (if any single file is extreme)
-  const maxBudgetPenalty = maxContextBudget > 15000 
-    ? Math.min(20, (maxContextBudget - 15000) / 500)
-    : 0;
-  
+  const maxBudgetPenalty =
+    maxContextBudget > 15000
+      ? Math.min(20, (maxContextBudget - 15000) / 500)
+      : 0;
+
   // Weighted average of subscores
-  const rawScore = (budgetScore * 0.4) + (depthScore * 0.3) + (fragmentationScore * 0.3);
-  const finalScore = rawScore - criticalPenalty - majorPenalty - maxBudgetPenalty;
-  
+  const rawScore =
+    budgetScore * 0.4 + depthScore * 0.3 + fragmentationScore * 0.3;
+  const finalScore =
+    rawScore - criticalPenalty - majorPenalty - maxBudgetPenalty;
+
   const score = Math.max(0, Math.min(100, Math.round(finalScore)));
-  
+
   // Build factors array
   const factors = [
     {
       name: 'Context Budget',
-      impact: Math.round((budgetScore * 0.4) - 40),
+      impact: Math.round(budgetScore * 0.4 - 40),
       description: `Avg ${Math.round(avgContextBudget)} tokens per file ${avgContextBudget < 5000 ? '(excellent)' : avgContextBudget < 10000 ? '(acceptable)' : '(high)'}`,
     },
     {
       name: 'Import Depth',
-      impact: Math.round((depthScore * 0.3) - 30),
+      impact: Math.round(depthScore * 0.3 - 30),
       description: `Avg ${avgImportDepth.toFixed(1)} levels ${avgImportDepth < 5 ? '(excellent)' : avgImportDepth < 8 ? '(acceptable)' : '(deep)'}`,
     },
     {
       name: 'Fragmentation',
-      impact: Math.round((fragmentationScore * 0.3) - 30),
+      impact: Math.round(fragmentationScore * 0.3 - 30),
       description: `${(avgFragmentation * 100).toFixed(0)}% fragmentation ${avgFragmentation < 0.3 ? '(well-organized)' : avgFragmentation < 0.5 ? '(moderate)' : '(high)'}`,
     },
   ];
-  
+
   if (criticalIssues > 0) {
     factors.push({
       name: 'Critical Issues',
@@ -100,7 +104,7 @@ export function calculateContextScore(
       description: `${criticalIssues} critical context issue${criticalIssues > 1 ? 's' : ''}`,
     });
   }
-  
+
   if (majorIssues > 0) {
     factors.push({
       name: 'Major Issues',
@@ -108,7 +112,7 @@ export function calculateContextScore(
       description: `${majorIssues} major context issue${majorIssues > 1 ? 's' : ''}`,
     });
   }
-  
+
   if (maxBudgetPenalty > 0) {
     factors.push({
       name: 'Extreme File Detected',
@@ -116,19 +120,22 @@ export function calculateContextScore(
       description: `One file requires ${Math.round(maxContextBudget)} tokens (very high)`,
     });
   }
-  
+
   // Generate recommendations
   const recommendations: ToolScoringOutput['recommendations'] = [];
-  
+
   if (avgContextBudget > 10000) {
-    const estimatedImpact = Math.min(15, Math.round((avgContextBudget - 10000) / 1000));
+    const estimatedImpact = Math.min(
+      15,
+      Math.round((avgContextBudget - 10000) / 1000)
+    );
     recommendations.push({
       action: 'Reduce file dependencies to lower context requirements',
       estimatedImpact,
       priority: 'high',
     });
   }
-  
+
   if (avgImportDepth > 8) {
     const estimatedImpact = Math.min(10, Math.round((avgImportDepth - 8) * 2));
     recommendations.push({
@@ -137,16 +144,19 @@ export function calculateContextScore(
       priority: avgImportDepth > 10 ? 'high' : 'medium',
     });
   }
-  
+
   if (avgFragmentation > 0.5) {
-    const estimatedImpact = Math.min(12, Math.round((avgFragmentation - 0.5) * 40));
+    const estimatedImpact = Math.min(
+      12,
+      Math.round((avgFragmentation - 0.5) * 40)
+    );
     recommendations.push({
       action: 'Consolidate related code into cohesive modules',
       estimatedImpact,
       priority: 'medium',
     });
   }
-  
+
   if (maxContextBudget > 20000) {
     recommendations.push({
       action: `Split large file (${Math.round(maxContextBudget)} tokens) into smaller modules`,
@@ -154,20 +164,20 @@ export function calculateContextScore(
       priority: 'high',
     });
   }
-  
+
   // Calculate business value metrics
   const cfg = { ...DEFAULT_COST_CONFIG, ...costConfig };
   // Total context budget across all files
   const totalContextBudget = avgContextBudget * summary.totalFiles;
   const estimatedMonthlyCost = calculateMonthlyCost(totalContextBudget, cfg);
-  
+
   // Convert issues to format for productivity calculation
   const issues = [
     ...Array(criticalIssues).fill({ severity: 'critical' as const }),
     ...Array(majorIssues).fill({ severity: 'major' as const }),
   ];
   const productivityImpact = calculateProductivityImpact(issues);
-  
+
   return {
     toolName: 'context-analyzer',
     score,