react-native-coverage 0.1.0

package/docs/releasing.md

@@ -0,0 +1,88 @@
+# Releasing
+
+Operator guide for publishing `react-native-coverage`. Releases are **manual only** (`workflow_dispatch`). There is no auto-publish on push to `main`.
+
+## Prerequisites
+
+| Item | Notes |
+|------|--------|
+| GitHub repo | `invertase/react-native-coverage` (see [Create the GitHub repo](#create-the-github-repo) if missing) |
+| Conventional Commits | PR titles enforced by `.github/workflows/pr-title.yml`; squash-merge preferred |
+| Green `main` | Unit + Appium e2e CI from `.github/workflows/ci.yml` |
+| First npm publish | **Human OTP bootstrap** — first human publish, not this release scaffolding |
+| npm OIDC | Configure Trusted Publisher **after** bootstrap; release workflow already has `id-token: write` |
+
+## Create the GitHub repo
+
+Local clone has **no `origin` remote** until a human creates the GitHub repository. From the package root:
+
+```sh
+cd /path/to/react-native-coverage
+
+# Create under invertase and set origin (public OSS / Apache-2.0):
+gh repo create invertase/react-native-coverage \
+  --public \
+  --source=. \
+  --remote=origin \
+  --description "Native code coverage tooling for React Native test apps (Pattern C)"
+
+# Push main (after reviewing uncommitted scaffolding / approved commits):
+git push -u origin main
+```
+
+Optional: create empty on GitHub first, then:
+
+```sh
+git remote add origin git@github.com:invertase/react-native-coverage.git
+git push -u origin main
+```
+
+Confirm: `gh repo view invertase/react-native-coverage`.
+
+## Conventional Commits
+
+- Prefer **squash merge**; the PR title becomes the release-relevant commit.
+- PR titles must match [Conventional Commits](https://www.conventionalcommits.org/) (enforced in CI).
+- Local check (optional):
+
+```sh
+echo "feat: add assert command" | yarn commitlint
+```
+
+Examples: `feat: …`, `fix: …`, `docs: …`, `chore: …`. Breaking changes: `feat!: …` or a `BREAKING CHANGE:` footer.
+
+## Release tooling
+
+| Piece | Path / command |
+|-------|----------------|
+| Config | `release.config.js` |
+| Workflow | `.github/workflows/release.yml` (`workflow_dispatch` only) |
+| Analyzer | Conventional Commits via `@semantic-release/commit-analyzer` |
+| Publish | `@semantic-release/npm` + `@semantic-release/github` |
+| **Not used** | `@semantic-release/git` — dropped so releases do not need a bot push past branch protection; version tags + GitHub Releases carry the release, not in-repo `package.json` bumps |
+
+Dry-run (no publish; needs network + git history):
+
+```sh
+yarn release:dry-run
+```
+
+## Operator: CI release (after bootstrap)
+
+Do **not** run a real publish until human bootstrap + OIDC Trusted Publisher setup are complete.
+
+1. Ensure `main` is green.
+2. GitHub → **Actions** → **Release** → **Run workflow** (branch `main`).
+3. Confirm the run created a GitHub Release + npm version with provenance.
+4. If nothing published: semantic-release found no releasable commits since the last tag (expected when only `chore`/`docs` landed).
+
+## First human publish and OIDC setup (do not do via this workflow alone)
+
+- First human `npm publish` (OTP), including bootstrap version / dist-tag so tags do not collide with later semantic-release versions
+- npm package settings → **Trusted Publisher** for `invertase/react-native-coverage` workflow `.github/workflows/release.yml`
+- Second publish via this Release workflow to prove OIDC + provenance
+
+## Rollback notes
+
+- npm: deprecate or unpublish only within npm policy; prefer a follow-up patch release.
+- Git: delete a mistaken `v*` tag only if it was never consumed; coordinate with maintainers.

package/docs.json

@@ -0,0 +1,24 @@
+{
+  "name": "react-native-coverage",
+  "description": "Native + JS/TS coverage tooling for React Native test apps",
+  "sidebar": [
+    {
+      "group": "Getting Started",
+      "pages": ["index", "pattern-c"]
+    },
+    {
+      "group": "Integration",
+      "pages": [
+        "integration/android",
+        "integration/ios",
+        "integration/js",
+        "integration/e2e-timing",
+        "integration/ci-appium"
+      ]
+    },
+    {
+      "group": "Reference",
+      "pages": ["cli", "config", "releasing"]
+    }
+  ]
+}

package/ios/Coverage.h

@@ -0,0 +1,5 @@
+#import <CoverageSpec/CoverageSpec.h>
+
+@interface Coverage : NSObject <NativeCoverageSpec>
+
+@end

package/ios/Coverage.mm

@@ -0,0 +1,47 @@
+#import "Coverage.h"
+#import "CoverageProfile.h"
+
+@implementation Coverage
+
+- (void)flush
+{
+  int status = CoverageFlushProfile();
+  if (status != 0) {
+    NSLog(@"[ios-native-coverage] TurboModule flush returned status=%d", status);
+  }
+}
+
+- (void)dumpJsCoverage:(NSString *)json
+{
+  NSArray<NSString *> *paths =
+      NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
+  NSString *docs = paths.firstObject;
+  if (docs == nil) {
+    NSLog(@"[ios-native-coverage] dumpJsCoverage: Documents directory missing");
+    return;
+  }
+  NSString *path = [docs stringByAppendingPathComponent:@"coverage-final.json"];
+  NSError *error = nil;
+  BOOL ok = [json writeToFile:path
+                   atomically:YES
+                     encoding:NSUTF8StringEncoding
+                        error:&error];
+  if (!ok) {
+    NSLog(@"[ios-native-coverage] dumpJsCoverage failed: %@", error);
+  } else {
+    NSLog(@"[ios-native-coverage] wrote JS coverage to %@", path);
+  }
+}
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params
+{
+  return std::make_shared<facebook::react::NativeCoverageSpecJSI>(params);
+}
+
++ (NSString *)moduleName
+{
+  return @"Coverage";
+}
+
+@end

package/ios/CoverageConfig.h

@@ -0,0 +1,21 @@
+/**
+ * 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 1
+static const char *const COVERAGE_FRAMEWORK_PREFIXES[] = {
+  "CoverageFixture"
+};
+#endif

package/ios/CoverageProfile.h

@@ -0,0 +1,22 @@
+#import <Foundation/Foundation.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Set LLVM_PROFILE_FILE / profile filename to Documents/coverage-%m.profraw. */
+void CoverageConfigureProfilePath(void);
+
+/**
+ * Mode (c) multi-image flush:
+ * - LINKEDIT dump for configured framework prefixes (e.g. CoverageFixture*)
+ * - LINKEDIT dump for MH_EXECUTE main
+ * - direct write for this Pod's own profile runtime last
+ *
+ * Returns 0 on success (at least one useful write), non-zero otherwise.
+ */
+int CoverageFlushProfile(void);
+
+#ifdef __cplusplus
+}
+#endif

package/ios/CoverageProfile.mm

@@ -0,0 +1,358 @@
+#import "CoverageProfile.h"
+#import "CoverageConfig.h"
+
+#import <mach-o/dyld.h>
+#import <mach-o/loader.h>
+#import <mach-o/nlist.h>
+#import <stdlib.h>
+#import <string.h>
+
+extern "C" {
+int __llvm_profile_write_file(void);
+void __llvm_profile_set_filename(const char *Name);
+const char *__llvm_profile_get_filename(void);
+}
+
+typedef int (*CoverageProfileWriteFn)(void);
+typedef void (*CoverageProfileSetFilenameFn)(const char *);
+
+typedef struct {
+  const struct mach_header *header;
+  intptr_t slide;
+  CoverageProfileWriteFn writeFile;
+  const char *imageName;
+} CoverageTrackedProfileImage;
+
+enum { CoverageMaxTrackedProfileImages = 64 };
+
+static CoverageTrackedProfileImage gCoverageTracked[CoverageMaxTrackedProfileImages];
+static uint32_t gCoverageTrackedCount = 0;
+
+/**
+ * `%m` expands to a unique module signature so each instrumented Mach-O image
+ * writes its own profraw instead of overwriting a single shared file.
+ */
+static NSString *CoverageProfilePattern(void)
+{
+  NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
+  return [[paths firstObject] stringByAppendingPathComponent:@COVERAGE_PROFILE_FILE_PATTERN];
+}
+
+/**
+ * clang_rt.profile symbols are linked into each instrumented framework as local
+ * (`t`) symbols — dlsym cannot see them. Resolve via the on-disk symbol table
+ * mapped through __LINKEDIT.
+ */
+static const void *CoverageFindSymbolInHeader(
+    const struct mach_header *header, intptr_t slide, const char *symbolName)
+{
+  if (header == NULL || symbolName == NULL) {
+    return NULL;
+  }
+  if (header->magic != MH_MAGIC_64 && header->magic != MH_CIGAM_64) {
+    return NULL;
+  }
+
+  const struct mach_header_64 *header64 = (const struct mach_header_64 *)header;
+  const uint8_t *cursor = (const uint8_t *)(header64 + 1);
+  const struct symtab_command *symtab = NULL;
+  const struct segment_command_64 *linkedit = NULL;
+
+  for (uint32_t i = 0; i < header64->ncmds; i++) {
+    const struct load_command *command = (const struct load_command *)cursor;
+    if (command->cmd == LC_SYMTAB) {
+      symtab = (const struct symtab_command *)command;
+    } else if (command->cmd == LC_SEGMENT_64) {
+      const struct segment_command_64 *segment = (const struct segment_command_64 *)command;
+      if (strcmp(segment->segname, SEG_LINKEDIT) == 0) {
+        linkedit = segment;
+      }
+    }
+    cursor += command->cmdsize;
+  }
+
+  if (symtab == NULL || linkedit == NULL || symtab->nsyms == 0) {
+    return NULL;
+  }
+
+  const uintptr_t linkeditBase =
+      (uintptr_t)slide + (uintptr_t)linkedit->vmaddr - (uintptr_t)linkedit->fileoff;
+  const char *strings = (const char *)(linkeditBase + symtab->stroff);
+  const struct nlist_64 *symbols =
+      (const struct nlist_64 *)(linkeditBase + symtab->symoff);
+  const size_t nameLength = strlen(symbolName);
+
+  for (uint32_t i = 0; i < symtab->nsyms; i++) {
+    uint32_t stringIndex = symbols[i].n_un.n_strx;
+    if (stringIndex == 0) {
+      continue;
+    }
+    const char *name = strings + stringIndex;
+    if (strncmp(name, symbolName, nameLength) != 0 || name[nameLength] != '\0') {
+      continue;
+    }
+    if ((symbols[i].n_type & N_TYPE) == N_UNDF || symbols[i].n_value == 0) {
+      continue;
+    }
+    return (const void *)((uintptr_t)symbols[i].n_value + (uintptr_t)slide);
+  }
+
+  return NULL;
+}
+
+static const char *CoverageImageNameForHeader(const struct mach_header *header)
+{
+  uint32_t imageCount = _dyld_image_count();
+  for (uint32_t index = 0; index < imageCount; index += 1) {
+    if (_dyld_get_image_header(index) == header) {
+      return _dyld_get_image_name(index);
+    }
+  }
+  return NULL;
+}
+
+static bool CoverageIsConfiguredFrameworkImage(const char *imageName)
+{
+  if (imageName == NULL) {
+    return false;
+  }
+#if !COVERAGE_ENABLED
+  return false;
+#endif
+  if (COVERAGE_FRAMEWORK_PREFIX_COUNT <= 0) {
+    return false;
+  }
+  const char *framework = strstr(imageName, ".framework");
+  if (framework == NULL) {
+    return false;
+  }
+  const char *basename = framework;
+  while (basename > imageName && basename[-1] != '/') {
+    basename -= 1;
+  }
+  for (int i = 0; i < COVERAGE_FRAMEWORK_PREFIX_COUNT; i++) {
+    const char *prefix = COVERAGE_FRAMEWORK_PREFIXES[i];
+    if (prefix == NULL) {
+      continue;
+    }
+    size_t prefixLen = strlen(prefix);
+    if (prefixLen > 0 && strncmp(basename, prefix, prefixLen) == 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * React Native / Expo Debug builds often place app + static-pod object code in
+ * `AppName.debug.dylib` (MH_DYLIB), not MH_EXECUTE. Flush that companion image
+ * via LINKEDIT so fixture/static-lib counters are not missed when Expo forces
+ * MACH_O_TYPE=staticlib on pods under use_frameworks.
+ */
+static bool CoverageIsAppCompanionDebugDylib(const char *imageName)
+{
+  if (imageName == NULL) {
+    return false;
+  }
+  if (strstr(imageName, ".app/") == NULL) {
+    return false;
+  }
+  return strstr(imageName, ".debug.dylib") != NULL;
+}
+
+static bool CoverageShouldTrackImage(const char *imageName)
+{
+  return CoverageIsConfiguredFrameworkImage(imageName) ||
+         CoverageIsAppCompanionDebugDylib(imageName);
+}
+
+static bool CoverageIsMainExecutable(const struct mach_header *header)
+{
+  return header != NULL && header->filetype == MH_EXECUTE;
+}
+
+static void CoverageSetFilenameOnImage(
+    const struct mach_header *header, intptr_t slide, const char *pattern)
+{
+  CoverageProfileSetFilenameFn setFilename =
+      (CoverageProfileSetFilenameFn)CoverageFindSymbolInHeader(
+          header, slide, "___llvm_profile_set_filename");
+  if (setFilename != NULL && pattern != NULL) {
+    setFilename(pattern);
+    return;
+  }
+  char **filenameVar = (char **)CoverageFindSymbolInHeader(
+      header, slide, "___llvm_profile_filename");
+  if (filenameVar != NULL && pattern != NULL) {
+    *filenameVar = (char *)pattern;
+  }
+}
+
+static void CoverageTrackProfileImage(const struct mach_header *header, intptr_t slide)
+{
+  const char *imageName = CoverageImageNameForHeader(header);
+  if (!CoverageShouldTrackImage(imageName)) {
+    return;
+  }
+
+  CoverageProfileWriteFn writeFile = (CoverageProfileWriteFn)CoverageFindSymbolInHeader(
+      header, slide, "___llvm_profile_write_file");
+  // Skip if missing or if it resolves to *this* Pod's runtime (not a distinct image).
+  if (writeFile == NULL || writeFile == __llvm_profile_write_file) {
+    NSLog(@"[ios-native-coverage] skip image (no distinct profile runtime): %s", imageName);
+    return;
+  }
+
+  for (uint32_t i = 0; i < gCoverageTrackedCount; i++) {
+    if (gCoverageTracked[i].writeFile == writeFile) {
+      return;
+    }
+  }
+
+  if (gCoverageTrackedCount >= CoverageMaxTrackedProfileImages) {
+    NSLog(@"[ios-native-coverage] tracked profile image cap reached (%d)",
+          CoverageMaxTrackedProfileImages);
+    return;
+  }
+
+  gCoverageTracked[gCoverageTrackedCount].header = header;
+  gCoverageTracked[gCoverageTrackedCount].slide = slide;
+  gCoverageTracked[gCoverageTrackedCount].writeFile = writeFile;
+  gCoverageTracked[gCoverageTrackedCount].imageName = imageName;
+  gCoverageTrackedCount += 1;
+  NSLog(@"[ios-native-coverage] tracked profile image[%u]: %s",
+        gCoverageTrackedCount - 1,
+        imageName);
+}
+
+static void CoverageOnAddImage(const struct mach_header *header, intptr_t slide)
+{
+  CoverageTrackProfileImage(header, slide);
+}
+
+__attribute__((constructor)) static void CoverageProfileInit(void)
+{
+  _dyld_register_func_for_add_image(CoverageOnAddImage);
+}
+
+static void CoverageRefreshTrackedFromDyld(void)
+{
+  uint32_t imageCount = _dyld_image_count();
+  for (uint32_t index = 0; index < imageCount; index += 1) {
+    CoverageTrackProfileImage(
+        _dyld_get_image_header(index), _dyld_get_image_vmaddr_slide(index));
+  }
+}
+
+static int CoverageFlushTracked(const char *pattern)
+{
+  int worstStatus = 0;
+  int wrote = 0;
+
+  for (uint32_t i = 0; i < gCoverageTrackedCount; i++) {
+    CoverageSetFilenameOnImage(
+        gCoverageTracked[i].header, gCoverageTracked[i].slide, pattern);
+    int status = gCoverageTracked[i].writeFile();
+    NSLog(
+        @"[ios-native-coverage] flush tracked[%u] status=%d image=%s",
+        i,
+        status,
+        gCoverageTracked[i].imageName ?: "(null)");
+    if (status != 0) {
+      worstStatus = status;
+    } else {
+      wrote += 1;
+    }
+  }
+
+  return wrote > 0 ? 0 : worstStatus;
+}
+
+static int CoverageFlushMainViaLinkedit(const char *pattern)
+{
+  uint32_t imageCount = _dyld_image_count();
+  for (uint32_t index = 0; index < imageCount; index += 1) {
+    const struct mach_header *header = _dyld_get_image_header(index);
+    intptr_t slide = _dyld_get_image_vmaddr_slide(index);
+    if (!CoverageIsMainExecutable(header)) {
+      continue;
+    }
+
+    const char *imageName = CoverageImageNameForHeader(header);
+    CoverageProfileWriteFn writeFile = (CoverageProfileWriteFn)CoverageFindSymbolInHeader(
+        header, slide, "___llvm_profile_write_file");
+    NSLog(
+        @"[ios-native-coverage] main-exe image=%s writeFile=%p podWriteFile=%p same=%d",
+        imageName ?: "(null)",
+        (void *)writeFile,
+        (void *)__llvm_profile_write_file,
+        writeFile == __llvm_profile_write_file ? 1 : 0);
+
+    if (writeFile == NULL) {
+      NSLog(@"[ios-native-coverage] main executable has no ___llvm_profile_write_file via LINKEDIT");
+      return -1;
+    }
+
+    CoverageSetFilenameOnImage(header, slide, pattern);
+    int status = writeFile();
+    NSLog(@"[ios-native-coverage] flush main-via-LINKEDIT status=%d", status);
+    return status;
+  }
+
+  NSLog(@"[ios-native-coverage] no MH_EXECUTE image found");
+  return -1;
+}
+
+extern "C" void CoverageConfigureProfilePath(void)
+{
+  const char *pattern = CoverageProfilePattern().UTF8String;
+  // Dynamic frameworks often lack set_filename (dead-stripped). getenv is consulted
+  // by every runtime copy on write.
+  setenv("LLVM_PROFILE_FILE", pattern, 1);
+  __llvm_profile_set_filename(pattern);
+  NSLog(
+      @"[ios-native-coverage] configure pattern=%@ podRuntimePath=%s",
+      CoverageProfilePattern(),
+      __llvm_profile_get_filename() ?: "(null)");
+}
+
+/**
+ * Mode (c): Pod LINKEDIT for configured frameworks + main executable, then pod write.
+ * Prefer this under use_frameworks! :linkage => :dynamic (05S1 verdict).
+ */
+extern "C" int CoverageFlushProfile(void)
+{
+#if !COVERAGE_ENABLED
+  NSLog(@"[ios-native-coverage] flush skipped (COVERAGE_ENABLED=0)");
+  return -1;
+#endif
+
+  CoverageConfigureProfilePath();
+  CoverageRefreshTrackedFromDyld();
+  const char *pattern = getenv("LLVM_PROFILE_FILE");
+
+  int trackedStatus = CoverageFlushTracked(pattern);
+  int mainStatus = CoverageFlushMainViaLinkedit(pattern);
+  int podStatus = __llvm_profile_write_file();
+
+  NSLog(
+      @"[ios-native-coverage] flush complete tracked=%u trackedStatus=%d mainStatus=%d podStatus=%d pattern=%s",
+      gCoverageTrackedCount,
+      trackedStatus,
+      mainStatus,
+      podStatus,
+      pattern ?: "(null)");
+
+  int okTracked = (trackedStatus == 0 && gCoverageTrackedCount > 0) ? 1 : 0;
+  int okMain = (mainStatus == 0) ? 1 : 0;
+  // Under Expo static-pod merge, fixture counters live in the same image as this
+  // Pod's profile runtime — pod write is the success path.
+  int okPod = (podStatus == 0) ? 1 : 0;
+  if (okTracked || okMain || okPod) {
+    return 0;
+  }
+  if (mainStatus != 0) {
+    return mainStatus;
+  }
+  return trackedStatus != 0 ? trackedStatus : podStatus;
+}

package/lib/module/NativeCoverage.js

@@ -0,0 +1,10 @@
+"use strict";
+
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * TurboModule surface for native coverage flush (New Architecture only).
+ */
+
+export default TurboModuleRegistry.getEnforcing('Coverage');
+//# sourceMappingURL=NativeCoverage.js.map

package/lib/module/NativeCoverage.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["TurboModuleRegistry","getEnforcing"],"sourceRoot":"../../src","sources":["NativeCoverage.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAA0B,cAAc;;AAEpE;AACA;AACA;;AAWA,eAAeA,mBAAmB,CAACC,YAAY,CAAO,UAAU,CAAC","ignoreList":[]}