react-native-coverage 0.1.0

package/android/src/main/java/com/coverage/CoveragePackage.kt

@@ -0,0 +1,35 @@
+package com.coverage
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import java.util.HashMap
+
+class CoveragePackage : BaseReactPackage() {
+  override fun getModule(
+    name: String,
+    reactContext: ReactApplicationContext,
+  ): NativeModule? =
+    if (name == CoverageModule.NAME) {
+      CoverageModule(reactContext)
+    } else {
+      null
+    }
+
+  override fun getReactModuleInfoProvider() =
+    ReactModuleInfoProvider {
+      mapOf(
+        CoverageModule.NAME to
+          ReactModuleInfo(
+            name = CoverageModule.NAME,
+            className = CoverageModule.NAME,
+            canOverrideExistingModule = false,
+            needsEagerInit = false,
+            isCxxModule = false,
+            isTurboModule = true,
+          ),
+      )
+    }
+}

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require('./plugin/build');

package/bin/rn-coverage.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CLI entry. Requires `yarn prepare` (bob build) so lib/ exists.
+ */
+import('../lib/module/cli/index.js').catch((error) => {
+  console.error(
+    '[rn-coverage] Failed to load CLI. Run `yarn prepare` first.\n',
+    error
+  );
+  process.exit(1);
+});

