pabst-checker 0.12.0

package/dist/discover.js

@@ -0,0 +1,113 @@
+import { existsSync, globSync } from "node:fs";
+import * as path from "node:path";
+import ts from "typescript";
+import { PabstError } from "./errors.js";
+const TS_EXT = /\.(ts|tsx|mts|cts)$/;
+const DECL_EXT = /\.d\.(ts|mts|cts)$/;
+/**
+ * True for TypeScript source files pabst should scan: .ts/.tsx/.mts/.cts,
+ * excluding declaration files — tsc copies JSDoc into declarations, so
+ * scanning them alongside their sources extracts every property twice.
+ */
+export function isTsSource(file) {
+    return TS_EXT.test(file) && !DECL_EXT.test(file);
+}
+/**
+ * The files pabst should scan: matches of the given patterns or, with no
+ * patterns, zero-argument discovery (the tsconfig.json file list, then the
+ * src/ convention). Throws PabstError when nothing usable is found.
+ */
+export function resolveFiles(patterns) {
+    if (patterns.length > 0) {
+        return { files: globbedFiles(patterns), source: "arguments" };
+    }
+    return discoverFiles();
+}
+// A pattern that itself names declaration files (index.d.ts, types/**/*.d.ts)
+// is an explicit ask for them and is honored; any other pattern drops
+// declaration matches (see isTsSource) so build output sitting next to its
+// sources is not scanned twice.
+function globbedFiles(patterns) {
+    const files = [
+        ...new Set(patterns.flatMap((p) => DECL_EXT.test(p) ? globSync(p) : globSync(p).filter(isTsSource))),
+    ];
+    if (files.length === 0)
+        throw new PabstError("no matching .ts files");
+    return files;
+}
+const NO_SOURCES = 'cannot determine where your source code is; pass files or globs (e.g. pabst test "src/**/*.ts")';
+// TS18003 ("No inputs were found in config file") and TS18002 ("The 'files'
+// list in config file is empty") are the config saying it names no files —
+// that is "no answer here", not a broken config, so discovery falls through
+// to the src/ convention.
+const NO_INPUTS_ERRORS = new Set([18002, 18003]);
+// Diagnostics about compilerOptions — unknown option (5023), unknown option
+// with a suggestion (5025), wrong value type (5024), value outside the known
+// set (6046) — cannot change which files the config enumerates, and routinely
+// arise from version skew between the user's TypeScript and the one pabst
+// bundles (a flag or target newer than ours). The file list is still exactly
+// what tsc would compile, so these are ignored.
+const OPTION_ERRORS = new Set([5023, 5024, 5025, 6046]);
+// Every other diagnostic (bad JSON, unresolvable extends, misspelled root
+// options like "excludes", ...) can make the file list differ from what the
+// user's config describes, so it is user-facing and fatal: silently testing
+// different files than the config means would be worse than stopping.
+function fatalError(diagnostics) {
+    return diagnostics.find((e) => !NO_INPUTS_ERRORS.has(e.code) && !OPTION_ERRORS.has(e.code));
+}
+function configError(diagnostic) {
+    const text = ts.flattenDiagnosticMessageText(diagnostic.messageText, " ");
+    return new PabstError(`tsconfig.json: ${text}`);
+}
+// path.relative yields ".."-led (or, across Windows drives, absolute) paths
+// for files outside cwd. Generated tests are rooted in ./.pabst/, so a source
+// outside the package cannot be tested from here — a monorepo neighbor's
+// files are that neighbor's run, not this one's — and is dropped.
+function insideCwd(rel) {
+    return (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+}
+/**
+ * The files tsc would compile for ./tsconfig.json, as sorted relative paths
+ * filtered to scannable sources; undefined when there is no tsconfig.json,
+ * empty when the config resolves to no usable files.
+ */
+function tsconfigFiles(cwd) {
+    const configPath = path.join(cwd, "tsconfig.json");
+    if (!existsSync(configPath))
+        return undefined;
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (read.error)
+        throw configError(read.error);
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, cwd, undefined, configPath);
+    const fatal = fatalError(parsed.errors);
+    if (fatal)
+        throw configError(fatal);
+    const files = parsed.fileNames
+        .map((f) => path.relative(cwd, f))
+        .filter(insideCwd)
+        .filter(isTsSource)
+        .sort();
+    // A "files" list names paths without checking them, so a stale entry comes
+    // back with no diagnostic; stop with a real message rather than crashing on
+    // the eventual read. (include-glob matches exist by construction.)
+    const missing = files.find((f) => !existsSync(path.resolve(cwd, f)));
+    if (missing) {
+        throw new PabstError(`tsconfig.json: file not found: ${missing}`);
+    }
+    return files;
+}
+/**
+ * Zero-argument mode: find the project's TypeScript sources. Uses the file
+ * list of ./tsconfig.json when it names any, then the src/ convention;
+ * throws PabstError when nothing is found.
+ */
+function discoverFiles() {
+    const fromConfig = tsconfigFiles(process.cwd());
+    if (fromConfig !== undefined && fromConfig.length > 0) {
+        return { files: fromConfig, source: "tsconfig.json" };
+    }
+    const files = globSync("src/**/*").filter(isTsSource).sort();
+    if (files.length > 0)
+        return { files, source: "src/" };
+    throw new PabstError(NO_SOURCES);
+}

