supercov 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Supercov contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -18,24 +18,51 @@ npm link
 
 ## Verifying the instrumenter
 
-The coverage engine has three independent test layers:
+The coverage engine has seven independent release gates:
 
 - semantic differential fixtures execute original and instrumented programs
   in isolated scopes and compare return values, thrown errors, and observable
   side-effect order;
 - a deterministic generated corpus exercises 160 nested combinations of
   short-circuiting, ternaries, coercion, and thrown expressions on every run;
+- seeded `fast-check` properties exercise another 500 generated nested
+  expressions and 300 generated control-flow executions, with shrinking and a
+  reproducible seed on failure;
 - coverage oracles assert exact decision vectors, MC/DC witnesses, and branch
-  alternatives independently of program behavior.
+  alternatives independently of program behavior;
+- the same three-condition masking-MC/DC golden cases must report 100% for a
+  complete witness set and 33.33% for an incomplete one under both Supercov
+  and Clang/LLVM source-based MC/DC;
+- release CI shards the pinned TC39 Test262 corpus across 16 workers, runs the
+  official Test262 harness on original and instrumented sources, and rejects
+  any scenario that passes originally but fails after transformation; and
+- checked performance budgets cover transform latency, output expansion, and
+  runtime probe overhead.
 
 ```sh
 npm test
+npm run test:clang-mcdc
+npm run benchmark:check
+TEST262_DIR=/path/to/test262 npm run test:test262
 ```
 
 The differential suite includes getters, proxies, optional calls and `this`,
 computed logical assignments, defaults, `try`/`catch`/`finally`, iterator
 closing, switch fallthrough, labeled loops, async functions, and generators.
-Every generated failure prints its reproducible seed and expression.
+The compatibility workflow additionally runs Node 22/24/25, Playwright
+1.55/current, Vite 5/current, Vitest 2/current, Chromium, Firefox, WebKit, and
+modern JavaScript/JSX/TypeScript/TSX syntax fixtures. Test262's module, async,
+raw, parse/resolution-negative, Annex B sloppy-script extension, and explicit
+`Function.prototype.toString`/function-source-coercion tests are intentionally
+excluded from the source-rewrite comparison, with reason counts printed for
+every shard. Annex B does not apply to the Vite application modules Supercov
+instruments; exact source reflection necessarily observes a source transform.
+When application code directly coerces or observes a function's source,
+Supercov leaves that function body uninstrumented and records a visible
+`semantic-safety` completeness blocker. The release corpus covers every other eligible synchronous
+script and runtime-negative scenario, while dedicated differential fixtures
+cover async functions and generators. Every semantic-equivalence failure
+blocks the trusted-publishing workflow.
 
 ## Agent query workflow
 
@@ -87,31 +114,99 @@ Text output is concise for an interactive agent; JSON is the stable machine
 interface that can later back hosted coverage tools without changing the
 stored schema.
 
-For a conventional Vite project, the CLI:
+For a conventional Vite project, or a Node project with no build step, the
+CLI:
 
-1. creates ignored Vite, Vitest, and Playwright overlays under
-   `.supercov/`;
+1. refreshes a stable isolated source namespace under
+   `.supercov/cache/instrumented-workspace/<project>/`, links the existing
+   dependency tree, and creates all Vite, Vitest, Playwright, and build output
+   only there; the stable path lets VM/container snapshot systems reuse a
+   coverage build without touching the application's ordinary build;
 2. inventories every `app/**/*.ts(x)` and `src/**/*.ts(x)` file for the
-   denominator, then
-   instruments modules loaded by Vite without changing the project's config;
-3. redirects existing `@playwright/test` imports at module-load time and injects
-   a Vitest setup through the child runner's generated config, without changing
-   specs, imports, package scripts, or checked-in configs;
-4. runs the exact command following `--`;
+   denominator, then instruments modules loaded by Vite without changing the
+   project's config; when no build script exists, it instruments only the
+   disposable source copy and supplies a module-format-neutral runtime through
+   the inherited Node preload;
+3. discovers the Playwright-compatible fixture provider, test export, and
+   additional named exports from the suite's existing imports, then redirects
+   that provider at module-load time; Vitest setup is injected through the
+   child runner's generated config;
+4. runs the exact command following `--`, propagating coverage through every
+   Node child process it launches;
 5. attributes every source hit and decision vector to its individual test,
    automatically wraps Playwright actions and assertions, and records the
    action/assertion phase responsible for each correlated hit; then merges
    server and browser evidence into HTML and JSON reports; and
