react-native-coverage 0.1.0

package/src/assert-coverage.ts

@@ -0,0 +1,260 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { CoverageConfig } from './config';
+import { DEFAULT_COVERAGE_CONFIG } from './config';
+import { EXIT_OK, EXIT_STRICT_EMPTY } from './exit-codes';
+
+export type AssertResult = {
+  code: number;
+  message: string;
+};
+
+function failEmpty(strict: boolean, message: string): AssertResult {
+  if (strict) {
+    return { code: EXIT_STRICT_EMPTY, message };
+  }
+  return { code: EXIT_OK, message: `(soft) ${message}` };
+}
+
+export type LcovAssertStats = {
+  sourceFileCount: number;
+  matchedPathHits: number;
+  linesHit: number;
+};
+
+/**
+ * Parse LCOV and count SF: paths matching configured includes.
+ * When `lcovPathIncludes` is empty, any SF: path counts as a match.
+ * `linesHit` sums `LH:` only for matched source files.
+ */
+export function analyzeLcov(
+  lcovPath: string,
+  lcovPathIncludes: string[] = []
+): LcovAssertStats {
+  const text = fs.readFileSync(lcovPath, 'utf8');
+  let sourceFileCount = 0;
+  let matchedPathHits = 0;
+  let linesHit = 0;
+  let currentMatched = false;
+
+  for (const line of text.split('\n')) {
+    if (line.startsWith('SF:')) {
+      sourceFileCount += 1;
+      const sf = line.slice(3).replace(/\\/g, '/');
+      currentMatched =
+        lcovPathIncludes.length === 0 ||
+        lcovPathIncludes.some(
+          (include) => sf.includes(include) || sf.startsWith(include)
+        );
+      if (currentMatched) {
+        matchedPathHits += 1;
+      }
+    } else if (line.startsWith('LH:') && currentMatched) {
+      linesHit += Number(line.slice(3)) || 0;
+    } else if (line.startsWith('end_of_record')) {
+      currentMatched = false;
+    }
+  }
+
+  return { sourceFileCount, matchedPathHits, linesHit };
+}
+
+/**
+ * Assert iOS (or any) LCOV has expected path hits with actual line coverage.
+ * Exit 2 in strict mode when missing/empty/no matched SF: paths/no LH hits.
+ */
+export function assertIosLcov(
+  lcovPath: string,
+  strict: boolean,
+  config: CoverageConfig = DEFAULT_COVERAGE_CONFIG,
+  cwd: string = process.cwd()
+): AssertResult {
+  const relative = path.relative(cwd, lcovPath) || lcovPath;
+  const includes = config.assert.lcovPathIncludes;
+
+  if (!fs.existsSync(lcovPath)) {
+    return failEmpty(strict, `iOS LCOV missing: ${relative}`);
+  }
+
+  const stat = fs.statSync(lcovPath);
+  if (stat.size === 0) {
+    return failEmpty(strict, `iOS LCOV empty (0 bytes): ${relative}`);
+  }
+
+  const { sourceFileCount, matchedPathHits, linesHit } = analyzeLcov(
+    lcovPath,
+    includes
+  );
+
+  if (matchedPathHits === 0 || linesHit === 0) {
+    const includeDesc =
+      includes.length > 0 ? includes.join(', ') : '(any SF: path)';
+    return failEmpty(
+      strict,
+      `iOS LCOV has no expected path/line hits [${includeDesc}] (sourceFiles=${sourceFileCount}, matchedPathHits=${matchedPathHits}, linesHit=${linesHit}): ${relative}`
+    );
+  }
+
+  return {
+    code: EXIT_OK,
+    message: `iOS ok: matchedPathHits=${matchedPathHits} sourceFiles=${sourceFileCount} linesHit=${linesHit} (${relative})`,
+  };
+}
+
+export type JacocoAssertStats = {
+  packageCount: number;
+  lineCovered: number;
+  lineMissed: number;
+};
+
+/**
+ * Parse Jacoco XML package rollups. Matchers are case-insensitive substrings
+ * of `<package name="...">`. Empty matchers → all packages.
+ *
+ * Jacoco uses `/` separators (`com/coverage/fixture`); configs often use Java
+ * dots (`coverage.fixture`). Normalize both so either form matches.
+ */
+export function analyzeJacocoXml(
+  xmlPath: string,
+  packageIncludes: string[] = []
+): JacocoAssertStats {
+  const xml = fs.readFileSync(xmlPath, 'utf8');
+  const packageBlocks = [
+    ...xml.matchAll(/<package name="([^"]+)"[^>]*>([\s\S]*?)<\/package>/g),
+  ];
+
+  const normalizePkg = (value: string) =>
+    value.toLowerCase().replace(/[./]/g, '/');
+  const normalizedIncludes = packageIncludes.map(normalizePkg);
+
+  let packageCount = 0;
+  let lineCovered = 0;
+  let lineMissed = 0;
+
+  for (const match of packageBlocks) {
+    const name = match[1]!;
+    const body = match[2]!;
+    const normalizedName = normalizePkg(name);
+    if (
+      normalizedIncludes.length > 0 &&
+      !normalizedIncludes.some((m) => normalizedName.includes(m))
+    ) {
+      continue;
+    }
+    packageCount += 1;
+
+    const trailing = body.match(
+      /((?:<counter type="[^"]+" missed="\d+" covered="\d+"\/>\s*)+)$/
+    );
+    if (!trailing) {
+      continue;
+    }
+    for (const c of trailing[1]!.matchAll(
+      /<counter type="(LINE|INSTRUCTION)" missed="(\d+)" covered="(\d+)"\/>/g
+    )) {
+      if (c[1] === 'LINE') {
+        lineMissed += Number(c[2]);
+        lineCovered += Number(c[3]);
+      }
+    }
+  }
+
+  return { packageCount, lineCovered, lineMissed };
+}
+
+/**
+ * Assert Android Jacoco XML has expected package LINE hits.
+ * Exit 2 in strict mode when missing/empty/no covered lines in matched packages.
+ */
+export function assertAndroidJacoco(
+  xmlPath: string,
+  strict: boolean,
+  config: CoverageConfig = DEFAULT_COVERAGE_CONFIG,
+  cwd: string = process.cwd()
+): AssertResult {
+  const relative = path.relative(cwd, xmlPath) || xmlPath;
+  const includes =
+    config.assert.jacocoPackageIncludes.length > 0
+      ? config.assert.jacocoPackageIncludes
+      : config.android.libraryProjectMatchers;
+
+  if (!fs.existsSync(xmlPath)) {
+    return failEmpty(strict, `Android Jacoco XML missing: ${relative}`);
+  }
+
+  const stat = fs.statSync(xmlPath);
+  if (stat.size === 0) {
+    return failEmpty(strict, `Android Jacoco XML empty (0 bytes): ${relative}`);
+  }
+
+  const { packageCount, lineCovered, lineMissed } = analyzeJacocoXml(
+    xmlPath,
+    includes
+  );
+
+  if (packageCount === 0 || lineCovered === 0) {
+    const includeDesc =
+      includes.length > 0 ? includes.join(', ') : '(any package)';
+    return failEmpty(
+      strict,
+      `Android Jacoco has empty package hits [${includeDesc}] (packages=${packageCount}, lineCovered=${lineCovered}, lineMissed=${lineMissed}): ${relative}`
+    );
+  }
+
+  return {
+    code: EXIT_OK,
+    message: `Android ok: packages=${packageCount} lineCovered=${lineCovered} lineMissed=${lineMissed} (${relative})`,
+  };
+}
+
+export type AssertCoverageOptions = {
+  platform?: 'ios' | 'android' | 'all';
+  lcov?: string;
+  jacocoXml?: string;
+  strict?: boolean;
+  config?: CoverageConfig;
+  cwd?: string;
+};
+
+/**
+ * Post-pipeline presence check. Returns the highest-priority failure code
+ * (prefer EXIT_STRICT_EMPTY over EXIT_OK).
+ */
+export function assertCoverage(
+  options: AssertCoverageOptions = {}
+): AssertResult {
+  const config = options.config ?? DEFAULT_COVERAGE_CONFIG;
+  const strict = options.strict ?? config.strict;
+  const cwd = options.cwd ?? process.cwd();
+  const platform = options.platform ?? 'all';
+
+  const lcov = options.lcov ?? path.resolve(cwd, config.assert.defaultLcovPath);
+  const jacocoXml =
+    options.jacocoXml ?? path.resolve(cwd, config.assert.defaultJacocoXmlPath);
+
+  const results: AssertResult[] = [];
+
+  if (platform === 'ios' || platform === 'all') {
+    results.push(assertIosLcov(lcov, strict, config, cwd));
+  }
+  if (platform === 'android' || platform === 'all') {
+    results.push(assertAndroidJacoco(jacocoXml, strict, config, cwd));
+  }
+
+  let code = EXIT_OK;
+  const messages: string[] = [];
+  for (const result of results) {
+    messages.push(result.message);
+    if (result.code === EXIT_STRICT_EMPTY) {
+      code = EXIT_STRICT_EMPTY;
+    } else if (result.code !== EXIT_OK && code === EXIT_OK) {
+      code = result.code;
+    }
+  }
+
+  return {
+    code,
+    message: messages.join('\n'),
+  };
+}

