siko 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,16 +1,39 @@
+## [0.4.0] - 2026-02-08
+
+### Added
+- **Source map support** - Reports now show original TypeScript line numbers
+- **Glob pattern exclusions** - Use `**/*.test.ts`, `*.tsx`, `src/jsx/**` patterns
+- Prettier code formatting with CI enforcement
+- `--no-source-maps` flag to disable source map resolution
+
+### Fixed
+- JSX/TSX file exclusion now works correctly with glob patterns
+- Line number accuracy in TypeScript projects
+- Exclude patterns like `*.test.js` now properly recognized
+
+### Improved
+- CI optimized - runs only on PRs, 2x faster
+- File discovery with robust glob pattern matching
+- Developer experience for TypeScript users
+
+---
+
 ## [0.3.1] - 2026-02-07
 
 ### Fixed
+
 - Glob pattern support for exclude patterns (e.g., `**/*.test.ts`, `*.tsx`)
 - File exclusion now properly handles wildcard patterns
 - JSX/TSX files can now be excluded using glob patterns
 
 ### Added
+
 - minimatch library for robust glob pattern matching
 - Comprehensive file discovery tests (12 new tests)
 - Support for nested directory exclusions (e.g., `src/jsx/**`)
 
 ### Improved
+
 - File discovery logic with proper glob matching
 - Documentation for exclude pattern usage
 - React/JSX project compatibility via proper exclusions
@@ -20,6 +43,7 @@
 ## [0.3.0] - 2026-02-07
 
 ### Added
+
 - Comprehensive test suite with Jest (28 tests, all passing)
 - ESLint configuration with TypeScript support
 - GitHub Actions CI/CD workflows
@@ -32,18 +56,21 @@
 - API.md for detailed API documentation
 
 ### Improved
+
 - Build process with proper TypeScript compilation
 - Error handling with type narrowing
 - Code quality with linting rules
 - Documentation structure
 
 ### CI/CD
+
 - Automated tests on every push and PR
 - ESLint checks in CI
 - Multi-version Node.js testing (18.x, 20.x)
 - Build verification checks
 
 ### Testing
+
 - Runtime tracker tests
 - Babel instrumentation tests
 - Configuration loader tests
@@ -56,6 +83,7 @@
 ## [0.1.0] - 2026-02-05
 
 ### Added
+
 - Initial package setup
 - Basic placeholder CLI
 
@@ -64,7 +92,7 @@
 ## Upcoming Features
 
 ### Planned
-- Source map support for TypeScript
+
 - HTML report generation
 - Watch mode
 - Historical trend analysis

package/README.md

