supercov 3.0.4 → 3.0.5

package/docs/cli.md

@@ -142,14 +142,14 @@ npx supercov runs <run-id> [query] [options]
 | --- | --- |
 | no query | Read the overall result, test outcome, completeness, and timings |
 | `gaps` | See only files with uncovered behavior or measurement limits |
-| `files` | See every included file, including fully covered files |
+| `files` | See every included file, including fully covered files; `--group dir` shows coverage by directory, split by test kind |
 | `file <path>` | Inspect the open obligations in one file |
 | `decision <id \| path:line>` | Understand missing boolean outcomes and MC/DC witnesses |
 | `line <path:line>` | See one line's state, obligations, and covering tests |
 | `test <id \| name>` | See the coverage attributed to one test |
 | `kinds` | Group coverage by test level, such as unit or E2E |
 | `runners` | Group coverage by test runner |
-| `scope` | Review included, excluded, and ambiguous source files |
+| `scope` | See what is source and what is not, by directory and reason; `--files` lists every file |
 | `assertions` | Read the share of executed statements the tests assert, and the ones they do not; `assertions assess` works it out |
 | `source <path>` | Read matching current project source with line numbers |
 | `minimize` | Find a small test subset that preserves a coverage target |
@@ -164,6 +164,27 @@ npx supercov runs latest line app/routes/checkout.ts:57
 npx supercov runs latest test "checkout retry"
 ```
 
+To see where the coverage is, read it by directory. Each row is a directory,
+with what it holds and how much of it each kind of test covers; `--depth`
+keeps more levels, and `--metric` picks branches, functions, statements or
+MC/DC instead of lines:
+
+```sh supercov
+npx supercov runs latest files --group dir
+npx supercov runs latest files --group dir --depth 2 --metric branches
+```
+
+```
+Directory   Files  Lines     e2e    unit      All
+app             4     15  86.67%   0.00%  100.00%
+lib             1     10  90.00%  40.00%   90.00%
+components      1      2 100.00%   0.00%  100.00%
+```
+
+In `--json`, every file of `files` and `gaps` carries `totals` and `covered`
+for each metric beside what is missing, so a percentage can be worked out for
+any file or set of files.
+
 Run any query with `--help` to see only the options valid for that query:
 
 ```sh supercov
@@ -509,6 +530,7 @@ terminal or offline environment after the package has been downloaded.
 | --- | --- |
 | `SUPERCOV_SOURCE_ROOTS` | Comma-separated directories or files that hold your own code, in any language; everything else is left out |
 | `SUPERCOV_TEST_KIND` | Label the wrapped command as a test level such as `unit` or `e2e` |
+| `SUPERCOV_KEEP_WORKSPACE` | Set to `1` to leave the instrumented copy of the project in `.supercov/workspaces/` after the run, to inspect what the command ran. It is kept without this when the build Supercov runs before the tests fails |
 | `SUPERCOV_BUILD_COMMAND` | The build a JavaScript project's tests need, as words or a JSON array, such as `yarn workspace web build` in a monorepo whose root `build` builds every package. Without it Supercov runs the project's `build` script, through the package manager that started the tests, when the tests need built output |
 
 Examples:

package/docs/coverage-model.md

@@ -94,6 +94,18 @@ Both are useful:
 - exact evidence helps you inspect or minimize individual tests;
 - aggregate evidence still shows whether the whole suite reached the source.
 
+Code that runs while no test is running counts in the run's total and in no
+test's: a server starting before the first test, modules loading, work between
+tests. When a run has any, the summary's `By test kind` table ends with a
+`no test` row for what only that covered, which is why a run with one kind of
+test can show a total above that kind's own:
+
+```
+By test kind
+  e2e             3 test(s)  lines  80.00%  branches  66.67%  MC/DC  25.00%
+  no test                    lines  17.14%  branches   0.00%  MC/DC   0.00%
+```
+
 See [Supported suites](supported-suites.md) for the attribution available from
 each runner.
 
@@ -128,6 +140,17 @@ If the summary reports ambiguous source scope, inspect it:
 npx supercov runs latest scope
 ```
 
+It prints the scope by directory and reason, the ambiguous places first, and
+the `SUPERCOV_SOURCE_ROOTS` value that would settle them. The summary names
+the same places under `Instrumentation`. Add `--files` to list every file.
+
+```
+Files  Status     Directory   Reason
+   79  AMBIGUOUS  components  unclassified first-party source
+  227  INCLUDED   app         discovered package source root
+  311  EXCLUDED   tests       test or fixture source
+```
+
 When first-party source lives in unusual directories, declare it explicitly:
 
 ```sh supercov