package/dist/domains.d.ts

@@ -0,0 +1,47 @@
+import type { Binder, Domain, Range } from "./ir.js";
+export declare const DOMAIN_TABLE: Record<Domain, string>;
+export declare function isDomain(s: string): s is Domain;
+export declare const MAX_SAFE = 9007199254740991n;
+export interface IntBounds {
+    lo: bigint;
+    hi: bigint;
+    /** A finite endpoint fell outside the safe integer range, so the
+     * interval was intersected with it (possibly to emptiness: lo > hi). */
+    clamped: boolean;
+}
+/** The inclusive fc.integer bounds an int/nat interval lowers to: open
+ * endpoints fold into ±1 (fc.integer has no exclusion options), nat floors
+ * at 0, and the result is intersected with the safe integer range. Both
+ * sides are always concrete — fc.integer's implicit defaults are 32-bit,
+ * so a far-out explicit bound with an omitted side would crash it — and an
+ * unbounded (∞) side means the safe-range limit. */
+export declare function intBounds(domain: "int" | "nat", range: Range): IntBounds;
+/** The inclusive fc.bigInt bounds a bigint interval lowers to. An
+ * unbounded side stays undefined — fc.bigInt, unlike fc.integer, widens
+ * its default range around a far-out explicit bound. */
+export declare function bigintBounds(range: Range): {
+    lo?: bigint;
+    hi?: bigint;
+};
+/** One endpoint of a number interval as fc.double sees it: the literal
+ * text emitted into the generated test, and its numeric value (used to
+ * validate the constraints with fc itself at parse time). */
+export interface NumberBound {
+    lit: string;
+    val: number;
+}
+export interface NumberConstraints {
+    min?: NumberBound;
+    minExcluded: boolean;
+    max?: NumberBound;
+    maxExcluded: boolean;
+}
+/** The fc.double constraints a number interval lowers to. An open ∞
+ * endpoint becomes an excluded infinite bound, which fast-check clamps to
+ * ±MAX_VALUE; a closed ∞ endpoint is fc.double's default (inclusive ±∞),
+ * so that side is simply omitted. */
+export declare function numberConstraints(range: Range): NumberConstraints;
+/** The binder's guards are mutually exclusive per domain, so arbitraryFor
+ * takes the binder itself rather than growing a positional parameter per
+ * guard kind. */
+export declare function arbitraryFor(binder: Pick<Binder, "domain" | "range" | "pattern">): string;

