diff --git a/.agents/skills/integrate-react-native-coverage/SKILL.md b/.agents/skills/integrate-react-native-coverage/SKILL.md new file mode 100644 index 0000000..b6e4048 --- /dev/null +++ b/.agents/skills/integrate-react-native-coverage/SKILL.md @@ -0,0 +1,14 @@ +--- +name: integrate-react-native-coverage +description: Add react-native-coverage to a dedicated React Native test harness. Reads the app developers page and does not copy it. Use when installing native coverage into an app. +metadata: + audience: integrator +--- + +# Integrate react-native-coverage + +You are adding this package to a project. You are not changing the react-native-coverage repository. + +Read https://docs.page/invertase/react-native-coverage/app-developers and follow that page. Do not copy the page into this skill. If this skill and that page disagree, the page wins. + +Do not clone invertase/react-native-coverage. Do not open that repo's `AGENTS.md`, `CONTRIBUTING.md`, or `okf-bundle/`. diff --git a/.gitignore b/.gitignore index 0c6aada..e48a95b 100644 --- a/.gitignore +++ b/.gitignore @@ -75,8 +75,10 @@ android/keystores/debug.keystore # Turborepo .turbo/ -# Agent / ephemeral local notes -.agents/ +# Agent / ephemeral local notes. The install skill is the one tracked file. +.agents/* +!.agents/skills/ +!.agents/skills/** # CI / local e2e artifacts (logs, LCOV, Jacoco) artifacts/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eac1af4..e4df1a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,128 +1,85 @@ # Contributing -Contributions are always welcome, no matter how large or small! +Two different jobs land in this repository. Do not mix them. -This package targets **dedicated test apps only** (Pattern C). See `docs/pattern-c.md` and `AGENTS.md`. +| Who | Start here | Do not | +|---|---|---| +| Someone adding the package to an app | [App developers](https://docs.page/invertase/react-native-coverage/app-developers) | This file, root `AGENTS.md`, `okf-bundle/` | +| Someone changing this repository | This file, then root `AGENTS.md` | The README Quick Prompt. That prompt installs the package into a harness. It is not how you develop this repo. | -License: Apache-2.0. Please follow the [code of conduct](./CODE_OF_CONDUCT.md). +Questions: [Discord](https://invertase.link/discord). -## Development workflow +Behaviour: [Invertase Code of Conduct](https://github.com/invertase/.github/blob/main/CODE_OF_CONDUCT.md). Report conduct issues to oss@invertase.io. The copy of `CODE_OF_CONDUCT.md` in this repository still has a placeholder contact. Use the org file. -This project is a monorepo managed using [Yarn workspaces](https://yarnpkg.com/features/workspaces). It contains the following packages: +## Report a bug -- The library package in the root directory. -- An example app in the `example/` directory. +Open a [bug report](https://github.com/invertase/react-native-coverage/issues/new/choose). The template asks for the library version, `react-native info`, and the steps. -To get started with the project, make sure you have the correct version of [Node.js](https://nodejs.org/) installed. See the [`.nvmrc`](./.nvmrc) file for the version used in this project. +## Request a feature -Run `yarn` in the root directory to install the required dependencies for each package: +Open an [issue](https://github.com/invertase/react-native-coverage/issues/new/choose). GitHub Discussions are off for this repository, so do not send people there. -```sh -yarn -``` - -> Since the project relies on Yarn workspaces, you cannot use [`npm`](https://github.com/npm/cli) for development without manually migrating. - -The [example app](/example/) demonstrates usage of the library. You need to run it to test any changes you make. - -It is configured to use the local version of the library, so any changes you make to the library's source code will be reflected in the example app. Changes to the library's JavaScript code will be reflected in the example app without a rebuild, but native code changes will require a rebuild of the example app. - -If you want to use Android Studio or Xcode to edit the native code, you can open the `example/android` or `example/ios` directories respectively in those editors. To edit the Objective-C or Swift files, open `example/ios/CoverageExample.xcworkspace` in Xcode and find the source files at `Pods > Development Pods > react-native-coverage`. - -To edit the Java or Kotlin files, open `example/android` in Android studio and find the source files at `react-native-coverage` under `Android`. - -You can use various commands from the root directory to work with the project. - -To start the packager: - -```sh -yarn example start -``` - -To run the example app on Android: - -```sh -yarn example android -``` - -To run the example app on iOS: - -```sh -yarn example ios -``` - -To confirm that the app is running with the new architecture, you can check the Metro logs for a message like this: - -```sh -Running "CoverageExample" with {"fabric":true,"initialProps":{"concurrentRoot":true},"rootTag":1} -``` +For an API or behaviour change, open that issue before the pull request. -Note the `"fabric":true` and `"concurrentRoot":true` properties. +## Set up -Make sure your code passes TypeScript: +Node.js `v24.13.0` (`.nvmrc`). This monorepo uses Yarn `4.11.0` (`packageManager` in `package.json`). Do not use npm to install the workspace. ```sh +yarn +yarn prepare +yarn test yarn typecheck -``` - -To check for linting errors, run the following: - -```sh yarn lint +node bin/rn-coverage.js --help ``` -To fix formatting errors, run the following: +`yarn test` is the unit suite. Run an end-to-end cell when the change touches the harness, the native flusher, or the pull/assert path: ```sh -yarn lint --fix +yarn e2e:ios:dynamic +yarn e2e:ios:static +yarn e2e:android ``` -Unit tests (path rewrite, config, LCOV helpers): +The example apps are `example/` (Expo, iOS static) and `example-dynamic/` (bare React Native, dynamic frameworks). How to open them is in `example/README.md` and `example-dynamic/README.md`. From the root, `yarn example start`, `yarn example android`, and `yarn example ios` drive the Expo example. Native edits need a rebuild of that app. -```sh -yarn test -``` +This package belongs in those harness apps, not in a shipping app. Autolinking reads dependencies, so `devDependencies` in a product app is not a safe place for it. -CLI smoke: +## Open a pull request -```sh -yarn prepare -node bin/rn-coverage.js --help -``` +There is no pull request template in this repository yet. The title is the check. -### Scripts +- One change per pull request. +- Title is a [Conventional Commit](https://www.conventionalcommits.org/), lowercase subject. CI enforces this (`.github/workflows/pr-title.yml`). Squash merge so the title becomes the release commit. +- Check locally: `echo "feat: your subject" | yarn commitlint` -The `package.json` file contains various scripts for common tasks: +Examples: -- `yarn`: setup project by installing dependencies. -- `yarn typecheck`: type-check files with TypeScript. - - `yarn lint`: lint files with [ESLint](https://eslint.org/). - - `yarn example start`: start the Metro server for the example app. -- `yarn example android`: run the example app on Android. -- `yarn example ios`: run the example app on iOS. - -### Sending a pull request +- `feat: add ios summary JSON schema` +- `fix: exit 2 when fixture LCOV is empty` +- `docs: document Pattern C consumer checklist` +- `chore: bump Appium in e2e workspace` -> **Working on your first pull request?** You can learn how from this _free_ series: [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github). +## What else changes with the code -When you're sending a pull request: +- Behaviour that a user follows: update the page under `docs/`. The site is that tree. +- Public install or the harness-only limit: update `README.md`. +- Tests: `yarn test` for the unit suite, and an e2e cell when the flush or assert path changes. +- Changelog: do not hand-edit `CHANGELOG.md`. semantic-release writes it from the squash-merged pull request title when someone runs the manual release workflow. -- Prefer small pull requests focused on one change. -- Verify that linters and tests are passing. -- Review the documentation to make sure it looks good. -- Follow the pull request template when opening a pull request. -- For pull requests that change the API or implementation, discuss with maintainers first by opening an issue. -- Use a [Conventional Commits](https://www.conventionalcommits.org/) **PR title** (enforced by CI). Prefer squash merges so the title becomes the release commit. +## Release -#### PR title examples +Maintainers only. Releases are manual (`workflow_dispatch`). Steps: [Releasing](https://docs.page/invertase/react-native-coverage/releasing). Do not publish from a laptop. -- `feat: add ios summary JSON schema` -- `fix: exit 2 when fixture LCOV is empty` -- `docs: document Pattern C consumer checklist` -- `chore: bump Appium in e2e workspace` +## Agents changing this repo -Local check: `echo "feat: your subject" | yarn commitlint` +An agent with this repository open is a maintainer agent. Read root `AGENTS.md` after this file. `AGENTS.md` names the workspaces, the test commands, and `okf-bundle/` for how this repo is validated. -### Releasing +- Do not follow the README line that says `Read https://docs.page/invertase/react-native-coverage/app-developers`. That is for an agent inside someone else's app. +- Do not clone this guidance into an app, and do not add `react-native-coverage` to a product `package.json`. +- Do not open a pull request whose title is not a Conventional Commit. The title is the changelog entry. +- Do not edit `CHANGELOG.md` by hand. +- Do not dispatch a release unless the task is explicitly a release. Publishing is a human workflow. -Maintainers: see [docs/releasing.md](./docs/releasing.md). Releases are **manual** (`workflow_dispatch` + semantic-release). Do not publish from a laptop unless performing the one-time human bootstrap (separate from day-to-day CI releases). +If the task is "add coverage to an app", stop using this file and follow the app developers page instead. diff --git a/README.md b/README.md index d0bb866..c51d1aa 100644 --- a/README.md +++ b/README.md @@ -7,16 +7,30 @@

