Code analysis tool to generate ÆtherLight sprint plans from any codebase
npm install aetherlight-analyzer@aetherlight/analyzer automates the entire process:
bash
Install globally
npm install -g @aetherlight/analyzer
Or run with npx (no install)
npx @aetherlight/analyzer --help
`
5-Minute Walkthrough:
`bash
1. Initialize ÆtherLight workspace
npx @aetherlight/analyzer init ./target-codebase
2. Analyze codebase
cd target-codebase
npx @aetherlight/analyzer analyze
3. Generate sprint plans
npx @aetherlight/analyzer generate-sprints
4. Execute sprints (dry-run)
npx @aetherlight/analyzer execute-sprint A --dry-run
5. Generate reports
npx @aetherlight/analyzer report --format html
`
Result: You now have:
- ✅ .aetherlight/analysis.json - Complete codebase analysis
- ✅ PHASE_A_ENHANCEMENT.md - Sprint plan for new features
- ✅ PHASE_B_RETROFIT.md - Sprint plan for refactoring legacy code
- ✅ PHASE_C_DOGFOOD.md - Sprint plan for integration testing
---
📚 Commands
$3
Initialize .aetherlight/ workspace in target directory.
`bash
npx @aetherlight/analyzer init ./my-project
Creates:
my-project/.aetherlight/
├── config.json # Analysis configuration
├── README.md # Next steps guide
└── analysis/ # Directory for analysis results
`
Options: None (uses sensible defaults)
---
$3
Parse and analyze codebase (TypeScript/JavaScript).
`bash
npx @aetherlight/analyzer analyze
Options:
--languages # Languages to parse (default: "ts,js")
--output # Output file (default: ".aetherlight/analysis.json")
--verbose # Show detailed progress
`
Example:
`bash
Analyze only TypeScript files
npx @aetherlight/analyzer analyze --languages ts --verbose
Output:
🔍 Analyzing codebase
✅ Parsed 47 files (12,345 LOC) in 1,234ms
✅ Architecture: Clean Architecture (confidence: 87%)
✅ Complexity: avg 4.2, 3 functions need refactoring
✅ Technical Debt: score 28/100, 12 issues
✅ Results saved to .aetherlight/analysis.json
`
Analysis includes:
- Architecture Pattern: MVC, Clean, Layered, Modular, Microservices, or Monolithic
- Complexity Analysis: Cyclomatic complexity per function, average complexity
- Technical Debt: TODOs, FIXMEs, console.log, duplicated code, long functions
- Dependency Graph: Import/export relationships
---
$3
Generate Phase A/B/C sprint plans from analysis results.
`bash
npx @aetherlight/analyzer generate-sprints
Options:
--input # Analysis results file (default: ".aetherlight/analysis.json")
--output # Output directory (default: "./")
--min-tasks # Minimum tasks per sprint (default: 5)
--max-tasks # Maximum tasks per sprint (default: 15)
`
Example:
`bash
npx @aetherlight/analyzer generate-sprints
Output:
📋 Generating sprint plans
✅ Analysis loaded
✅ All sprint plans generated
#
📂 Generated files:
✓ PHASE_A_ENHANCEMENT.md (12 tasks, 4 weeks)
✓ PHASE_B_RETROFIT.md (8 tasks, 3 weeks)
✓ PHASE_C_DOGFOOD.md (5 tasks, 2 weeks)
`
Sprint Phases:
- Phase A (Enhancement): Add new features with Chain of Thought documentation
- Phase B (Retrofit): Refactor legacy code, reduce technical debt
- Phase C (Dogfood): Integrate ÆtherLight patterns, enable autonomous sprints
---
$3
Execute sprint autonomously (requires Phase 4 orchestrator).
`bash
npx @aetherlight/analyzer execute-sprint A --dry-run
Options:
--dry-run # Preview execution without running tasks
`
Example:
`bash
npx @aetherlight/analyzer execute-sprint A --dry-run
Output:
🚀 Executing Sprint Phase A
✅ Loaded PHASE_A_ENHANCEMENT.md
✅ Found 12 tasks
#
📋 Dry Run - Tasks to Execute:
1. Implement TypeScript parser (Estimated: 4h)
2. Add complexity analyzer (Estimated: 3h)
3. Create sprint generator (Estimated: 5h)
...
⚠️ Dry run complete. No changes made.
`
Status: Phase 4 orchestrator not yet implemented. This command previews execution order and validates sprint plans.
---
$3
Generate summary report from analysis results.
`bash
npx @aetherlight/analyzer report --format html
Options:
--input # Analysis results file (default: ".aetherlight/analysis.json")
--output # Output report file (default: "ANALYSIS_REPORT.md")
--format # Report format: md, html, json (default: "md")
`
Example:
`bash
npx @aetherlight/analyzer report --format html --output report.html
Output:
📊 Generating analysis report
✅ Analysis loaded
✅ Report generated: report.html
`
Report includes:
- Executive Summary: Files analyzed, LOC, architecture pattern, complexity, debt score
- Architecture Analysis: Pattern detected, confidence score, key components
- Complexity Analysis: Average complexity, high-complexity functions
- Technical Debt Analysis: Debt score, issues by category
- Recommendations: Actionable improvements
---
🏗️ Architecture
`
@aetherlight/analyzer/
├── src/
│ ├── cli/ # CLI commands ✅
│ │ ├── index.ts # Commander.js entry point (141 lines)
│ │ └── commands/
│ │ ├── init.ts # Initialize workspace (153 lines)
│ │ ├── analyze.ts # Run analysis (180 lines)
│ │ ├── generate.ts # Generate sprints (71 lines)
│ │ ├── execute.ts # Execute sprint (161 lines)
│ │ └── report.ts # Generate reports (318 lines)
│ │
│ ├── parsers/ # Week 1: Analysis Engine ✅
│ │ ├── types.ts # Shared types (150 lines)
│ │ ├── typescript-parser.ts # TypeScript/JS parser (387 lines)
│ │ └── index.ts # Barrel exports
│ │
│ ├── analyzers/ # Week 1: Analysis Engine ✅
│ │ ├── types.ts # Analyzer types (120 lines)
│ │ ├── architecture-analyzer.ts # Detect MVC/Clean/etc (280 lines)
│ │ ├── complexity-analyzer.ts # Cyclomatic complexity (220 lines)
│ │ ├── technical-debt-analyzer.ts # TODOs, FIXMEs, etc (310 lines)
│ │ └── index.ts # Barrel exports
│ │
│ ├── generators/ # Week 2: Sprint Generation ✅
│ │ ├── types.ts # Generator types (180 lines)
│ │ ├── sprint-generator.ts # Generate Phase A/B/C (450 lines)
│ │ ├── pattern-extractor.ts # Extract patterns (320 lines)
│ │ ├── cot-documenter.ts # Chain of Thought docs (280 lines)
│ │ └── index.ts # Barrel exports
│ │
│ ├── executors/ # Week 3: Sprint Execution ✅
│ │ ├── sprint-executor.ts # Wave-based execution (598 lines)
│ │ └── sprint-executor.test.ts # 25 tests, 577 lines
│ │
│ └── index.ts # Main entry point
│
├── dist/ # Compiled TypeScript output
├── templates/ # Handlebars templates (future)
├── package.json # npm package configuration
├── tsconfig.json # TypeScript configuration
└── README.md # This file
`
Total: ~4,800 lines of production code + ~1,200 lines of tests
---
📊 Performance Targets
| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| TypeScript parsing | <5s for 50k LOC | ~10k LOC/s | ✅ |
| Complexity analysis | <2s for 100 files | <1s | ✅ |
| Architecture detection | <1s | <500ms | ✅ |
| Sprint generation | <5s | <2s | ✅ |
| CLI startup time | <500ms | ~200ms | ✅ |
| Memory usage | <100MB | <50MB | ✅ |
---
🧪 Testing
`bash
Run all tests
npm test
Run with coverage
npm test -- --coverage
Run specific test suite
npm test -- sprint-executor.test.ts
`
Test Coverage:
- Parsers: >80% coverage (13+ tests)
- Analyzers: >80% coverage (15+ tests)
- Generators: >75% coverage (10+ tests)
- Executors: >90% coverage (25 tests)
Total: 63+ test cases, all passing ✅
---
💡 Chain of Thought Documentation
All code follows ÆtherLight's Chain of Thought standard:
`typescript
/**
* DESIGN DECISION: Use ts-morph for TypeScript AST parsing
* WHY: Official TypeScript compiler API, type-safe, comprehensive AST access
*
* REASONING CHAIN:
* 1. Evaluated alternatives: @babel/parser, acorn, esprima
* 2. Babel parser: Fast but less type information
* 3. Acorn: Lightweight but JavaScript-only
* 4. ts-morph: Full TypeScript support, type checking, refactoring APIs
* 5. Result: ts-morph chosen for type safety and completeness
*
* PATTERN: Pattern-ANALYZER-001 (AST-Based Code Analysis)
* PERFORMANCE: <5s for 50k LOC (target met)
*/
export class TypeScriptParser {
// Implementation...
}
`
Why this matters:
- AI assistants understand WHY decisions were made
- Human developers learn the reasoning behind code
- Enables meta-learning (pattern extraction from decisions)
---
🎯 Use Cases
$3
`bash
Analyze unknown codebase
npx @aetherlight/analyzer init ./legacy-app
cd legacy-app
npx @aetherlight/analyzer analyze --verbose
Generate refactoring plan
npx @aetherlight/analyzer generate-sprints
Review PHASE_B_RETROFIT.md for step-by-step refactoring
`
$3
`bash
Analyze candidate's portfolio
npx @aetherlight/analyzer analyze --languages ts,js
npx @aetherlight/analyzer report --format html
Review report.html for:
- Architecture quality
- Code complexity
- Technical debt level
`
$3
`bash
Run weekly analysis in CI/CD
npx @aetherlight/analyzer analyze
npx @aetherlight/analyzer report --format json > metrics.json
Track complexity and debt over time
`
$3
`bash
Generate architecture documentation
npx @aetherlight/analyzer analyze
npx @aetherlight/analyzer report --format md
New developer reads ANALYSIS_REPORT.md to understand codebase
`
---
🚀 Roadmap
$3
- [x] A-001: TypeScript AST Parser (387 lines, 10+ tests)
- [x] A-002: Rust AST Parser (SKIPPED - not needed for Phase 0)
- [x] A-003: Architecture Analyzer (280 lines, pattern detection)
- [x] A-004: Complexity Analyzer (220 lines, cyclomatic complexity)
- [x] A-005: Technical Debt Analyzer (310 lines, 8 debt categories)
$3
- [x] B-001: Sprint Plan Generator (450 lines, Phase A/B/C)
- [x] B-002: Pattern Extractor (320 lines, extract reusable patterns)
- [x] B-003: Chain of Thought Documenter (280 lines, CoT templates)
$3
- [x] C-001: CLI Interface (883 lines, 5 commands)
- [x] C-002: Sprint Executor (598 lines, wave-based execution, 25 tests)
- [x] C-003: Package & Publish (README, LICENSE, npm ready)
$3
- [ ] Multi-agent orchestration (database, UI, API, infrastructure agents)
- [ ] Human approval gates (strategic oversight)
- [ ] Real-time progress tracking
- [ ] Automated git commits with Chain of Thought
---
📝 Examples
$3
`bash
$ npx @aetherlight/analyzer init
$ npx @aetherlight/analyzer analyze
🔍 Analyzing codebase
✅ Parsed 47 files (12,345 LOC) in 1,234ms
✅ Architecture: Clean Architecture (confidence: 87%)
✅ Complexity: avg 4.2, 3 functions need refactoring
✅ Technical Debt: score 28/100, 12 issues
✅ Results saved to .aetherlight/analysis.json
📊 Analysis Summary:
Files analyzed: 47
Lines of code: 12,345
Architecture: Clean Architecture
Avg complexity: 4.2
Debt score: 28/100
📝 Next step:
Generate sprints: npx @aetherlight/analyzer generate-sprints
`
$3
`bash
$ npx @aetherlight/analyzer generate-sprints
📋 Generating sprint plans
✅ Analysis loaded
✅ All sprint plans generated
📂 Generated files:
✓ PHASE_A_ENHANCEMENT.md (12 tasks, 4 weeks)
✓ PHASE_B_RETROFIT.md (8 tasks, 3 weeks)
✓ PHASE_C_DOGFOOD.md (5 tasks, 2 weeks)
📝 Next steps:
1. Review sprint plans
2. Execute: npx @aetherlight/analyzer execute-sprint A
`
$3
`bash
$ npx @aetherlight/analyzer report --format html --output report.html
📊 Generating analysis report
✅ Analysis loaded
✅ Report generated: report.html
📂 Open report.html in browser to view detailed analysis
`
---
🔧 Configuration
Configuration is stored in .aetherlight/config.json:
`json
{
"project": {
"name": "my-project",
"rootDir": "./",
"exclude": ["node_modules", "dist", "build"]
},
"analysis": {
"languages": ["typescript", "javascript"],
"includeTests": false,
"minComplexity": 10,
"debtThreshold": 50
},
"sprints": {
"minTasksPerSprint": 5,
"maxTasksPerSprint": 15,
"estimatedStartDate": "2025-10-14"
}
}
`
Auto-generated by init command. Edit as needed.
---
🤝 Contributing
This is Phase 0 of the ÆtherLight project. Contributions welcome!
How to contribute:
1. Fork the repository
2. Create feature branch: git checkout -b feature/my-feature`