react-native-coverage 0.1.0

package/src/config.ts

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Neutral defaults — no consumer product names.
+ * Pattern C: this package targets dedicated test apps only.
+ */
+export type SourcePathRewriteRule =
+  | {
+      kind: 'after-marker';
+      /** Substring to locate (e.g. `/packages/`). */
+      marker: string;
+      /**
+       * When true (default), the returned path starts at `marker` without a
+       * leading slash (e.g. `packages/...`). When false, returns the substring
+       * after the marker.
+       */
+      includeMarker?: boolean;
+    }
+  | {
+      kind: 'regex';
+      pattern: string;
+      flags?: string;
+      replacement: string;
+    };
+
+export type CoverageAssertConfig = {
+  /**
+   * Substrings that must appear in ≥1 LCOV `SF:` path.
+   * Empty → any SF: path counts. Default `packages/` matches common monorepos.
+   */
+  lcovPathIncludes: string[];
+  /**
+   * Case-insensitive substrings matching Jacoco `<package name="">`.
+   * Empty falls back to `android.libraryProjectMatchers`, then any package.
+   */
+  jacocoPackageIncludes: string[];
+  /** Default relative path for `rn-coverage assert --lcov`. */
+  defaultLcovPath: string;
+  /** Default relative path for `rn-coverage assert --jacoco-xml`. */
+  defaultJacocoXmlPath: string;
+};
+
+export type CoverageConfig = {
+  /** TurboModule / NativeModules name. Default: `Coverage`. */
+  nativeModuleName: string;
+  app: {
+    androidApplicationId: string;
+    iosBundleId: string;
+    iosProductName: string;
+  };
+  ios: {
+    /** Framework basename prefixes to include as llvm-cov `-object`s. */
+    frameworkNamePrefixes: string[];
+  };
+  android: {
+    libraryProjectMatchers: string[];
+    /** Optional staging path used by some e2e runners (e.g. Detox). */
+    detoxStagingPath: string;
+    coverageRelativePath: string;
+    /** Relative path to jacocoTestReport.xml after `android report`. */
+    jacocoReportXml: string;
+  };
+  /**
+   * Istanbul / NYC (TypeScript via source maps). Written by TurboModule
+   * `dumpJsCoverage` during `flush()` when Metro is instrumented.
+   */
+  js: {
+    androidRelativePath: string;
+    androidStagingPath: string;
+    /** Path under the iOS app data container (usually Documents/…). */
+    iosRelativePath: string;
+  };
+  /** Rules applied left-to-right to LCOV `SF:` paths. */
+  sourcePathRewrite: SourcePathRewriteRule[];
+  /**
+   * When true (recommended in CI), pull/export/report/assert exit 2 if
+   * expected hits/artifacts are empty.
+   */
+  strict: boolean;
+  /** Presence-guard matchers and default artifact paths. */
+  assert: CoverageAssertConfig;
+};
+
+export const DEFAULT_COVERAGE_CONFIG: CoverageConfig = {
+  nativeModuleName: 'Coverage',
+  app: {
+    androidApplicationId: 'com.example.coverage',
+    iosBundleId: 'com.example.coverage',
+    iosProductName: 'CoverageExample',
+  },
+  ios: {
+    frameworkNamePrefixes: [],
+  },
+  android: {
+    libraryProjectMatchers: [],
+    detoxStagingPath: '/data/local/tmp/coverage/coverage.ec',
+    coverageRelativePath: 'files/coverage.ec',
+    jacocoReportXml:
+      'android/app/build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml',
+  },
+  js: {
+    androidRelativePath: 'files/coverage-final.json',
+    androidStagingPath: '/data/local/tmp/coverage/coverage-final.json',
+    iosRelativePath: 'Documents/coverage-final.json',
+  },
+  sourcePathRewrite: [],
+  strict: true,
+  assert: {
+    lcovPathIncludes: ['packages/'],
+    jacocoPackageIncludes: [],
+    defaultLcovPath: 'coverage/ios/lcov.info',
+    defaultJacocoXmlPath:
+      'android/app/build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml',
+  },
+};
+
+export type CoverageConfigInput = {
+  nativeModuleName?: string;
+  app?: Partial<CoverageConfig['app']>;
+  ios?: Partial<CoverageConfig['ios']>;
+  android?: Partial<CoverageConfig['android']>;
+  js?: Partial<CoverageConfig['js']>;
+  sourcePathRewrite?: SourcePathRewriteRule[];
+  strict?: boolean;
+  assert?: Partial<CoverageAssertConfig>;
+};
+
+export function resolveCoverageConfig(
+  input: CoverageConfigInput = {}
+): CoverageConfig {
+  return {
+    nativeModuleName:
+      input.nativeModuleName ?? DEFAULT_COVERAGE_CONFIG.nativeModuleName,
+    app: {
+      ...DEFAULT_COVERAGE_CONFIG.app,
+      ...input.app,
+    },
+    ios: {
+      ...DEFAULT_COVERAGE_CONFIG.ios,
+      ...input.ios,
+    },
+    android: {
+      ...DEFAULT_COVERAGE_CONFIG.android,
+      ...input.android,
+    },
+    js: {
+      ...DEFAULT_COVERAGE_CONFIG.js,
+      ...input.js,
+    },
+    sourcePathRewrite:
+      input.sourcePathRewrite ?? DEFAULT_COVERAGE_CONFIG.sourcePathRewrite,
+    strict: input.strict ?? DEFAULT_COVERAGE_CONFIG.strict,
+    assert: {
+      ...DEFAULT_COVERAGE_CONFIG.assert,
+      ...input.assert,
+    },
+  };
+}
+
+const CONFIG_FILENAMES = [
+  'react-native-coverage.config.js',
+  'react-native-coverage.config.cjs',
+  'react-native-coverage.config.mjs',
+] as const;
+
+/**
+ * Load config from `cwd` (or `configPath`). Missing file → defaults.
+ */
+export async function loadCoverageConfig(
+  cwd: string = process.cwd(),
+  configPath?: string
+): Promise<CoverageConfig> {
+  const resolvedPath =
+    configPath != null
+      ? path.resolve(cwd, configPath)
+      : CONFIG_FILENAMES.map((name) => path.join(cwd, name)).find((p) =>
+          fs.existsSync(p)
+        );
+
+  if (resolvedPath == null || !fs.existsSync(resolvedPath)) {
+    return resolveCoverageConfig();
+  }
+
+  const mod = await import(pathToFileURL(resolvedPath).href);
+  const raw = (mod.default ?? mod) as CoverageConfigInput;
+  return resolveCoverageConfig(raw);
+}