package/cocoapods/coverage_post_install.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+# react-native-coverage CocoaPods helper (safe split).
+#
+# Expo / config plugin owns Android + stable iOS app-target mods.
+# Pod LLVM coverage flags (and optional dynamic-framework restore) live here:
+#
+#   require_relative '../node_modules/react-native-coverage/cocoapods/coverage_post_install'
+#   # After use_expo_modules! — wrap Installer so restore runs after Expo's staticlib downgrade:
+#   ReactNativeCoverage.install_installer_hooks!
+#
+#   post_install do |installer|
+#     ReactNativeCoverage.apply_post_install!(
+#       installer,
+#       framework_name_prefixes: ['CoverageFixture'],
+#       force_dynamic_frameworks: true
+#     )
+#   end
+
+require 'fileutils'
+
+module ReactNativeCoverage
+  module_function
+
+  DEFAULT_FRAMEWORK_PREFIXES = ['CoverageFixture'].freeze
+  COVERAGE_POD_NAMES = %w[Coverage CoverageFixture].freeze
+
+  # Wrap Installer AFTER Expo's `use_expo_modules!` patch. Call from the Podfile
+  # below `use_expo_modules!` (Expo plugin injects the call).
+  # Using prepend-at-require races Expo's define_method and recurses forever.
+  def install_installer_hooks!(options = {})
+    if options.key?(:force_dynamic_frameworks)
+      self.force_dynamic_frameworks = options[:force_dynamic_frameworks]
+    end
+    return if @installer_hooks_installed
+
+    installer_class = Pod::Installer
+    original = installer_class.instance_method(:run_podfile_pre_install_hooks)
+
+    installer_class.define_method(:run_podfile_pre_install_hooks) do
+      original.bind_call(self)
+      ReactNativeCoverage.restore_dynamic_frameworks!(self)
+    end
+
+    @installer_hooks_installed = true
+  end
+
+  def restore_dynamic_frameworks!(installer, pod_names: nil)
+    return unless force_dynamic_frameworks_enabled?
+
+    names = Array(pod_names || dynamic_framework_pod_names)
+    restored = []
+
+    installer.pod_targets.each do |target|
+      next unless names.any? { |name| target.name == name || target.name.include?(name) }
+
+      target.define_singleton_method(:build_type) do
+        Pod::BuildType.dynamic_framework
+      end
+      restored << target.name
+    end
+
+    return if restored.empty?
+
+    Pod::UI.puts '[react-native-coverage] Restored dynamic frameworks for: ' \
+                 "#{restored.uniq.join(', ')}".green
+  end
+
+  def force_dynamic_frameworks_enabled?
+    # Default false: Expo force-statics React-Core, so dynamic Coverage* pods
+    # fail CocoaPods transitive static→dynamic validation. Opt in on bare/RNFB.
+    @force_dynamic_frameworks == true
+  end
+
+  def force_dynamic_frameworks=(value)
+    @force_dynamic_frameworks = value
+  end
+
+  def dynamic_framework_pod_names
+    @dynamic_framework_pod_names || COVERAGE_POD_NAMES
+  end
+
+  def dynamic_framework_pod_names=(names)
+    @dynamic_framework_pod_names = Array(names)
+  end
+
+  def apply_ios_native_coverage!(build_settings, link_profile:)
+    build_settings['CLANG_ENABLE_CODE_COVERAGE'] = 'YES'
+    build_settings['OTHER_CFLAGS'] =
+      '$(inherited) -fprofile-instr-generate -fcoverage-mapping'
+    build_settings['OTHER_SWIFT_FLAGS'] =
+      '$(inherited) -profile-generate -profile-coverage-mapping'
+    return unless link_profile
+
+    # -Wl,-u keeps __llvm_profile_set_filename from being dead-stripped so
+    # per-image flush can retarget coverage-%m.profraw under dynamic frameworks.
+    build_settings['OTHER_LDFLAGS'] = [
+      '$(inherited)',
+      '-fprofile-instr-generate',
+      '-Wl,-u,___llvm_profile_set_filename',
+      '-L$(DT_TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME)',
+      '-L$(SDKROOT)/usr/lib/swift',
+    ].join(' ')
+  end
+
+  def write_coverage_config_header!(prefixes:)
+    header_path = File.expand_path('../ios/CoverageConfig.h', __dir__)
+    list = Array(prefixes)
+    list = DEFAULT_FRAMEWORK_PREFIXES if list.empty?
+
+    entries = list.map { |prefix| "  \"#{prefix}\"" }.join(",\n")
+    contents = <<~HEADER
+      /**
+       * Generated by react-native-coverage CocoaPods helper.
+       * Do not edit by hand — regenerate via apply_post_install! /
+       * Expo config plugin `frameworkNamePrefixes`.
+       */
+      #pragma once
+
+      #ifndef COVERAGE_ENABLED
+      #define COVERAGE_ENABLED 1
+      #endif
+
+      #ifndef COVERAGE_PROFILE_FILE_PATTERN
+      #define COVERAGE_PROFILE_FILE_PATTERN "coverage-%m.profraw"
+      #endif
+
+      #ifndef COVERAGE_FRAMEWORK_PREFIX_COUNT
+      #define COVERAGE_FRAMEWORK_PREFIX_COUNT #{list.length}
+      static const char *const COVERAGE_FRAMEWORK_PREFIXES[] = {
+      #{entries}
+      };
+      #endif
+    HEADER
+
+    FileUtils.mkdir_p(File.dirname(header_path))
+    File.write(header_path, contents)
+    Pod::UI.puts "[react-native-coverage] Wrote #{header_path} " \
+                 "(prefixes=#{list.inspect})".green
+  end
+
+  def apply_post_install!(installer, options = {})
+    prefixes = Array(options.fetch(:framework_name_prefixes, DEFAULT_FRAMEWORK_PREFIXES))
+    link_profile = options.fetch(:link_profile, true)
+    instrument_app = options.fetch(:instrument_app, true)
+    quiet = options.fetch(:quiet, false)
+    write_header = options.fetch(:write_config_header, true)
+    force_dynamic = options.fetch(:force_dynamic_frameworks, false)
+
+    self.force_dynamic_frameworks = force_dynamic
+    self.dynamic_framework_pod_names =
+      options.fetch(:dynamic_framework_pod_names, COVERAGE_POD_NAMES + prefixes)
+
+    # Belt-and-suspenders: re-apply if Expo/other hooks ran after our prepend.
+    restore_dynamic_frameworks!(installer) if force_dynamic
+
+    write_coverage_config_header!(prefixes: prefixes) if write_header
+
+    if instrument_app
+      installer.aggregate_targets.each do |aggregate_target|
+        user_project = aggregate_target.user_project
+        next if user_project.nil?
+
+        user_project.native_targets.each do |target|
+          target.build_configurations.each do |config|
+            apply_ios_native_coverage!(config.build_settings, link_profile: true)
+          end
+        end
+        user_project.save
+      end
+    end
+
+    installer.pods_project.targets.each do |target|
+      matched = prefixes.any? { |prefix| target.name.include?(prefix) }
+      # Always link profile into the Coverage flusher Pod under dynamic linkage
+      # so configure/set_filename and the final pod write resolve.
+      is_coverage_pod = target.name == 'Coverage'
+      next unless matched || is_coverage_pod
+
+      target.build_configurations.each do |config|
+        apply_ios_native_coverage!(
+          config.build_settings,
+          link_profile: link_profile || is_coverage_pod
+        )
+      end
+    end
+
+    unless quiet
+      Pod::UI.puts '[react-native-coverage] applied LLVM coverage flags ' \
+                   "(prefixes=#{prefixes.inspect}, force_dynamic=#{force_dynamic})"
+    end
+  end
+end
+
+# Do not auto-install hooks on require — Expo patches Installer during
+# `use_expo_modules!`. Call `ReactNativeCoverage.install_installer_hooks!`
+# from the Podfile after that (Expo config plugin injects the call).