@@ -145,6 +168,20 @@ without a conventional source directory is measured as a whole. Functions passed
 to compile-time style macros (`stylex.create(...)`) are left as written because
 the bundler consumes them at build time; nothing about them runs.
 
+Inside the roots, tests, fixtures, tool scripts and configuration files are
+still recognised by their path and left out. A root you name settles what it
+names: with `SUPERCOV_SOURCE_ROOTS=src,scripts` the `scripts/` directory is
+source, and so is `src/test-utils` when it is named as a root. Only what lies
+below a named root is still judged by its path, and a root that is a single
+file is always measured.
+
+In a Next.js application, root `components/` and `pages/`, and the root files
+Next.js reads by name (`proxy`, `middleware`, `instrumentation`) are source
+without being declared. Under `app/` a folder is a URL segment, so the files
+the App Router serves (`route.ts`, `page.tsx`, `layout.tsx` and the rest) are
+source whatever their folders are called: `app/api/wordpress/test/route.ts` is
+the handler of `/api/wordpress/test`, not a test.
+
 Choose roots that describe code the repository owns. Do not include dependencies
 or generated output merely to make a warning disappear.
 

package/docs/troubleshooting.md

@@ -32,7 +32,8 @@ unusual directory, declare the source roots explicitly:
 SUPERCOV_SOURCE_ROOTS=src,app npx supercov -- npm test
 ```
 
-Then inspect what Supercov included and excluded:
+Then inspect what Supercov included and excluded, by directory, or file by
+file with `--files`:
 
 ```sh supercov
 npx supercov runs latest scope
@@ -41,6 +42,10 @@ npx supercov runs latest scope
 Do not broaden the roots to dependencies or generated output merely to remove a
 warning. The goal is an honest boundary around code the repository owns.
 
+A file `scope` lists as `test or fixture source` or `conventional tool script`
+was recognised by its path. If it is your code, name its directory, or the file
+itself, as a root: a named root is source whatever it is called.
+
 ## Too much is measured
 
 Vendored or generated code beside your own is measured like the rest of the

package/docs/workspace-isolation.md

@@ -34,6 +34,8 @@ and the instrumented copy is not what you wrote:
 
 - Linters, formatters and `tsc --noEmit` (ESLint, Prettier, standard, xo and
   the like) read each file as you wrote it, and don't see `.supercov`.
+- The type check `next build` runs reads each file as you wrote it too, while
+  the build itself compiles the instrumented copy.
 - Coverage tools the command runs itself (tap, c8, nyc, Jest's and Vitest's
   `--coverage`) still collect and report coverage. They measure the
   instrumented copy, and report close to what they report without Supercov,
@@ -42,12 +44,23 @@ and the instrumented copy is not what you wrote:
 
 Files the wrapped command creates or changes inside the isolated workspace are
 synced back to the project after the run, so `supercov -- npm test -- -u`