-6. restores an ordinary application build even after a failed test command.
+6. atomically publishes the evidence/report into `.supercov/` and retains only
+   the disposable isolated build namespace as a provider snapshot cache. The
+   ordinary application build is never read as an input, overwritten, or
+   rebuilt afterward.
+
+Only `.supercov/` is modified in the user's checkout. A per-project lock
+rejects overlapping runs before either can build. Run state is durably written
+through preparing/building/testing/reporting/terminal phases; SIGINT, SIGTERM,
+and SIGHUP are forwarded to the entire child process group. If the process is
+killed without a cleanup opportunity, the next invocation marks the dead PID's
+run abandoned and refreshes the isolated namespace before using it. Report,
+evidence, and state writes use sibling-temp files, fsync, and atomic rename;
+lock acquisition uses exclusive creation and fsync.
+
+Retention is deterministic because UTC run IDs sort chronologically:
+
+```sh
+npx supercov clean --keep 20
+npx supercov clean --keep 20 --dry-run
+```
+
+The cleanup command never removes an active workspace and never touches files
+outside `.supercov/`.
 
 The automatic adapters currently support standard Playwright suites (ESM and
-CommonJS specs in arbitrary project directories), Vitest, and the Essential
-Apps isolated Playwright VM runner. A single command such as
-`supercov -- npm test` can collect Vitest and Playwright evidence into
-the same run. The application build must currently be Vite-based. Jest,
-`node:test`, non-Vite build systems, browser component runners, and distributed
-multi-host merging still require adapters; they are not silently reported as
-covered.
+CommonJS specs in arbitrary project directories), project-owned Playwright
+fixture packages, Vitest, no-build Node commands, and Node coordinators that
+launch tests inside a mounted VM/container workspace. A single command such as
+`supercov -- npm test` can collect Vitest and Playwright evidence into the same
+run. No-build Node execution is retained as background/unattributed evidence
+until a recognized test-runner adapter supplies exact test boundaries. Jest,
+exact `node:test` attribution, non-Vite application builds, browser component
+runners, and distributed multi-host merging still require adapters; they are
+not silently reported as per-test coverage.
+
+Remote execution discovery is structural rather than provider-specific. The
+preload observes CommonJS exports for a static `build(options)` capability,
+activates only when those options contain a host-to-guest mount that includes
+the isolated project, scopes an existing cache/snapshot identity to the run's
+source fingerprint, and follows the opaque returned object graph. A method
+whose options contain `argv`, `cmd`, or `command` receives guest-translated
+Supercov paths and a guest-valid Node preload. The execution log records this
+process/capability graph but hashes long or multiline arguments so embedded
+shell bodies and credentials are never persisted.
+
+This first zero-edit mechanism has explicit boundaries. It follows Node child
+processes, not arbitrary non-Node supervisors or a remote control plane that
+never exposes launches to the local process. The remote SDK must currently be
+visible through CommonJS loading, its build options must expose the workspace
+mount, and its execution call must accept an environment. Pure-ESM executor
+SDKs, positional-only remote exec APIs, and providers that hide all launch
+state behind an RPC need additional interception layers. Supercov reports
+missing evidence rather than claiming those paths are covered.
+
+The public regression suite includes a provider-neutral opaque executor. Its
+CommonJS SDK exposes only a static build capability, a host-to-guest mount,
+an existing snapshot key, an opaque image/pool/machine chain, and an
+argv-shaped execution method. CI requires Supercov to discover that structure,
+scope the cache identity, translate paths and the Node preload into the guest,
+run nested Vitest and Playwright commands, parse every concurrent trace shard,
+and produce 100% fixture coverage. A separate clean-room gate packs the npm
+tarball and invokes it through `npx` in a project with no build step, asserting
+that no source or configuration file changes.
+
+Before the isolated build, Supercov also compares the invoked npm/pnpm/yarn/bun
+script with explicit string-valued `process.env` mode checks in the project's
+build config. A semantic match such as `test:preview` and
+`process.env.TEST_PREVIEW === "true"` activates that build-only flag and is
+printed before the build. It never guesses values for unrelated environment
+variables.
 
 Each test carries two independent provenance fields:
 