package/docs/cli.md

@@ -0,0 +1,51 @@
+# CLI
+
+Binary: `rn-coverage`
+
+```
+rn-coverage --help
+rn-coverage [--strict|--no-strict] [-c <config>]
+
+rn-coverage android pull [--device <serial>] [--output <dir>] [--retries <n>]
+rn-coverage android report [--android-dir <path>] [--jacoco-xml <path>]
+
+rn-coverage ios pull --device <udid> [--output <dir>]
+rn-coverage ios export --derived-data <path> [--configuration Debug] [--app-name <name>] [--output <path>]
+rn-coverage ios report --derived-data <path> [--profdata <path>] [--output-dir <path>]
+rn-coverage ios summary --derived-data <path> [--profdata <path>]
+
+rn-coverage assert [--platform ios|android|all] [--lcov <path>] [--jacoco-xml <path>]
+
+rn-coverage js pull --platform android|ios [--device <id>] [--output <dir>]
+rn-coverage js report --input <coverage-final.json> [--output <dir>] [--cwd <path>] [--nyc-config <path>]
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| **0** | Success (or soft-mode empty artifact with warning) |
+| **1** | Unexpected error / bad invocation / tooling failure |
+| **2** | Strict empty-hit / missing artifact (CI presence guard) |
+
+### Strict / assert contract
+
+- Config default: `strict: true` (recommended for CI).
+- Global flags: `--strict` / `--no-strict` override config for the process.
+- Soft local (`--no-strict` or `strict: false`): missing/empty expected hits **warn and exit 0**.
+- Strict CI: the same conditions **exit 2** so a sabotaged or silent pipeline fails the job.
+
+Commands that enforce the guard:
+
+| Command | Exit 2 when (strict) |
+|---------|----------------------|
+| `android pull` | No `.ec` after retries |
+| `android report` | Gradle ok but Jacoco XML missing/empty/no matched LINE hits |
+| `ios pull` | No `.profraw` in the simulator container |
+| `ios export` | No `.profraw`, or LCOV has no expected path hits with `LH` > 0 (default: `packages/`) |
+| `ios report` / `ios summary` | Missing `profdata` (run `ios export` first) |
+| `assert` | Dedicated post-pipeline check for LCOV and/or Jacoco XML |
+
+`rn-coverage assert` is the package-owned replacement for one-off shell presence scripts. Prefer wiring this CLI (exit 2) into consumer CI rather than maintaining a permanent bespoke assert.
+
+Matchers and default artifact paths live under `assert.*` in config (see [config.md](./config.md)).

package/docs/config.md

@@ -0,0 +1,27 @@
+# Config
+
+Copy [`react-native-coverage.config.js.example`](../react-native-coverage.config.js.example) to `react-native-coverage.config.js` in your dedicated test app.
+
+Key fields:
+
+| Key | Purpose |
+|-----|---------|
+| `nativeModuleName` | TurboModule name (default `Coverage`) |
+| `app.androidApplicationId` | `run-as` package for adb pull |
+| `app.iosBundleId` | simctl container lookup |
+| `app.iosProductName` | App binary / `.app` name |
+| `ios.frameworkNamePrefixes` | Extra llvm-cov `-object` frameworks |
+| `android.coverageRelativePath` | On-device `.ec` path under app files |
+| `android.libraryProjectMatchers` | Fallback Jacoco package substrings for assert |
+| `android.jacocoReportXml` | Default Jacoco XML path after `android report` |
+| `js.androidRelativePath` | On-device Istanbul JSON under `run-as` (default `files/coverage-final.json`) |
+| `js.androidStagingPath` | adb staging path for JS JSON pull |
+| `js.iosRelativePath` | Path under sim data container (default `Documents/coverage-final.json`) |
+| `sourcePathRewrite` | LCOV `SF:` path normalization rules |
+| `strict` | Exit **2** on empty artifacts when true (CI default) |
+| `assert.lcovPathIncludes` | Substrings required in ≥1 LCOV `SF:` (default `packages/`) |
+| `assert.jacocoPackageIncludes` | Jacoco package name substrings that must have LINE covered (`.` or `/`) |
+| `assert.defaultLcovPath` | Default `--lcov` for `rn-coverage assert` |
+| `assert.defaultJacocoXmlPath` | Default `--jacoco-xml` for `rn-coverage assert` |
+
+Defaults contain **no** product-specific names.

package/docs/index.md

@@ -0,0 +1,16 @@
+# react-native-coverage
+
+Coverage tooling for **dedicated React Native test apps** (Pattern C): native TurboModule flush (LLVM / Jacoco), Istanbul/NYC TypeScript coverage with source-map remap, pull/export CLI, Expo config plugin, and docs.
+
+This package is **New Architecture / TurboModule only**. It does not depend on `expo-modules-core`.
+
+## Quick links
+
+- [Pattern C](pattern-c.md) — dedicated test apps only
+- [Android integration](integration/android.md) — Gradle helpers + Expo plugin
+- [iOS integration](integration/ios.md) — Ruby helper + dynamic frameworks
+- [JS / TypeScript](integration/js.md) — Istanbul + NYC remap + Codecov
+- [E2E timing](integration/e2e-timing.md)
+- [CI Appium notes](integration/ci-appium.md) — GHA pitfalls (simulator, adb reverse, Jacoco paths)
+- [CLI](cli.md)
+- [Config](config.md)

package/docs/integration/android.md

@@ -0,0 +1,83 @@
+# Android integration
+
+Enable Android test coverage in your dedicated test app (Pattern C) and wire Jacoco reporting.
+
+## Expo (recommended)
+
+Add the config plugin — it applies both Gradle helpers and enables debug `testCoverageEnabled`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-coverage",
+        {
+          "libraryProjectMatchers": ["coverage-fixture", "my-native-lib"],
+          "enableAndroidCoverage": true
+        }
+      ]
+    ]
+  }
+}
+```
+
+Then:
+
+```sh
+npx expo prebuild
+```
+
+Inspect `android/build.gradle` (root instrumentation) and `android/app/build.gradle` (Jacoco report + `testCoverageEnabled`).
+
+## Bare React Native / manual Gradle
+
+In the **root** `android/build.gradle`:
+
+```gradle
+ext.coverageLibraryProjectMatchers = ['my-native-lib']
+def rnCoverageRoot = new File(
+  ["node", "--print", "require.resolve('react-native-coverage/package.json')"]
+    .execute(null, rootDir).text.trim()
+).parentFile
+apply from: new File(rnCoverageRoot, "android/rn-coverage.gradle")
+```
+
+In **app** `android/app/build.gradle`:
+
+```gradle
+android {
+  buildTypes {
+    debug {
+      testCoverageEnabled true
+    }
+  }
+}
+
+def rnCoverageRoot = new File(
+  ["node", "--print", "require.resolve('react-native-coverage/package.json')"]
+    .execute(null, rootDir).text.trim()
+).parentFile
+apply from: new File(rnCoverageRoot, "android/rn-coverage-jacoco.gradle")
+```
+
+## Runtime + CLI
+
+1. Call `flush()` from the TurboModule at the end of an e2e run (Emma `RT.dumpCoverageData` → `filesDir/coverage.ec`; also dumps Istanbul JSON when Metro is instrumented).
+2. `rn-coverage android pull` — output under **`android/app/build/…`** so Jacoco sees the `.ec` (not only `artifacts/`). Staging parent dirs are created for you.
+3. `rn-coverage android report` (`jacocoTestReport`).
+4. `rn-coverage assert` (strict empty → exit 2).
+5. Optional JS: `rn-coverage js pull` / `js report` — see [JS / TypeScript](js.md).
+
+Jacoco package names in XML use slashes (`com/foo`); assert matchers may use dots (`com.foo`) — both work.
+
+CI pitfalls (emulator Metro, `byTestId`, etc.): [CI Appium notes](ci-appium.md).
+
+Shipped helpers:
+
+| File | Role |
+|------|------|
+| `android/rn-coverage.gradle` | Enable Jacoco + `enableAndroidTestCoverage` on matched library projects |
+| `android/rn-coverage-jacoco.gradle` | `jacocoTestReport` / unit / e2e-only report tasks |
+
+Pod LLVM flags are **not** applied by regex-editing the Podfile; use the Ruby helper on iOS (see [iOS integration](ios.md)).