-updates snapshots in the repository exactly as `npm test -- -u` would. Two
+updates snapshots in the repository exactly as `npm test -- -u` would. Three
 exceptions are reported instead of applied: changes the command makes to
 instrumented source files (the instrumented copies must never overwrite your
-sources) and deletions (never propagated automatically). Changes inside any
-`node_modules` directory are neither applied nor reported: dependency trees are
-not command outputs.
+sources), a build the command made from them, and deletions (never propagated
+automatically). Such a build stays behind whole: when a file in `.next/`,
+`dist/` or another directory that git ignores or the project does not have was
+built from instrumented source, nothing in that directory is copied, so the
+project never holds an instrumented build. Changes inside any `node_modules`
+directory are neither applied nor reported: dependency trees are not command
+outputs.
+
+The run prints where the synced files went, what stayed behind and what the
+command deleted, by top-level directory (`test-results/ 6`, `.next/ 2547`).
+
+When the build Supercov runs before the tests fails, the instrumented copy is
+left in `.supercov/workspaces/` until the next run, and the run prints its
+path. `SUPERCOV_KEEP_WORKSPACE=1` leaves it after any run.
 
 ## Files Supercov creates
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supercov",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "Coverage, security and code quality for coding agents",
   "keywords": [
     "coverage",
@@ -66,6 +66,7 @@
     "sync:rust-assets": "node scripts/sync-rust-package-assets.mjs",
     "test:rust-assets": "node scripts/sync-rust-package-assets.mjs --check",
     "test": "cargo test --workspace",
+    "test:next-playwright": "cargo build -p supercov && npm --prefix tests/fixtures/next-playwright ci && node scripts/next-playwright-integration.mjs",
     "test:react": "cargo build -p supercov && node scripts/rust-vitest-projects-integration.mjs && npm --prefix examples/react-verification ci && npm --prefix examples/react-verification run demo && node scripts/react-hydration-compatibility.mjs",
     "test:release-tooling": "node --test tests/release/*.test.mjs",
     "test:runtime": "node --test tests/runtime/*.test.mjs",
@@ -118,14 +119,14 @@
     "test:windows-tls": "node scripts/windows-tls-test.mjs"
   },
   "optionalDependencies": {
-    "@supercov/cli-darwin-arm64": "3.0.4",
-    "@supercov/cli-darwin-x64": "3.0.4",
-    "@supercov/cli-linux-arm64-gnu": "3.0.4",
-    "@supercov/cli-linux-arm64-musl": "3.0.4",
-    "@supercov/cli-linux-x64-gnu": "3.0.4",
-    "@supercov/cli-linux-x64-musl": "3.0.4",
-    "@supercov/cli-win32-arm64": "3.0.4",
-    "@supercov/cli-win32-x64": "3.0.4"
+    "@supercov/cli-darwin-arm64": "3.0.5",
+    "@supercov/cli-darwin-x64": "3.0.5",
+    "@supercov/cli-linux-arm64-gnu": "3.0.5",
+    "@supercov/cli-linux-arm64-musl": "3.0.5",
+    "@supercov/cli-linux-x64-gnu": "3.0.5",
+    "@supercov/cli-linux-x64-musl": "3.0.5",
+    "@supercov/cli-win32-arm64": "3.0.5",
+    "@supercov/cli-win32-x64": "3.0.5"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",

package/runtime/javascript/register.mjs

@@ -178,6 +178,24 @@ const isAnalysisEntrypoint = new RegExp(`/node_modules/(?:\\.bin/(?:${analysisTo
         process.argv.includes("--noEmit"));
 if (isAnalysisEntrypoint)
     installAuthoredSourceView();
+// `next build` type-checks in a worker of its own instead of running tsc. A
+// probe in a condition stops TypeScript narrowing through it, so an inferred
+// return type widens, and a file outside the source roots that calls the
+// function fails the build on code nobody wrote ("'client' is possibly
+// 'null'"). Only that worker gets the authored view: the bundler, and `next
+// dev`, which sets TypeScript up in its main process, must read the copies.
+else if (/\/node_modules\/next\/dist\/compiled\/jest-worker\/processChild\.js$/.test(entrypoint) ||
+    (!workerThreads.isMainThread && /\/node_modules\/(?:\.bin\/next$|next\/dist\/)/.test(entrypoint))) {
+    const compile = Module.prototype._compile;
+    let installed = false;
+    Module.prototype._compile = function _compile(content, filename, ...rest) {
+        if (!installed && /[\\/]next[\\/]dist[\\/]lib[\\/]verify-typescript-setup\.js$/.test(filename)) {
+            installed = true;
+            installAuthoredSourceView();
+        }
+        return Reflect.apply(compile, this, [content, filename, ...rest]);
+    };
+}
 function installAuthoredSourceView() {
     let authored;
     try {

package/runtime/javascript/runtime.mjs

@@ -890,7 +890,7 @@ function cleanInstrumentationStack(error) {
   if (!error || typeof error !== "object" || typeof error.stack !== "string")
     return error;
   const lines = error.stack.split("\n");
-  const visible = lines.filter((line, index) => index === 0 || !/[\\/]\.supercov[\\/](?:playwright|nodeTest|vitest|runtime|launchSupervisor|nodeAssert|nodeAssertStrict|nodeAssertAdapter|register|resolve-loader)\.(?:js|mjs)(?::|\))/u.test(line));
+  const visible = lines.filter((line, index) => index === 0 || !/[\\/]\.supercov[\\/](?:node_modules[\\/])?(?:playwright|nodeTest|vitest|runtime|launchSupervisor|nodeAssert|nodeAssertStrict|nodeAssertAdapter|register|resolve-loader)\.(?:js|mjs)(?::|\))/u.test(line));
   if (visible.length !== lines.length) {
     try {
       error.stack = visible.join("\n");