supercov 3.0.5 → 4.0.1

package/docs/cli.md

@@ -530,8 +530,8 @@ 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 |
+| `SUPERCOV_SOURCE_TOOLS` | Comma-separated names of tools the test command runs that read source as text, such as a linter or a spell checker, besides Biome, oxlint, dprint, cspell and knip. Each is run on your source as you wrote it instead of on the instrumented copy |
+| `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 |
 
 Examples:
 

package/docs/performance.md

@@ -1,8 +1,9 @@
 # Speed and storage
 
-A Supercov run includes your test command, an instrumented build, and evidence
-publication. The first pass is usually the slowest; repeated passes can reuse
-the isolated build when the relevant inputs have not changed.
+A Supercov run includes your test command and evidence publication, and for a
+compiled language an instrumented build, which repeated passes can reuse when
+the relevant inputs have not changed. A JavaScript project has no such build:
+the command runs as given, and a build inside it is part of the command's time.
 
 ## See where the time went
 
@@ -17,7 +18,7 @@ The summary separates:
 | Initialization | Recovery, project discovery, and input checks |
 | Workspace preparation | Refreshing the isolated project copy |
 | Adapter setup | Preparing the runner integration |
-| Instrumented build | Building measured source, or almost nothing on a cache hit |
+| Instrumented build | Building measured source for a compiled language, or almost nothing on a cache hit; 0 for JavaScript |
 | Test command | The wrapped command, including browser, VM, or remote latency |
 | Evidence publication | Validating and storing the completed run |
 
@@ -41,7 +42,9 @@ before Supercov starts and is not coverage-engine overhead.
 
 Supercov reuses an instrumented build only when source, dependencies,
 configuration, toolchain, build mode, and instrumenter identity match. A
-possible mismatch triggers a fresh build rather than risking stale coverage.
+possible mismatch triggers a fresh build rather than risking stale coverage. A
+build inside a JavaScript project's command is the command's own and runs every
+time, as it does without Supercov.
 
 ## Use focused runs carefully
 

package/docs/troubleshooting.md

@@ -142,6 +142,21 @@ Its lines, methods and simple branches stay measured; everything that needs a
 probe is declared as a measurement limit for that file. Please report the file,
 since Supercov aims to instrument every Ruby source correctly.
 
+## The tests cannot find `dist/` or a production build
+
+Supercov runs your command in a copy of the project, and the copy starts
+without build output: `dist/`, `build/`, `.next/` and the like are not copied,
+because they hold code that was never instrumented. Supercov does not run your
+`build` script for you (earlier versions did). If the tests read build output, put
+the build in the command:
+
+```bash
+npx supercov -- sh -c "npm run build && npm test"
+```
+
+A `pretest` script, or a Playwright `webServer` that builds, does the same. The
+build then compiles the instrumented copy, and what the tests run is measured.
+
 ## A test that reads your source fails under Supercov
 
 A test that opens your source files and asserts on their text sees the probes,
@@ -220,10 +235,8 @@ runs remain intact.
 
 ## The first run is slow
 
-The first run may include the npm download, browser or toolchain startup,
-workspace creation, and an instrumented build. Repeated runs can reuse the
-isolated build when source, dependencies, configuration, toolchain, and build
-mode still match.
+The first run may include the npm download, browser or toolchain startup, and
+workspace creation.
 
 Inspect the recorded phases with:
 

package/docs/workspace-isolation.md

@@ -36,6 +36,19 @@ and the instrumented copy is not what you wrote:
   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.
+- Biome, oxlint, dprint, cspell and knip run on your source as you wrote it:
+  the copy's `node_modules/.bin` starts each of them in a view of the copy
+  that holds every file in its original text. A file the tool writes there
+  (a report, a cache) is the command's output like any other. To have another
+  tool that reads source as text run the same way, name it:
+  `SUPERCOV_SOURCE_TOOLS=typos,stylelint`.
+- A change one of these tools makes to a source file (`prettier --write`,
+  `eslint --fix`, `biome check --write`, `dprint fmt`) is made in your
+  project when the command ends, and a tool later in the same command reads
+  the changed text. The tests ran the copy instrumented before the change, so
+  the run measured the file as it was, says so, and reads as stale; the next
+  run measures the changed file. A file you edited yourself while the command
+  ran keeps your edit, and the run names it.
 - 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,
@@ -58,9 +71,19 @@ 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.
+The copy starts without build output: `dist/`, `build/`, `.next/` and the
+like are not copied, because they hold code that was never instrumented.
+Supercov runs the command you give it and no build of its own, so a suite that
+needs build output has the build in its command:
+
+```bash
+npx supercov -- sh -c "npm run build && npm test"
+```
+
+A `pretest` script, or a Playwright `webServer` that builds, does the same.
+When a run fails in a project that has a `build` script the command does not
+reach, it says this. `SUPERCOV_KEEP_WORKSPACE=1` leaves the instrumented copy
+in `.supercov/workspaces/` after a run, to inspect.
 
 ## Files Supercov creates
 
@@ -80,9 +103,10 @@ fallback instead of adopting or deleting it.
 
 ## Repeated runs and the build cache
 
-When source, dependencies, configuration, toolchain, and build mode still
-match, Supercov can reuse the isolated instrumented build. Test-only changes do
-not force an unrelated application rebuild.
+For a compiled language, when source, dependencies, configuration, toolchain,
+and build mode still match, Supercov can reuse the isolated instrumented build,
+so test-only changes do not force an unrelated rebuild. A JavaScript project's
+build is part of its command and runs every time.
 
 Workspace refreshes are prepared separately and become active only when
 complete. An interrupted refresh does not replace the last complete cache with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supercov",
-  "version": "3.0.5",
+  "version": "4.0.1",
   "description": "Coverage, security and code quality for coding agents",
   "keywords": [
     "coverage",
@@ -119,14 +119,14 @@
     "test:windows-tls": "node scripts/windows-tls-test.mjs"
   },
   "optionalDependencies": {
-    "@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"
+    "@supercov/cli-darwin-arm64": "4.0.1",
+    "@supercov/cli-darwin-x64": "4.0.1",
+    "@supercov/cli-linux-arm64-gnu": "4.0.1",
+    "@supercov/cli-linux-arm64-musl": "4.0.1",
+    "@supercov/cli-linux-x64-gnu": "4.0.1",
+    "@supercov/cli-linux-x64-musl": "4.0.1",
+    "@supercov/cli-win32-arm64": "4.0.1",
+    "@supercov/cli-win32-x64": "4.0.1"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",

package/runtime/javascript/register.mjs

@@ -8,7 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import Module, { register, syncBuiltinESMExports } from "node:module";
 import fs, { closeSync, openSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { installLaunchSupervisor, wrapImportedCapability } from "./launchSupervisor.mjs";
 import { __supercovBindCapabilityWrapper } from "./capability.mjs";
@@ -205,6 +205,8 @@ function installAuthoredSourceView() {
         authored = new Set();
     }
     const authoredRoot = fileURLToPath(new URL("./.authored/", import.meta.url));
+    // What a tool of the command wrote to a rewritten file: `--fix`, `--write`.
+    const changedRoot = fileURLToPath(new URL("./.changed/", import.meta.url));
     const workspace = fileURLToPath(new URL("../../", import.meta.url));
     const roots = [...new Set([workspace, (() => {
                 try {
@@ -231,9 +233,28 @@ function installAuthoredSourceView() {
         }
         return undefined;
     };
+    const { existsSync: exists, mkdirSync: makeDirectory } = fs;
+    // A rewritten file reads as the command has it now: what one of its
+    // tools made of it, or what its author wrote.
     const authoredPath = (path) => {
         const local = inside(path);
-        return local !== undefined && authored.has(local) ? resolve(authoredRoot, local) : path;
+        if (local === undefined || !authored.has(local))
+            return path;
+        const changed = resolve(changedRoot, local);
+        return exists(changed) ? changed : resolve(authoredRoot, local);
+    };
+    // And it is written beside the instrumented copy, never over it. Prettier
+    // with `--write` and ESLint with `--fix` replaced the copy with the
+    // source they had read: the file then ran unmeasured, and one whose tests
+    // passed read 0% covered. Supercov gives the project the change when the
+    // command ends.
+    const changedPath = (path) => {
+        const local = inside(path);
+        if (local === undefined || !authored.has(local))
+            return path;
+        const changed = resolve(changedRoot, local);
+        makeDirectory(dirname(changed), { recursive: true });
+        return changed;
     };
     // A recursive listing names nested entries by relative path, or as
     // entries whose parent is inside .supercov.
@@ -250,7 +271,17 @@ function installAuthoredSourceView() {
         ? entries
         : entries.filter((entry) => !hidden(entry));
     const { readFileSync: readSync, readFile: readCallback, readdirSync: listSync, readdir: listCallback } = fs;
-    const { readFile: readPromise, readdir: listPromise } = fs.promises;
+    const { readFile: readPromise, readdir: listPromise, writeFile: writePromise } = fs.promises;
+    const { writeFileSync: writeSync, writeFile: writeCallback } = fs;
+    fs.writeFileSync = function writeFileSync(path, ...rest) {
+        return Reflect.apply(writeSync, this, [changedPath(path), ...rest]);
+    };
+    fs.writeFile = function writeFile(path, ...rest) {
+        return Reflect.apply(writeCallback, this, [changedPath(path), ...rest]);
+    };
+    fs.promises.writeFile = function writeFile(path, ...rest) {
+        return Reflect.apply(writePromise, this, [changedPath(path), ...rest]);
+    };
     fs.readFileSync = function readFileSync(path, ...rest) {
         return Reflect.apply(readSync, this, [authoredPath(path), ...rest]);
     };
@@ -390,7 +421,16 @@ function skipCoverageThresholds(tool) {
             console.error(`[supercov] ${tool}'s coverage thresholds stay as configured`, error);
     }
 }
