jest-test-lineage-reporter 2.0.1 → 2.1.0

package/src/cli/commands/report.js

@@ -0,0 +1,65 @@
+/**
+ * Report Command
+ * Generate HTML report from existing lineage data
+ */
+
+const TestCoverageReporter = require('../../TestCoverageReporter');
+const { loadLineageData, processLineageDataForMutation } = require('../utils/data-loader');
+const { loadFullConfig } = require('../utils/config-loader');
+const { spinner, success, error, info } = require('../utils/output-formatter');
+const open = require('open');
+const chalk = require('chalk');
+const path = require('path');
+
+async function reportCommand(options) {
+  try {
+    // Load configuration
+    const config = loadFullConfig(options);
+
+    // Load lineage data
+    info(`Loading lineage data from: ${chalk.yellow(options.data)}`);
+    const rawData = loadLineageData(options.data);
+
+    const testCount = rawData.tests.length;
+    info(`Loaded ${chalk.cyan(testCount)} tests`);
+
+    // Process lineage data
+    const lineageData = processLineageDataForMutation(rawData);
+
+    // Create reporter instance with minimal config
+    const reporter = new TestCoverageReporter(
+      { rootDir: process.cwd() },
+      { outputFile: options.output, ...config }
+    );
+
+    // Load data into reporter
+    reporter.processLineageResults(lineageData, 'unknown');
+
+    // Generate HTML report
+    const spin = spinner('Generating HTML report...');
+    spin.start();
+
+    await reporter.generateHtmlReport();
+
+    spin.succeed('HTML report generated!');
+
+    const reportPath = path.resolve(process.cwd(), options.output);
+    success(`Report saved to: ${chalk.cyan(reportPath)}`);
+
+    // Open in browser if requested
+    if (options.open) {
+      info('Opening report in browser...');
+      await open(reportPath);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    error(`Failed to generate report: ${err.message}`);
+    if (process.env.JEST_LINEAGE_DEBUG === 'true') {
+      console.error(err.stack);
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = reportCommand;

package/src/cli/commands/test.js

@@ -0,0 +1,56 @@
+/**
+ * Test Command
+ * Run Jest tests with lineage tracking
+ */
+
+const { runJest } = require('../utils/jest-runner');
+const { loadFullConfig } = require('../utils/config-loader');
+const { lineageDataExists } = require('../utils/data-loader');
+const { success, error, info } = require('../utils/output-formatter');
+const fs = require('fs');
+const path = require('path');
+
+async function testCommand(jestArgs, options) {
+  try {
+    // Load configuration
+    const config = loadFullConfig(options);
+
+    // Run Jest with lineage tracking
+    const result = await runJest({
+      args: jestArgs || [],
+      config: options.config,
+      enableLineage: options.lineage !== false,
+      enablePerformance: options.performance !== false,
+      enableQuality: options.quality !== false,
+      quiet: options.quiet
+    });
+
+    // Check if lineage data was generated
+    const dataPath = path.join(process.cwd(), '.jest-lineage-data.json');
+    if (result.success && fs.existsSync(dataPath)) {
+      const data = JSON.parse(fs.readFileSync(dataPath, 'utf8'));
+      const testCount = data.tests ? data.tests.length : 0;
+      const fileCount = data.tests
+        ? new Set(data.tests.flatMap(t =>
+            Object.keys(t.coverage || {}).map(k => k.split(':')[0])
+          )).size
+        : 0;
+
+      if (!options.quiet) {
+        info(`Lineage data saved to: ${dataPath}`);
+        console.log(`   - ${testCount} tests tracked`);
+        console.log(`   - ${fileCount} files analyzed\n`);
+      }
+    } else if (!result.success) {
+      error('Tests failed. Lineage data may be incomplete.');
+    }
+
+    // Exit with Jest's exit code
+    process.exit(result.exitCode);
+  } catch (err) {
+    error(`Failed to run tests: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = testCommand;

package/src/cli/index.js

@@ -0,0 +1,89 @@
+/**
+ * CLI Command Router
+ * Main CLI logic with commander.js
+ */
+
+const { Command } = require('commander');
+const testCommand = require('./commands/test');
+const mutateCommand = require('./commands/mutate');
+const reportCommand = require('./commands/report');
+const queryCommand = require('./commands/query');
+const analyzeCommand = require('./commands/analyze');
+const pkg = require('../../package.json');
+
+async function run(argv) {
+  const program = new Command();
+
+  program
+    .name('jest-lineage')
+    .description('Comprehensive test analytics with lineage tracking and mutation testing')
+    .version(pkg.version, '-v, --version', 'Display version number');
+
+  // Test command - Run Jest with lineage tracking
+  program
+    .command('test [jest-args...]')
+    .description('Run Jest tests with lineage tracking enabled')
+    .option('--no-lineage', 'Disable lineage tracking')
+    .option('--no-performance', 'Disable performance tracking')
+    .option('--no-quality', 'Disable quality analysis')
+    .option('--config <path>', 'Path to Jest config file')
+    .option('--quiet, -q', 'Suppress console output')
+    .action(testCommand);
+
+  // Mutate command - Run mutation testing standalone
+  program
+    .command('mutate')
+    .description('Run mutation testing on existing lineage data')
+    .option('--data <path>', 'Path to lineage data file', '.jest-lineage-data.json')
+    .option('--threshold <number>', 'Mutation score threshold (%)', '80')
+    .option('--timeout <ms>', 'Timeout per mutation (ms)', '5000')
+    .option('--debug', 'Create debug mutation files instead of running tests')
+    .option('--debug-dir <path>', 'Directory for debug files', './mutations-debug')
+    .option('--operators <list>', 'Comma-separated mutation operators to enable')
+    .option('--verbose', 'Enable debug logging')
+    .action(mutateCommand);
+
+  // Report command - Generate HTML report
+  program
+    .command('report')
+    .description('Generate HTML report from existing lineage data')
+    .option('--data <path>', 'Path to lineage data file', '.jest-lineage-data.json')
+    .option('--output <path>', 'Output HTML file path', 'test-lineage-report.html')
+    .option('--open', 'Open report in browser after generation')
+    .option('--format <type>', 'Report format (html, json)', 'html')
+    .action(reportCommand);
+
+  // Query command - Query test coverage
+  program
+    .command('query <file> [line]')
+    .description('Query which tests cover specific files or lines')
+    .option('--data <path>', 'Path to lineage data file', '.jest-lineage-data.json')
+    .option('--json', 'Output as JSON')
+    .option('--format <type>', 'Output format (table, list, json)', 'table')
+    .action(queryCommand);
+
+  // Analyze command - Full workflow
+  program
+    .command('analyze')
+    .description('Full workflow: test + mutation + report')
+    .option('--config <path>', 'Path to Jest config file')
+    .option('--threshold <number>', 'Mutation score threshold (%)', '80')
+    .option('--output <path>', 'Output HTML file path', 'test-lineage-report.html')
+    .option('--open', 'Open report in browser')
+    .option('--skip-tests', 'Skip running tests (use existing data)')
+    .option('--skip-mutation', 'Skip mutation testing')
+    .option('--no-lineage', 'Disable lineage tracking')
+    .option('--no-performance', 'Disable performance tracking')
+    .option('--no-quality', 'Disable quality analysis')
+    .action(analyzeCommand);
+
+  // Show help if no command provided
+  if (argv.length <= 2) {
+    program.help();
+  }
+
+  // Parse and execute
+  await program.parseAsync(argv);
+}
+
+module.exports = { run };

package/src/cli/utils/config-loader.js

@@ -0,0 +1,114 @@
+/**
+ * Configuration Loader
+ * Load and merge configuration from multiple sources
+ * Priority: CLI args > env vars > config file > package.json > defaults
+ */
+
+const { loadConfig } = require('../../config');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Load full configuration with proper priority
+ * @param {object} cliOptions - Options from CLI arguments
+ * @returns {object} Merged configuration
+ */
+function loadFullConfig(cliOptions = {}) {
+  // Start with defaults from config.js (includes env var processing)
+  let config = loadConfig();
+
+  // Load from package.json if available
+  const pkgConfig = loadPackageJsonConfig();
+  if (pkgConfig) {
+    config = { ...config, ...pkgConfig };
+  }
+
+  // Override with CLI options (highest priority)
+  const cliConfig = mapCliOptionsToConfig(cliOptions);
+  config = { ...config, ...cliConfig };
+
+  return config;
+}
+
+/**
+ * Map CLI options to config object
+ * @param {object} cliOptions - CLI options
+ * @returns {object} Config object
+ */
+function mapCliOptionsToConfig(cliOptions) {
+  const config = {};
+
+  // Feature toggles
+  if (cliOptions.lineage === false) config.enableLineageTracking = false;
+  if (cliOptions.performance === false) config.enablePerformanceTracking = false;
+  if (cliOptions.quality === false) config.enableQualityAnalysis = false;
+
+  // Mutation testing settings
+  if (cliOptions.threshold !== undefined) {
+    config.mutationThreshold = parseInt(cliOptions.threshold);
+  }
+  if (cliOptions.timeout !== undefined) {
+    config.mutationTimeout = parseInt(cliOptions.timeout);
+  }
+  if (cliOptions.debug === true) {
+    config.debugMutations = true;
+  }
+  if (cliOptions.debugDir !== undefined) {
+    config.debugMutationDir = cliOptions.debugDir;
+  }
+  if (cliOptions.operators !== undefined) {
+    // Parse comma-separated operators
+    const operators = cliOptions.operators.split(',').map(o => o.trim());
+    config.mutationOperators = {
+      arithmetic: operators.includes('arithmetic'),
+      comparison: operators.includes('comparison'),
+      logical: operators.includes('logical'),
+      conditional: operators.includes('conditional'),
+      assignment: operators.includes('assignment'),
+      literals: operators.includes('literals'),
+      returns: operators.includes('returns'),
+      increments: operators.includes('increments')
+    };
+  }
+
+  // Output settings
+  if (cliOptions.output !== undefined) {
+    config.outputFile = cliOptions.output;
+  }
+  if (cliOptions.verbose === true) {
+    config.enableDebugLogging = true;
+  }
+  if (cliOptions.quiet === true) {
+    config.enableConsoleOutput = false;
+  }
+
+  // Skip options
+  if (cliOptions.skipMutation === true) {
+    config.enableMutationTesting = false;
+  }
+
+  return config;
+}
+
+/**
+ * Load config from package.json "jest-lineage" field
+ * @returns {object|null} Config from package.json or null
+ */
+function loadPackageJsonConfig() {
+  try {
+    const pkgPath = path.join(process.cwd(), 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      return pkg['jest-lineage'] || null;
+    }
+  } catch (error) {
+    // Silently ignore errors
+  }
+  return null;
+}
+
+module.exports = {
+  loadFullConfig,
+  mapCliOptionsToConfig,
+  loadPackageJsonConfig
+};

package/src/cli/utils/data-loader.js

@@ -0,0 +1,118 @@
+/**
+ * Lineage Data Loader
+ * Load and validate .jest-lineage-data.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Load lineage data from file
+ * @param {string} dataPath - Path to lineage data file
+ * @returns {object} Parsed lineage data
+ */
+function loadLineageData(dataPath = '.jest-lineage-data.json') {
+  const resolvedPath = path.resolve(process.cwd(), dataPath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(
+      `Lineage data file not found: ${chalk.yellow(resolvedPath)}\n\n` +
+      `${chalk.cyan('Hint:')} Run ${chalk.green('jest-lineage test')} first to generate lineage data.`
+    );
+  }
+
+  try {
+    const content = fs.readFileSync(resolvedPath, 'utf8');
+    const data = JSON.parse(content);
+
+    // Validate structure
+    if (!data.timestamp || !Array.isArray(data.tests)) {
+      throw new Error(
+        `Invalid lineage data format in ${chalk.yellow(resolvedPath)}\n\n` +
+        `Expected format: { timestamp: number, tests: array }`
+      );
+    }
+
+    if (data.tests.length === 0) {
+      throw new Error(
+        `No test data found in ${chalk.yellow(resolvedPath)}\n\n` +
+        `The file exists but contains no test results. Run ${chalk.green('jest-lineage test')} to generate data.`
+      );
+    }
+
+    return data;
+  } catch (error) {
+    if (error.name === 'SyntaxError') {
+      throw new Error(
+        `Failed to parse lineage data file: ${chalk.yellow(resolvedPath)}\n\n` +
+        `The file contains invalid JSON. Error: ${error.message}`
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Process raw lineage data into format needed by MutationTester
+ * @param {object} rawData - Raw data from .jest-lineage-data.json
+ * @returns {object} Processed lineage data { filePath: { lineNumber: [testInfo, ...] } }
+ */
+function processLineageDataForMutation(rawData) {
+  const processed = {};
+
+  if (!rawData.tests) {
+    return processed;
+  }
+
+  rawData.tests.forEach((test) => {
+    if (!test.coverage) {
+      return;
+    }
+
+    const coverageKeys = Object.keys(test.coverage);
+
+    coverageKeys.forEach((lineKey) => {
+      // Parse line key: "file.ts:lineNumber"
+      const [filePath, lineNumber, ...suffixes] = lineKey.split(':');
+
+      // Skip metadata entries (depth, performance, meta) - only process basic line coverage
+      if (!lineNumber || suffixes.length > 0) {
+        return;
+      }
+
+      if (!processed[filePath]) {
+        processed[filePath] = {};
+      }
+
+      if (!processed[filePath][lineNumber]) {
+        processed[filePath][lineNumber] = [];
+      }
+
+      processed[filePath][lineNumber].push({
+        testName: test.name,
+        testType: test.type || 'it',
+        testFile: test.testFile || 'unknown',
+        executionCount: test.coverage[lineKey] || 1
+      });
+    });
+  });
+
+  return processed;
+}
+
+/**
+ * Check if lineage data file exists
+ * @param {string} dataPath - Path to check
+ * @returns {boolean} True if file exists
+ */
+function lineageDataExists(dataPath = '.jest-lineage-data.json') {
+  const resolvedPath = path.resolve(process.cwd(), dataPath);
+  return fs.existsSync(resolvedPath);
+}
+
+module.exports = {
+  loadLineageData,
+  processLineageDataForMutation,
+  lineageDataExists
+};

package/src/cli/utils/jest-runner.js

@@ -0,0 +1,105 @@
+/**
+ * Jest Runner
+ * Orchestrate Jest execution with proper environment variables
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Run Jest with lineage tracking enabled
+ * @param {object} options - Jest run options
+ * @returns {Promise<object>} Result object with success status and exit code
+ */
+async function runJest(options = {}) {
+  const {
+    args = [],                     // Jest arguments
+    config = null,                 // Path to Jest config
+    enableLineage = true,          // Enable lineage tracking
+    enablePerformance = true,      // Enable performance tracking
+    enableQuality = true,          // Enable quality analysis
+    enableMutation = false,        // Enable mutation mode
+    cwd = process.cwd(),           // Working directory
+    stdio = 'inherit',             // Stdio handling
+    quiet = false                  // Suppress output
+  } = options;
+
+  // Build Jest command
+  const jestPath = 'jest'; // Use npx/global jest
+  const jestArgs = [...args];
+
+  // Add config if specified
+  if (config) {
+    jestArgs.push('--config', config);
+  }
+
+  // Ensure coverage is collected (required for lineage tracking)
+  if (!jestArgs.includes('--coverage') && !jestArgs.includes('--no-coverage')) {
+    jestArgs.push('--coverage');
+  }
+
+  // Set environment variables for lineage tracking
+  const env = {
+    ...process.env,
+    JEST_LINEAGE_ENABLED: enableLineage ? 'true' : 'false',
+    JEST_LINEAGE_TRACKING: enableLineage ? 'true' : 'false',
+    JEST_LINEAGE_PERFORMANCE: enablePerformance ? 'true' : 'false',
+    JEST_LINEAGE_QUALITY: enableQuality ? 'true' : 'false',
+    JEST_LINEAGE_MUTATION: enableMutation ? 'true' : 'false',
+    JEST_LINEAGE_MUTATION_TESTING: 'false', // Not in mutation testing mode
+  };
+
+  if (!quiet) {
+    console.log(chalk.cyan('\n🧪 Running Jest with lineage tracking...\n'));
+    console.log(chalk.gray(`Command: ${jestPath} ${jestArgs.join(' ')}\n`));
+  }
+
+  return new Promise((resolve, reject) => {
+    const jest = spawn(jestPath, jestArgs, {
+      cwd,
+      env,
+      stdio,
+      shell: true
+    });
+
+    jest.on('close', (code) => {
+      if (code === 0) {
+        if (!quiet) {
+          console.log(chalk.green('\n✅ Tests completed successfully'));
+        }
+        resolve({ success: true, exitCode: code });
+      } else {
+        if (!quiet) {
+          console.log(chalk.red(`\n❌ Tests failed with exit code ${code}`));
+        }
+        resolve({ success: false, exitCode: code });
+      }
+    });
+
+    jest.on('error', (error) => {
+      console.error(chalk.red('\n❌ Failed to run Jest:'), error.message);
+      console.error(chalk.yellow('\nMake sure Jest is installed:'));
+      console.error(chalk.gray('  npm install --save-dev jest\n'));
+      reject(error);
+    });
+  });
+}
+
+/**
+ * Validate that Jest is available
+ * @returns {boolean} True if Jest is available
+ */
+function isJestAvailable() {
+  try {
+    require.resolve('jest');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  runJest,
+  isJestAvailable
+};

package/src/cli/utils/output-formatter.js

@@ -0,0 +1,126 @@
+/**
+ * Output Formatter
+ * Format console output with colors and formatting
+ */
+
+const chalk = require('chalk');
+const ora = require('ora');
+
+/**
+ * Print success message
+ * @param {string} message - Success message
+ */
+function success(message) {
+  console.log(chalk.green(`✅ ${message}`));
+}
+
+/**
+ * Print error message
+ * @param {string} message - Error message
+ */
+function error(message) {
+  console.error(chalk.red(`❌ ${message}`));
+}
+
+/**
+ * Print warning message
+ * @param {string} message - Warning message
+ */
+function warning(message) {
+  console.log(chalk.yellow(`⚠️  ${message}`));
+}
+
+/**
+ * Print info message
+ * @param {string} message - Info message
+ */
+function info(message) {
+  console.log(chalk.cyan(`ℹ️  ${message}`));
+}
+
+/**
+ * Print section header
+ * @param {string} title - Section title
+ */
+function section(title) {
+  console.log(chalk.bold.cyan(`\n${title}`));
+  console.log(chalk.gray('═'.repeat(title.length + 2)));
+}
+
+/**
+ * Create a spinner for long operations
+ * @param {string} text - Spinner text
+ * @returns {object} Ora spinner instance
+ */
+function spinner(text) {
+  return ora({
+    text,
+    color: 'cyan',
+    spinner: 'dots'
+  });
+}
+
+/**
+ * Print mutation results summary
+ * @param {object} results - Mutation test results
+ */
+function printMutationSummary(results) {
+  section('🧬 Mutation Testing Results');
+
+  console.log(`📊 ${chalk.bold('Total Mutations:')} ${results.totalMutations}`);
+  console.log(`${chalk.green('✅ Killed:')} ${results.killedMutations}`);
+  console.log(`${chalk.red('🔴 Survived:')} ${results.survivedMutations}`);
+  console.log(`${chalk.yellow('⏰ Timeout:')} ${results.timeoutMutations || 0}`);
+  console.log(`${chalk.gray('❌ Error:')} ${results.errorMutations || 0}`);
+  console.log(`${chalk.bold.cyan('🎯 Mutation Score:')} ${chalk.bold(results.mutationScore.toFixed(1))}%`);
+
+  if (results.mutationScore >= 80) {
+    console.log(chalk.green('\n✅ Excellent mutation score!'));
+  } else if (results.mutationScore >= 60) {
+    console.log(chalk.yellow('\n⚠️  Good mutation score, but room for improvement'));
+  } else {
+    console.log(chalk.red('\n❌ Low mutation score - consider improving test quality'));
+  }
+}
+
+/**
+ * Print lineage data summary
+ * @param {object} data - Lineage data
+ */
+function printLineageDataSummary(data) {
+  const testCount = data.tests.length;
+  const failedTests = data.tests.filter(t => t.failed).length;
+  const passedTests = testCount - failedTests;
+
+  console.log(chalk.cyan(`\n📊 Lineage data loaded:`));
+  console.log(`  ${chalk.green('✓')} ${passedTests} tests passed`);
+  if (failedTests > 0) {
+    console.log(`  ${chalk.red('✗')} ${failedTests} tests failed`);
+  }
+  console.log(`  ${chalk.gray('📅')} Generated: ${new Date(data.timestamp).toLocaleString()}`);
+}
+
+/**
+ * Format file path for display
+ * @param {string} filePath - File path
+ * @returns {string} Formatted path
+ */
+function formatPath(filePath) {
+  const cwd = process.cwd();
+  if (filePath.startsWith(cwd)) {
+    return chalk.gray(filePath.replace(cwd, '.'));
+  }
+  return chalk.gray(filePath);
+}
+
+module.exports = {
+  success,
+  error,
+  warning,
+  info,
+  section,
+  spinner,
+  printMutationSummary,
+  printLineageDataSummary,
+  formatPath
+};