package/src/exit-codes.ts

@@ -0,0 +1,20 @@
+/**
+ * CLI / library exit codes for presence / silent-fail guards.
+ *
+ * Aligns with the RNFB interim assert contract (exit 2 = strict empty).
+ */
+export const EXIT_OK = 0;
+/** Unexpected error / bad invocation / tooling failure. */
+export const EXIT_ERROR = 1;
+/** Strict empty-hit / missing artifact (CI guard). */
+export const EXIT_STRICT_EMPTY = 2;
+
+/** Thrown when a strict presence guard fails (map to exit 2 in the CLI). */
+export class StrictEmptyError extends Error {
+  readonly exitCode = EXIT_STRICT_EMPTY;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'StrictEmptyError';
+  }
+}

package/src/index.tsx

@@ -0,0 +1,35 @@
+import Coverage from './NativeCoverage';
+
+export { default as Coverage } from './NativeCoverage';
+export type { Spec as CoverageSpec } from './NativeCoverage';
+
+/**
+ * Flush in-process native coverage buffers to disk.
+ * iOS: LLVM multi-image (mode c). Android: Jacoco/Emma RT dump.
+ *
+ * React Native entry only — Node/CLI APIs live under `react-native-coverage/node`.
+ */
+/**
+ * Flush Istanbul JS coverage (when Metro instrumented) then native buffers.
+ * No-op for JS dump when `global.__coverage__` is absent.
+ */
+export function flush(): void {
+  try {
+    const coverage = (globalThis as { __coverage__?: unknown }).__coverage__;
+    if (coverage != null && typeof Coverage.dumpJsCoverage === 'function') {
+      Coverage.dumpJsCoverage(JSON.stringify(coverage));
+    }
+  } catch {
+    // Older native binaries without dumpJsCoverage — native flush still runs.
+  }
+  Coverage.flush();
+}
+
+/** Write `global.__coverage__` only (no native Emma/LLVM flush). */
+export function flushJs(): void {
+  const coverage = (globalThis as { __coverage__?: unknown }).__coverage__;
+  if (coverage == null) {
+    return;
+  }
+  Coverage.dumpJsCoverage(JSON.stringify(coverage));
+}