package/src/cli/index.ts

@@ -0,0 +1,420 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+
+import { assertCoverage } from '../assert-coverage';
+import type { CoverageConfig } from '../config';
+import { loadCoverageConfig } from '../config';
+import {
+  EXIT_ERROR,
+  EXIT_OK,
+  EXIT_STRICT_EMPTY,
+  StrictEmptyError,
+} from '../exit-codes';
+import {
+  exportIosLcov,
+  reportIosHtml,
+  summarizeIos,
+} from '../process-ios-native-coverage';
+import {
+  pullAndroidCoverageWithRetry,
+  pullIosCoverage,
+  resolveAndroidDeviceId,
+  runJacocoTestReport,
+} from '../pull-native-coverage';
+import {
+  pullAndroidJsCoverage,
+  pullIosJsCoverage,
+  reportJsCoverage,
+} from '../js-coverage';
+
+export { EXIT_OK, EXIT_ERROR, EXIT_STRICT_EMPTY };
+
+type RootOpts = {
+  config?: string;
+  strict?: boolean;
+};
+
+function applyStrictOverride(
+  config: CoverageConfig,
+  rootOpts: RootOpts
+): CoverageConfig {
+  if (rootOpts.strict === true) {
+    config.strict = true;
+  } else if (rootOpts.strict === false) {
+    config.strict = false;
+  }
+  return config;
+}
+
+function rootOptsFrom(cmd: Command): RootOpts {
+  // android/ios subcommands: parent.parent is program
+  // assert: parent is program
+  const parent = cmd.parent;
+  if (parent?.parent) {
+    return (parent.parent.opts() ?? {}) as RootOpts;
+  }
+  return (parent?.opts() ?? {}) as RootOpts;
+}
+
+function mapErrorToExit(error: unknown): number {
+  // Exit 2 only for explicit empty/missing coverage-hit guards.
+  // Tooling/config failures (e.g. missing app binary) stay exit 1.
+  if (error instanceof StrictEmptyError) {
+    return EXIT_STRICT_EMPTY;
+  }
+  return EXIT_ERROR;
+}
+
+async function main(): Promise<void> {
+  const program = new Command();
+
+  program
+    .name('rn-coverage')
+    .description(
+      'Native coverage CLI for React Native (pull / export / report / summary / assert). Pattern C: dedicated test apps only.'
+    )
+    .option('-c, --config <path>', 'Path to react-native-coverage.config.js')
+    .option('--strict', 'Fail with exit 2 when artifacts/hits are empty')
+    .option('--no-strict', 'Warn instead of exit 2 on empty artifacts');
+
+  program
+    .command('android')
+    .description('Android coverage commands')
+    .addCommand(
+      new Command('pull')
+        .description('Pull .ec coverage from a connected device/emulator')
+        .option('--device <id>', 'adb device serial')
+        .option('--output <dir>', 'Local output directory')
+        .option('--retries <n>', 'Retry count while waiting for .ec', '15')
+        .action(async (opts, cmd) => {
+          const rootOpts = rootOptsFrom(cmd);
+          const config = applyStrictOverride(
+            await loadCoverageConfig(process.cwd(), rootOpts.config),
+            rootOpts
+          );
+          try {
+            const deviceId = resolveAndroidDeviceId(opts.device);
+            const pulled = await pullAndroidCoverageWithRetry(deviceId, {
+              softFail: !config.strict,
+              outputDir: opts.output,
+              retries: Number(opts.retries) || 15,
+              config,
+            });
+            if (!pulled && config.strict) {
+              console.error(
+                '[rn-coverage] Android coverage.ec missing (strict)'
+              );
+              process.exitCode = EXIT_STRICT_EMPTY;
+            }
+          } catch (error) {
+            console.error(`[rn-coverage] ${(error as Error).message}`);
+            process.exitCode = mapErrorToExit(error);
+          }
+        })
+    )
+    .addCommand(
+      new Command('report')
+        .description(
+          'Run jacocoTestReport then assert Jacoco XML LINE hits (exit 2 if strict empty)'
+        )
+        .option('--android-dir <path>', 'Android project directory', 'android')
+        .option('--jacoco-xml <path>', 'Jacoco XML path to assert after report')
+        .action(async (opts, cmd) => {
+          const rootOpts = rootOptsFrom(cmd);
+          const config = applyStrictOverride(
+            await loadCoverageConfig(process.cwd(), rootOpts.config),
+            rootOpts
+          );
+          const result = runJacocoTestReport({
+            androidDir: opts.androidDir,
+            jacocoXml: opts.jacocoXml,
+            config,
+          });
+          if (!result.ok) {
+            process.exitCode = result.exitCode;
+          }
+        })
+    );
+
+  program
+    .command('ios')
+    .description('iOS coverage commands')
+    .addCommand(
+      new Command('pull')
+        .description('Pull .profraw from a simulator app container')
+        .requiredOption('--device <udid>', 'Simulator UDID')
+        .option('--output <dir>', 'Local output directory')
+        .action(async (opts, cmd) => {
+          const rootOpts = rootOptsFrom(cmd);
+          const config = applyStrictOverride(
+            await loadCoverageConfig(process.cwd(), rootOpts.config),
+            rootOpts
+          );
+          try {
+            const pulled = pullIosCoverage(opts.device, {
+              outputDir: opts.output,
+              softFail: !config.strict,
+              config,
+            });
+            if (pulled.length === 0 && config.strict) {
+              process.exitCode = EXIT_STRICT_EMPTY;
+            }
+          } catch (error) {
+            console.error(`[rn-coverage] ${(error as Error).message}`);
+            process.exitCode = mapErrorToExit(error);
+          }
+        })
+    )
+    .addCommand(
+      new Command('export')
+        .description(
+          'Merge profraw and export LCOV via llvm-cov (asserts path hits; exit 2 if strict empty)'
+        )
+        .requiredOption('--derived-data <path>', 'Xcode derived data path')
+        .option('--configuration <name>', 'Xcode configuration', 'Debug')
+        .option('--app-name <name>', 'App product name')
+        .option('--output <path>', 'LCOV output path', 'coverage/ios/lcov.info')
+        .action(async (opts, cmd) => {
+          const rootOpts = rootOptsFrom(cmd);
+          const config = applyStrictOverride(
+            await loadCoverageConfig(process.cwd(), rootOpts.config),
+            rootOpts
+          );
+          try {
+            await exportIosLcov({
+              derivedData: opts.derivedData,
+              configuration: opts.configuration,
+              appName: opts.appName ?? config.app.iosProductName,
+              output: opts.output,
+              config,
+            });
+          } catch (error) {
+            console.error(`[rn-coverage] ${(error as Error).message}`);
+            process.exitCode = mapErrorToExit(error);
+          }
+        })
+    )
+    .addCommand(
+      new Command('report')
+        .description('HTML report via llvm-cov show -format=html')
+        .requiredOption('--derived-data <path>', 'Xcode derived data path')
+        .option('--configuration <name>', 'Xcode configuration', 'Debug')
+        .option('--app-name <name>', 'App product name')
+        .option(
+          '--profdata <path>',
+          'Merged profdata path',
+          'coverage/ios/profdata'
+        )
+        .option(
+          '--output-dir <path>',
+          'HTML output directory',
+          'coverage/ios/html'
+        )
+        .action(async (opts, cmd) => {
+          const rootOpts = rootOptsFrom(cmd);
+          const config = applyStrictOverride(
+            await loadCoverageConfig(process.cwd(), rootOpts.config),
+            rootOpts
+          );
+          try {
+            reportIosHtml({
+              derivedData: opts.derivedData,
+              configuration: opts.configuration,
+              appName: opts.appName,
+              profdata: opts.profdata,
+              outputDir: opts.outputDir,
+              config,
+            });
+          } catch (error) {
+            console.error(`[rn-coverage] ${(error as Error).message}`);
+            process.exitCode = mapErrorToExit(error);
+          }
+        })
+    )
+    .addCommand(
+      new Command('summary')
+        .description('Terminal summary via llvm-cov report')
+        .requiredOption('--derived-data <path>', 'Xcode derived data path')
+        .option('--configuration <name>', 'Xcode configuration', 'Debug')
+        .option('--app-name <name>', 'App product name')
+        .option(
+          '--profdata <path>',
+          'Merged profdata path',
+          'coverage/ios/profdata'
+        )
+        .action(async (opts, cmd) => {
+          const rootOpts = rootOptsFrom(cmd);
+          const config = applyStrictOverride(
+            await loadCoverageConfig(process.cwd(), rootOpts.config),
+            rootOpts
+          );
+          try {
+            summarizeIos({
+              derivedData: opts.derivedData,
+              configuration: opts.configuration,
+              appName: opts.appName,
+              profdata: opts.profdata,
+              config,
+            });
+          } catch (error) {
+            console.error(`[rn-coverage] ${(error as Error).message}`);
+            process.exitCode = mapErrorToExit(error);
+          }
+        })
+    );
+
+  program
+    .command('js')
+    .description(
+      'Istanbul/NYC TypeScript coverage (source-map remap after Metro e2e)'
+    )
+    .addCommand(
+      new Command('pull')
+        .description(
+          'Pull coverage-final.json written by flush()/dumpJsCoverage'
+        )
+        .option('--platform <name>', 'android | ios', 'android')
+        .option('--device <id>', 'adb serial or simulator UDID')
+        .option('--output <dir>', 'Local output directory', 'coverage/js')
+        .action(async (opts, cmd) => {
+          const rootOpts = rootOptsFrom(cmd);
+          const config = applyStrictOverride(
+            await loadCoverageConfig(process.cwd(), rootOpts.config),
+            rootOpts
+          );
+          try {
+            if (opts.platform === 'android') {
+              const deviceId = resolveAndroidDeviceId(opts.device);
+              const pulled = pullAndroidJsCoverage(deviceId, {
+                softFail: !config.strict,
+                outputDir: opts.output,
+                config,
+              });
+              if (!pulled && config.strict) {
+                process.exitCode = EXIT_STRICT_EMPTY;
+              }
+            } else if (opts.platform === 'ios') {
+              if (!opts.device) {
+                console.error(
+                  '[rn-coverage] js pull --platform ios requires --device <udid>'
+                );
+                process.exitCode = EXIT_ERROR;
+                return;
+              }
+              const pulled = pullIosJsCoverage(opts.device, {
+                softFail: !config.strict,
+                outputDir: opts.output,
+                config,
+              });
+              if (!pulled && config.strict) {
+                process.exitCode = EXIT_STRICT_EMPTY;
+              }
+            } else {
+              console.error(
+                `[rn-coverage] js pull: --platform must be android|ios (got ${opts.platform})`
+              );
+              process.exitCode = EXIT_ERROR;
+            }
+          } catch (error) {
+            console.error(`[rn-coverage] ${(error as Error).message}`);
+            process.exitCode = mapErrorToExit(error);
+          }
+        })
+    )
+    .addCommand(
+      new Command('report')
+        .description(
+          'NYC report from coverage-final.json (sourceMap remap → lcov.info)'
+        )
+        .requiredOption(
+          '--input <path>',
+          'coverage-final.json or directory of Istanbul JSON'
+        )
+        .option('--output <dir>', 'Report directory', 'coverage/js')
+        .option('--cwd <path>', 'NYC cwd for include globs', process.cwd())
+        .option('--nyc-config <path>', 'Path to nyc.config.js')
+        .action(async (opts, cmd) => {
+          const rootOpts = rootOptsFrom(cmd);
+          const config = applyStrictOverride(
+            await loadCoverageConfig(process.cwd(), rootOpts.config),
+            rootOpts
+          );
+          try {
+            const result = reportJsCoverage({
+              input: opts.input,
+              outputDir: opts.output,
+              cwd: opts.cwd,
+              nycConfig: opts.nycConfig,
+              softFail: !config.strict,
+            });
+            if (!result.ok && config.strict) {
+              process.exitCode = EXIT_STRICT_EMPTY;
+            }
+          } catch (error) {
+            console.error(`[rn-coverage] ${(error as Error).message}`);
+            process.exitCode = mapErrorToExit(error);
+          }
+        })
+    );
+
+  program
+    .command('assert')
+    .description(
+      'Post-pipeline presence check (exit 2 on empty/missing expected hits)'
+    )
+    .option('--platform <name>', 'ios | android | all (default: all)', 'all')
+    .option('--lcov <path>', 'LCOV file to assert non-empty expected hits')
+    .option('--jacoco-xml <path>', 'Jacoco XML to assert non-empty LINE hits')
+    .action(async (opts, cmd) => {
+      const rootOpts = rootOptsFrom(cmd);
+      const config = applyStrictOverride(
+        await loadCoverageConfig(process.cwd(), rootOpts.config),
+        rootOpts
+      );
+
+      if (!['ios', 'android', 'all'].includes(opts.platform)) {
+        console.error(
+          `[rn-coverage] assert: --platform must be ios|android|all (got ${opts.platform})`
+        );
+        process.exitCode = EXIT_ERROR;
+        return;
+      }
+
+      const result = assertCoverage({
+        platform: opts.platform,
+        lcov: opts.lcov,
+        jacocoXml: opts.jacocoXml,
+        strict: config.strict,
+        config,
+      });
+
+      if (result.code === EXIT_OK) {
+        for (const line of result.message.split('\n')) {
+          console.log(`[rn-coverage] assert: ${line}`);
+        }
+        console.log('[rn-coverage] assert: ok');
+        return;
+      }
+
+      for (const line of result.message.split('\n')) {
+        if (config.strict) {
+          console.error(`[rn-coverage] assert: ${line}`);
+        } else {
+          console.warn(`[rn-coverage] assert: ${line}`);
+        }
+      }
+      if (result.code === EXIT_STRICT_EMPTY) {
+        console.error(
+          '[rn-coverage] assert: FAIL empty or missing native coverage (exit 2)'
+        );
+      }
+      process.exitCode = result.code;
+    });
+
+  await program.parseAsync(process.argv);
+}
+
+main().catch((error: unknown) => {
+  console.error(`[rn-coverage] ${(error as Error).message}`);
+  process.exitCode = EXIT_ERROR;
+});