@@ -6,12 +6,12 @@
 [![npm version](https://badge.fury.io/js/siko.svg)](https://www.npmjs.com/package/siko)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Unlike static analysis tools that *guess* which code is unused, **siko actually runs your code** and tells you what never executed.
+Unlike static analysis tools that _guess_ which code is unused, **siko actually runs your code** and tells you what never executed.
 
 ✅ **Zero false positives** - Based on real execution data  
 ✅ **Finds runtime-only dead code** - Not just unused exports  
 ✅ **Works with any test framework** - Jest, Mocha, Vitest, etc.  
-✅ **CI/CD ready** - Enforce coverage thresholds in your pipeline  
+✅ **CI/CD ready** - Enforce coverage thresholds in your pipeline
 
 ---
 
@@ -19,31 +19,34 @@ Unlike static analysis tools that *guess* which code is unused, **siko actually
 
 ### The Problem with Static Analysis
 
-Popular tools like **Knip**, **ts-prune**, and **ESLint** use static analysis - they analyze your code *without running it*. This leads to:
+Popular tools like **Knip**, **ts-prune**, and **ESLint** use static analysis - they analyze your code _without running it_. This leads to:
 
 ❌ **False positives** - Code flagged as unused but actually runs conditionally  
 ❌ **Missed dead code** - Private functions that are never called  
-❌ **Can't handle dynamic code** - Feature flags, conditional logic, runtime imports  
+❌ **Can't handle dynamic code** - Feature flags, conditional logic, runtime imports
 
 ### siko's Runtime Approach
 
 **siko instruments your code and tracks what actually executes during your tests.**
+
 ```javascript
 // example.js
-export function apiCall() { }      // Used in prod only
-function validateInput() { }       // Used everywhere  
-function legacyHelper() { }        // NEVER called!
+export function apiCall() {} // Used in prod only
+function validateInput() {} // Used everywhere
+function legacyHelper() {} // NEVER called!
 
 // Your test
-test('api', () => {
+test("api", () => {
   apiCall(); // siko tracks this execution
 });
 ```
 
 **Static tools report:**
+
 - ❌ All three functions look "used" (or flag `apiCall` incorrectly)
 
 **siko reports:**
+
 - ✅ `legacyHelper()` never executed - **true dead code!**
 - ⚠️ `apiCall()` called 1x during tests
 - ✅ `validateInput()` called 5x during tests
@@ -52,18 +55,19 @@ test('api', () => {
 
 ## 🔍 Comparison Matrix
 
-| Feature | Knip/ts-prune | ESLint | **siko** |
-|---------|---------------|--------|----------|
-| **Analysis Type** | Static | Static | **Runtime** ✨ |
-| **Runs Your Code** | No | No | **Yes** |
-| **Finds Unused Exports** | ✅ | ✅ | ❌ |
-| **Finds Never-Executed Functions** | ❌ | ❌ | **✅** |
-| **False Positives** | Common | Common | **Rare** |
-| **Works on Private Functions** | Limited | Limited | **✅** |
-| **Detects Feature-Flagged Code** | ❌ | ❌ | **✅** |
-| **Execution Count** | ❌ | ❌ | **✅** |
+| Feature                            | Knip/ts-prune | ESLint  | **siko**       |
+| ---------------------------------- | ------------- | ------- | -------------- |
+| **Analysis Type**                  | Static        | Static  | **Runtime** ✨ |
+| **Runs Your Code**                 | No            | No      | **Yes**        |
+| **Finds Unused Exports**           | ✅            | ✅      | ❌             |
+| **Finds Never-Executed Functions** | ❌            | ❌      | **✅**         |
+| **False Positives**                | Common        | Common  | **Rare**       |
+| **Works on Private Functions**     | Limited       | Limited | **✅**         |
+| **Detects Feature-Flagged Code**   | ❌            | ❌      | **✅**         |
+| **Execution Count**                | ❌            | ❌      | **✅**         |
 
 **💡 Pro Tip**: Use **both approaches** together!
+
 - **Knip** for structural cleanup (unused files, dependencies, exports)
 - **siko** for runtime cleanup (never-executed functions)
 
@@ -72,6 +76,7 @@ test('api', () => {
 ### Static Analysis (No Execution Required)
 
 **Knip, ts-prune, ESLint**
+
 - ✅ Fast - no execution needed
 - ✅ Finds structural issues (unused exports, files)
 - ❌ Can't see runtime behavior
@@ -82,6 +87,7 @@ test('api', () => {
 ### Runtime Analysis (Execution Required)
 
 **siko**
+
 - ✅ High accuracy - based on real execution
 - ✅ Finds never-executed functions
 - ✅ No false positives
@@ -92,6 +98,7 @@ test('api', () => {
 ### Traditional Coverage Tools
 
 **Istanbul, nyc, c8**
+
 - ✅ Line/branch/statement coverage
 - ✅ Standard industry metrics
 - ❌ Focus on "% covered", not "what's unused"
@@ -101,11 +108,12 @@ test('api', () => {
 ---
 
 **The Complete Toolkit:**
+
 ```bash
 # 1. Structural cleanup
 npx knip
 
-# 2. Runtime analysis  
+# 2. Runtime analysis
 npx siko run npm test
 
 # 3. Coverage metrics
@@ -130,11 +138,13 @@ npx nyc npm test
 ## 🚀 Quick Start
 
 ### Installation
+
 ```bash
 npm install --save-dev siko
 ```
 
 ### Basic Usage
+
 ```bash
 # Run your tests with instrumentation
 npx siko run npm test
@@ -144,6 +154,7 @@ npx siko report
 ```
 
 **Example Output:**
+
 ```
 📊 siko Signal Analysis Report
 ────────────────────────────────────────────────────────────
@@ -172,9 +183,10 @@ Now you can **confidently delete** those 3 functions - they never executed durin
 ## 📖 How It Works
 
 siko uses a unique **runtime instrumentation approach**:
+
 ```
 1. Instrument    → Babel plugin injects tracking calls
-2. Execute       → Run your tests/app normally  
+2. Execute       → Run your tests/app normally
 3. Track         → Record which functions actually run
 4. Analyze       → Compare inventory vs execution
 5. Report        → Show never-executed functions
@@ -185,6 +197,7 @@ siko uses a unique **runtime instrumentation approach**:
 siko performs **runtime analysis** - it needs to execute your code to track what runs.
 
 ### You Can Run:
+
 ```bash
 # ✅ Tests (recommended - most comprehensive)
 siko run npm test
@@ -205,13 +218,15 @@ siko run ts-node src/index.ts
 ### Best Results: Comprehensive Test Suites
 
 **With good test coverage:**
+
 ```bash
 siko run npm test
-# Result: High confidence - if tests are thorough, 
+# Result: High confidence - if tests are thorough,
 #         unused functions are likely dead code
 ```
 
 **Without tests (manual app run):**
+
 ```bash
 siko run node app.js
 # Use app for 5 minutes, then stop
@@ -220,6 +235,7 @@ siko run node app.js
 ```
 
 ### 💡 Pro Tip: Run Multiple Times
+
 ```bash
 # Run tests first
 siko run npm test
@@ -234,6 +250,7 @@ siko report
 This gives you the most comprehensive view of your codebase!
 
 ### Architecture
+
 ```
 Source Code → Babel Instrumentation → Runtime Tracking → Signal Report
 ```
@@ -250,21 +267,23 @@ Unlike static analysis, siko gives you **certainty** - if a function didn't run
 ✅ **Refactoring with confidence** - Know exactly what's safe to delete  
 ✅ **Test coverage insights** - Which code paths are never tested  
 ✅ **Legacy code cleanup** - Find ancient functions that never run  
-✅ **CI/CD quality gates** - Enforce execution coverage standards  
+✅ **CI/CD quality gates** - Enforce execution coverage standards
 
 ### When to Use Static Tools Instead:
 
 Use **Knip** or **ts-prune** when you want to:
+
 - Find unused files and dependencies
 - Detect unused exports across modules
 - Quick analysis without running code
 
 ### Best Practice: Use Both! 🎯
+
 ```bash
 # 1. Static analysis - structural cleanup
 npx knip
 
-# 2. Runtime analysis - execution cleanup  
+# 2. Runtime analysis - execution cleanup
 npx siko run npm test
 npx siko report
 ```
@@ -278,6 +297,7 @@ npx siko report
 #### `siko run <command>`
 
 Instruments your code and runs a command:
+
 ```bash
 # Run tests
 npx siko run npm test
@@ -290,6 +310,7 @@ npx siko run jest --coverage
 ```
 
 **Options:**
+
 - `-v, --verbose` - Show detailed instrumentation info
 - `--no-clean` - Don't clean previous execution data
 - `-c, --config <path>` - Path to config file
@@ -297,6 +318,7 @@ npx siko run jest --coverage
 #### `siko report`
 
 Generate analysis report:
+
 ```bash
 # Terminal report (default)
 npx siko report
@@ -318,6 +340,7 @@ npx siko report --fail-on-threshold
 ```
 
 **Options:**
+
 - `-v, --verbose` - Show executed functions with call counts
 - `-a, --all` - Show all statistics
 - `-f, --format <format>` - Output format: `terminal`, `json`, or `both`
@@ -327,6 +350,7 @@ npx siko report --fail-on-threshold
 #### `siko init`
 
 Create a configuration file:
+
 ```bash
 # Create JSON config (default)
 npx siko init
@@ -338,6 +362,7 @@ npx siko init --format js
 #### `siko clean`
 
 Remove execution data files:
+
 ```bash
 npx siko clean
 ```
@@ -347,6 +372,7 @@ npx siko clean
 ## ⚙️ Configuration
 
 Create a `siko.config.json` or `siko.config.js` file:
+
 ```json
 {
   "include": ["src", "lib"],
@@ -370,18 +396,18 @@ Create a `siko.config.json` or `siko.config.js` file:
 
 ### Configuration Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `include` | `string[]` | `["src", "lib", "app"]` | Directories to instrument |
-| `exclude` | `string[]` | `["node_modules", "dist", ...]` | Patterns to exclude |
-| `extensions` | `string[]` | `[".js", ".jsx", ".ts", ".tsx"]` | File extensions to instrument |
-| `output.inventory` | `string` | `.siko-signal.inventory.json` | Static inventory output path |
-| `output.execution` | `string` | `.siko-signal.exec.json` | Execution data output path |
-| `thresholds.coverage` | `number` | `undefined` | Minimum coverage % (0-100) |
-| `thresholds.maxUnused` | `number` | `undefined` | Maximum unused functions allowed |
-| `report.format` | `string` | `"terminal"` | Default report format |
-| `report.verbose` | `boolean` | `false` | Show verbose output by default |
-| `report.showAll` | `boolean` | `false` | Show all statistics by default |
+| Option                 | Type       | Default                          | Description                      |
+| ---------------------- | ---------- | -------------------------------- | -------------------------------- |
+| `include`              | `string[]` | `["src", "lib", "app"]`          | Directories to instrument        |
+| `exclude`              | `string[]` | `["node_modules", "dist", ...]`  | Patterns to exclude              |
+| `extensions`           | `string[]` | `[".js", ".jsx", ".ts", ".tsx"]` | File extensions to instrument    |
+| `output.inventory`     | `string`   | `.siko-signal.inventory.json`    | Static inventory output path     |
+| `output.execution`     | `string`   | `.siko-signal.exec.json`         | Execution data output path       |
+| `thresholds.coverage`  | `number`   | `undefined`                      | Minimum coverage % (0-100)       |
+| `thresholds.maxUnused` | `number`   | `undefined`                      | Maximum unused functions allowed |
+| `report.format`        | `string`   | `"terminal"`                     | Default report format            |
+| `report.verbose`       | `boolean`  | `false`                          | Show verbose output by default   |
+| `report.showAll`       | `boolean`  | `false`                          | Show all statistics by default   |
 
 ---
 
@@ -390,6 +416,7 @@ Create a `siko.config.json` or `siko.config.js` file:
 Use thresholds to enforce code quality standards:
 
 **GitHub Actions Example:**
+
 ```yaml
 name: Dead Code Check
 
@@ -402,20 +429,20 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: '20'
-      
+          node-version: "20"
+
       - name: Install dependencies
         run: npm ci
-      
+
       - name: Install siko
         run: npm install -g siko
-      
+
       - name: Run tests with tracking
         run: siko run npm test
-      
+
       - name: Check execution coverage
         run: siko report --fail-on-threshold
-      
+
       - name: Upload runtime report
         if: always()
         uses: actions/upload-artifact@v3
@@ -425,6 +452,7 @@ jobs:
 ```
 
 **siko.config.json:**
+
 ```json
 {
   "thresholds": {
@@ -441,6 +469,7 @@ If thresholds are not met, the build will fail with exit code 1.
 ## 📊 Example Report
 
 ### Terminal Report
+
 ```
 📊 siko Signal Analysis Report
 ────────────────────────────────────────────────────────────
@@ -464,6 +493,7 @@ Generated by siko - Runtime Signal Analyzer
 ```
 
 ### JSON Report
+
 ```json
 {
   "summary": {
@@ -500,6 +530,7 @@ Generated by siko - Runtime Signal Analyzer
 ## 🔧 Real-World Examples
 
 ### Example 1: Feature Flag Detection
+
 ```javascript
 // src/features.js
 function newCheckout() {
@@ -511,18 +542,20 @@ function oldCheckout() {
 }
 
 // Tests only run with new feature flag
-test('checkout', () => {
+test("checkout", () => {
   newCheckout(); // Executed ✅
   // oldCheckout never called
 });
 ```
 
 **siko report shows:**
+
 ```
 ❌ Unused: oldCheckout() - Safe to delete!
 ```
 
 ### Example 2: Error Path Coverage
+
 ```javascript
 // src/api.js
 function handleSuccess(data) {
@@ -537,18 +570,20 @@ function handleError(error) {
 ```
 
 **siko report shows:**
+
 ```
 ⚠️  handleError() never executed
 💡 Add tests for error scenarios!
 ```
 
 ### Example 3: Refactoring Confidence
+
 ```javascript
 // After a big refactor, which old helpers are still needed?
-function newImplementation() { }  // ✅ Called 50x
-function oldHelper1() { }         // ❌ Never called
-function oldHelper2() { }         // ❌ Never called  
-function stillNeeded() { }        // ✅ Called 3x
+function newImplementation() {} // ✅ Called 50x
+function oldHelper1() {} // ❌ Never called
+function oldHelper2() {} // ❌ Never called
+function stillNeeded() {} // ✅ Called 3x
 ```
 
 **siko gives you confidence to delete `oldHelper1` and `oldHelper2`!**
@@ -558,6 +593,7 @@ function stillNeeded() { }        // ✅ Called 3x
 ## 🆚 When to Use siko vs Static Tools
 
 ### Use **siko** when you want to:
+
 - ✅ Find functions that **never execute** during tests
 - ✅ Get **high-confidence** dead code detection (zero false positives)
 - ✅ Discover **untested code paths** (error handlers, edge cases)
@@ -565,12 +601,14 @@ function stillNeeded() { }        // ✅ Called 3x
 - ✅ Clean up after **refactoring** (what old code is still needed?)
 
 ### Use **Knip/ts-prune** when you want to:
+
 - ✅ Find unused **files** and **dependencies**
 - ✅ Detect unused **exports** across modules
 - ✅ Quick analysis **without running** code
 - ✅ Static analysis for **build-time** optimization
 
 ### 🏆 Best Practice: Use Both!
+
 ```bash
 # 1. Structural cleanup (static)
 npx knip
@@ -581,6 +619,7 @@ npx siko report
 ```
 
 This combination gives you **complete dead code coverage**:
+
 - Knip removes structural waste
 - siko removes runtime waste
 
@@ -589,11 +628,13 @@ This combination gives you **complete dead code coverage**:
 ## 🚀 Quick Start
 
 ### Installation
+
 ```bash
 npm install --save-dev siko
 ```
 
 ### Basic Usage
+
 ```bash
 # Run your tests with instrumentation
 npx siko run npm test
@@ -618,7 +659,7 @@ A: Yes! Full support for both JavaScript and TypeScript.
 A: siko is designed for development/test environments, not production monitoring.
 
 **Q: How is this different from code coverage tools?**  
-A: Code coverage shows which *lines* ran. siko shows which *functions* never ran - perfect for finding entire unused functions.
+A: Code coverage shows which _lines_ ran. siko shows which _functions_ never ran - perfect for finding entire unused functions.
 
 **Q: Do I need to change my code?**  
 A: No! siko instruments your code automatically - no changes needed.
@@ -637,6 +678,7 @@ A: No! siko instruments your code automatically - no changes needed.
 6. **Reporting**: Shows functions that never ran
 
 ### Architecture
+
 ```
 Source Code → Babel Instrumentation → Runtime Tracking → Signal Report
                      ↓
@@ -674,6 +716,7 @@ Source Code → Babel Instrumentation → Runtime Tracking → Signal Report
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ### Development
+
 ```bash
 # Clone repository
 git clone https://github.com/sikojs/signal.git
@@ -727,6 +770,7 @@ Currently, siko has **limited support for JSX/TSX files** due to Babel transform
 **Issue**: Instrumentation can break JSX syntax in some cases, causing TypeScript compilation errors.
 
 **Workaround for React/Next.js/JSX projects:**
+
 ```json
 {
   "extensions": [".js", ".ts"],
@@ -735,6 +779,7 @@ Currently, siko has **limited support for JSX/TSX files** due to Babel transform
 ```
 
 Or exclude specific JSX directories:
+
 ```json
 {
   "exclude": ["src/components", "src/jsx"]
@@ -744,6 +789,7 @@ Or exclude specific JSX directories:
 **Status**: Full JSX/TSX support is in active development for **v0.4.0**
 
 **Current Best Use Cases** (v0.3.0):
+
 - ✅ Node.js backends and APIs
 - ✅ TypeScript libraries and packages
 - ✅ JavaScript utilities and tools
@@ -758,4 +804,4 @@ Glob patterns in `exclude` (like `*.test.js`) may require full paths. Use `exten
 
 **Made with ❤️ by [Mayukh Sinha](https://github.com/neu-msinha)**
 
-*Runtime analysis for a cleaner codebase.*
+_Runtime analysis for a cleaner codebase._