package/src/js-coverage.ts

@@ -0,0 +1,213 @@
+import { execFileSync, execSync } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import type { CoverageConfig } from './config';
+import { DEFAULT_COVERAGE_CONFIG } from './config';
+import { StrictEmptyError } from './exit-codes';
+import { getAdbBinary, resolveAndroidDeviceId } from './pull-native-coverage';
+
+export type JsPullOptions = {
+  softFail?: boolean;
+  outputDir?: string;
+  config?: CoverageConfig;
+};
+
+function ensureDir(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Pull Android Istanbul JSON written by `dumpJsCoverage` (`files/coverage-final.json`).
+ */
+export function pullAndroidJsCoverage(
+  deviceId: string,
+  options: JsPullOptions = {}
+): string | null {
+  const config = options.config ?? DEFAULT_COVERAGE_CONFIG;
+  const softFail = options.softFail ?? !config.strict;
+  const localDestDir =
+    options.outputDir ?? path.resolve(process.cwd(), 'coverage/js');
+  const localDestFile = path.join(localDestDir, 'coverage-final.json');
+  const relative = config.js.androidRelativePath;
+  const staging = config.js.androidStagingPath;
+  const adb = getAdbBinary();
+  const serial = deviceId ? `-s ${deviceId}` : '';
+
+  try {
+    const stagingDir = path.posix.dirname(staging);
+    execSync(`${adb} ${serial} shell "mkdir -p ${stagingDir}"`);
+    execSync(
+      `${adb} ${serial} shell "run-as ${config.app.androidApplicationId} cat ${relative} > ${staging}"`
+    );
+    ensureDir(localDestDir);
+    execSync(`${adb} ${serial} pull ${staging} ${localDestFile}`);
+    console.log(`JS coverage downloaded to: ${localDestFile}`);
+    return localDestFile;
+  } catch (error) {
+    const message = `Android JS coverage pull failed: ${(error as Error).message}`;
+    if (softFail) {
+      console.warn(`[rn-coverage] ${message}`);
+      return null;
+    }
+    throw new Error(message);
+  }
+}
+
+/**
+ * Pull iOS Istanbul JSON from the simulator data container.
+ */
+export function pullIosJsCoverage(
+  deviceId: string,
+  options: JsPullOptions = {}
+): string | null {
+  const config = options.config ?? DEFAULT_COVERAGE_CONFIG;
+  const softFail = options.softFail ?? !config.strict;
+  const localDestDir =
+    options.outputDir ?? path.resolve(process.cwd(), 'coverage/js');
+  const localDestFile = path.join(localDestDir, 'coverage-final.json');
+  const relative = config.js.iosRelativePath;
+  const bundleId = config.app.iosBundleId;
+
+  try {
+    const container = execSync(
+      `xcrun simctl get_app_container ${deviceId} ${bundleId} data`,
+      { encoding: 'utf8' }
+    ).trim();
+    const src = path.join(container, relative);
+    if (!fs.existsSync(src)) {
+      const message = `iOS JS coverage missing at ${src}`;
+      if (softFail) {
+        console.warn(`[rn-coverage] ${message}`);
+        return null;
+      }
+      throw new StrictEmptyError(message);
+    }
+    ensureDir(localDestDir);
+    fs.copyFileSync(src, localDestFile);
+    console.log(`JS coverage downloaded to: ${localDestFile}`);
+    return localDestFile;
+  } catch (error) {
+    if (error instanceof StrictEmptyError) {
+      throw error;
+    }
+    const message = `iOS JS coverage pull failed: ${(error as Error).message}`;
+    if (softFail) {
+      console.warn(`[rn-coverage] ${message}`);
+      return null;
+    }
+    throw new Error(message);
+  }
+}
+
+export type JsReportOptions = {
+  /** Istanbul coverage-final.json (or directory of JSON files). */
+  input: string;
+  /** Directory for lcov.info / HTML (NYC report-dir). */
+  outputDir?: string;
+  /** Working directory for NYC include globs (usually repo or app root). */
+  cwd?: string;
+  /** Optional path to nyc.config.js */
+  nycConfig?: string;
+  softFail?: boolean;
+};
+
+/**
+ * Run NYC report with source-map remap (TypeScript SF: paths).
+ * Expects pre-instrumented coverage JSON (`instrument: false` in nyc config).
+ */
+export function reportJsCoverage(options: JsReportOptions): {
+  ok: boolean;
+  lcovPath: string | null;
+} {
+  const cwd = options.cwd ?? process.cwd();
+  const outputDir = options.outputDir ?? path.resolve(cwd, 'coverage/js');
+  const softFail = options.softFail ?? false;
+  const nycOutput = path.join(outputDir, '.nyc_output');
+  ensureDir(nycOutput);
+  ensureDir(outputDir);
+
+  const inputPath = path.resolve(options.input);
+  if (!fs.existsSync(inputPath)) {
+    const message = `JS coverage input missing: ${inputPath}`;
+    if (softFail) {
+      console.warn(`[rn-coverage] ${message}`);
+      return { ok: false, lcovPath: null };
+    }
+    throw new StrictEmptyError(message);
+  }
+
+  if (fs.statSync(inputPath).isDirectory()) {
+    for (const name of fs.readdirSync(inputPath)) {
+      if (name.endsWith('.json')) {
+        fs.copyFileSync(path.join(inputPath, name), path.join(nycOutput, name));
+      }
+    }
+  } else {
+    fs.copyFileSync(inputPath, path.join(nycOutput, 'coverage-final.json'));
+  }
+
+  const resolveNycBin = (): string => {
+    const bases = [cwd, process.cwd()];
+    for (const base of bases) {
+      try {
+        return createRequire(path.join(base, 'package.json')).resolve(
+          'nyc/bin/nyc.js'
+        );
+      } catch {
+        // try next
+      }
+      const direct = path.join(base, 'node_modules', 'nyc', 'bin', 'nyc.js');
+      if (fs.existsSync(direct)) {
+        return direct;
+      }
+    }
+    throw new Error(
+      'nyc is required for `rn-coverage js report` — yarn add nyc in the package or test app'
+    );
+  };
+  const nycBin = resolveNycBin();
+
+  const args = [
+    nycBin,
+    'report',
+    '--reporter=lcov',
+    '--reporter=text-summary',
+    `--report-dir=${outputDir}`,
+    `--temp-dir=${nycOutput}`,
+    '--exclude-after-remap',
+  ];
+  if (options.nycConfig) {
+    args.push(`--nycrc-path=${path.resolve(options.nycConfig)}`);
+  }
+
+  try {
+    execFileSync(process.execPath, args, {
+      cwd,
+      stdio: 'inherit',
+    });
+  } catch (error) {
+    const message = `NYC report failed: ${(error as Error).message}`;
+    if (softFail) {
+      console.warn(`[rn-coverage] ${message}`);
+      return { ok: false, lcovPath: null };
+    }
+    throw new Error(message);
+  }
+
+  const lcovPath = path.join(outputDir, 'lcov.info');
+  if (!fs.existsSync(lcovPath) || fs.statSync(lcovPath).size === 0) {
+    const message = `JS LCOV missing or empty after NYC report: ${lcovPath}`;
+    if (softFail) {
+      console.warn(`[rn-coverage] ${message}`);
+      return { ok: false, lcovPath: null };
+    }
+    throw new StrictEmptyError(message);
+  }
+
+  console.log(`[rn-coverage] JS LCOV written to ${lcovPath}`);
+  return { ok: true, lcovPath };
+}
+
+export { resolveAndroidDeviceId };

package/src/node.ts

@@ -0,0 +1,52 @@
+/**
+ * Node/library surface (CLI helpers, config, assert, pull/export).
+ * Do not import from React Native / Metro — use package root `flush()` there.
+ */
+export type {
+  CoverageAssertConfig,
+  CoverageConfig,
+  SourcePathRewriteRule,
+} from './config';
+export {
+  DEFAULT_COVERAGE_CONFIG,
+  loadCoverageConfig,
+  resolveCoverageConfig,
+} from './config';
+export { normalizeSourcePath, applySourcePathRewrite } from './path-rewrite';
+export {
+  EXIT_OK,
+  EXIT_ERROR,
+  EXIT_STRICT_EMPTY,
+  StrictEmptyError,
+} from './exit-codes';
+export {
+  analyzeLcov,
+  analyzeJacocoXml,
+  assertIosLcov,
+  assertAndroidJacoco,
+  assertCoverage,
+} from './assert-coverage';
+export type { AssertResult, AssertCoverageOptions } from './assert-coverage';
+export {
+  walkFiles,
+  collectCoverageObjects,
+  resolveIosCoverageContext,
+  rewriteLcovFile,
+  exportIosLcov,
+  reportIosHtml,
+  summarizeIos,
+} from './process-ios-native-coverage';
+export {
+  resolveAndroidDeviceId,
+  androidCoverageFileExists,
+  pullAndroidCoverage,
+  pullAndroidCoverageWithRetry,
+  pullIosCoverage,
+  runJacocoTestReport,
+  getAdbBinary,
+} from './pull-native-coverage';
+export {
+  pullAndroidJsCoverage,
+  pullIosJsCoverage,
+  reportJsCoverage,
+} from './js-coverage';

package/src/path-rewrite.ts

@@ -0,0 +1,52 @@
+import type { SourcePathRewriteRule } from './config';
+
+/**
+ * Apply a single rewrite rule to a source path (forward slashes).
+ * Returns the rewritten path, or the input if the rule did not match.
+ */
+export function applySourcePathRewrite(
+  sourcePath: string,
+  rule: SourcePathRewriteRule
+): string {
+  const normalized = sourcePath.replace(/\\/g, '/');
+
+  if (rule.kind === 'after-marker') {
+    const idx = normalized.indexOf(rule.marker);
+    if (idx < 0) {
+      return normalized;
+    }
+    const includeMarker = rule.includeMarker !== false;
+    if (includeMarker) {
+      const fromMarker = normalized.slice(idx);
+      return fromMarker.startsWith('/') ? fromMarker.slice(1) : fromMarker;
+    }
+    return normalized.slice(idx + rule.marker.length);
+  }
+
+  if (rule.kind === 'regex') {
+    const re = new RegExp(rule.pattern, rule.flags ?? '');
+    if (!re.test(normalized)) {
+      return normalized;
+    }
+    // Reset lastIndex after .test() for global regexes; always rewrite via replace.
+    re.lastIndex = 0;
+    return normalized.replace(re, rule.replacement);
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize an LCOV `SF:` path using ordered rewrite rules.
+ * Rules are applied left-to-right; each rule sees the previous result.
+ */
+export function normalizeSourcePath(
+  sourcePath: string,
+  rules: SourcePathRewriteRule[] = []
+): string {
+  let current = sourcePath.replace(/\\/g, '/').replace(/^\.\//, '');
+  for (const rule of rules) {
+    current = applySourcePathRewrite(current, rule);
+  }
+  return current;
+}