package/docs/integration/ci-appium.md

@@ -0,0 +1,41 @@
+# CI Appium notes (learned the hard way)
+
+Practical pitfalls from getting GitHub Actions green for this package’s Appium cells. Consumer CI should copy the same patterns.
+
+## Matrix
+
+| Cell | Harness | What it proves |
+|------|---------|----------------|
+| `e2e:ios:dynamic` | `example-dynamic/` (bare RN, `USE_FRAMEWORKS=dynamic`) | Primary LLVM LCOV with a real dynamic `CoverageFixture.framework` |
+| `e2e:ios:static` | `example/` (Expo prebuild, static merge) | Honest static cell still asserts fixture hits |
+| `e2e:android` | `example/` (Expo + emulator) | Emma `.ec` → Jacoco → assert |
+
+Scripts: `scripts/ci/`. Specs: `e2e/`.
+
+## iOS / Xcode / simulator
+
+- Prefer **`macos-26`** + **`maxim-lobanov/setup-xcode`** with `latest-stable` (Expo SDK 57 wants Xcode 26.4+).
+- Default simulator name: **`iPhone 17`**. Xcode 26.6 images do not ship a plain `iPhone 16`; wrong names fail destination lookup.
+- Boot with an exact-name match, open **Simulator.app**, then poll `bootstatus` (see `scripts/ci/boot-ios-simulator.sh`). Headless `simctl boot` alone + Appium restart hung at WDA timeouts on GHA.
+- Give Appium room: `simulatorStartupTimeout` ≥ 300s, long WDA timeouts (helpers in `e2e/helpers.js`).
+- List sims once before the run (`xcrun simctl list`) — same deflake idea as RNFB.
+
+## Android / Metro / Appium
+
+- Debug APK loads JS from Metro. Emulator `localhost` is **not** the host — run **`adb reverse tcp:8081 tcp:8081`** (or your Metro port) before launching the app, or the bundle never loads and Appium never sees UI.
+- React Native `testID` on Android maps to **`resource-id`**, not accessibility id. Prefer a shared helper (`byTestId`) that uses `UiSelector().resourceId(...)` on Android and `~id` on iOS.
+- Allow a long `appWaitDuration` for first Metro bundle.
+
+## Android coverage pull → Jacoco
+
+1. Staging path (`android.detoxStagingPath`, default `/data/local/tmp/coverage/coverage.ec`): **`mkdir -p` the parent** before `run-as … cat … > staging`. Unlike Detox’s `/data/local/tmp/detox/`, this package does not create that directory for you (`rn-coverage android pull` does).
+2. Land `emulator_coverage.ec` under the **app `buildDir`** (e.g. `android/app/build/outputs/code_coverage/`). Jacoco `executionData` is a `fileTree` over `project.buildDir` (+ matched libraries). Pulling only into `artifacts/` leaves `:app:jacocoTestReport` **SKIPPED** with empty data.
+3. Assert matchers: Jacoco XML package names use **slashes** (`com/coverage/fixture`). Config often uses Java **dots** (`coverage.fixture`). `rn-coverage assert` normalizes `/` ↔ `.` — keep matchers readable either way.
+
+## Action pins
+
+Pin third-party Actions by **full commit SHA** (and comment the release tag). Typo’d SHAs fail the job before any app code runs.
+
+## Artifacts
+
+Upload `artifacts/e2e/coverage/**` and `artifacts/e2e/logs/**` with `if: always()` so failed pulls/asserts remain diagnosable.

