@aiready/context-analyzer 0.9.20 → 0.9.23

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/context-analyzer@0.9.20 build /Users/pengcao/projects/aiready/packages/context-analyzer
+> @aiready/context-analyzer@0.9.23 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,18 +9,18 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-CJS dist/cli.js   62.68 KB
-CJS dist/index.js 50.93 KB
-CJS ⚡️ Build success in 83ms
+CJS dist/index.js 55.45 KB
+CJS dist/cli.js   67.03 KB
+CJS ⚡️ Build success in 162ms
 ESM dist/cli.mjs                     18.53 KB
-ESM dist/chunk-VTALAPQZ.mjs          42.65 KB
-ESM dist/chunk-Y6FXYEAI.mjs          390.00 B
+ESM dist/chunk-MBE4AQP5.mjs          47.02 KB
 ESM dist/python-context-UOPTQH44.mjs 5.64 KB
-ESM dist/index.mjs                   585.00 B
-ESM ⚡️ Build success in 84ms
+ESM dist/chunk-Y6FXYEAI.mjs          390.00 B
+ESM dist/index.mjs                   697.00 B
+ESM ⚡️ Build success in 162ms
 DTS Build start
-DTS ⚡️ Build success in 8122ms
+DTS ⚡️ Build success in 7868ms
 DTS dist/cli.d.ts    20.00 B
-DTS dist/index.d.ts  6.03 KB
+DTS dist/index.d.ts  7.37 KB
 DTS dist/cli.d.mts   20.00 B
-DTS dist/index.d.mts 6.03 KB
+DTS dist/index.d.mts 7.37 KB

package/.turbo/turbo-test.log