-register(new URL("./resolve-loader.mjs", import.meta.url));
+// A handler for `.ts` in the CommonJS loader that is not Node's own is a
+// transpiler's require hook: ts-node/register, @swc/register and the like.
+// It was there before this preload, and it is how the project's TypeScript
+// loads. Any `--import` sends the entry point through the module loader
+// instead, where such a file is read as an ES module and the hook never
+// sees it; the loader is told so it can hand those files back.
+const typescriptHandler = Module._extensions[".ts"];
+register(new URL("./resolve-loader.mjs", import.meta.url), {
+    data: { typescriptRequireHook: typeof typescriptHandler === "function" && typescriptHandler.name !== "loadTS" },
+});
 if (process.env.SUPERCOV_DEBUG === "1") {
     console.error("[supercov] preload", { entrypoint });
 }

package/runtime/javascript/resolve-loader.mjs

@@ -1,4 +1,5 @@
-import { resolve as resolvePath } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 const GENERATED_TARGET = "__SUPERCOV_PLAYWRIGHT_MODULE__";
 const TARGET = process.env.SUPERCOV_PLAYWRIGHT_MODULE ??
@@ -25,6 +26,41 @@ function belongsToProject(parentURL) {
     const generatedURL = `${projectURL}.supercov/`;
     return (parentURL.startsWith(projectURL) && !parentURL.startsWith(generatedURL));
 }