package/docs/integration/e2e-timing.md

@@ -0,0 +1,20 @@
+# E2E timing (document only)
+
+Glue for when to flush and pull belongs in the consumer test runner (Jet, Detox, Mocha, Appium, etc.). This package does not ship a particular e2e framework.
+
+Typical sequence:
+
+1. Run instrumented e2e against the dedicated test app (`RN_COVERAGE_JS=1` for Istanbul).
+2. Invoke `Coverage.flush()` (TurboModule) once at suite teardown — native buffers **and** `global.__coverage__` when present.
+3. Host-side: `rn-coverage android pull` / `rn-coverage ios pull`.
+4. `rn-coverage android report` or `rn-coverage ios export` (+ optional `ios report` / `ios summary`).
+5. Optional: `rn-coverage js pull` + `rn-coverage js report` (NYC source-map remap).
+6. Optional: `rn-coverage assert` (exit 2 on empty artifacts when `strict: true`).
+
+The example app documents Appium as the intended e2e runner. CI wiring:
+
+- `yarn e2e:ios:dynamic` — primary bare-RN dynamic frameworks cell
+- `yarn e2e:ios:static` — Expo static cell
+- `yarn e2e:android` — Expo Android Jacoco + JS cell
+
+Scripts live under `scripts/ci/`; WDIO specs under `e2e/`. See also [CI Appium notes](ci-appium.md) and [JS / TypeScript](js.md).