Code coverage for React Native — Typescript, iOS, and Android — without touching the native stuff.

+ npm downloads + npm version Codecov Docs New Architecture only Apache-2.0

+**react-native-coverage** is a React Native library for **iOS and Android** that produces native and TypeScript coverage from end-to-end runs in a dedicated test app. +

Install it into a dedicated test / e2e harness app (Pattern C) — never your shipping app.

+## Quick Prompt + +**Prompt your agent:** + +```txt +Read https://docs.page/invertase/react-native-coverage/app-developers, and set up react-native-coverage in this project. +``` + +**Or set it up yourself:** follow [App developers](https://docs.page/invertase/react-native-coverage/app-developers), or the [Install](#install) section below. +

A TurboModule flushes real device coverage; the CLI pulls it, merges every framework's .profraw and the app binary into clean LCOV / Jacoco, and remaps your instrumented JS line-for-line back to TypeScript. Use that as a signal in your development loop or CI to gate development iterations or CI pass/fail.

@@ -105,36 +119,9 @@ pattern this README describes. --- -## Have your agent wire it up - -Paste this into your coding agent (Cursor, Claude, Codex, …) **before** you touch Gradle or -Podfiles by hand: - -```text -Integrate react-native-coverage into this repo's dedicated React Native test / -e2e harness app only (Pattern C — never the production app package.json). - -Constraints: -- New Architecture / TurboModule only -- Follow https://docs.page/invertase/react-native-coverage -- Prefer the Expo config plugin when the harness is Expo; otherwise use the bare - Gradle + CocoaPods Ruby helpers from the integration docs -- Wire libraryProjectMatchers / frameworkNamePrefixes for every native library - we need hits from -- Add CI steps that pull coverage and fail with rn-coverage assert (exit 2) - when hits are empty -- Do not invent product-app install paths; keep the package out of the shipping app - -After install: yarn/npm add react-native-coverage in the harness, apply the plugin or -manual hooks, prebuild / pod install as needed, then show me the exact CI commands -to run and what green looks like. -``` - ---- - ## Install -Install in the **harness** (your dedicated test/e2e app), never the product app: +**Or set it up yourself.** Install in the **harness** (your dedicated test/e2e app), never the product app. The same steps are on [App developers](https://docs.page/invertase/react-native-coverage/app-developers). ```sh yarn add react-native-coverage @@ -253,15 +240,23 @@ Conventional Commits + semantic-release, **manual `workflow_dispatch` only** (no push-to-main publish). Operator steps: [docs → Releasing](https://docs.page/invertase/react-native-coverage/releasing). +## Contributing + +- [Issues](https://github.com/invertase/react-native-coverage/issues) +- [Pull requests](https://github.com/invertase/react-native-coverage/pulls) +- [Contributing guide](./CONTRIBUTING.md) +- [Code of Conduct](https://github.com/invertase/.github/blob/main/CODE_OF_CONDUCT.md) + ## License Apache-2.0 — see [LICENSE](./LICENSE).

-
- - Invertase + + Invertase -
- Built and maintained by Invertase. +

+ +

+ Built and maintained by Invertase.