All jobs

Replace nyc with c8 for Code Coverage in a Node.js Library

Yes. The agent swaps the two commands, keeps the lcov file CI uploads, and reports how the percentages move, because V8 and Istanbul count differently.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

Swapping one coverage tool for another is two edited lines, and the agent treats those lines as the easy part. It begins with where nyc is wired in. In a library like forwardemail/supertest that is two scripts in package.json: test is nyc --reporter=html --reporter=text mocha --exit --require should --reporter spec --check-leaks, and coverage is nyc report --reporter=text-lcov > coverage.lcov. There is no .nycrc and no nyc key in package.json, so every option is on those command lines. .github/workflows/ci.yml runs npm test, then npm run coverage, then codecov/codecov-action@v3, which picks up the coverage.lcov the second script writes. .gitignore has a section for coverage, *.lcov and .nyc_output. Nothing sets a threshold, and no source file has an istanbul ignore comment.

Then it takes the baseline, since the number is what the change will be judged by. With nyc 15.1.0 the suite's 137 tests pass and the summary line reads 93.29 percent of statements, 90.69 of branches, 94.36 of functions and 94.44 of lines, over five files: index.js and four under lib/. The agent saves that table and the list of files in the lcov output.

Choosing the c8 version is a compatibility question, not a matter of taking the latest. When this page was written c8 12 required Node ^20.19.0 || ^22.12.0 || >=23, and the workflow matrix runs Node 18, 20, 22 and 24. c8 10 declares >=18 and is the newest major that every job can install, so the agent installs that one and says why. c8 accepts the same --reporter flags and the same report subcommand, so both scripts keep their shape with one word changed. It runs the suite: 137 tests pass, and the lcov file lists the same five files. Mocha's --exit does not get in the way; V8 still writes its coverage data when the process ends.

The numbers are where a reviewer needs help. c8 reports 96.58, 92.43, 95.34 and 96.58, higher on every column, with no test added. The agent explains this without presenting it as an improvement. nyc rewrites each file to count statements, while c8 reads byte ranges from V8 and maps them to lines, which is why its statement and line figures are equal. The uncovered line lists differ too: for lib/test.js nyc lists 40-43,83-85,245,252,257 and c8 lists 17-18,40-45,83-85,245-246,252,257, the same gaps plus the closing lines of the blocks around them. Last, it removes nyc and reads the lockfile diff: 102 packages go, @babel/core and Istanbul's instrumenter among them, and c8's raw data now lands in coverage/tmp, which the existing ignore rule already covers.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Replace nyc with c8 for coverage in this repository. First find every place nyc is configured or called: package.json scripts and any nyc key, .nycrc files, .gitignore, .github/workflows, and source comments that start with istanbul ignore. Run the current test and coverage scripts and save the summary table, the list of files in the lcov output, and the test count. Choose the c8 version by reading engines.node for its recent majors and comparing them with every Node version in the workflow matrix and with engines in package.json; install the newest major that all of them can run and state the reasoning. Replace nyc with c8 in the scripts, keeping the same reporters and the same output file name and location, so the upload step in CI needs no change. Carry over any thresholds, include and exclude patterns from the nyc config to c8's equivalents; if there are istanbul ignore comments, list them and convert them to the c8 form. Run the scripts again. The test count must match, and the lcov output must list the same source files; if a file is missing or new, explain it. Put the two summary tables side by side and explain each difference in terms of how the two tools measure, without describing a higher number as an improvement. If a threshold exists and the new figures cross it in either direction, do not change the threshold; report it. Uninstall nyc, and report how many packages left the lockfile. Remove ignore entries that only nyc needed. Open a pull request with the tables, the version choice, and anything a coverage service will see as a step change.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that changes two scripts and one devDependency in package.json, the lockfile, and one line of .gitignore. The workflow file is untouched, because the coverage script still writes coverage.lcov in the place the upload step reads. The lockfile diff is the large part, and almost all of it is deletion.

The description leads with the two tables, nyc's and c8's, row by row for each file, followed by a short account of why they differ. That paragraph is there for whoever watches the coverage service: the first upload after the merge will show a jump of a few points on a commit that changed no tests, and the pull request says in advance that this is a change of ruler. If the project had a threshold, the description says which side of it each figure falls on and leaves the threshold alone.

A reviewer checks three things before merging: the test count is unchanged, the lcov output names the same source files as before, and the c8 major chosen runs on the oldest Node in the matrix. The description gives the engines.node range it read for each candidate version, so the last check is a comparison of two lines.

Run it on every repository still on nyc

Nobody schedules this job; someone notices the size of the dependency tree, or a Babel advisory against a package only nyc pulls in, and wants it gone. They send this body to POST /o/{org}/sessions from a terminal or an MCP client with a request_id that is a UUID made for the job, and the pull request is on the session when the run completes.

The same change usually applies to every package a team maintains. A script sends the body once per repository, each with a request_id that is a UUID v5 of the repository's full name, so a second run of the script starts nothing new. The key queues what it cannot run at once, and its webhook_url receives run.completed for each run it started. Repositories with thresholds or ignore comments come back with those called out, which separates the ones that merge on sight from the ones that need a decision.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The edit is small enough that it is tempting to make it blind, and that is how a coverage figure moves three points with nobody able to say why. Doing it properly means two full runs, two saved tables, a comparison of file lists and a read of the lockfile diff. In the run's sandbox the agent does each of those on a clean install, and the commands and their output are kept in the transcript at GET /o/{org}/sessions/{id}/messages.

It is also a chore that sits below everything else on a developer's list. Handing it to a run costs one request, and what comes back is a pull request that explains its own side effect. If the reviewer would prefer the other c8 major, a follow-up to POST /o/{org}/sessions/{id}/messages wakes the same sandbox with both runs' output still on disk.

Frequently asked questions

Why did coverage go up when no tests changed?

The two tools measure different things. nyc instruments the source and counts statements; c8 reads the ranges V8 recorded and maps them to lines. In forwardemail/supertest the same 137 tests give 93.29 percent of statements under nyc and 96.58 under c8. Neither is wrong, but the two series should not be compared across the switch.

Does c8 work with Mocha's --exit flag and with proxyquire?

In this fixture, yes to both. V8 writes its coverage data when the process ends, including when Mocha ends it, and c8 does not rewrite modules, so loaders that patch require are unaffected. The agent confirms it by checking that the lcov output lists every source file it listed before.

What happens to istanbul ignore comments?

c8 does not read them; its own form is /* c8 ignore next */ and related hints. The agent lists every Istanbul comment it finds and converts each one, since a comment left in the old form silently stops excluding its code. The fixture above has none.

Do I need to change my Codecov or Coveralls setup?

Not if the report keeps its format and path. c8 writes lcov with the same --reporter=text-lcov flag nyc used, so a script that redirects it to coverage.lcov produces a file the upload step already finds. Expect the service to show a step on the first upload.

More jobs like this: Hand off a long task

Keep reading