@aiready/context-analyzer 0.9.19 → 0.9.22

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/context-analyzer@0.9.19 build /Users/pengcao/projects/aiready/packages/context-analyzer
+> @aiready/context-analyzer@0.9.22 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
@@ -11,15 +11,15 @@
 ESM Build start
 CJS dist/cli.js   62.68 KB
 CJS dist/index.js 50.93 KB
-CJS ⚡️ Build success in 101ms
-ESM dist/cli.mjs                     18.53 KB
+CJS ⚡️ Build success in 36ms
 ESM dist/python-context-UOPTQH44.mjs 5.64 KB
 ESM dist/chunk-VTALAPQZ.mjs          42.65 KB
-ESM dist/chunk-Y6FXYEAI.mjs          390.00 B
 ESM dist/index.mjs                   585.00 B
-ESM ⚡️ Build success in 101ms
+ESM dist/chunk-Y6FXYEAI.mjs          390.00 B
+ESM dist/cli.mjs                     18.53 KB
+ESM ⚡️ Build success in 37ms
 DTS Build start
-DTS ⚡️ Build success in 2132ms
+DTS ⚡️ Build success in 1637ms
 DTS dist/cli.d.ts    20.00 B
 DTS dist/index.d.ts  6.03 KB
 DTS dist/cli.d.mts   20.00 B

package/.turbo/turbo-test.log

@@ -1,31 +1,31 @@
 
 
-> @aiready/context-analyzer@0.9.19 test /Users/pengcao/projects/aiready/packages/context-analyzer
+> @aiready/context-analyzer@0.9.22 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) 4ms
  ✓ dist/__tests__/scoring.test.js (7 tests) 2ms
- ✓ src/__tests__/scoring.test.ts (7 tests) 3ms
- ✓ src/__tests__/enhanced-cohesion.test.ts (6 tests) 2ms
- ✓ dist/__tests__/fragmentation-coupling.test.js (2 tests) 22ms
- ✓ src/__tests__/structural-cohesion.test.ts (4 tests) 5ms
- ✓ dist/__tests__/analyzer.test.js (14 tests) 280ms
- ✓ src/__tests__/fragmentation-coupling.test.ts (2 tests) 194ms
- ✓ dist/__tests__/auto-detection.test.js (8 tests) 30ms
- ✓ src/__tests__/analyzer.test.ts (14 tests) 265ms
- ✓ dist/__tests__/enhanced-cohesion.test.js (6 tests) 5ms
- ✓ src/__tests__/auto-detection.test.ts (8 tests) 48ms
+ ✓ src/__tests__/analyzer.test.ts (14 tests) 17ms
+ ✓ dist/__tests__/enhanced-cohesion.test.js (6 tests) 2ms
+ ✓ dist/__tests__/fragmentation-advanced.test.js (3 tests) 14ms
+ ✓ dist/__tests__/fragmentation-coupling.test.js (2 tests) 130ms
+ ✓ dist/__tests__/auto-detection.test.js (8 tests) 230ms
+ ✓ src/__tests__/fragmentation-coupling.test.ts (2 tests) 69ms
+ ✓ src/__tests__/fragmentation-advanced.test.ts (3 tests) 4ms
+ ✓ dist/__tests__/analyzer.test.js (14 tests) 191ms
+ ✓ src/__tests__/structural-cohesion.test.ts (4 tests) 2ms
+ ✓ src/__tests__/auto-detection.test.ts (8 tests) 30ms
+ ✓ src/__tests__/enhanced-cohesion.test.ts (6 tests) 4ms
  ✓ dist/__tests__/fragmentation-log.test.js (3 tests) 3ms
- ✓ src/__tests__/fragmentation-advanced.test.ts (3 tests) 1ms
- ✓ dist/__tests__/structural-cohesion.test.js (4 tests) 3ms
- ✓ dist/__tests__/fragmentation-advanced.test.js (3 tests) 2ms
+ ✓ dist/__tests__/structural-cohesion.test.js (4 tests) 1ms
  ✓ src/__tests__/fragmentation-log.test.ts (3 tests) 1ms
 
  Test Files  16 passed (16)
       Tests  94 passed (94)
-   Start at  00:26:59
-   Duration  4.80s (transform 7.26s, setup 0ms, import 30.96s, tests 867ms, environment 3ms)
+   Start at  00:46:20
+   Duration  2.34s (transform 4.67s, setup 0ms, import 14.26s, tests 706ms, environment 2ms)
 
 [?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
@@ -270,6 +300,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 +381,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 +397,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 +417,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 +425,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 +433,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 +441,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 +449,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 +652,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 +699,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 +742,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 +799,7 @@ Machine-readable output for CI/CD integration:
 ```
 
 ### HTML
+
 Shareable report with tables and visualizations. Perfect for stakeholders:
 
 ```bash
@@ -764,6 +816,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 +866,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

package/package.json

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