pabst-checker 0.12.0

package/dist/formula-lexer.js

@@ -0,0 +1,191 @@
+import ts from "typescript";
+import { PabstError } from "./errors.js";
+const GLYPH = {
+    "¬": "not",
+    "∧": "and",
+    "∨": "or",
+    "→": "implies",
+    "↔": "iff",
+};
+const OPEN = new Set([
+    ts.SyntaxKind.OpenParenToken,
+    ts.SyntaxKind.OpenBracketToken,
+    ts.SyntaxKind.OpenBraceToken,
+    // `…${ opens a substitution: its contents are never at depth 0.
+    ts.SyntaxKind.TemplateHead,
+]);
+const CLOSE = new Set([
+    ts.SyntaxKind.CloseParenToken,
+    ts.SyntaxKind.CloseBracketToken,
+    ts.SyntaxKind.CloseBraceToken,
+    // }…` ends the last substitution. TemplateMiddle (}…${) closes one and
+    // opens the next — net depth unchanged — so it stays a js token.
+    ts.SyntaxKind.TemplateTail,
+]);
+/**
+ * Scan `text` with the context fixes the standalone TS scanner does not
+ * apply on its own: `/` regex-vs-division, `>` re-merged into >=, >>, … (the
+ * base scan splits them for generic-closing-`>` handling), and template
+ * continuation after a `${…}` substitution closes (the scanner would
+ * otherwise leave template mode and corrupt the middle/tail text).
+ */
+export function* scanTokens(text, start = 0) {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, /*skipTrivia*/ true);
+    scanner.setText(text, start);
+    let kind;
+    let prev = null;
+    let prevText = "";
+    // Open-brace count within each active template substitution, innermost last.
+    const templateBraces = [];
+    while ((kind = scanner.scan()) !== ts.SyntaxKind.EndOfFileToken) {
+        if (kind === ts.SyntaxKind.SlashToken ||
+            kind === ts.SyntaxKind.SlashEqualsToken) {
+            // A `/` right after a `\` is the `\/` (or) fallback, not a regex.
+            if (regexCanFollow(prev) && prevText !== "\\") {
+                const re = scanner.reScanSlashToken();
+                if (re === ts.SyntaxKind.RegularExpressionLiteral)
+                    kind = re;
+            }
+        }
+        if (kind === ts.SyntaxKind.GreaterThanToken) {
+            kind = scanner.reScanGreaterToken();
+        }
+        const top = templateBraces.length - 1;
+        if (kind === ts.SyntaxKind.TemplateHead) {
+            // `` `…${ `` opens a template; its first substitution is now active.
+            templateBraces.push(0);
+        }
+        else if (kind === ts.SyntaxKind.OpenBraceToken && top >= 0) {
+            templateBraces[top] = templateBraces[top] + 1;
+        }
+        else if (kind === ts.SyntaxKind.CloseBraceToken && top >= 0) {
+            if (templateBraces[top] > 0) {
+                // an ordinary `}` inside the substitution
+                templateBraces[top] = templateBraces[top] - 1;
+            }
+            else {
+                // This `}` ends the substitution: re-scan as template continuation so
+                // the following text stays template text rather than loose tokens.
+                kind = scanner.reScanTemplateToken(/*isTaggedTemplate*/ false);
+                if (kind === ts.SyntaxKind.TemplateTail)
+                    templateBraces.pop();
+                // TemplateMiddle keeps the same level (a new substitution follows).
+            }
+        }
+        const tokenText = scanner.getTokenText();
+        yield {
+            kind,
+            text: tokenText,
+            start: scanner.getTokenStart(),
+            end: scanner.getTextPos(),
+        };
+        prev = kind;
+        prevText = tokenText;
+    }
+}
+/** Tokenize a formula body. Glyphs/fallbacks become connective tokens; the rest is js. */
+export function lexFormula(body) {
+    const raw = [];
+    for (const { kind, text, start, end } of scanTokens(body)) {
+        rejectQuantifiers(text);
+        const fkind = GLYPH[text] ??
+            (text === "iff"
+                ? "iff"
+                : OPEN.has(kind)
+                    ? "open"
+                    : CLOSE.has(kind)
+                        ? "close"
+                        : "js");
+        raw.push({ kind: fkind, text, start, end });
+    }
+    return mergeArrowFallbacks(mergeSlashFallbacks(raw));
+}
+/** The source text spanned by toks (empty when toks is empty). */
+export function sliceText(source, toks) {
+    if (toks.length === 0)
+        return "";
+    return source.slice(toks[0].start, toks[toks.length - 1].end);
+}
+/** A `/` can begin a regex unless the previous token ends a value (then it's division). */
+export function regexCanFollow(prev) {
+    if (prev === null)
+        return true;
+    switch (prev) {
+        case ts.SyntaxKind.Identifier:
+        case ts.SyntaxKind.CloseParenToken:
+        case ts.SyntaxKind.CloseBracketToken:
+        case ts.SyntaxKind.CloseBraceToken:
+        case ts.SyntaxKind.RegularExpressionLiteral:
+        case ts.SyntaxKind.TemplateTail:
+        case ts.SyntaxKind.ThisKeyword:
+        case ts.SyntaxKind.TrueKeyword:
+        case ts.SyntaxKind.FalseKeyword:
+        case ts.SyntaxKind.NullKeyword:
+        case ts.SyntaxKind.PlusPlusToken:
+        case ts.SyntaxKind.MinusMinusToken:
+            return false;
+    }
+    return !(prev >= ts.SyntaxKind.FirstLiteralToken &&
+        prev <= ts.SyntaxKind.LastLiteralToken);
+}
+function rejectQuantifiers(text) {
+    if (text === "∃" || text === "exists") {
+        throw new PabstError("existential quantifiers (∃ / exists) are not supported: property-based " +
+            "testing samples inputs, so it can refute ∀ with a counterexample but cannot " +
+            "soundly confirm ∃ (a bounded/exhaustive mode would be needed)");
+    }
+    if (text === "∀" || text === "forall") {
+        throw new PabstError("nested quantifiers are not supported: bind all variables in the leading ∀ prefix");
+    }
+}
+/** Merge adjacent js tokens forming -> / ==> (implies) and <-> (iff). */
+function mergeArrowFallbacks(toks) {
+    const out = [];
+    for (let i = 0; i < toks.length; i++) {
+        const a = toks[i], b = toks[i + 1], c = toks[i + 2];
+        const adj = (x, y) => !!y && x.end === y.start;
+        // <-> : "<" "-" ">"
+        if (a.text === "<" &&
+            b?.text === "-" &&
+            c?.text === ">" &&
+            adj(a, b) &&
+            adj(b, c)) {
+            out.push({ kind: "iff", text: "<->", start: a.start, end: c.end });
+            i += 2;
+            continue;
+        }
+        // -> : "-" ">"    and    ==> : "==" ">"
+        if ((a.text === "-" || a.text === "==") && b?.text === ">" && adj(a, b)) {
+            out.push({
+                kind: "implies",
+                text: a.text + ">",
+                start: a.start,
+                end: b.end,
+            });
+            i += 1;
+            continue;
+        }
+        out.push(a);
+    }
+    return out;
+}
+/** Merge a real slash adjacent to a backslash: /\ → and, \/ → or. */
+function mergeSlashFallbacks(toks) {
+    const out = [];
+    for (let i = 0; i < toks.length; i++) {
+        const a = toks[i], b = toks[i + 1];
+        const adj = !!b && a.end === b.start;
+        if (adj && a.text === "/" && b.text === "\\") {
+            out.push({ kind: "and", text: "/\\", start: a.start, end: b.end });
+            i += 1;
+            continue;
+        }
+        if (adj && a.text === "\\" && b.text === "/") {
+            out.push({ kind: "or", text: "\\/", start: a.start, end: b.end });
+            i += 1;
+            continue;
+        }
+        out.push(a);
+    }
+    return out;
+}