package/docs/integration/ios.md

@@ -0,0 +1,77 @@
+# iOS integration
+
+- New Architecture only; TurboModule autolinks via the podspec.
+- Flusher packaging (dynamic frameworks): **mode (c)** — Pod LINKEDIT for
+  configured `frameworkNamePrefixes` **and** the main executable (see spike verdict).
+
+## Expo (recommended)
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-coverage",
+        {
+          "frameworkNamePrefixes": ["MyLib"],
+          "forceDynamicFrameworks": false
+        }
+      ]
+    ]
+  }
+}
+```
+
+Keep `forceDynamicFrameworks` **false** under Expo (React-Core is force-static). Set **true** only on bare RN / RNFB hosts that build React as dynamic frameworks.
+
+## CI cells (honest matrix)
+
+| Cell | App | Linkage | Gate |
+|------|-----|---------|------|
+| **iOS dynamic (primary)** | `example-dynamic/` bare RN | `use_frameworks! :linkage => :dynamic` | Non-zero fixture LCOV **and** `CoverageFixture.framework` is a dylib |
+| **iOS static** | `example/` Expo | staticlib merge into app / `.debug.dylib` | Non-zero fixture LCOV |
+| **Android** | `example/` Expo | Jacoco-instrumented libraries | Non-zero fixture package LINE hits |
+
+Appium (WebDriverIO) drives the harness; see `e2e/` and `scripts/ci/run-ios-e2e-cell.sh`.
+
+1. Sets `ios.useFrameworks=dynamic` in Podfile properties (needed for multi-image LINKEDIT on dynamic-React hosts).
+2. Requires the shipped Ruby helper and calls `apply_post_install!` once (safe split — no Podfile regex for LLVM flags).
+3. Optionally restores dynamic frameworks for `Coverage` + matched fixture pods
+   (`forceDynamicFrameworks: true`) — **only when React is also dynamic**
+   (bare RN / RNFB). Leave `false` under Expo (React-Core is force-static);
+   CocoaPods rejects dynamic Coverage* pods that transitively depend on static
+   React-Core. Under Expo, Coverage* remain static libraries merged into the app.
+
+```sh
+npx expo prebuild
+cd ios && pod install
+```
+
+## Bare React Native / manual Podfile
+
+```ruby
+require_relative '../node_modules/react-native-coverage/cocoapods/coverage_post_install'
+
+# After `use_expo_modules!` (wraps Installer so restore runs after Expo's staticlib downgrade):
+ReactNativeCoverage.install_installer_hooks!
+
+post_install do |installer|
+  ReactNativeCoverage.apply_post_install!(
+    installer,
+    framework_name_prefixes: ['MyLib'],
+    force_dynamic_frameworks: true
+  )
+end
+```
+
+The helper:
+
+- Applies LLVM `-fprofile-instr-generate` / `-fcoverage-mapping` (+ link flags) to the app target and matching pods.
+- Regenerates `ios/CoverageConfig.h` from `framework_name_prefixes`.
+- Restores `Pod::BuildType.dynamic_framework` for Coverage / fixture pods when Expo forced `static_library`.
+
+## Runtime + CLI
+
+Call `flush()` before `rn-coverage ios pull`, then `rn-coverage ios export` for LCOV.
+
+The Expo config plugin wires the Podfile helper call; it does **not** replace the Ruby helper for Pod LLVM flags (safe split).

package/docs/integration/js.md

@@ -0,0 +1,38 @@
+# JavaScript / TypeScript coverage
+
+Complete the React Native coverage story alongside native LLVM/Jacoco:
+
+| Layer | Tooling | Artifact |
+|-------|---------|----------|
+| Unit (package) | Jest `--coverage` | `coverage/unit/lcov.info` |
+| E2e JS/TS | `babel-plugin-istanbul` + NYC source-map remap | `coverage/js/lcov.info` |
+| Native iOS | llvm-cov | `lcov.info` |
+| Native Android | Jacoco | `jacocoTestReport.xml` |
+
+## Instrument Metro (e2e)
+
+Set `RN_COVERAGE_JS=1` before starting Metro (CI scripts do this). Example babel configs load `babel-plugin-istanbul` only when that env is set.
+
+`flush()` dumps `global.__coverage__` via TurboModule `dumpJsCoverage` **before** the native Emma/LLVM flush:
+
+- Android → `filesDir/coverage-final.json` (`files/coverage-final.json` under `run-as`)
+- iOS → `Documents/coverage-final.json`
+
+## CLI
+
+```sh
+rn-coverage js pull --platform android --output coverage/js
+rn-coverage js pull --platform ios --device <udid> --output coverage/js
+
+rn-coverage js report \
+  --input coverage/js/coverage-final.json \
+  --output coverage/js \
+  --cwd example \
+  --nyc-config example/nyc.config.js
+```
+
+NYC is configured with `sourceMap: true` and `exclude-after-remap: true` so LCOV `SF:` paths point at **TypeScript** sources (not only the Metro-transformed JS line map). Ship a `nyc.config.js` next to the harness (see `example/nyc.config.js`).
+
+## Codecov
+
+CI uploads unit LCOV, e2e native LCOV/Jacoco, and e2e JS LCOV with distinct `flags` (`unit-js`, `e2e-ios-dynamic`, …). Wire `CODECOV_TOKEN` (or Codecov GitHub app OIDC) on the repo for private uploads; public repos may work tokenless depending on Codecov settings.

package/docs/pattern-c.md

@@ -0,0 +1,5 @@
+# Pattern C — dedicated test apps only
+
+`react-native-coverage` is intended for **dedicated test / e2e harness apps** (for example a monorepo `tests/` app), not production product `package.json` trees.
+
+Autolinking still scans dependencies; do not rely on `devDependency` alone to keep the TurboModule out of a product app. Keep the package in the test app workspace only.