tech-debt-score 0.1.0

package/DEVELOPMENT.md

@@ -0,0 +1,147 @@
+# Development Guide
+
+## Project Structure
+
+The project follows **Hexagonal Architecture** (Ports & Adapters pattern):
+
+```
+src/
+├── domain/              # ✅ Pure business logic (COMPLETE)
+│   ├── entities/        # Score, Metric, Rule, Finding
+│   └── rules/           # ComplexityRule, SizeRule, TypeSafetyRule
+│
+├── application/         # ✅ Use cases & orchestration (COMPLETE)
+│   ├── services/        # AnalysisService
+│   ├── ports/           # Interface definitions
+│   └── config/          # AnalysisConfig
+│
+├── adapters/            # 🚧 External integrations (PARTIAL)
+│   ├── input/           # FileSystemReader (TODO: implement scan)
+│   │                    # TypeScriptParser (TODO: implement AST parsing)
+│   └── output/          # TerminalReporter, JsonExporter (COMPLETE)
+│
+├── cli/                 # ✅ Command-line interface (COMPLETE)
+│   └── commands/        # analyze command
+│
+└── shared/              # ✅ Shared types (COMPLETE)
+```
+
+## Current Status
+
+### ✅ Completed
+
+- [x] Complete hexagonal architecture setup
+- [x] Domain layer (all entities and rules)
+- [x] Application layer (services, ports, config)
+- [x] CLI entry point and analyze command
+- [x] Output adapters (Terminal and JSON reporters)
+- [x] Build system configured and working
+- [x] TypeScript strict mode enabled
+
+### 🚧 TODO - High Priority
+
+1. **Implement FileSystemReader.scan()** (Currently returns empty array)
+   - Use `fast-glob` or `glob` library
+   - Implement file pattern matching
+   - Respect ignore patterns
+
+2. **Implement TypeScriptParser.parse()** (Currently only counts LOC)
+   - Use `@typescript-eslint/parser` or TypeScript Compiler API
+   - Extract all metrics:
+     - Function length
+     - Cyclomatic complexity
+     - Nesting depth
+     - Parameter count
+     - `any` usage (TypeScript)
+     - TODO/FIXME comments
+
+3. **Add Dependencies**
+
+   ```bash
+   npm install fast-glob
+   npm install @typescript-eslint/parser @typescript-eslint/typescript-estree
+   ```
+
+4. **Write Tests**
+   - Domain layer unit tests (high priority)
+   - Application layer integration tests
+   - E2E tests with sample codebases
+
+### 📋 TODO - Medium Priority
+
+- [ ] Add more sophisticated scoring algorithm
+- [ ] Implement code duplication detection
+- [ ] Add test coverage integration
+- [ ] Create configuration file support (`.tech-debt-score.json`)
+- [ ] Add CLI flags for customization
+- [ ] Better error handling and user feedback
+
+### 🎯 TODO - Future Enhancements
+
+- [ ] Git integration for trend tracking
+- [ ] Additional output formats (HTML, Markdown)
+- [ ] VS Code extension
+- [ ] CI/CD examples (GitHub Actions, GitLab CI)
+- [ ] Multi-language support (Python, Go, Java)
+
+## Quick Commands
+
+```bash
+# Build the project
+npm run build
+
+# Run analysis (placeholder - needs implementation)
+npm run analyze
+
+# Run with specific path
+npm run dev -- ./path/to/code
+
+# Run tests (when implemented)
+npm test
+```
+
+## Architecture Guidelines
+
+### Dependency Rule
+
+Dependencies point **inward only**:
+
+```
+CLI → Application → Domain
+        ↓
+    Adapters (depend on Domain interfaces)
+```
+
+### Domain Layer Rules
+
+- ❌ NO filesystem access
+- ❌ NO CLI dependencies
+- ❌ NO Node.js APIs
+- ❌ NO external libraries (except utilities)
+- ✅ Pure TypeScript/JavaScript logic only
+- ✅ 100% unit testable
+
+### Testing Strategy
+
+1. **Domain Tests**: No mocks needed, test pure logic
+2. **Application Tests**: Use mock adapters
+3. **E2E Tests**: Test with real codebases
+
+## Next Steps
+
+1. **Implement file scanning** - Get FileSystemReader working
+2. **Implement AST parsing** - Extract real metrics from code
+3. **Test with real code** - Run against this project itself!
+4. **Write tests** - Start with domain layer
+5. **Publish to npm** - Make it available for others
+
+## Contributing
+
+When adding new features:
+
+1. Start with domain layer (pure logic)
+2. Define ports (interfaces) in application layer
+3. Implement adapters for external dependencies
+4. Wire everything together in CLI commands
+
+This ensures clean separation and testability!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 panduken
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# tech-debt-score
+
+> Quantify technical debt you can actually control.  
+> **Built by developers, for developers.**
+
+`tech-debt-score` is an open-source CLI and engine that analyzes your codebase and produces a **single, actionable Technical Debt Score**, along with a breakdown of the factors that impact it.
+
+The goal is not to find _everything that could be wrong_, but to measure **what your team can realistically improve**.
+
+---
+
+## Why tech-debt-score?
+
+Most tools focus on:
+
+- Lint errors
+- Code smells
+- Best practices
+
+But engineering teams need answers to questions like:
+
+- _How bad is our technical debt, really?_
+- _Is it getting better or worse over time?_
+- _Where should we focus first?_
+
+`tech-debt-score` provides:
+
+- A normalized **0–100 score**
+- Clear ownership (team-controllable factors)
+- CI-friendly output
+- A foundation for long-term debt tracking
+- **Designed with developers in mind: fast, minimal friction, and easy to integrate**
+
+> ⚡ **We made it by devs, for devs. Focus on your code, not the tooling.**
+
+---
+
+## What it measures (v1 scope)
+
+The first version focuses only on **signals fully controlled by the engineering team**:
+
+- Code complexity (cyclomatic, nesting)
+- File and function size
+- Code duplication
+- Test coverage (if available)
+- Type safety indicators
+- Project structure consistency
+
+> ⚠️ External factors such as deprecated dependencies, security vulnerabilities, or runtime risks are intentionally **out of scope for v1**.
+
+---
+
+## How it works (high level)
+
+1. Scan the codebase
+2. Collect raw metrics using AST parsing
+3. Normalize metrics into signals
+4. Apply weighted scoring
+5. Generate:
+   - Global score
+   - Category breakdown
+   - Human-readable report
+   - Optional JSON output
+
+---
+
+## Installation
+
+Install as a dev dependency:
+
+```bash
+npm install --save-dev tech-debt-score
+```
+
+---
+
+## Usage
+
+### Analyze current directory
+
+```bash
+npx tech-debt-score
+```
+
+### Analyze specific directory
+
+```bash
+npx tech-debt-score ./src
+```
+
+### Output Options
+
+Generate a JSON report for CI/CD integration:
+
+```bash
+npx tech-debt-score . --json report.json
+```
+
+### Development
+
+```bash
+# Build the project
+npm run build
+
+# Run analysis on current project
+npm run analyze
+
+# Run self-scan verification
+npm run scan
+```
+
+---
+
+## Project Structure
+
+This project follows **Hexagonal Architecture** (Ports & Adapters):
+
+```
+src/
+├── domain/              # Pure business logic (no dependencies)
+│   ├── entities/        # Core entities: Score, Metric, Rule, Finding
+│   └── rules/           # Scoring rules: ComplexityRule, SizeRule, etc.
+│
+├── application/         # Use cases & orchestration
+│   ├── services/        # AnalysisService
+│   ├── ports/           # Interface definitions (IFileReader, IParser, IReporter)
+│   └── config/          # Configuration
+│
+├── adapters/            # External integrations
+│   ├── input/           # FileSystemReader, TypeScriptParser
+│   └── output/          # TerminalReporter, JsonExporter
+│
+├── cli/                 # Command-line interface (entry point)
+│   └── commands/        # CLI commands
+│
+└── shared/              # Shared types and utilities
+```
+
+---
+
+## Architecture Principles
+
+- **Clean Architecture**: Domain layer has zero dependencies
+- **Dependency Inversion**: Dependencies point inward
+- **Testability**: Pure business logic, easy to unit test
+- **Extensibility**: Easy to add new parsers, rules, or output formats
+
+For detailed architecture information, see [TECHNICAL_DESIGN.md](./TECHNICAL_DESIGN.md)
+
+---
+
+## Development Status
+
+**Current Version:** 0.1.0 (Beta)
+
+### ✅ Completed
+
+- [x] Hexagonal architecture setup
+- [x] Domain layer (entities and rules)
+- [x] Application layer (services and ports)
+- [x] **Full AST parsing implementation**
+- [x] **File scanning with fast-glob**
+- [x] **Code Duplication detection**
+- [x] **Circular Dependency detection**
+- [x] CLI entry point with JSON export
+
+### 🚧 Roadmap v0.2.0
+
+- [ ] Configuration file support (`.tech-debt-score.json`)
+- [ ] Git integration for trend tracking
+- [ ] Ignore patterns configuration
+- [ ] Unit tests coverage improvement
+
+### 📋 Roadmap
+
+- [ ] Additional rules (duplication, test coverage)
+- [ ] Configuration file support
+- [ ] Enhanced CLI with options
+- [ ] Git integration for trend tracking
+- [ ] VS Code extension
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines (coming soon).
+
+---
+
+## License
+
+MIT © @panduken
+
+---
+
+## Links
+
+- **GitHub**: [github.com/panduken/tech-debt-score](https://github.com/panduken/tech-debt-score)
+- **Issues**: [Report a bug](https://github.com/panduken/tech-debt-score/issues)
+- **Technical Design**: [TECHNICAL_DESIGN.md](./TECHNICAL_DESIGN.md)

package/SETUP_COMPLETE.md

@@ -0,0 +1,188 @@
+# Project Setup Complete! 🎉
+
+## What Was Created
+
+Your **tech-debt-score** project now has a complete **Hexagonal Architecture** implementation with:
+
+### ✅ Core Structure (20 files created)
+
+#### **Domain Layer** (Pure Business Logic - Zero Dependencies)
+
+- `src/domain/entities/`
+  - `Metric.ts` - Core metric entity with builder pattern
+  - `Finding.ts` - Issue representation with builder pattern
+  - `Score.ts` - Score entity with calculator service
+  - `Rule.ts` - Rule interface and base class
+- `src/domain/rules/`
+  - `ComplexityRule.ts` - Evaluates cyclomatic complexity and nesting
+  - `SizeRule.ts` - Evaluates file/function size and parameters
+  - `TypeSafetyRule.ts` - Detects TypeScript `any` usage
+
+#### **Application Layer** (Orchestration)
+
+- `src/application/ports/` (Interfaces)
+  - `IFileReader.ts` - File system abstraction
+  - `IParser.ts` - AST parser abstraction
+  - `IReporter.ts` - Output abstraction
+
+- `src/application/services/`
+  - `AnalysisService.ts` - Main orchestration service
+
+- `src/application/config/`
+  - `AnalysisConfig.ts` - Configuration with defaults
+
+#### **Adapters Layer** (External Integrations)
+
+- `src/adapters/input/`
+  - `FileSystemReader.ts` - File I/O adapter (⚠️ scan() needs implementation)
+  - `TypeScriptParser.ts` - AST parser adapter (⚠️ needs full implementation)
+
+- `src/adapters/output/`
+  - `TerminalReporter.ts` - Beautiful console output ✅
+  - `JsonExporter.ts` - JSON report export ✅
+
+#### **CLI Layer** (Entry Point)
+
+- `src/cli/`
+  - `index.ts` - CLI entry point with help
+  - `commands/analyze.ts` - Analyze command (wires everything together)
+
+#### **Shared**
+
+- `src/shared/types.ts` - Common types
+
+### 📄 Documentation
+
+- `TECHNICAL_DESIGN.md` - Complete architecture specification
+- `README.md` - Updated with usage and structure
+- `DEVELOPMENT.md` - Development guide with TODO list
+
+### 🧪 Test Structure
+
+- `tests/domain/` - Unit tests placeholder
+- `tests/application/` - Integration tests placeholder
+- `tests/e2e/` - End-to-end tests placeholder
+
+### ⚙️ Configuration
+
+- Updated `package.json` with:
+  - `type: "module"` for ES modules
+  - Build scripts (`build`, `dev`, `analyze`)
+  - CLI bin entry point
+- `.gitignore` - Comprehensive ignore rules
+
+## Build Status
+
+✅ **Project builds successfully!**
+
+```bash
+npm run build
+```
+
+All TypeScript strict mode checks pass.
+
+## What's Next?
+
+The architecture is complete, but **two adapters need implementation** to make it functional:
+
+### 🚧 High Priority TODOs
+
+1. **FileSystemReader.scan()**
+   - Currently returns empty array
+   - Needs: `fast-glob` implementation
+2. **TypeScriptParser.parse()**
+   - Currently only counts lines
+   - Needs: Full AST parsing with `@typescript-eslint/parser`
+   - Should extract: complexity, nesting, parameters, `any` usage, comments
+
+3. **Add Required Dependencies**
+
+   ```bash
+   npm install fast-glob
+   npm install @typescript-eslint/parser @typescript-eslint/typescript-estree
+   ```
+
+4. **Write Tests**
+   - Start with domain layer (easiest - no I/O)
+   - Add integration tests
+   - Create E2E tests with sample code
+
+## Architecture Highlights
+
+### Clean Separation
+
+```
+┌─────────────────────────────────────────┐
+│           CLI (Entry Point)             │
+│         No Business Logic               │
+└─────────────────┬───────────────────────┘
+                  ↓
+┌─────────────────────────────────────────┐
+│      Application (Orchestration)        │
+│   AnalysisService coordinates everything│
+└───┬──────────────────────────────────┬──┘
+    ↓                                  ↓
+┌───────────┐                    ┌─────────────┐
+│  Adapters │                    │   Domain    │
+│  (I/O)    │                    │ (Pure Logic)│
+└───────────┘                    └─────────────┘
+```
+
+### Key Benefits
+
+✅ **100% Testable** - Domain layer has zero dependencies  
+✅ **Extensible** - Easy to add new parsers, rules, outputs  
+✅ **Type-Safe** - Full TypeScript strict mode  
+✅ **Portable** - Domain logic works anywhere (Node, Deno, Browser)  
+✅ **Maintainable** - Clear separation of concerns
+
+## Try It Out
+
+Even though the parsers aren't complete, you can still build and run:
+
+```bash
+# Build
+npm run build
+
+# See CLI help
+node dist/cli/index.js --help
+
+# Try to analyze (will show you the flow)
+node dist/cli/index.js .
+```
+
+## Files Summary
+
+```
+Created: 20 TypeScript source files
+Created: 3 test placeholder files
+Created: 4 documentation files
+Updated: package.json, README.md
+Total: 28 files
+
+Lines of Code: ~1,500+ LOC
+```
+
+## Architecture Compliance
+
+✅ **Domain Layer**: Zero external dependencies  
+✅ **Dependency Rule**: All deps point inward  
+✅ **Interface Segregation**: Clean port definitions  
+✅ **Pure Functions**: Domain logic is side-effect free
+
+## Resources Generated
+
+- [TECHNICAL_DESIGN.md](./TECHNICAL_DESIGN.md) - Full specification
+- [DEVELOPMENT.md](./DEVELOPMENT.md) - Dev guide
+- [README.md](./README.md) - User documentation
+
+---
+
+**Ready to implement the parsers and make this fully functional!** 🚀
+
+The foundation is rock-solid. Now just need to:
+
+1. Wire up file scanning
+2. Implement AST parsing
+3. Test it on real code
+4. Ship it! 📦