package/dist/formula-parser.d.ts

@@ -0,0 +1,2 @@
+import type { Formula } from "./formula-ast.js";
+export declare function parseBody(body: string): Formula;

package/dist/formula-parser.js

@@ -0,0 +1,122 @@
+import { lexFormula, sliceText } from "./formula-lexer.js";
+import { PabstError } from "./errors.js";
+import { desugarEquations } from "./equations.js";
+export function parseBody(body) {
+    const toks = lexFormula(body);
+    return parseFormula(toks, 0, toks.length, body);
+}
+const BINARY = new Set(["and", "or", "implies", "iff"]);
+/** formula ::= equivalence   (docs/grammar.ebnf) — must consume the whole range. */
+function parseFormula(toks, start, end, src) {
+    const c = { toks, pos: start, end, src };
+    const f = parseEquivalence(c);
+    if (c.pos !== c.end) {
+        throw new PabstError(`unbalanced parentheses in formula: unexpected '${c.toks[c.pos].text}' (in: ${src})`);
+    }
+    return f;
+}
+/** equivalence ::= implication (IFF implication)?   — non-associative. */
+function parseEquivalence(c) {
+    const left = parseImplication(c);
+    if (peek(c)?.kind !== "iff")
+        return left;
+    c.pos++;
+    const right = parseImplication(c);
+    if (peek(c)?.kind === "iff") {
+        throw new PabstError("chained ↔ is ambiguous: parenthesize, e.g. (a ↔ b) ↔ c");
+    }
+    return { kind: "iff", left, right };
+}
+/** implication ::= disjunction (IMPLIES disjunction)*
+ * A chain a → b → c makes every segment but the last an antecedent. */
+function parseImplication(c) {
+    const segs = [parseDisjunction(c)];
+    while (peek(c)?.kind === "implies") {
+        c.pos++;
+        segs.push(parseDisjunction(c));
+    }
+    if (segs.length === 1)
+        return segs[0];
+    return {
+        kind: "implication",
+        antecedents: segs.slice(0, -1),
+        consequent: segs[segs.length - 1],
+    };
+}
+/** disjunction ::= conjunction (OR conjunction)*   — left-associative. */
+function parseDisjunction(c) {
+    let f = parseConjunction(c);
+    while (peek(c)?.kind === "or") {
+        c.pos++;
+        f = { kind: "or", left: f, right: parseConjunction(c) };
+    }
+    return f;
+}
+/** conjunction ::= negation (AND negation)*   — left-associative. */
+function parseConjunction(c) {
+    let f = parseNegation(c);
+    while (peek(c)?.kind === "and") {
+        c.pos++;
+        f = { kind: "and", left: f, right: parseNegation(c) };
+    }
+    return f;
+}
+/** negation ::= NOT negation | primary */
+function parseNegation(c) {
+    if (peek(c)?.kind === "not") {
+        c.pos++;
+        return { kind: "not", arg: parseNegation(c) };
+    }
+    return parsePrimary(c);
+}
+/** primary ::= "(" formula ")" | atom
+ * The operand extends to the next depth-0 binary connective (or an
+ * unmatched close, or the end). A wholly-wrapped ( … ) is logical
+ * grouping; any other parenthesis belongs to the JavaScript island. */
+function parsePrimary(c) {
+    const start = c.pos;
+    let depth = 0;
+    while (c.pos < c.end) {
+        const t = c.toks[c.pos];
+        if (t.kind === "open")
+            depth++;
+        else if (t.kind === "close") {
+            if (depth === 0)
+                break;
+            depth--;
+        }
+        else if (depth === 0 && BINARY.has(t.kind))
+            break;
+        c.pos++;
+    }
+    const span = c.toks.slice(start, c.pos);
+    if (span.length === 0) {
+        throw new PabstError("empty operand: a connective is missing a side");
+    }
+    if (whollyWrapped(span)) {
+        return parseFormula(c.toks, start + 1, c.pos - 1, c.src);
+    }
+    const text = sliceText(c.src, span).trim();
+    return { kind: "atom", text, js: desugarEquations(text) };
+}
+function peek(c) {
+    return c.pos < c.end ? c.toks[c.pos] : undefined;
+}
+/** True when span[0] is "(" whose match is the final token. */
+function whollyWrapped(span) {
+    if (span.length < 2 || span[0].kind !== "open" || span[0].text !== "(") {
+        return false;
+    }
+    let depth = 0;
+    for (let i = 0; i < span.length; i++) {
+        const t = span[i];
+        if (t.kind === "open")
+            depth++;
+        else if (t.kind === "close") {
+            depth--;
+            if (depth === 0)
+                return i === span.length - 1;
+        }
+    }
+    return false;
+}

