supercov 0.0.42 → 0.0.43

package/README.md

@@ -1,6 +1,6 @@
-![Supercov: Coverage for coding agents working overnight](https://raw.githubusercontent.com/supercorp-ai/supercov/main/supercov.jpg)
+![Coverage for coding agents and software factories 🌙](https://raw.githubusercontent.com/supercorp-ai/supercov/main/supercov.jpg)
 
-**Coverage for coding agents working overnight.**
+**Coverage for coding agents and software factories 🌙**
 
 **Supercov gives your coding agent the next useful test to write.** It runs the test command you already use, records local coverage evidence, and turns uncovered paths into small, actionable queries. Your agent writes a focused test, reruns the suite, proves what improved, and keeps going while useful gaps remain.
 
@@ -10,6 +10,9 @@ No account, config file, import, custom reporter, or hosted service is required.
 
 Supported by [Supercorp](https://supercorp.ai).
 
+[Try the worked example](https://supercov.com/docs/code-verification): find an
+untested session-expiry condition, run an additional test, and compare the results.
+
 ## Start with the suite you already have
 
 ```bash
@@ -43,6 +46,23 @@ npx supercov -- python -m unittest
 npx supercov -- bundle exec rspec
 ```
 
+## Inspect assertion evidence (JS/TS)
+
+After a run, inspect what existing assertions appear to check:
+
+```sh
+npx supercov runs latest assertions --limit 5
+npx supercov runs latest assertions --pragmas --json
+npx supercov runs latest assertions --evidence /tests --limit 5 --json
+```
+
+This npm-only query uses the run archive and matching source; it adds no new
+test-time instrumentation. It requires a compatible project TypeScript compiler
+API (5.8.3 and native 7.0.2 are tested). Results are candidates, not proof
+that changes are safe or a verified assertion percentage. Follow
+[`assertion-evidence.md`](docs/assertion-evidence.md) for provenance, optional
+assertion hints, pagination, and limitations.
+
 ## Give Supercov a job
 
 Paste one of these prompts into Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, or any coding agent that can run terminal commands.
@@ -150,7 +170,7 @@ Supercov uses exact per-test attribution where an adapter is available. For othe
 | --- | --- |
 | Playwright | Exact per test, worker, retry, outcome, action, and assertion phase |
 | Vitest | Exact per test, with setup execution kept separate |
-| Jest | Exact per test, including concurrent and parameterized tests |
+| Jest | Exact per test, including parameterized tests; `expect` assertions link the evidence they check |
 | `node:test` | Exact per test |
 | AVA and Mocha | Aggregate structural coverage |
 | Cargo's standard libtest runner | Exact test, attempt, and passing-assertion identity |

package/analyzers/typescript/README.md

@@ -0,0 +1,55 @@
+# JS/TS assertion analyzer (internal)
+
+This private package is the post-run analysis component used by Supercov's
+`runs <run> assertions` command. It is bundled in the npm distribution, not
+published as a separate CLI or SDK.
+
+See [Assertion evidence](../../docs/assertion-evidence.md) for public commands,
+pragma syntax, report interpretation and supported scope.
+
+## Product boundary
+
+- `bin/query.mjs` is the CLI-to-analyzer JSON transport. It accepts an ordinary
+  archive representation prepared by Rust, validates identities and returns facts.
+- `bin/identity.mjs` checks the analyzer source/build identity; its direct
+  invocation writes that identity during the build.
+- `bin/compiler-identity.mjs` fingerprints the project's compiler implementation.
+- `src/archive.ts` validates the archive protocol, source positions and attempt
+  ownership, then constructs query-local evidence in memory.
+- `src/analyze.ts` extracts source-flow facts and exact assertion witnesses.
+  The Rust engine joins those facts into candidate classifications.
+- `src/frontend.ts` and `src/native-frontend.ts` implement the legacy and native
+  TypeScript compiler boundaries. `src/pragmas.ts` validates optional hints.
+
+There is no converted-input command, on-disk research input, V8 remapping,
+mutation runner or diagnostic-ablation option in the product interface.
+Source files ship to support build-identity verification; tests and research
+tools do not ship. Assertion candidates remain unverified, not safety proofs.
+Only executable JavaScript and its build identity ship from `dist`; there is no
+public SDK declaration surface or generated source-map payload.
+
+## Build and test
+
+From this directory:
+
+```sh
+npm ci --ignore-scripts
+npm test
+```
+
+The build uses pinned TypeScript 5.8.3 explicitly. Project analysis uses the
+project's compiler; native 7.0.2 has a separate frontend and identity checks.
+Native compiler processes close after both successful and failed queries.
+
+From the repository root, exercise real Node/Vitest archives and the installed
+npm package:
+
+```sh
+npm run test:asserted-integration
+npm run test:asserted-package
+```
+
+Controlled unit fixtures test parser, flow and witness rules. The ordinary-archive
+integration tests execute real suites and explicit behavioral counterexamples.
+Compiler-path and identity regressions run across supported CI platforms.
+Historical external-cohort research is not part of the default suite or product.

package/analyzers/typescript/bin/compiler-identity.mjs

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { projectCompilerPath } from "../dist/compiler.js";
+
+/** Hash the native implementation as well as its JS client; version.cjs alone is not the compiler. */
+export function compilerIdentity(projectRoot) {
+  return compilerIdentityFromEntry(projectCompilerPath(projectRoot));
+}
+
+export function compilerIdentityFromEntry(entry) {
+  const require = createRequire(pathToFileURL(entry));
+  const { version } = require(entry);
+  const entrySha256 = createHash("sha256")
+    .update(readFileSync(entry))
+    .digest("hex");
+  if (version !== "7.0.2")
+    return { backend: "typescript-legacy", version, sha256: entrySha256 };
+  const packageRoot = dirname(require.resolve("typescript/package.json"));
+  const platform = `@typescript/typescript-${process.platform}-${process.arch}`;
+  let nativeRoot;
+  try {
+    nativeRoot = dirname(require.resolve(`${platform}/package.json`));
+  } catch (cause) {
+    throw new Error(
+      `TypeScript 7's native compiler dependency ${platform} is missing. Install the project's optional TypeScript dependencies before recapturing tests.`,
+      { cause },
+    );
+  }
+  const nativeMetadata = JSON.parse(
+    readFileSync(resolve(nativeRoot, "package.json"), "utf8"),
+  );
+  if (nativeMetadata.name !== platform || nativeMetadata.version !== version)
+    throw new Error(
+      `TypeScript native package identity mismatch: expected ${platform}@${version}`,
+    );
+  const executable = resolve(
+    nativeRoot,
+    "lib",
+    process.platform === "win32" ? "tsc.exe" : "tsc",
+  );
+  const nativeSha256 = createHash("sha256")
+    .update(readFileSync(executable))
+    .digest("hex");
+  const hash = createHash("sha256");
+  let files = 0;
+  function walk(root, relative = "") {
+    for (const file of readdirSync(resolve(root, relative), {
+      withFileTypes: true,
+    }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (file.name === "node_modules") continue;
+      const path = relative ? `${relative}/${file.name}` : file.name;
+      if (file.isDirectory()) walk(root, path);
+      else if (file.isFile()) {
+        hash
+          .update(path)
+          .update("\0")
+          .update(readFileSync(resolve(root, path)))
+          .update("\0");
+        files++;
+      } else throw new Error(`Unsupported compiler package entry: ${path}`);
+    }
+  }
+  hash.update("typescript-package\0");
+  walk(packageRoot);
+  hash.update("native-package\0");
+  walk(nativeRoot);
+  return {
+    backend: "typescript-native-7",
+    version,
+    sha256: hash.digest("hex"),
+    nativePackage: platform,
+    nativeSha256,
+    files,
+  };
+}

package/analyzers/typescript/bin/identity.mjs

@@ -0,0 +1,67 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(import.meta.dirname, "..");
+const sources = [
+  "src/analyze.ts",
+  "src/archive.ts",
+  "src/compiler.ts",
+  "src/frontend.ts",
+  "src/native-frontend.ts",
+  "src/types.ts",
+  "src/pragmas.ts",
+  "bin/query.mjs",
+  "bin/compiler-identity.mjs",
+  "bin/identity.mjs",
+  "tsconfig.json",
+  // npm excludes package-lock.json from tarballs. Hash shipped build inputs,
+  // not a checkout-only file, so installed and development checks are identical.
+  "package.json",
+];
+const outputs = [
+  "dist/analyze.js",
+  "dist/archive.js",
+  "dist/compiler.js",
+  "dist/frontend.js",
+  "dist/native-frontend.js",
+  "dist/types.js",
+  "dist/pragmas.js",
+];
+function digest(files) {
+  const hash = createHash("sha256");
+  for (const file of files)
+    hash
+      .update(file)
+      .update("\0")
+      .update(readFileSync(resolve(root, file)))
+      .update("\0");
+  return hash.digest("hex");
+}
+export function identity() {
+  return {
+    schema: 1,
+    sourceSha256: digest(sources),
+    compiledSha256: digest(outputs),
+  };
+}
+export function checkedIdentity() {
+  const built = JSON.parse(
+    readFileSync(resolve(root, "dist/build-identity.json"), "utf8"),
+  );
+  const current = identity();
+  if (JSON.stringify(built) !== JSON.stringify(current))
+    throw new Error(
+      "Assertion analyzer build is stale or modified; rebuild analyzers/typescript",
+    );
+  return current;
+}
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+)
+  writeFileSync(
+    resolve(root, "dist/build-identity.json"),
+    JSON.stringify(identity()) + "\n",
+  );

package/analyzers/typescript/bin/query.mjs

@@ -0,0 +1,29 @@
+// First-party query transport, never executed by the test runner.
+import { readFileSync } from "node:fs";
+import { checkedIdentity } from "./identity.mjs";
+
+try {
+  const analyzer = checkedIdentity();
+  const input = JSON.parse(readFileSync(0, "utf8"));
+  // Check the build before importing executable analyzer code.
+  const { compilerIdentity } = await import("./compiler-identity.mjs");
+  const { analyzeArchive } = await import("../dist/archive.js");
+  const compiler = compilerIdentity(input.projectRoot);
+  const compilerSha256 = compiler.sha256;
+  const result = analyzeArchive(input);
+  if (
+    JSON.stringify(compilerIdentity(input.projectRoot)) !==
+      JSON.stringify(compiler) ||
+    JSON.stringify(checkedIdentity()) !== JSON.stringify(analyzer)
+  )
+    throw new Error("Analyzer or compiler changed during analysis");
+  process.stdout.write(
+    JSON.stringify({
+      ...result,
+      analyzer: { ...analyzer, compilerSha256, compiler },
+    }),
+  );
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}