@@ -1,31 +1,35 @@
 
 
-> @aiready/context-analyzer@0.9.20 test /Users/pengcao/projects/aiready/packages/context-analyzer
+> @aiready/context-analyzer@0.9.23 test /Users/pengcao/projects/aiready/packages/context-analyzer
 > vitest run
 
 [?25l
  RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/context-analyzer
 
- ✓ src/__tests__/scoring.test.ts (7 tests) 5ms
- ✓ dist/__tests__/scoring.test.js (7 tests) 10ms
- ✓ src/__tests__/structural-cohesion.test.ts (4 tests) 6ms
- ✓ src/__tests__/fragmentation-coupling.test.ts (2 tests) 161ms
- ✓ src/__tests__/analyzer.test.ts (14 tests) 134ms
- ✓ dist/__tests__/enhanced-cohesion.test.js (6 tests) 66ms
+ ✓ dist/__tests__/scoring.test.js (7 tests) 27ms
+ ✓ src/__tests__/scoring.test.ts (7 tests) 11ms
+ ✓ src/__tests__/auto-detection.test.ts (8 tests) 612ms
+     ✓ should auto-detect domain keywords from folder paths  315ms
+ ✓ src/__tests__/file-classification.test.ts (17 tests) 242ms
+ ✓ src/__tests__/analyzer.test.ts (14 tests) 491ms
+     ✓ should build a basic dependency graph  379ms
+ ✓ dist/__tests__/fragmentation-coupling.test.js (2 tests) 38ms
+ ✓ src/__tests__/fragmentation-coupling.test.ts (2 tests) 271ms
+ ✓ dist/__tests__/fragmentation-log.test.js (3 tests) 6ms
+ ✓ dist/__tests__/analyzer.test.js (14 tests) 542ms
+     ✓ should calculate import depth correctly  314ms
+ ✓ dist/__tests__/auto-detection.test.js (8 tests) 536ms
+ ✓ src/__tests__/fragmentation-advanced.test.ts (3 tests) 111ms
+ ✓ dist/__tests__/enhanced-cohesion.test.js (6 tests) 24ms
  ✓ dist/__tests__/structural-cohesion.test.js (4 tests) 1ms
- ✓ dist/__tests__/fragmentation-coupling.test.js (2 tests) 202ms
- ✓ dist/__tests__/fragmentation-log.test.js (3 tests) 4ms
- ✓ src/__tests__/auto-detection.test.ts (8 tests) 205ms
- ✓ dist/__tests__/analyzer.test.js (14 tests) 610ms
- ✓ dist/__tests__/auto-detection.test.js (8 tests) 317ms
- ✓ src/__tests__/fragmentation-advanced.test.ts (3 tests) 2ms
- ✓ dist/__tests__/fragmentation-advanced.test.js (3 tests) 8ms
- ✓ src/__tests__/enhanced-cohesion.test.ts (6 tests) 4ms
- ✓ src/__tests__/fragmentation-log.test.ts (3 tests) 47ms
+ ✓ src/__tests__/enhanced-cohesion.test.ts (6 tests) 31ms
+ ✓ src/__tests__/fragmentation-log.test.ts (3 tests) 4ms
+ ✓ src/__tests__/structural-cohesion.test.ts (4 tests) 240ms
+ ✓ dist/__tests__/fragmentation-advanced.test.js (3 tests) 6ms
 
- Test Files  16 passed (16)
-      Tests  94 passed (94)
-   Start at  15:34:38
-   Duration  10.60s (transform 21.01s, setup 0ms, import 58.32s, tests 1.78s, environment 37ms)
+ Test Files  17 passed (17)
+      Tests  111 passed (111)
+   Start at  11:30:31
+   Duration  10.28s (transform 3.68s, setup 0ms, import 60.43s, tests 3.19s, environment 12ms)
 
 [?25h

package/README.md

@@ -7,31 +7,48 @@ When AI tools try to help with your code, they need to load files into their con
 ## 🏛️ Architecture
 
 ```
-                           🎯 USER
-                             │
-                             ▼
-                   🎛️  CLI (orchestrator)
-                             │
-                             ▼
-                     🏢 HUB (core)
-                             │
-      ┌──────────────────────┼───────────┬───────────┐
-      ▼                      ▼           ▼           ▼
-  📊 PATTERN          ┌─────────────┐  🔧 CONSIST  📚 DOC
-   DETECT             │ 📦 CONTEXT  │ ⬅ YOU ARE HERE
-   ✅ Ready           │  ANALYZER   │   ENCY        DRIFT
-                      │ ✅ Ready    │  ✅ Ready    🔜 Soon
-                      └─────────────┘
+                    🎯 USER
+                      │
+                      ▼
+            🎛️  CLI (orchestrator)
+                      │
+    ┌─────────────────┴─────────────────┐
+    │                                   │
+    ▼                                   ▼
+┌────────┐                        ┌────────┐
+│🎨 VIS- │                        │ ANALY- │
+│UALIZER │                        │  SIS   │
+│✅ Ready│                        │ SPOKES │
+└────────┘                        └───┬────┘
+    │                                 │
+    │           ┌─────────────────────┼─────────────────────┐
+    │           ▼                     ▼                     ▼
+    │     ┌────────┐           ┌────────┐           ┌────────┐
+    │     │📊 PAT- │           │📦 CON- │           │🔧 CON- │
+    │     │TERN    │           │TEXT    │           │SISTENCY│
+    │     │DETECT  │           │ANALYZER│           │        │
+    │     │        │           │        │           │        │
+    │     │✅ Ready│           │✅ Ready│           │✅ Ready│
+    │     └────────┘           └────────┘           └────────┘
+    │                                 │                     │
+    │                    ← YOU ARE HERE                    │
+    │                                                       │
+    └───────────────────────────────────────────────────────┘
+                            │
+                            ▼
+                  🏢 HUB (@aiready/core)
 ```
 
 ## 🌍 Language Support
 
 **Currently Supported (64% market coverage):**
+
 - ✅ **TypeScript** (`.ts`, `.tsx`) - Import chains, context budget, cohesion
 - ✅ **JavaScript** (`.js`, `.jsx`) - Import chains, context budget, cohesion
 - ✅ **Python** (`.py`) - Import chains, context budget, circular deps, cohesion
 
 **Roadmap:**
+
 - 🔜 **Java** (Q3 2026) - Package dependencies, Maven/Gradle analysis
 - 🔜 **Go** (Q4 2026) - Module dependencies, package cohesion
 - 🔜 **Rust** (Q4 2026) - Crate dependencies, module structure
@@ -65,11 +82,13 @@ aiready-context ./src
 ### 🎯 Input & Output
 
 **Input:** Path to your source code directory
+
 ```bash
 aiready-context ./src
 ```
 
 **Output:** Terminal report + optional JSON file (saved to `.aiready/` directory)
+
 ```
 📊 Context Analysis Results
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -130,11 +149,13 @@ Result: AI sees everything, gives complete answers ✅
 | Recommendations | Generic | Rule-based | AI context optimization |
 
 **Recommended Workflow:**
+
 - Use **dependency-cruiser** to enforce architecture rules (blocking)
 - Use **@aiready/context-analyzer** to optimize for AI tools (advisory)
 - Track improvements over time with SaaS tier
 
 **Related AIReady Tools:**
+
 - [**@aiready/cli**](https://www.npmjs.com/package/@aiready/cli) - Unified CLI with all analysis tools
 - [**@aiready/pattern-detect**](https://www.npmjs.com/package/@aiready/pattern-detect) - Semantic duplicate detection
 - [**@aiready/consistency**](https://www.npmjs.com/package/@aiready/consistency) - Consistency checking
@@ -148,11 +169,13 @@ This tool measures four key dimensions that affect how much context AI tools nee
 **What it measures:** Total AI tokens needed to understand a file (file content + all dependencies)
 
 **Why it matters:** AI tools have limited context windows (e.g., 128K tokens). Large context budgets mean:
+
 - AI needs to load more files to understand your code
 - Risk of hitting context limits → incomplete/wrong answers
 - Slower AI responses (more processing time)
 
 **Example:**
+
 ```typescript
 // High context budget (15,000 tokens)
 import { A, B, C } from './deeply/nested/utils'  // +5,000 tokens
@@ -174,12 +197,15 @@ import { X, Y, Z } from './another/chain'       // +8,000 tokens
 **What it measures:** How many layers deep your import chains go
 
 **Why it matters:** Deep import chains create cascading context loads:
+
 ```
 app.ts → service.ts → helper.ts → util.ts → core.ts → base.ts
 ```
+
 AI must load all 6 files just to understand app.ts!
 
 **Example:**
+
 ```typescript
 // Deep chain (depth 8) = AI loads 8+ files
 import { validate } from '../../../utils/validators/user/schema'
@@ -197,10 +223,12 @@ import { validate } from './validators'
 **What it measures:** How related the exports in a file are to each other
 
 **How it's calculated:** Uses Shannon entropy of inferred domains
+
 - 1.0 = Perfect cohesion (all exports are related)
 - 0.0 = Zero cohesion (completely unrelated exports)
 
 **Why it matters:** Low cohesion = "God object" pattern = AI confusion
+
 ```typescript
 // Low cohesion (0.3) - mixing unrelated concerns
 export function validateUser() { }      // User domain
@@ -226,10 +254,12 @@ export interface User { }
 **What it measures:** How scattered a domain/concept is across different directories
 
 **How it's calculated:** `(unique directories - 1) / (total files - 1)`
+
 - 0.0 = No fragmentation (all files in same directory)
 - 1.0 = Maximum fragmentation (each file in different directory)
 
 **Why it matters:** Scattered domains force AI to load many unrelated paths
+
 ```typescript
 // High fragmentation (0.8) - User domain scattered
 src/api/user-routes.ts           // 800 tokens
@@ -260,6 +290,57 @@ These signals are included in the JSON summary (`fragmentedModules` entries) so
 
 ---
 
+### 🏷️ File Classification (Reducing False Positives)
+
+**What it measures:** The tool now classifies files into categories to distinguish real issues from acceptable patterns:
+
+| Classification | Description | Fragmentation Treatment |
+|---------------|-------------|------------------------|
+| **barrel-export** | Re-exports from other modules (index.ts) | 0% (expected behavior) |
+| **type-definition** | Primarily type/interface definitions | 0% (centralized types are good) |
+| **cohesive-module** | Single domain, high cohesion (≥70%) | 30% of original (large but focused is OK) |
+| **mixed-concerns** | Multiple domains, low cohesion | 100% (real issue) |
+| **unknown** | Doesn't fit other categories | 70% of original (benefit of doubt) |
+
+**Why it matters:** Previous versions could flag files that were actually well-designed:
+
+```typescript
+// ❌ Old behavior: Flagged as "high fragmentation (99%)"
+// shared/src/index.ts - barrel export with 6 domains
+export * from './user';
+export * from './order';
+export * from './product';
+// ... more re-exports
+
+// ✅ New behavior: Classified as "barrel-export"
+// Fragmentation score: 0% (this is what barrel files DO)
+// Recommendation: "Barrel export file detected - multiple domains are expected here"
+```
+
+```typescript
+// ❌ Old behavior: Flagged as "high fragmentation (98%)"
+// gst-calculator/client.tsx - 346 lines, 7 dependencies, 1 domain
+
+// ✅ New behavior: Classified as "cohesive-module"
+// Fragmentation score: 29% (reduced from 98%)
+// Recommendation: "Module has good cohesion despite its size"
+```
+
+**🎯 Benefit:** Focus on real issues while accepting legitimate patterns.
+
+**JSON Output includes classification:**
+
+```json
+{
+  "file": "src/index.ts",
+  "fileClassification": "barrel-export",
+  "fragmentationScore": 0,
+  "severity": "info"
+}
+```
+
+---
+
 ### ⚖️ The Tradeoff: Splitting vs. Consolidating
 
 **Important:** These metrics can pull in opposite directions!
@@ -270,6 +351,7 @@ These signals are included in the JSON summary (`fragmentedModules` entries) so
 | **Consolidate scattered files** | ⚠️ May increase | ✅ Reduces | ⚠️ May decrease |
 
 **Best Practice:** Optimize for your use case:
+
 - **Large files with mixed concerns** → Split by domain (improves cohesion + reduces budget)
 - **Scattered single-domain files** → Consolidate (reduces fragmentation)
 - **Large files with high cohesion** → May be OK if under context budget threshold
@@ -350,6 +432,7 @@ aiready-context ./src --max-depth 3 --max-context 5000 --min-cohesion 0.7 --max-
 ```
 
 **What this means:**
+
 - `--max-depth 3`: Flag files with import depth ≥4 (stricter than default 5-7)
 - `--max-context 5000`: Flag files needing 5K+ tokens (catches smaller files)
 - `--min-cohesion 0.7`: Require 70%+ cohesion (stricter about mixed concerns)
@@ -365,6 +448,7 @@ aiready-context ./src --max-depth 10 --max-context 30000 --min-cohesion 0.4 --ma
 ```
 
 **What this means:**
+
 - `--max-depth 10`: Only flag import depth ≥11 (very deep chains)
 - `--max-context 30000`: Only flag files needing 30K+ tokens (only huge files)
 - `--min-cohesion 0.4`: Accept 40%+ cohesion (more lenient about mixed concerns)
@@ -384,6 +468,7 @@ aiready-context ./src --max-depth 10 --max-context 30000 --min-cohesion 0.4 --ma
 ### Common Tuning Scenarios
 
 **Small codebase getting too many warnings?**
+
 ```bash
 aiready-context ./src --max-depth 6 --min-cohesion 0.5
 # Explanation: Allow slightly deeper imports and more mixed concerns
@@ -391,6 +476,7 @@ 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
 # Explanation: Be stricter about depth and context to catch more problems
@@ -398,6 +484,7 @@ 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
 # Explanation: Very lenient - only show the worst offenders
@@ -405,6 +492,7 @@ aiready-context ./src --max-depth 8 --max-context 25000 --min-cohesion 0.3
 ```
 
 **Preparing for AI refactoring sprint:**
+
 ```bash
 aiready-context ./src --max-depth 4 --max-context 8000 --min-cohesion 0.6 --max-fragmentation 0.5
 # Explanation: Strict on all dimensions to get comprehensive issue list
@@ -412,6 +500,7 @@ aiready-context ./src --max-depth 4 --max-context 8000 --min-cohesion 0.6 --max-
 ```
 
 **Microservices architecture (naturally fragmented):**
+
 ```bash
 aiready-context ./src --max-fragmentation 0.9
 # Explanation: Very lenient on fragmentation (services are meant to be separate)
@@ -614,24 +703,28 @@ for (const result of results) {
 ## 📊 Metrics Explained
 
 ### Import Depth
+
 **What:** Maximum chain length of transitive dependencies  
 **Impact:** Deeper chains = more files to load = higher context cost  
 **Threshold:** >5 is concerning, >8 is critical  
 **Fix:** Flatten dependency tree, use facade pattern, break circular deps
 
 ### Context Budget
+
 **What:** Total tokens AI needs to load to understand this file  
 **Impact:** Higher budget = more expensive AI assistance  
 **Threshold:** >10,000 tokens often hits context limits  
 **Fix:** Split files, reduce dependencies, extract interfaces
 
 ### Fragmentation Score
+
 **What:** How scattered related code is across directories (0-100%)  
 **Impact:** Higher = more files to load for domain understanding  
 **Threshold:** >50% indicates poor organization  
 **Fix:** Consolidate related code into cohesive modules
 
 ### Cohesion Score
+
 **What:** How related exports are within a file (0-100%)  
 **Impact:** Lower = mixed concerns = wasted context  
 **Threshold:** <60% indicates low cohesion  
@@ -657,6 +750,7 @@ for (const result of results) {
 ### Default Exclusions
 
 By default, these patterns are excluded (unless `--include-node-modules` is used):
+
 ```bash
 # Dependencies (excluded by default, override with --include-node-modules)
 **/node_modules/**
@@ -699,29 +793,37 @@ interface ContextAnalyzerOptions {
 ## 🔬 How It Works
 
 ### 1. Dependency Graph Builder
+
 Parses imports and exports to build a complete dependency graph of your codebase.
 
 ### 2. Depth Calculator
+
 Calculates maximum import chain depth using graph traversal, identifying circular dependencies.
 
 ### 3. Semantic Domain Detection
+
 Uses **co-usage patterns** (files imported together) and **type dependencies** (shared types) to automatically identify semantic domains. No configuration needed - the tool discovers relationships from actual code usage.
 
 ### 4. Fragmentation Detector
+
 Groups files by semantic domain and calculates how scattered they are across directories.
 
 ### 5. Cohesion Analyzer
+
 Uses entropy to measure how related exports are within each file (low entropy = high cohesion).
 
 ### 6. Context Budget Calculator
+
 Sums tokens across entire dependency tree to estimate AI context cost for each file.
 
 ## 🎨 Output Formats
 
 ### Console (Default)
+
 Rich formatted output with colors, emojis, and actionable recommendations.
 
 ### JSON
+
 Machine-readable output for CI/CD integration:
 
 ```json
@@ -748,6 +850,7 @@ Machine-readable output for CI/CD integration:
 ```
 
 ### HTML
+
 Shareable report with tables and visualizations. Perfect for stakeholders:
 
 ```bash
@@ -764,6 +867,7 @@ aiready-context ./src --interactive
 ```
 
 Interactive mode:
+
 - Detects frameworks and recommends excludes (e.g., .next, cdk.out)
 - Lets you choose focus areas: frontend, backend, or both
 - Applies configuration without modifying your files
@@ -813,6 +917,7 @@ aiready-patterns src           # Duplicate pattern detection
 ## 💰 SaaS Features (Coming Soon)
 
 ### Free Tier (CLI)
+
 ✅ One-time snapshot analysis  
 ✅ All metrics and recommendations  
 ✅ JSON/HTML export