pabst-checker 0.12.0 → 0.12.1

package/dist/cli.js

@@ -90,13 +90,17 @@ function run(command, patterns, seedArg) {
     console.error(`pabst: generated ${generated} propert${generated === 1 ? "y" : "ies"} across ${results.length} file(s) into .pabst/`);
     if (command === "gen")
         return 0;
-    const result = runTests(".pabst", {
-        version,
-        startedAt,
-        cwd,
-        seed,
-        generated,
-    });
+    const meta = { version, startedAt, cwd, seed, generated };
+    // Scope the run to the out-files generated by THIS invocation (issue #41):
+    // .pabst/ accumulates mirrors from earlier runs, and running the whole
+    // directory would re-execute them and mix their issues into this envelope.
+    // With nothing generated there is nothing to run — and an empty file list
+    // would tell vitest to run everything, so short-circuit instead.
+    if (results.length === 0) {
+        console.log(JSON.stringify({ ...meta, passed: 0, failed: 0, issues: [] }, null, 2));
+        return 0;
+    }
+    const result = runTests(results.map((r) => r.outFile), meta);
     if (result.kind === "no-results") {
         process.stderr.write(result.stdout);
         process.stderr.write(result.stderr);

package/dist/contract.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The generated-code contract: every spelling that must agree across the
+ * seam between emitted test code, the runtime it imports, and the issue
+ * wire format the CLI parses back out of vitest. Each value here is either
+ * written into generated output or used to decode it — the two sides of
+ * each seam import this module instead of spelling the string twice.
+ */
+export type IssueKind = "falsified" | "threw" | "exhausted";
+export interface Issue {
+    file: string;
+    function: string;
+    property: string;
+    kind: IssueKind;
+    counterexample?: Record<string, unknown>;
+    error?: string;
+}
+/**
+ * Module specifier generated tests import the runtime from. Must match
+ * package.json's `name` + `exports` map (pinned by a test).
+ */
+export declare const RUNTIME_SPECIFIER = "pabst-checker/runtime";
+/** Names the runtime module exports (pinned against src/runtime.ts by a test). */
+export declare const BOOL_EXPORT = "bool";
+export declare const REPORT_EXPORT = "report";
+/** Aliases those exports are bound to inside generated test files. */
+export declare const BOOL_ALIAS = "__bool";
+export declare const REPORT_ALIAS = "__pabstReport";
+/**
+ * The exact message fast-check puts on the error it synthesizes when a
+ * property returns false (as opposed to throwing). The runtime's
+ * falsified-vs-threw classification string-matches this because RunDetails
+ * carries no discriminator field — fast-check knows which case occurred and
+ * erases it into this prose. The principled fix is upstream: a `failureKind`
+ * field on RunDetails. Until then, a live pin test fails loudly if a
+ * fast-check upgrade rewords it.
+ */
+export declare const FC_PROPERTY_FAILED_MESSAGE = "Property failed by returning false";
+export declare const ISSUE_SENTINEL = "PABST_ISSUE:";
+/** Encode an issue for the wire: sentinel + single-line JSON, carried on an Error message. */
+export declare function encodeIssue(issue: Issue): string;
+/**
+ * Extract a pabst Issue from a vitest failure message, or null if the message
+ * carries no tagged payload. The payload is single-line JSON, so a stack trace
+ * on following lines is ignored.
+ */
+export declare function parseIssue(failureMessage: string): Issue | null;

package/dist/contract.js

@@ -0,0 +1,52 @@
+/**
+ * The generated-code contract: every spelling that must agree across the
+ * seam between emitted test code, the runtime it imports, and the issue
+ * wire format the CLI parses back out of vitest. Each value here is either
+ * written into generated output or used to decode it — the two sides of
+ * each seam import this module instead of spelling the string twice.
+ */
+/**
+ * Module specifier generated tests import the runtime from. Must match
+ * package.json's `name` + `exports` map (pinned by a test).
+ */
+export const RUNTIME_SPECIFIER = "pabst-checker/runtime";
+/** Names the runtime module exports (pinned against src/runtime.ts by a test). */
+export const BOOL_EXPORT = "bool";
+export const REPORT_EXPORT = "report";
+/** Aliases those exports are bound to inside generated test files. */
+export const BOOL_ALIAS = "__bool";
+export const REPORT_ALIAS = "__pabstReport";
+/**
+ * The exact message fast-check puts on the error it synthesizes when a
+ * property returns false (as opposed to throwing). The runtime's
+ * falsified-vs-threw classification string-matches this because RunDetails
+ * carries no discriminator field — fast-check knows which case occurred and
+ * erases it into this prose. The principled fix is upstream: a `failureKind`
+ * field on RunDetails. Until then, a live pin test fails loudly if a
+ * fast-check upgrade rewords it.
+ */
+export const FC_PROPERTY_FAILED_MESSAGE = "Property failed by returning false";
+export const ISSUE_SENTINEL = "PABST_ISSUE:";
+// Escaped so a future sentinel containing regex metacharacters can't
+// silently change what the regex matches.
+const ISSUE_RE = new RegExp(`${ISSUE_SENTINEL.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\{.*\\})`);
+/** Encode an issue for the wire: sentinel + single-line JSON, carried on an Error message. */
+export function encodeIssue(issue) {
+    return ISSUE_SENTINEL + JSON.stringify(issue);
+}
+/**
+ * Extract a pabst Issue from a vitest failure message, or null if the message
+ * carries no tagged payload. The payload is single-line JSON, so a stack trace
+ * on following lines is ignored.
+ */
+export function parseIssue(failureMessage) {
+    const m = ISSUE_RE.exec(failureMessage);
+    if (!m)
+        return null;
+    try {
+        return JSON.parse(m[1]);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/emit.js

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { BOOL_ALIAS, BOOL_EXPORT, REPORT_ALIAS, REPORT_EXPORT, RUNTIME_SPECIFIER, } from "./contract.js";
 import { arbitraryFor } from "./domains.js";
 import { qualifiedName } from "./qualified-name.js";
 const SRC_EXT = /\.(ts|tsx|mts|cts|js|mjs|cjs)$/;
@@ -12,7 +13,7 @@ export function emit(specs, sourceFile, outFile, seed) {
     const lines = [];
     lines.push(`import { describe } from "vitest";`);
     lines.push(`import { test, fc } from "@fast-check/vitest";`);
-    lines.push(`import { report as __pabstReport, bool as __bool } from "pabst-checker/runtime";`);
+    lines.push(`import { ${REPORT_EXPORT} as ${REPORT_ALIAS}, ${BOOL_EXPORT} as ${BOOL_ALIAS} } from "${RUNTIME_SPECIFIER}";`);
     lines.push(`import * as __M from "${rel}";`);
     if (allExports.length > 0)
         lines.push(`const { ${allExports.join(", ")} } = __M;`);
@@ -61,7 +62,7 @@ function emitProp(s, sourceFile, seed, indent) {
     const name = JSON.stringify(s.name);
     const file = JSON.stringify(sourceFile);
     const fn = JSON.stringify(qualifiedName(s.functionName, s.className, s.isStatic));
-    const reporter = `(d) => __pabstReport(${file}, ${fn}, ${name}, [${varNames}], d)`;
+    const reporter = `(d) => ${REPORT_ALIAS}(${file}, ${fn}, ${name}, [${varNames}], d)`;
     const params = `{ seed: ${seed}, reporter: ${reporter} }`;
     const out = [];
     out.push(`${indent}test.prop([${arbs}], ${params})(${name}, (${vars}) => {`);

package/dist/envelope.d.ts

@@ -1,4 +1,15 @@
-import { type Issue, type Envelope } from "./issue.js";
+import { type Issue } from "./contract.js";
+/** The full report of one pabst run: metadata, counts, and parsed issues. */
+export interface Envelope {
+    version: string;
+    startedAt: string;
+    cwd: string;
+    seed: number;
+    generated: number;
+    passed: number;
+    failed: number;
+    issues: Issue[];
+}
 /** The subset of vitest's JSON reporter output the envelope consumes. */
 export interface AssertionResult {
     status: string;

package/dist/envelope.js

@@ -1,4 +1,4 @@
-import { parseIssue } from "./issue.js";
+import { parseIssue } from "./contract.js";
 /** Parse every failed assertion's tagged payload into an Issue. */
 export function collectIssues(json) {
     const issues = [];

package/dist/issue-schema.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const IssueSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"falsified">;
+    counterexample: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>>;
+    file: z.ZodString;
+    function: z.ZodString;
+    property: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"threw">;
+    counterexample: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>>;
+    error: z.ZodString;
+    file: z.ZodString;
+    function: z.ZodString;
+    property: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"exhausted">;
+    error: z.ZodString;
+    file: z.ZodString;
+    function: z.ZodString;
+    property: z.ZodString;
+}, z.core.$strict>], "kind">;
+/** The issue JSON Schema as a plain object — the generator and the sync test both call this. */
+export declare function issueJsonSchema(): unknown;

package/dist/issue-schema.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { QUALIFIED_NAME_PATTERN } from "./qualified-name.js";
+/**
+ * Single source of truth for the issue wire shape. The static type side is
+ * guarded one-way against the loose `Issue` interface in contract.ts (see
+ * tests/contract-pins.test.ts); the JSON side is generated into
+ * schemas/issue.schema.json (npm run generate:schema) and pinned by a
+ * deep-equal sync test.
+ */
+const functionName = z.string().regex(QUALIFIED_NAME_PATTERN).meta({
+    id: "functionName",
+    description: "Bare function name, or Class#method (instance) / Class.method (static).",
+});
+const counterexample = z
+    .record(z.string(), z.union([z.number(), z.boolean(), z.string()]))
+    .meta({ id: "counterexample" });
+const common = {
+    file: z.string(),
+    function: functionName,
+    property: z.string().min(1),
+};
+export const IssueSchema = z
+    .discriminatedUnion("kind", [
+    z
+        .strictObject({
+        ...common,
+        kind: z.literal("falsified"),
+        counterexample,
+    })
+        .meta({ title: "falsified" }),
+    z
+        .strictObject({
+        ...common,
+        kind: z.literal("threw"),
+        counterexample,
+        error: z.string(),
+    })
+        .meta({ title: "threw" }),
+    z
+        .strictObject({
+        ...common,
+        kind: z.literal("exhausted"),
+        error: z.string(),
+    })
+        .meta({ title: "exhausted" }),
+])
+    .meta({
+    title: "Pabst Issue",
+    description: "A single property failure emitted by the pabst reporter.",
+});
+/** The issue JSON Schema as a plain object — the generator and the sync test both call this. */
+export function issueJsonSchema() {
+    const schema = z.toJSONSchema(IssueSchema, { target: "draft-7" });
+    // zod ignores a root-level meta id, so the document identifier is stamped here.
+    return {
+        $schema: schema.$schema,
+        $id: "https://pabst.test/schemas/issue.schema.json",
+        ...schema,
+    };
+}

package/dist/lower.js

@@ -1,8 +1,9 @@
+import { BOOL_ALIAS } from "./contract.js";
 /** A pure boolean expression string for any sub-formula (implication = material). */
 export function lowerExpr(f) {
     switch (f.kind) {
         case "atom":
-            return `__bool(${f.js}, ${JSON.stringify(f.text)})`;
+            return `${BOOL_ALIAS}(${f.js}, ${JSON.stringify(f.text)})`;
         case "not":
             return `!(${lowerExpr(f.arg)})`;
         case "and":

package/dist/qualified-name.d.ts

@@ -3,3 +3,12 @@
  * (instance) / `Class.method` (static) when it lives on a class.
  */
 export declare function qualifiedName(functionName: string, className?: string, isStatic?: boolean): string;
+/**
+ * Matches the strings qualifiedName() produces: a bare identifier, or two
+ * identifiers joined by `#` (instance) / `.` (static). Segments are ASCII
+ * TypeScript identifiers; unicode identifiers (e.g. `précis`) are legal
+ * TypeScript but not matched — a known gap, kept so the pattern stays within
+ * JSON Schema's ECMA-regex subset (schemas/issue.schema.json embeds it; a
+ * sync test keeps the two spellings identical).
+ */
+export declare const QUALIFIED_NAME_PATTERN: RegExp;

package/dist/qualified-name.js

@@ -9,3 +9,12 @@ export function qualifiedName(functionName, className, isStatic) {
         ? `${className}.${functionName}`
         : `${className}#${functionName}`;
 }
+/**
+ * Matches the strings qualifiedName() produces: a bare identifier, or two
+ * identifiers joined by `#` (instance) / `.` (static). Segments are ASCII
+ * TypeScript identifiers; unicode identifiers (e.g. `précis`) are legal
+ * TypeScript but not matched — a known gap, kept so the pattern stays within
+ * JSON Schema's ECMA-regex subset (schemas/issue.schema.json embeds it; a
+ * sync test keeps the two spellings identical).
+ */
+export const QUALIFIED_NAME_PATTERN = /^[$A-Za-z_][$A-Za-z0-9_]*([#.][$A-Za-z_][$A-Za-z0-9_]*)?$/;

package/dist/run.d.ts

@@ -1,5 +1,4 @@
-import { type RunMeta } from "./envelope.js";
-import type { Envelope } from "./issue.js";
+import { type Envelope, type RunMeta } from "./envelope.js";
 /** Where the spawned vitest writes its JSON results, relative to cwd. */
 export declare const RESULTS_FILE = ".pabst/.last-run.json";
 export type RunResult = {
@@ -16,11 +15,11 @@ export type RunResult = {
     messages: string[];
 };
 /**
- * Run vitest over `target` (the generated-test root, or a single generated
- * file) and assemble the run envelope from its JSON results. When vitest
- * produces no parseable results file (e.g. it died on startup before its
- * reporter ran), the run yielded nothing trustworthy to report: instead of an
- * envelope, return vitest's raw output and exit status so the caller can
- * surface the underlying error.
+ * Run vitest over `target` (the generated out-files of one invocation, or a
+ * single file or directory) and assemble the run envelope from its JSON
+ * results. When vitest produces no parseable results file (e.g. it died on
+ * startup before its reporter ran), the run yielded nothing trustworthy to
+ * report: instead of an envelope, return vitest's raw output and exit status
+ * so the caller can surface the underlying error.
  */
-export declare function runTests(target: string, meta: RunMeta, resultsFile?: string): RunResult;
+export declare function runTests(target: string | string[], meta: RunMeta, resultsFile?: string): RunResult;

package/dist/run.js

@@ -1,15 +1,15 @@
 import { spawnSync } from "node:child_process";
 import { readFileSync, rmSync } from "node:fs";
-import { buildEnvelope } from "./envelope.js";
+import { buildEnvelope, } from "./envelope.js";
 /** Where the spawned vitest writes its JSON results, relative to cwd. */
 export const RESULTS_FILE = ".pabst/.last-run.json";
 /**
- * Run vitest over `target` (the generated-test root, or a single generated
- * file) and assemble the run envelope from its JSON results. When vitest
- * produces no parseable results file (e.g. it died on startup before its
- * reporter ran), the run yielded nothing trustworthy to report: instead of an
- * envelope, return vitest's raw output and exit status so the caller can
- * surface the underlying error.
+ * Run vitest over `target` (the generated out-files of one invocation, or a
+ * single file or directory) and assemble the run envelope from its JSON
+ * results. When vitest produces no parseable results file (e.g. it died on
+ * startup before its reporter ran), the run yielded nothing trustworthy to
+ * report: instead of an envelope, return vitest's raw output and exit status
+ * so the caller can surface the underlying error.
  */
 export function runTests(target, meta, resultsFile = RESULTS_FILE) {
     // A stale results file from a previous run must not be mistaken for this
@@ -25,7 +25,14 @@ export function runTests(target, meta, resultsFile = RESULTS_FILE) {
             stderr: `pabst: cannot clear stale results file ${resultsFile}: ${e instanceof Error ? e.message : String(e)}\n`,
         };
     }
-    const res = spawnSync("npx", ["vitest", "run", target, "--reporter=json", `--outputFile=${resultsFile}`], { encoding: "utf8" });
+    const targets = Array.isArray(target) ? target : [target];
+    const res = spawnSync("npx", [
+        "vitest",
+        "run",
+        ...targets,
+        "--reporter=json",
+        `--outputFile=${resultsFile}`,
+    ], { encoding: "utf8" });
     let json;
     try {
         json = JSON.parse(readFileSync(resultsFile, "utf8"));

package/dist/runtime.js

@@ -1,5 +1,5 @@
 import { stringify } from "fast-check";
-import { ISSUE_SENTINEL } from "./issue.js";
+import { encodeIssue, FC_PROPERTY_FAILED_MESSAGE, } from "./contract.js";
 /**
  * Encode a single counterexample value for JSON output: finite numbers,
  * booleans, and strings round-trip as native JSON; everything else (bigint,
@@ -13,7 +13,7 @@ function encodeValue(v) {
     return stringify(v);
 }
 function throwIssue(issue) {
-    throw new Error(ISSUE_SENTINEL + JSON.stringify(issue));
+    throw new Error(encodeIssue(issue));
 }
 /**
  * Assert that a property atom evaluated to a genuine boolean (no truthiness
@@ -54,7 +54,7 @@ export function report(file, functionName, name, varNames, d) {
         counterexample[n] = encodeValue(d.counterexample[i]);
     });
     const err = d.errorInstance;
-    const threw = !!err && err.message !== "Property failed by returning false";
+    const threw = !!err && err.message !== FC_PROPERTY_FAILED_MESSAGE;
     if (threw) {
         throwIssue({ ...base, kind: "threw", counterexample, error: err.message });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pabst-checker",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Property-based testing from @ensures annotations, powered by fast-check.",
   "repository": {
     "type": "git",
@@ -56,12 +56,12 @@
   },
   "devDependencies": {
     "@fast-check/vitest": "^0.4.1",
-    "fast-check": "^4.8.0",
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^26.1.0",
     "@vitest/coverage-v8": "^4.1.9",
     "ajv": "^8.20.0",
+    "fast-check": "^4.8.0",
     "prettier": "3.9.5"
   }
 }