jest-test-lineage-reporter 2.0.2 → 2.1.1

package/README.md

@@ -16,6 +16,287 @@ A comprehensive test analytics platform that provides line-by-line test coverage
 - **Easy integration**: Simple Jest reporter that works alongside existing reporters
 - **TypeScript support**: Built with TypeScript support out of the box
 - **Statistics and insights**: File-level and overall statistics about test coverage patterns
+- **🆕 CLI Tool**: Powerful command-line interface for standalone operations
+
+## 🚀 CLI Usage (New!)
+
+Jest Test Lineage Reporter now includes a powerful CLI tool with automatic configuration!
+
+### Quick Start with CLI
+
+```bash
+# 1. Install the package
+npm install --save-dev jest-test-lineage-reporter jest babel-jest @babel/core @babel/preset-env
+
+# 2. Initialize configuration (creates jest.config.js and babel.config.js)
+npx jest-lineage init
+
+# 3. Run tests with lineage tracking
+npx jest-lineage test
+
+# 4. Generate HTML report
+npx jest-lineage report --open
+
+# 5. Run mutation testing
+npx jest-lineage mutate --threshold 85
+
+# 6. Query which tests cover a specific line
+npx jest-lineage query src/calculator.ts 42
+
+# 7. Full analysis workflow (test + mutate + report)
+npx jest-lineage analyze --open
+```
+
+### CLI Commands
+
+#### `jest-lineage init` ⭐ NEW
+Initialize project configuration automatically.
+
+```bash
+# Create jest.config.js and babel.config.js with all required settings
+npx jest-lineage init
+
+# Force overwrite existing config files
+npx jest-lineage init --force
+
+# Configure for TypeScript project
+npx jest-lineage init --typescript
+```
+
+**What it does:**
+- ✅ Checks for required dependencies
+- ✅ Creates `jest.config.js` with lineage reporter configured
+- ✅ Creates `babel.config.js` with instrumentation plugin
+- ✅ Detects TypeScript and configures accordingly
+- ✅ Shows clear next steps
+
+
+
+#### `jest-lineage test [jest-args...]`
+Run Jest tests with lineage tracking enabled.
+
+```bash
+# Basic usage
+jest-lineage test
+
+# Pass Jest arguments
+jest-lineage test --watch --testPathPattern=calculator
+
+# Disable specific features
+jest-lineage test --no-performance --no-quality
+```
+
+#### `jest-lineage mutate`
+Run mutation testing standalone (on existing lineage data).
+
+```bash
+# Basic mutation testing
+jest-lineage mutate
+
+# With custom threshold
+jest-lineage mutate --threshold 90
+
+# Debug mode (create mutation files without running tests)
+jest-lineage mutate --debug --debug-dir ./mutations
+```
+
+#### `jest-lineage report`
+Generate HTML report from existing lineage data.
+
+```bash
+# Generate and open report
+jest-lineage report --open
+
+# Custom output path
+jest-lineage report --output coverage-report.html
+```
+
+#### `jest-lineage query <file> [line]`
+Query which tests cover specific files or lines.
+
+```bash
+# Query entire file
+jest-lineage query src/calculator.ts
+
+# Query specific line
+jest-lineage query src/calculator.ts 42
+```
+
+#### `jest-lineage analyze`
+Full workflow: run tests, mutation testing, and generate report.
+
+```bash
+# Complete analysis
+jest-lineage analyze --open
+
+# Skip mutation testing
+jest-lineage analyze --skip-mutation --open
+
+# Use existing test data
+jest-lineage analyze --skip-tests --open
+```
+
+### CLI Options
+
+```
+Global Options:
+  -v, --version          Show version number
+  -h, --help            Show help
+
+Test Command:
+  --config <path>       Path to Jest config file
+  --no-lineage          Disable lineage tracking
+  --no-performance      Disable performance tracking
+  --no-quality          Disable quality analysis
+  --quiet, -q           Suppress console output
+
+Mutate Command:
+  --data <path>         Path to lineage data file (default: .jest-lineage-data.json)
+  --threshold <number>  Mutation score threshold (default: 80)
+  --timeout <ms>        Timeout per mutation (default: 5000)
+  --debug               Create debug mutation files
+  --debug-dir <path>    Directory for debug files (default: ./mutations-debug)
+  --verbose             Enable debug logging
+
+Report Command:
+  --data <path>         Path to lineage data file
+  --output <path>       Output HTML file path (default: test-lineage-report.html)
+  --open                Open report in browser
+  --format <type>       Report format (default: html)
+
+Query Command:
+  --data <path>         Path to lineage data file
+  --json                Output as JSON
+  --format <type>       Output format: table, list, json (default: table)
+
+Analyze Command:
+  --config <path>       Path to Jest config file
+  --threshold <number>  Mutation score threshold (default: 80)
+  --output <path>       Output HTML file path
+  --open                Open report in browser
+  --skip-tests          Skip running tests (use existing data)
+  --skip-mutation       Skip mutation testing
+```
+
+### Configuration Priority
+
+The CLI respects configuration from multiple sources with this priority:
+
+1. **CLI Arguments** (highest priority)
+2. **Environment Variables** (`JEST_LINEAGE_*`)
+3. **Config File** (jest.config.js)
+4. **package.json** (`"jest-lineage"` field)
+5. **Defaults** (lowest priority)
+
+Example package.json configuration:
+
+```json
+{
+  "jest-lineage": {
+    "mutationThreshold": 85,
+    "outputFile": "test-analytics.html",
+    "enableMutationTesting": true
+  }
+}
+```
+
+## 🤖 MCP Server (New!)
+
+Jest Test Lineage Reporter now includes a Model Context Protocol (MCP) server for programmatic access via AI assistants like Claude.
+
+### What is MCP?
+
+The Model Context Protocol allows AI assistants to interact with your test infrastructure programmatically. With the MCP server, you can ask Claude to run tests, analyze mutation scores, generate reports, and query coverage data directly.
+
+### Setting Up the MCP Server
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "jest-test-lineage-reporter": {
+      "command": "node",
+      "args": [
+        "/path/to/your/project/node_modules/jest-test-lineage-reporter/src/mcp/server.js"
+      ]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "jest-test-lineage-reporter": {
+      "command": "node",
+      "args": [
+        "$(npm root -g)/jest-test-lineage-reporter/src/mcp/server.js"
+      ]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+The MCP server exposes these tools:
+
+#### `run_tests`
+Run Jest tests with lineage tracking and generate coverage data.
+
+**Parameters:**
+- `args` (array): Jest command-line arguments
+- `enableLineage` (boolean): Enable lineage tracking (default: true)
+- `enablePerformance` (boolean): Enable performance tracking (default: true)
+- `enableQuality` (boolean): Enable quality analysis (default: true)
+
+#### `run_mutation_testing`
+Run mutation testing on existing lineage data to assess test effectiveness.
+
+**Parameters:**
+- `dataPath` (string): Path to lineage data file (default: `.jest-lineage-data.json`)
+- `threshold` (number): Minimum mutation score threshold 0-100 (default: 80)
+- `timeout` (number): Timeout per mutation in milliseconds (default: 5000)
+- `debug` (boolean): Create debug mutation files instead of running tests (default: false)
+
+#### `generate_report`
+Generate HTML report from existing lineage data.
+
+**Parameters:**
+- `dataPath` (string): Path to lineage data file (default: `.jest-lineage-data.json`)
+- `outputPath` (string): Output HTML file path (default: `test-lineage-report.html`)
+
+#### `query_coverage`
+Query which tests cover specific files or lines.
+
+**Parameters:**
+- `file` (string, required): File path to query (e.g., "src/calculator.ts")
+- `line` (number, optional): Line number to query
+- `dataPath` (string): Path to lineage data file (default: `.jest-lineage-data.json`)
+
+#### `analyze_full`
+Run full workflow: tests, mutation testing, and generate report.
+
+**Parameters:**
+- `skipTests` (boolean): Skip running tests (use existing data) (default: false)
+- `skipMutation` (boolean): Skip mutation testing (default: false)
+- `threshold` (number): Mutation score threshold (default: 80)
+- `outputPath` (string): Output HTML file path (default: `test-lineage-report.html`)
+
+### Example MCP Usage with Claude
+
+Once configured, you can ask Claude:
+
+- "Run the tests with lineage tracking"
+- "Run mutation testing with an 85% threshold"
+- "Generate an HTML report from the latest test data"
+- "Which tests cover line 42 of src/calculator.ts?"
+- "Run a full analysis and generate the report"
+
+Claude will use the MCP server to execute these operations in your project.
 
 ## 📦 Installation
 

package/bin/jest-lineage.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+/**
+ * Jest Test Lineage Reporter CLI
+ * Main entry point for command-line interface
+ */
+
+const cli = require('../src/cli');
+
+// Run CLI with error handling
+cli.run(process.argv).catch((error) => {
+  console.error('\n❌ Error:', error.message);
+
+  if (process.env.JEST_LINEAGE_DEBUG === 'true') {
+    console.error('\nStack trace:');
+    console.error(error.stack);
+  }
+
+  process.exit(1);
+});

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "jest-test-lineage-reporter",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "main": "src/TestCoverageReporter.js",
+  "bin": {
+    "jest-lineage": "./bin/jest-lineage.js"
+  },
   "scripts": {
     "test": "jest",
     "test:watch": "jest --watch",
@@ -47,16 +50,20 @@
     "npm": ">=6.0.0"
   },
   "files": [
-    "src/TestCoverageReporter.js",
-    "src/MutationTester.js",
-    "src/testSetup.js",
-    "src/babel-plugin-lineage-tracker.js",
-    "src/babel-plugin-mutation-tester.js",
-    "src/config.js",
+    "bin/",
+    "src/",
     "babel.config.js",
     "README.md",
     "LICENSE"
   ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.3",
+    "commander": "^11.0.0",
+    "open": "^8.4.0",
+    "ora": "^5.4.1"
+  },
   "devDependencies": {
     "@babel/core": "^7.23.0",
     "@babel/plugin-transform-modules-commonjs": "^7.27.1",

package/src/__tests__/assertion-test.test.ts

@@ -0,0 +1,59 @@
+import { directFunction } from '../depth-example';
+
+describe('Assertion Counting Test', () => {
+  test('should count multiple expect statements correctly', () => {
+    // This test has many expect statements to test assertion counting
+    
+    const result1 = directFunction(5);
+    expect(result1).toBe(10);
+    expect(result1).toBeGreaterThan(5);
+    expect(result1).toBeLessThan(20);
+    
+    const result2 = directFunction(0);
+    expect(result2).toBe(0);
+    expect(result2).toEqual(0);
+    expect(result2).not.toBe(1);
+    
+    const result3 = directFunction(-5);
+    expect(result3).toBe(-10);
+    expect(result3).toBeLessThan(0);
+    expect(result3).toBeGreaterThan(-20);
+    
+    // Test arrays and objects
+    const results = [result1, result2, result3];
+    expect(results).toHaveLength(3);
+    expect(results).toContain(10);
+    expect(results).toContain(0);
+    expect(results).toContain(-10);
+    
+    // Test properties
+    const obj = { value: result1 };
+    expect(obj).toHaveProperty('value');
+    expect(obj).toHaveProperty('value', 10);
+    
+    // Test null/undefined
+    expect(result1).toBeDefined();
+    expect(result1).not.toBeNull();
+    expect(result1).not.toBeUndefined();
+    
+    // Test truthiness
+    expect(result1).toBeTruthy();
+    expect(result2).toBeFalsy();
+    
+    // Test error handling
+    expect(() => {
+      if (result1 < 0) {
+        throw new Error('Should not be negative');
+      }
+    }).not.toThrow();
+    
+    // This test should show:
+    // - 22+ expect statements (high assertion count)
+    // - Error handling with expect().not.toThrow()
+    // - Property testing with toHaveProperty()
+    // - Array testing with toContain() and toHaveLength()
+    // - Boundary testing with toBeGreaterThan/toBeLessThan
+    // - Null/undefined testing
+    // - Truthiness testing
+  });
+});

package/src/__tests__/calculator.test.ts

@@ -0,0 +1,30 @@
+import { add, subtract, multiply } from '../calculator';
+
+describe('Calculator', () => {
+  it('should correctly add two numbers', () => {
+    expect(add(1, 2)).toBe(3);
+  });
+
+  it('should subtract a smaller number from a larger one', () => {
+    expect(subtract(5, 2)).toBe(3); // This will hit line 9
+  });
+
+  it('should subtract a larger number from a smaller one and return a positive result', () => {
+    expect(subtract(2, 5)).toBe(3); // This will hit line 7
+  });
+    
+  // This test covers the same line as the first subtraction test, which our report will show.
+  it('should handle zero correctly in subtraction', () => {
+    expect(subtract(10, 0)).toBe(10); // This will also hit line 9
+  });
+
+  // This test ONLY calls multiply, so it will show different coverage
+  it('should multiply two numbers correctly', () => {
+    expect(multiply(3, 4)).toBe(12); // This will ONLY hit line 13 (multiply function)
+  });
+
+  // This test ONLY calls add, so it will show different coverage
+  it('should add negative numbers', () => {
+    expect(add(-5, -3)).toBe(-8); // This will ONLY hit lines 2-3 (add function)
+  });
+});

package/src/__tests__/depth-example.test.ts

@@ -0,0 +1,237 @@
+import {
+  directFunction,
+  oneLevel,
+  twoLevels,
+  threeLevels,
+  complexFunction,
+  recursiveFunction,
+  memoryLeakFunction,
+  clearMemoryLeaks,
+  getMemoryLeakCount
+} from '../depth-example';
+
+describe('Call Depth Tracking Examples', () => {
+  test('should call directFunction directly (depth 1)', () => {
+    const result = directFunction(5);
+    expect(result).toBe(10);
+  });
+
+  test('should call directFunction through oneLevel (depth 2)', () => {
+    const result = oneLevel(5);
+    expect(result).toBe(11);
+  });
+
+  test('should call directFunction through twoLevels (depth 3)', () => {
+    const result = twoLevels(5);
+    expect(result).toBe(12);
+  });
+
+  test('should call directFunction through threeLevels (depth 4)', () => {
+    const result = threeLevels(5);
+    expect(result).toBe(13);
+  });
+
+  test('should call directFunction at multiple depths in complexFunction', () => {
+    const result = complexFunction(5);
+    expect(result).toBe(33); // 10 + 11 + 12 = 33
+  });
+
+  test('should call directFunction through recursive calls (very deep)', () => {
+    const result = recursiveFunction(5);
+    expect(result).toBe(13); // 10 + 1 + 1 + 1 = 13
+  });
+
+  test('should demonstrate memory leak detection with large allocations', () => {
+    // This test intentionally creates memory leaks to demonstrate tracking
+    const largeArrays = [];
+
+    // Create multiple large arrays (each >1MB) to trigger memory leak detection
+    for (let i = 0; i < 3; i++) {
+      // Allocate ~2MB array (will trigger 🚨LEAK alert)
+      const largeArray = new Array(500000).fill(0).map((_, index) => ({
+        id: index,
+        data: `Large data string for item ${index} with extra padding to increase memory usage`,
+        timestamp: Date.now(),
+        metadata: {
+          created: new Date(),
+          processed: false,
+          tags: ['memory', 'test', 'large', 'allocation']
+        }
+      }));
+
+      largeArrays.push(largeArray);
+
+      // Call our function to track memory usage at different call depths
+      const result = directFunction(i);
+      expect(result).toBe(i * 2);
+    }
+
+    // Verify we created the expected number of arrays
+    expect(largeArrays).toHaveLength(3);
+    expect(largeArrays[0]).toHaveLength(500000);
+
+    // Test edge cases with memory allocation
+    expect(largeArrays[0][0]).toHaveProperty('id', 0);
+    expect(largeArrays[0][0]).toHaveProperty('data');
+    expect(largeArrays[0][0].metadata).toHaveProperty('tags');
+    expect(largeArrays[0][0].metadata.tags).toContain('memory');
+
+    // Test error conditions
+    expect(() => {
+      if (largeArrays.length === 0) {
+        throw new Error('No arrays created');
+      }
+    }).not.toThrow();
+
+    // Test boundary conditions
+    expect(largeArrays[2][499999]).toHaveProperty('id', 499999);
+
+    // This should show high memory usage, multiple assertions, and good error handling
+    // Expected quality metrics:
+    // - High assertion count (8+ expect statements)
+    // - Error handling (try/catch equivalent with expect().not.toThrow())
+    // - Edge case testing (boundary values, null checks)
+    // - Memory leak detection (large allocations)
+  });
+
+  test('should demonstrate GC pressure with many small allocations', () => {
+    const smallObjects = [];
+
+    // Create many small objects to trigger GC pressure detection
+    for (let i = 0; i < 1000; i++) {
+      // Small allocations (<1KB each) to trigger 🗑️GC alert
+      const smallObj = {
+        id: i,
+        value: Math.random(),
+        processed: false
+      };
+      smallObjects.push(smallObj);
+
+      // Call function at different depths to test performance impact
+      if (i % 100 === 0) {
+        const result = oneLevel(i);
+        expect(result).toBeGreaterThan(i);
+      }
+    }
+
+    expect(smallObjects).toHaveLength(1000);
+    expect(smallObjects[999]).toHaveProperty('id', 999);
+
+    // This should show GC pressure but smaller memory footprint
+  });
+
+  test('should demonstrate slow execution patterns', () => {
+    const results = [];
+
+    // Create intentionally variable performance to trigger slow execution detection
+    for (let i = 0; i < 5; i++) {
+      const startTime = Date.now();
+
+      // Sometimes do heavy work, sometimes light work (creates performance variance)
+      if (i % 2 === 0) {
+        // Heavy work - should be slower
+        let heavyResult = 0;
+        for (let j = 0; j < 10000; j++) {
+          heavyResult += Math.sin(j) * Math.cos(j);
+        }
+        results.push(heavyResult);
+      } else {
+        // Light work - should be faster
+        results.push(i * 2);
+      }
+
+      const result = directFunction(i);
+      expect(result).toBe(i * 2);
+
+      const endTime = Date.now();
+      expect(endTime).toBeGreaterThanOrEqual(startTime);
+    }
+
+    expect(results).toHaveLength(5);
+
+    // This should show performance variance and trigger 🐌SLOW alert
+  });
+
+  test('should create actual memory leaks with large objects', () => {
+    // Clear any existing leaks first
+    const initialCount = getMemoryLeakCount();
+    expect(initialCount).toBeGreaterThanOrEqual(0);
+
+    // Create multiple memory leaks with large objects
+    for (let i = 0; i < 3; i++) {
+      // Each call creates ~1MB of leaked memory (1000 items * 1KB each)
+      const result = memoryLeakFunction(1000);
+      expect(result).toBe(1000 * 2); // directFunction returns x * 2
+
+      // Verify memory leak count is increasing
+      const currentCount = getMemoryLeakCount();
+      expect(currentCount).toBe(initialCount + i + 1);
+    }
+
+    // Verify we have created 3 memory leaks
+    const finalCount = getMemoryLeakCount();
+    expect(finalCount).toBe(initialCount + 3);
+
+    // This test should show:
+    // - High memory usage (3MB+ leaked)
+    // - 🚨LEAK alerts in console
+    // - Multiple expect() statements (good assertion count)
+    // - Error handling with expect().toBe() validations
+  });
+
+  test('should create massive memory leak for testing', () => {
+    // Create a very large memory leak to ensure detection
+    const initialMemoryCount = getMemoryLeakCount();
+
+    // Create 5 large objects (each ~2MB)
+    for (let i = 0; i < 5; i++) {
+      const result = memoryLeakFunction(2000); // 2000 items * ~1KB each = ~2MB
+      expect(result).toBe(2000 * 2);
+
+      // Verify the leak is growing
+      expect(getMemoryLeakCount()).toBeGreaterThan(initialMemoryCount + i);
+    }
+
+    // Verify total memory leaks
+    const totalLeaks = getMemoryLeakCount();
+    expect(totalLeaks).toBeGreaterThanOrEqual(initialMemoryCount + 5);
+
+    // Test edge cases
+    expect(() => memoryLeakFunction(0)).not.toThrow();
+    expect(memoryLeakFunction(0)).toBe(0);
+
+    // Test error conditions
+    expect(() => {
+      if (totalLeaks < 0) {
+        throw new Error('Invalid leak count');
+      }
+    }).not.toThrow();
+
+    // This should create ~10MB of leaked memory and trigger multiple 🚨LEAK alerts
+    // Quality metrics should show:
+    // - High assertion count (8+ expect statements)
+    // - Good error handling (expect().not.toThrow())
+    // - Edge case testing (zero values, negative checks)
+    // - Boundary testing (memory thresholds)
+  });
+
+  test('should demonstrate memory cleanup', () => {
+    // Create some leaks first
+    const result1 = memoryLeakFunction(500);
+    const result2 = memoryLeakFunction(500);
+
+    expect(result1).toBe(1000);
+    expect(result2).toBe(1000);
+    expect(getMemoryLeakCount()).toBeGreaterThanOrEqual(2);
+
+    // Clear all memory leaks
+    const clearedCount = clearMemoryLeaks();
+    expect(clearedCount).toBeGreaterThanOrEqual(2);
+    expect(getMemoryLeakCount()).toBe(0);
+
+    // Verify cleanup worked
+    expect(getMemoryLeakCount()).toBe(0);
+
+    // This test shows proper cleanup and should have fewer memory issues
+  });
+});