package/dist/domains.js

@@ -0,0 +1,130 @@
+import { PabstError } from "./errors.js";
+import { anchoredSource, regexGuardDomainError } from "./regex-guard.js";
+export const DOMAIN_TABLE = {
+    int: "fc.integer()",
+    nat: "fc.nat()",
+    number: "fc.double()",
+    boolean: "fc.boolean()",
+    string: "fc.string()",
+    bigint: "fc.bigInt()",
+};
+export function isDomain(s) {
+    return Object.prototype.hasOwnProperty.call(DOMAIN_TABLE, s);
+}
+export const MAX_SAFE = 9007199254740991n;
+/** The inclusive fc.integer bounds an int/nat interval lowers to: open
+ * endpoints fold into ±1 (fc.integer has no exclusion options), nat floors
+ * at 0, and the result is intersected with the safe integer range. Both
+ * sides are always concrete — fc.integer's implicit defaults are 32-bit,
+ * so a far-out explicit bound with an omitted side would crash it — and an
+ * unbounded (∞) side means the safe-range limit. */
+export function intBounds(domain, range) {
+    let lo = range.min === undefined
+        ? -MAX_SAFE
+        : BigInt(range.min) + (range.minOpen ? 1n : 0n);
+    let hi = range.max === undefined
+        ? MAX_SAFE
+        : BigInt(range.max) - (range.maxOpen ? 1n : 0n);
+    if (domain === "nat" && lo < 0n)
+        lo = 0n;
+    const clamped = lo < -MAX_SAFE || lo > MAX_SAFE || hi < -MAX_SAFE || hi > MAX_SAFE;
+    if (lo < -MAX_SAFE)
+        lo = -MAX_SAFE;
+    if (hi > MAX_SAFE)
+        hi = MAX_SAFE;
+    return { lo, hi, clamped };
+}
+/** The inclusive fc.bigInt bounds a bigint interval lowers to. An
+ * unbounded side stays undefined — fc.bigInt, unlike fc.integer, widens
+ * its default range around a far-out explicit bound. */
+export function bigintBounds(range) {
+    const lo = range.min === undefined
+        ? undefined
+        : BigInt(range.min) + (range.minOpen ? 1n : 0n);
+    const hi = range.max === undefined
+        ? undefined
+        : BigInt(range.max) - (range.maxOpen ? 1n : 0n);
+    const bounds = {};
+    if (lo !== undefined)
+        bounds.lo = lo;
+    if (hi !== undefined)
+        bounds.hi = hi;
+    return bounds;
+}
+/** The fc.double constraints a number interval lowers to. An open ∞
+ * endpoint becomes an excluded infinite bound, which fast-check clamps to
+ * ±MAX_VALUE; a closed ∞ endpoint is fc.double's default (inclusive ±∞),
+ * so that side is simply omitted. */
+export function numberConstraints(range) {
+    const c = {
+        minExcluded: range.minOpen === true,
+        maxExcluded: range.maxOpen === true,
+    };
+    if (range.min !== undefined) {
+        c.min = { lit: range.min, val: Number(range.min) };
+    }
+    else if (range.minOpen) {
+        c.min = { lit: "Number.NEGATIVE_INFINITY", val: Number.NEGATIVE_INFINITY };
+    }
+    if (range.max !== undefined) {
+        c.max = { lit: range.max, val: Number(range.max) };
+    }
+    else if (range.maxOpen) {
+        c.max = { lit: "Number.POSITIVE_INFINITY", val: Number.POSITIVE_INFINITY };
+    }
+    return c;
+}
+/** The binder's guards are mutually exclusive per domain, so arbitraryFor
+ * takes the binder itself rather than growing a positional parameter per
+ * guard kind. */
+export function arbitraryFor(binder) {
+    const { domain, range, pattern } = binder;
+    if (pattern) {
+        if (domain !== "string") {
+            // Unreachable via the parser (parseRegexGuard rejects these), kept
+            // as a backstop for direct callers.
+            throw regexGuardDomainError(domain);
+        }
+        // Safe to re-emit as a literal: the source came from a literal scan,
+        // so any '/' in it is escaped or inside a character class.
+        return `fc.stringMatching(/${anchoredSource(pattern.source)}/${pattern.flags})`;
+    }
+    if (!range)
+        return DOMAIN_TABLE[domain];
+    switch (domain) {
+        case "int":
+        case "nat": {
+            // A ranged nat is just a bounded integer; fc.nat has no `min`.
+            const { lo, hi } = intBounds(domain, range);
+            return `fc.integer({ min: ${lo}, max: ${hi} })`;
+        }
+        case "number": {
+            // Bounded fc.double still generates NaN unless told otherwise, and
+            // NaN satisfies no interval.
+            const c = numberConstraints(range);
+            const opts = [];
+            if (c.min)
+                opts.push(`min: ${c.min.lit}`);
+            if (c.minExcluded)
+                opts.push(`minExcluded: true`);
+            if (c.max)
+                opts.push(`max: ${c.max.lit}`);
+            if (c.maxExcluded)
+                opts.push(`maxExcluded: true`);
+            opts.push(`noNaN: true`);
+            return `fc.double({ ${opts.join(", ")} })`;
+        }
+        case "bigint": {
+            const { lo, hi } = bigintBounds(range);
+            return `fc.bigInt${render(lo === undefined ? undefined : `min: ${lo}n`, hi === undefined ? undefined : `max: ${hi}n`)}`;
+        }
+        default:
+            // Unreachable via the parser (parseRange rejects these), kept as a
+            // backstop for direct callers.
+            throw new PabstError(`domain '${domain}' does not support interval constraints`);
+    }
+}
+function render(...opts) {
+    const present = opts.filter((o) => o !== undefined);
+    return present.length === 0 ? "()" : `({ ${present.join(", ")} })`;
+}