package/bin/supercov.js

@@ -13,6 +13,16 @@ const child = spawn(
   },
 );
 
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.once(signal, () => {
+    try {
+      child.kill(signal);
+    } catch {
+      // The child may already have completed.
+    }
+  });
+}
+
 child.on("error", (error) => {
   console.error("[supercov] failed to start", error);
   process.exitCode = 1;

package/dist/atomic.d.ts

@@ -0,0 +1,6 @@
+import { type WriteFileOptions } from "node:fs";
+/** Write a complete sibling file and atomically replace the destination. */
+export declare function atomicWriteFileSync(path: string, data: string | NodeJS.ArrayBufferView, options?: WriteFileOptions): void;
+/** Atomically publish a fully prepared file or directory and persist its entry. */
+export declare function atomicRenameSync(source: string, destination: string): void;
+//# sourceMappingURL=atomic.d.ts.map

package/dist/atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../src/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,gBAAgB,EACtB,MAAM,SAAS,CAAC;AAiBjB,4EAA4E;AAC5E,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,eAAe,EACrC,OAAO,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAmBN;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAI1E"}

package/dist/atomic.js

@@ -0,0 +1,47 @@
+import { mkdirSync, openSync, closeSync, fsyncSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+function fsyncDirectory(path) {
+    try {
+        const directory = openSync(path, "r");
+        try {
+            fsyncSync(directory);
+        }
+        finally {
+            closeSync(directory);
+        }
+    }
+    catch {
+        // Some platforms (notably Windows) do not permit opening directories.
+    }
+}
+/** Write a complete sibling file and atomically replace the destination. */
+export function atomicWriteFileSync(path, data, options) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    let descriptor;
+    try {
+        descriptor = openSync(temporary, "wx", 0o600);
+        writeFileSync(descriptor, data, options);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        renameSync(temporary, path);
+        // Persist the directory entry as well as the file contents on POSIX. Some
+        // platforms (notably Windows) do not permit opening directories, so file
+        // fsync + atomic rename remains the portable fallback there.
+        fsyncDirectory(dirname(path));
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        rmSync(temporary, { force: true });
+    }
+}
+/** Atomically publish a fully prepared file or directory and persist its entry. */
+export function atomicRenameSync(source, destination) {
+    mkdirSync(dirname(destination), { recursive: true });
+    renameSync(source, destination);
+    fsyncDirectory(dirname(destination));
+}
+//# sourceMappingURL=atomic.js.map

package/dist/atomic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../src/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,QAAQ,EACR,SAAS,EACT,SAAS,EACT,UAAU,EACV,MAAM,EACN,aAAa,GAEd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC;YACH,SAAS,CAAC,SAAS,CAAC,CAAC;QACvB,CAAC;gBAAS,CAAC;YACT,SAAS,CAAC,SAAS,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,IAAqC,EACrC,OAA0B;IAE1B,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC;IAC/D,IAAI,UAA8B,CAAC;IACnC,IAAI,CAAC;QACH,UAAU,GAAG,QAAQ,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAC9C,aAAa,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACzC,SAAS,CAAC,UAAU,CAAC,CAAC;QACtB,SAAS,CAAC,UAAU,CAAC,CAAC;QACtB,UAAU,GAAG,SAAS,CAAC;QACvB,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC5B,0EAA0E;QAC1E,yEAAyE;QACzE,6DAA6D;QAC7D,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAChC,CAAC;YAAS,CAAC;QACT,IAAI,UAAU,KAAK,SAAS;YAAE,SAAS,CAAC,UAAU,CAAC,CAAC;QACpD,MAAM,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,WAAmB;IAClE,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,UAAU,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAChC,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;AACvC,CAAC"}