+let typescriptRequireHook = false;
+export function initialize(data) {
+    typescriptRequireHook = data?.typescriptRequireHook === true;
+}
+const packageTypes = new Map();
+function packageType(directory) {
+    if (packageTypes.has(directory))
+        return packageTypes.get(directory);
+    let type;
+    try {
+        type = JSON.parse(readFileSync(resolvePath(directory, "package.json"), "utf8")).type ?? "commonjs";
+    }
+    catch {
+        const parent = dirname(directory);
+        type = parent === directory ? "commonjs" : packageType(parent);
+    }
+    packageTypes.set(directory, type);
+    return type;
+}
+// `node -r ts-node/register --test tests/a.test.ts` in a package without
+// `"type"` passed alone and failed here with ERR_MODULE_NOT_FOUND on an
+// extensionless import: the preload made Node load the entry point as an ES
+// module, past the require hook that compiles it. A TypeScript file of a
+// CommonJS package is given back to the CommonJS loader, where that hook is.
+function throughRequireHook(resolved) {
+    if (!typescriptRequireHook || !resolved?.url?.startsWith("file:") || resolved.url.includes("/node_modules/"))
+        return resolved;
+    if (!/\.(?:ts|tsx|cts)$/.test(resolved.url) || /\.d\.c?ts$/.test(resolved.url))
+        return resolved;
+    if (resolved.format === "module" || resolved.format === "module-typescript")
+        return resolved;
+    if (!resolved.url.endsWith(".cts") && packageType(dirname(fileURLToPath(resolved.url))) === "module")
+        return resolved;
+    return { ...resolved, format: "commonjs" };
+}
 export async function resolve(specifier, context, nextResolve) {
     // Some transpilers preserve the source-relative runtime import while moving
     // only the transformed application file to an output directory. The
@@ -73,7 +109,7 @@ export async function resolve(specifier, context, nextResolve) {
         }
         return nextResolve(REPLACEMENT, context);
     }