package/dist/free-idents.d.ts

@@ -0,0 +1,6 @@
+export declare const GLOBALS: Set<string>;
+export declare function freeIdentifiers(expr: string): Set<string>;
+export interface Classification {
+    freeExports: string[];
+}
+export declare function classify(idents: Set<string>, boundVars: Set<string>, moduleExports: Set<string>): Classification;

package/dist/free-idents.js

@@ -0,0 +1,60 @@
+import ts from "typescript";
+import { PabstError } from "./errors.js";
+export const GLOBALS = new Set([
+    "Math",
+    "Number",
+    "JSON",
+    "Object",
+    "Array",
+    "String",
+    "Boolean",
+    "BigInt",
+    "Date",
+    "isNaN",
+    "isFinite",
+    "parseInt",
+    "parseFloat",
+    "undefined",
+    "NaN",
+    "Infinity",
+    "Symbol",
+    "Map",
+    "Set",
+    "RegExp",
+    "Error",
+    "console",
+]);
+export function freeIdentifiers(expr) {
+    const sf = ts.createSourceFile("__expr.ts", `(${expr});`, ts.ScriptTarget.Latest, true);
+    const found = new Set();
+    const visit = (node) => {
+        if (ts.isIdentifier(node)) {
+            const p = node.parent;
+            const isPropName = ts.isPropertyAccessExpression(p) && p.name === node;
+            const isQualified = ts.isQualifiedName(p) && p.right === node;
+            const isObjKey = ts.isPropertyAssignment(p) && p.name === node;
+            if (!isPropName && !isQualified && !isObjKey)
+                found.add(node.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return found;
+}
+export function classify(idents, boundVars, moduleExports) {
+    const freeExports = [];
+    for (const id of idents) {
+        if (boundVars.has(id))
+            continue;
+        if (GLOBALS.has(id))
+            continue;
+        if (moduleExports.has(id)) {
+            freeExports.push(id);
+            continue;
+        }
+        // The per-annotation wrapper in build-spec prefixes file, line, and
+        // property name, so naming them here would state them twice.
+        throw new PabstError(`references '${id}', which is not exported`);
+    }
+    return { freeExports: [...new Set(freeExports)] };
+}

package/dist/ir.d.ts

@@ -0,0 +1,45 @@
+export type Domain = "int" | "nat" | "number" | "boolean" | "string" | "bigint";
+/** Interval constraint on a numeric binder. Endpoints are the user's
+ * literal text, kept verbatim so floats are emitted exactly as written —
+ * except a leading `+`, redundant leading zeros, and a bigint `n` suffix
+ * are stripped (lowering re-adds `n` for bigint). An absent endpoint is
+ * unbounded (the user wrote -∞ / ∞); an open flag means that side's
+ * endpoint is excluded. */
+export interface Range {
+    min?: string;
+    max?: string;
+    minOpen?: boolean;
+    maxOpen?: boolean;
+}
+/** Regex guard on a string binder. Source and flags are the user's literal
+ * text, kept verbatim; lowering anchors the source (see anchoredSource in
+ * regex-guard.ts) so the guard means whole-string membership. */
+export interface StringPattern {
+    source: string;
+    flags: string;
+}
+export interface Binder {
+    varName: string;
+    domain: Domain;
+    range?: Range;
+    pattern?: StringPattern;
+}
+export interface PropertySpec {
+    name: string;
+    functionName: string;
+    /** Set when the property lives on a class method. */
+    className?: string;
+    /** Meaningful only when className is set: true for a static method. */
+    isStatic?: boolean;
+    binders: Binder[];
+    /** Desugared boolean expression, ready to drop into a predicate. */
+    body: string;
+    /** Desugared top-level antecedents, each lifted to fc.pre. */
+    preconditions: string[];
+    /** Module exports the body/preconditions reference. */
+    freeExports: string[];
+    location: {
+        file: string;
+        line: number;
+    };
+}

package/dist/ir.js

@@ -0,0 +1 @@
+export {};

package/dist/issue.d.ts

@@ -0,0 +1,26 @@
+export type IssueKind = "falsified" | "threw" | "exhausted";
+export interface Issue {
+    file: string;
+    function: string;
+    property: string;
+    kind: IssueKind;
+    counterexample?: Record<string, unknown>;
+    error?: string;
+}
+export interface Envelope {
+    version: string;
+    startedAt: string;
+    cwd: string;
+    seed: number;
+    generated: number;
+    passed: number;
+    failed: number;
+    issues: Issue[];
+}
+export declare const ISSUE_SENTINEL = "PABST_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 declare function parseIssue(failureMessage: string): Issue | null;

package/dist/issue.js

@@ -0,0 +1,18 @@
+export const ISSUE_SENTINEL = "PABST_ISSUE:";
+const ISSUE_RE = /PABST_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/lower.d.ts

@@ -0,0 +1,12 @@
+import type { Formula } from "./formula-ast.js";
+/** A pure boolean expression string for any sub-formula (implication = material). */
+export declare function lowerExpr(f: Formula): string;
+/**
+ * Lower the body root. A top-level implication's antecedents become fc.pre(...)
+ * discards (QuickCheck conditional-property semantics); everything else is one
+ * boolean expression. NOTE: ↔ never reaches here as a precondition — only `→`.
+ */
+export declare function lowerTop(f: Formula): {
+    preconditions: string[];
+    body: string;
+};

package/dist/lower.js

@@ -0,0 +1,37 @@
+/** 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)})`;
+        case "not":
+            return `!(${lowerExpr(f.arg)})`;
+        case "and":
+            return `(${lowerExpr(f.left)} && ${lowerExpr(f.right)})`;
+        case "or":
+            return `(${lowerExpr(f.left)} || ${lowerExpr(f.right)})`;
+        case "iff":
+            return `(${lowerExpr(f.left)} === ${lowerExpr(f.right)})`;
+        case "implication":
+            return materialImplication(f.antecedents, f.consequent);
+    }
+}
+function materialImplication(antecedents, consequent) {
+    if (antecedents.length === 0)
+        return lowerExpr(consequent);
+    const [head, ...rest] = antecedents;
+    return `(!(${lowerExpr(head)}) || ${materialImplication(rest, consequent)})`;
+}
+/**
+ * Lower the body root. A top-level implication's antecedents become fc.pre(...)
+ * discards (QuickCheck conditional-property semantics); everything else is one
+ * boolean expression. NOTE: ↔ never reaches here as a precondition — only `→`.
+ */
+export function lowerTop(f) {
+    if (f.kind === "implication") {
+        return {
+            preconditions: f.antecedents.map(lowerExpr),
+            body: lowerExpr(f.consequent),
+        };
+    }
+    return { preconditions: [], body: lowerExpr(f) };
+}

package/dist/parse-formula.d.ts

@@ -0,0 +1,12 @@
+import ts from "typescript";
+import type { Binder } from "./ir.js";
+export interface ParsedFormula {
+    binders: Binder[];
+    /** Raw TS expression text of each `pre(...)` argument, in source order. */
+    preconditions: string[];
+    /** Raw TS expression text of the returned / expression body. */
+    body: string;
+    /** Precondition arguments + body, as nodes to walk for free identifiers. */
+    exprNodes: ts.Expression[];
+}
+export declare function parseFormula(formula: string): ParsedFormula;

package/dist/parse-formula.js

@@ -0,0 +1,78 @@
+import ts from "typescript";
+import { isDomain } from "./domains.js";
+const VALID_DOMAINS = "int, nat, number, boolean, string, bigint";
+export function parseFormula(formula) {
+    const sf = ts.createSourceFile("__formula.ts", `(${formula});`, ts.ScriptTarget.Latest, true);
+    const stmt = sf.statements[0];
+    /* v8 ignore next 3 -- the `(...)` wrapper always parses to an ExpressionStatement; defensive guard only */
+    if (!stmt || !ts.isExpressionStatement(stmt)) {
+        throw new Error(`property must be an arrow function '(x: domain, ...) => body': ${formula.trim().slice(0, 60)}`);
+    }
+    let expr = stmt.expression;
+    while (ts.isParenthesizedExpression(expr))
+        expr = expr.expression;
+    if (!ts.isArrowFunction(expr)) {
+        throw new Error(`property must be an arrow function '(x: domain, ...) => body': ${formula.trim().slice(0, 60)}`);
+    }
+    const binders = parseBinders(expr, sf);
+    const { preconditions, body, exprNodes } = parseBody(expr.body, sf);
+    return { binders, preconditions, body, exprNodes };
+}
+function parseBinders(arrow, sf) {
+    const binders = [];
+    for (const p of arrow.parameters) {
+        if (!ts.isIdentifier(p.name)) {
+            throw new Error(`binder must be a simple name '(x: domain)', no destructuring: ${p.getText(sf)}`);
+        }
+        if (p.dotDotDotToken)
+            throw new Error(`rest parameters are not supported: ${p.getText(sf)}`);
+        if (p.questionToken)
+            throw new Error(`optional binders are not supported: ${p.name.text}`);
+        if (p.initializer)
+            throw new Error(`default binder values are not supported: ${p.name.text}`);
+        if (!p.type)
+            throw new Error(`binder '${p.name.text}' needs a domain, e.g. (${p.name.text}: int)`);
+        const domain = p.type.getText(sf);
+        if (!isDomain(domain)) {
+            throw new Error(`unknown generation domain '${domain}' — valid domains: ${VALID_DOMAINS}`);
+        }
+        binders.push({ varName: p.name.text, domain });
+    }
+    if (binders.length === 0) {
+        throw new Error(`property needs at least one binder, e.g. (x: int) => ...`);
+    }
+    return binders;
+}
+function parseBody(bodyNode, sf) {
+    const preconditions = [];
+    const exprNodes = [];
+    if (!ts.isBlock(bodyNode)) {
+        exprNodes.push(bodyNode);
+        return { preconditions, body: bodyNode.getText(sf), exprNodes };
+    }
+    let returnExpr;
+    for (const s of bodyNode.statements) {
+        if (ts.isExpressionStatement(s) && isPreCall(s.expression)) {
+            const arg = s.expression.arguments[0];
+            preconditions.push(arg.getText(sf));
+            exprNodes.push(arg);
+            continue;
+        }
+        if (ts.isReturnStatement(s)) {
+            if (returnExpr)
+                throw new Error(`property block body has more than one return`);
+            if (!s.expression)
+                throw new Error(`property block body must return a boolean expression`);
+            returnExpr = s.expression;
+            continue;
+        }
+        throw new Error(`property block body may contain only pre(...) and one return: ${s.getText(sf)}`);
+    }
+    if (!returnExpr)
+        throw new Error(`property block body must return a boolean expression`);
+    exprNodes.push(returnExpr);
+    return { preconditions, body: returnExpr.getText(sf), exprNodes };
+}
+function isPreCall(e) {
+    return ts.isCallExpression(e) && ts.isIdentifier(e.expression) && e.expression.text === "pre" && e.arguments.length === 1;
+}

package/dist/prefix-parser.d.ts

@@ -0,0 +1,7 @@
+import type { Binder } from "./ir.js";
+export interface ParsedPrefix {
+    binders: Binder[];
+    body: string;
+}
+/** prefix ::= FORALL binder-group+   (docs/grammar.ebnf) */
+export declare function parsePrefix(formula: string): ParsedPrefix;