package/dist/emit.d.ts

@@ -0,0 +1,2 @@
+import type { PropertySpec } from "./ir.js";
+export declare function emit(specs: PropertySpec[], sourceFile: string, outFile: string, seed: number): string;

package/dist/emit.js

@@ -0,0 +1,74 @@
+import * as path from "node:path";
+import { arbitraryFor } from "./domains.js";
+import { qualifiedName } from "./qualified-name.js";
+const SRC_EXT = /\.(ts|tsx|mts|cts|js|mjs|cjs)$/;
+export function emit(specs, sourceFile, outFile, seed) {
+    const srcAbs = path.resolve(sourceFile).replace(SRC_EXT, "");
+    const outDir = path.dirname(path.resolve(outFile));
+    let rel = path.relative(outDir, srcAbs).split(path.sep).join("/");
+    if (!rel.startsWith("."))
+        rel = "./" + rel;
+    const allExports = [...new Set(specs.flatMap((s) => s.freeExports))].sort();
+    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 * as __M from "${rel}";`);
+    if (allExports.length > 0)
+        lines.push(`const { ${allExports.join(", ")} } = __M;`);
+    lines.push("");
+    lines.push(`describe("pabst", () => {`);
+    // Group by class (undefined = top-level function), then by member name.
+    const byClass = new Map();
+    for (const s of specs) {
+        let methods = byClass.get(s.className);
+        if (!methods) {
+            methods = new Map();
+            byClass.set(s.className, methods);
+        }
+        const arr = methods.get(s.functionName) ?? [];
+        arr.push(s);
+        methods.set(s.functionName, arr);
+    }
+    for (const [className, methods] of byClass) {
+        if (className === undefined) {
+            for (const [fnName, fnSpecs] of methods) {
+                lines.push(`  describe(${JSON.stringify(fnName)}, () => {`);
+                for (const s of fnSpecs)
+                    lines.push(emitProp(s, sourceFile, seed, "    "));
+                lines.push(`  });`);
+            }
+        }
+        else {
+            lines.push(`  describe(${JSON.stringify(className)}, () => {`);
+            for (const [methodName, mSpecs] of methods) {
+                lines.push(`    describe(${JSON.stringify(methodName)}, () => {`);
+                for (const s of mSpecs)
+                    lines.push(emitProp(s, sourceFile, seed, "      "));
+                lines.push(`    });`);
+            }
+            lines.push(`  });`);
+        }
+    }
+    lines.push(`});`);
+    lines.push("");
+    return lines.join("\n");
+}
+function emitProp(s, sourceFile, seed, indent) {
+    const arbs = s.binders.map((b) => arbitraryFor(b)).join(", ");
+    const vars = s.binders.map((b) => b.varName).join(", ");
+    const varNames = s.binders.map((b) => JSON.stringify(b.varName)).join(", ");
+    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 params = `{ seed: ${seed}, reporter: ${reporter} }`;
+    const out = [];
+    out.push(`${indent}test.prop([${arbs}], ${params})(${name}, (${vars}) => {`);
+    for (const p of s.preconditions)
+        out.push(`${indent}  fc.pre(${p});`);
+    out.push(`${indent}  const __r = (${s.body});`);
+    out.push(`${indent}  return __r;`);
+    out.push(`${indent}});`);
+    return out.join("\n");
+}

package/dist/envelope.d.ts

@@ -0,0 +1,29 @@
+import { type Issue, type Envelope } from "./issue.js";
+/** The subset of vitest's JSON reporter output the envelope consumes. */
+export interface AssertionResult {
+    status: string;
+    failureMessages: string[];
+}
+export interface FileResult {
+    status?: string;
+    message?: string;
+    assertionResults: AssertionResult[];
+}
+export interface VitestJson {
+    numPassedTests: number;
+    numFailedTests: number;
+    success: boolean;
+    testResults: FileResult[];
+}
+/** Run-level metadata the CLI captures, independent of the vitest run. */
+export interface RunMeta {
+    version: string;
+    startedAt: string;
+    cwd: string;
+    seed: number;
+    generated: number;
+}
+/** Parse every failed assertion's tagged payload into an Issue. */
+export declare function collectIssues(json: VitestJson): Issue[];
+/** Assemble the full run envelope from metadata and a parsed vitest run. */
+export declare function buildEnvelope(meta: RunMeta, json: VitestJson): Envelope;

package/dist/envelope.js

@@ -0,0 +1,28 @@
+import { parseIssue } from "./issue.js";
+/** Parse every failed assertion's tagged payload into an Issue. */
+export function collectIssues(json) {
+    const issues = [];
+    for (const file of json.testResults ?? []) {
+        for (const a of file.assertionResults ?? []) {
+            if (a.status !== "failed")
+                continue;
+            const issue = parseIssue(a.failureMessages[0] ?? "");
+            if (issue)
+                issues.push(issue);
+        }
+    }
+    return issues;
+}
+/** Assemble the full run envelope from metadata and a parsed vitest run. */
+export function buildEnvelope(meta, json) {
+    return {
+        version: meta.version,
+        startedAt: meta.startedAt,
+        cwd: meta.cwd,
+        seed: meta.seed,
+        generated: meta.generated,
+        passed: json.numPassedTests,
+        failed: json.numFailedTests,
+        issues: collectIssues(json),
+    };
+}

package/dist/equations.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validate an atom's JS and desugar its equation (see README, "Equations"):
+ * a depth-0 `A ≡ B` becomes `Object.is(A, B)` and `A ≢ B` becomes
+ * `!Object.is(A, B)`. The glyphs are available only at the atom's top
+ * level — in nested positions (callbacks, arguments, template
+ * substitutions) call Object.is directly.
+ */
+export declare function desugarEquations(text: string): string;