-    return nextResolve(specifier, context);
+    return throughRequireHook(await nextResolve(specifier, context));
 }
 
 // Node's own test coverage filters files by `--test-coverage-include` and

package/runtime/javascript/runtime.mjs

@@ -1402,6 +1402,10 @@ function registerProbeV2(definition) {
     // A selection's outcomes -- short falsy, short truthy, right falsy, right
     // truthy -- are four consecutive points per site from the first index.
     selectionPoints: definition.selectionPoints,
+    // What selectEndV2 and selectNextV2 read, for each tree of more than two
+    // leaves.
+    selectionSteps: (definition.selectionTrees || []).map((tree) => tree[0]),
+    selectionChoices: (definition.selectionTrees || []).map((tree) => tree[1]),
     none: optionalCallEmptySpread
   };
   state.probeV2Files.add(file);
@@ -1626,6 +1630,44 @@ function selectPathV2(file, value) {
   }
   return value;
 }
+// A selection tree whose leaves stay the program's own expressions: each is
+// the last operand of a comma that names it in the site's frame, so a type
+// checker reading the instrumented copy narrows through `a && a.b` as it does
+// in the source, and the tree's value is recorded here, once, for the leaf
+// that produced it. What a leaf before the last decided on the way is known
+// from where evaluation went next, and is recorded there as plain hits.
+// Two leaves: the left one is last only when it decided the result.
+function selectEnd2V2(file, first, value, right) {
+  coverageHitV2(file, first + (right ? 2 : 0) + (value ? 1 : 0));
+  return value;
+}
+// More: the leaf's steps, the ones selectPathV2 takes as arguments, come from
+// the file's table, whose entry for a tree is `[steps of each leaf, for each
+// leaf the points each leaf before it has decided by then]`.
+function selectEndV2(file, tree, value, leaf) {
+  const steps = file.selectionSteps[tree][leaf];
+  for (let index = 0; index < steps.length; index += 1) {
+    const step = steps[index];
+    const code = step & 3;
+    const first = (step - code) / 4;
+    if (code === 3)
+      coverageHitV2(file, value ? first + 3 : first + 2);
+    else if (code === 0 ? value : code === 1 ? !value : value !== null && value !== void 0)
+      coverageHitV2(file, value ? first + 1 : first);
+    else
+      break;
+  }
+  return value;
+}
+// Where one of several leaves can come before a leaf, the frame says which.
+// Written out in the program as a choice, it would be a branch of the user's
+// line to a coverage tool the tests run.
+function selectNextV2(file, tree, from, to) {
+  const points = file.selectionChoices[tree][to][from];
+  if (points)
+    for (let index = 0; index < points.length; index += 1)
+      coverageHitV2(file, points[index]);
+}
 // `x ||= y`, `x &&= y`, `x ??= y` keep their operator and their single
 // evaluation of the target: the right side goes through selectRightV2 (or the
 // named form, for an anonymous function the assignment would have named), and
@@ -1851,6 +1893,9 @@ const directRuntimeApi = {
   selectNamedRightV2,
   selectAssignEndV2,
   selectPathV2,
+  selectEnd2V2,
+  selectEndV2,
+  selectNextV2,
   takeNodeAssertionPhases,
   tryBegin,
   tryCatch,
@@ -1913,6 +1958,9 @@ export {
   selectNamedRightV2,
   selectAssignEndV2,
   selectPathV2,
+  selectEnd2V2,
+  selectEndV2,
+  selectNextV2,
   takeNodeAssertionPhases,
   tryBegin,
   tryCatch,