pabst-checker 0.12.0

package/dist/equations.js

@@ -0,0 +1,256 @@
+import ts from "typescript";
+import { PabstError } from "./errors.js";
+import { lexFormula, scanTokens, sliceText, } from "./formula-lexer.js";
+/**
+ * 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 function desugarEquations(text) {
+    const toks = lexFormula(text);
+    // --- Token-level rules (single tokens are visible at every depth) ---
+    let sawPlainAssign = false;
+    let sawAssignMaterial = false;
+    for (let i = 0; i < toks.length; i++) {
+        const t = toks[i];
+        if (t.text === "≠") {
+            throw new PabstError(`≠ is not pabst syntax: write ≢ for negated identity (in: ${text})`);
+        }
+        if (isGlyph(t)) {
+            const sub = t.text === "≡" ? "==" : "!=";
+            const prev = toks[i - 1];
+            const next = toks[i + 1];
+            const fused = (prev && prev.end === t.start && scansAsOne(prev.text + sub[0])) ||
+                (next && next.start === t.end && !scanSplitsAt(sub, next.text));
+            if (fused) {
+                throw new PabstError(`an equation glyph fused with an adjacent operator (e.g. ≡= scans ` +
+                    `as ===): write the equation as A ≡ B with the glyph standing ` +
+                    `alone (in: ${text})`);
+            }
+        }
+        if (t.text === "=") {
+            sawPlainAssign = true;
+            sawAssignMaterial = true;
+        }
+        else if (ASSIGN_TOKENS.has(t.text)) {
+            sawAssignMaterial = true;
+        }
+    }
+    // --- Locate depth-0 glyphs and classify the atom's shape ---
+    const depth0 = depthZeroIndex(toks);
+    const glyphs = [...depth0.keys()].filter((i) => isGlyph(toks[i]));
+    if (glyphs.length > 0) {
+        // Splitting on the glyph splices each side into Object.is(l, r), so a
+        // depth-0 neighbor binding looser than ≡ would silently regroup.
+        for (const i of depth0.keys()) {
+            const t = toks[i].text;
+            if (t === "?" || t === ":") {
+                throw new PabstError(`an equation cannot sit beside an unparenthesized ternary: write ` +
+                    `a ≡ (b ? c : d), or call Object.is in the ternary's branches ` +
+                    `(in: ${text})`);
+            }
+            if (t === ",") {
+                throw new PabstError(`an equation cannot sit beside a depth-0 comma: parenthesize ` +
+                    `the comma expression, e.g. (a, b) ≡ x (in: ${text})`);
+            }
+            if (t === "=>") {
+                throw new PabstError(`an equation cannot sit beside an unparenthesized arrow ` +
+                    `function: parenthesize it, e.g. f ≡ (x => x) (in: ${text})`);
+            }
+            if (t === "&&") {
+                throw new PabstError(`use ∧ for conjunction at the property's top level, not JS && ` +
+                    `(note: ≡ binds tighter than &&) (in: ${text})`);
+            }
+            if (t === "||") {
+                throw new PabstError(`use ∨ for disjunction at the property's top level, not JS || ` +
+                    `(note: ≡ binds tighter than ||) (in: ${text})`);
+            }
+        }
+    }
+    if (glyphs.length > 1) {
+        throw new PabstError(`chained equations are not supported: split into conjuncts, ` +
+            `e.g. a ≡ b ∧ b ≡ c, or parenthesize (in: ${text})`);
+    }
+    // --- Loose equality (any depth) ---
+    for (const t of toks) {
+        if (t.text === "==") {
+            throw new PabstError(`loose equality (==) is not allowed: use ≡ for identity ` +
+                `(Object.is) or === for JS strict equality (in: ${text})`);
+        }
+        if (t.text === "!=") {
+            throw new PabstError(`loose inequality (!=) is not allowed: use ≢ for negated ` +
+                `identity or !== for JS strict inequality (in: ${text})`);
+        }
+    }
+    // --- Split the equation and guard its sides ---
+    let js = text;
+    if (glyphs.length === 1) {
+        const g = glyphs[0];
+        const left = toks.slice(0, g);
+        const right = toks.slice(g + 1);
+        if (left.length === 0 || right.length === 0) {
+            throw new PabstError(`cannot parse atom: ${text}`);
+        }
+        guardSide(left, "left", text);
+        guardSide(right, "right", text);
+        const l = sliceText(text, left).trim();
+        const r = sliceText(text, right).trim();
+        const call = `Object.is(${l}, ${r})`;
+        js = toks[g].text === "≡" ? call : `!${call}`;
+    }
+    // --- TS-AST validation ---
+    const sf = ts.createSourceFile("__atom.ts", `(${js});`, ts.ScriptTarget.Latest, true);
+    const stmt = sf.statements[0];
+    const diags = sf
+        .parseDiagnostics;
+    const root = stmt &&
+        ts.isExpressionStatement(stmt) &&
+        ts.isParenthesizedExpression(stmt.expression)
+        ? stmt.expression.expression
+        : null;
+    if (!root || diags.length > 0) {
+        if (sawPlainAssign)
+            throw new PabstError(assignmentMessage(text));
+        const nested = nestedGlyph(toks, depth0);
+        if (nested) {
+            throw new PabstError(`${nested.text} is only available at an atom's top level — in a ` +
+                `nested position, call Object.is(A, B) (or !Object.is(A, B)) ` +
+                `directly (in: ${text})`);
+        }
+        if (glyphs.length > 0 || sawAssignMaterial) {
+            throw new PabstError(`cannot parse atom: ${text}`);
+        }
+        // Not TS-parseable and no formula material: leave the atom for the
+        // generated test code to diagnose.
+        return js;
+    }
+    banAssignments(root, text);
+    // A desugared ≢ is our own `!Object.is(…)` — the leaf rule judges only
+    // atoms the user wrote, so it applies when no equation was split.
+    if (glyphs.length === 0)
+        enforceLeafRule(root, text);
+    return js;
+}
+function assignmentMessage(original) {
+    return (`= is JS assignment, and assignments are not allowed in a formula atom: ` +
+        `if you meant equality, write A ≡ B for identity (Object.is), or call ` +
+        `Object.is(A, B) directly (in: ${original})`);
+}
+const ASSIGN_TOKENS = new Set([
+    "=",
+    "+=",
+    "-=",
+    "*=",
+    "/=",
+    "%=",
+    "**=",
+    "<<=",
+    ">>=",
+    ">>>=",
+    "&=",
+    "|=",
+    "^=",
+    "&&=",
+    "||=",
+    "??=",
+]);
+function isGlyph(t) {
+    return t.text === "≡" || t.text === "≢";
+}
+/** True when `s` scans as a single token — a glyph neighbor with this
+ * property merges with the substituted ==/!= (e.g. ! + == scans as !==). */
+function scansAsOne(s) {
+    let count = 0;
+    let end = 0;
+    for (const t of scanTokens(s)) {
+        count++;
+        end = t.end;
+    }
+    return count === 1 && end === s.length;
+}
+/** True when `left + right` scans with a token boundary after `left`. */
+function scanSplitsAt(left, right) {
+    const first = scanTokens(left + right).next().value;
+    return first !== undefined && first.end === left.length;
+}
+/** The set of token indices at depth 0 (template substitutions nest). */
+function depthZeroIndex(toks) {
+    const at = new Set();
+    let depth = 0;
+    for (let i = 0; i < toks.length; i++) {
+        const t = toks[i];
+        if (t.kind === "open")
+            depth++;
+        else if (t.kind === "close")
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0)
+            at.add(i);
+    }
+    return at;
+}
+/** The first equation glyph NOT at depth 0, if any. */
+function nestedGlyph(toks, depth0) {
+    for (let i = 0; i < toks.length; i++) {
+        if (isGlyph(toks[i]) && !depth0.has(i))
+            return toks[i];
+    }
+    return undefined;
+}
+/** An equation side may not carry a depth-0 ===/!== (ambiguous chain) or
+ * ?? (parenthesize the intended grouping). */
+function guardSide(side, which, text) {
+    for (const i of depthZeroIndex(side)) {
+        const t = side[i];
+        if (t.text === "===" || t.text === "!==") {
+            throw new PabstError(`chained equations are not supported: split into conjuncts, ` +
+                `e.g. a ≡ b ∧ b ≡ c, or parenthesize (in: ${text})`);
+        }
+        if (t.text === "??") {
+            throw which === "right"
+                ? new PabstError(`parenthesize the ?? expression: ≡ binds tighter than ?? , so ` +
+                    `a ≡ b ?? c means (a ≡ b) ?? c (in: ${text})`)
+                : new PabstError(`?? at an atom's top level over an equation is dead code — ` +
+                    `Object.is results are never nullish: parenthesize the ` +
+                    `intended grouping (in: ${text})`);
+        }
+    }
+}
+/** Assignments cannot appear in an atom at any depth. A parameter default
+ * ((x = 1) => …) is an initializer, not a BinaryExpression, so it passes. */
+function banAssignments(root, text) {
+    const visit = (node) => {
+        if (ts.isBinaryExpression(node)) {
+            const op = node.operatorToken.kind;
+            if (op >= ts.SyntaxKind.FirstAssignment &&
+                op <= ts.SyntaxKind.LastAssignment) {
+                throw new PabstError(op === ts.SyntaxKind.EqualsToken
+                    ? assignmentMessage(text)
+                    : `${ts.tokenToString(op)} is JS assignment: assignments are ` +
+                        `not allowed in a formula atom (in: ${text})`);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(root);
+}
+/** Formula connectives may not surface at the atom's root (the leaf rule):
+ * use ∧ ∨ ¬, not JS && || !. Deeper occurrences are ordinary JS. */
+function enforceLeafRule(root, text) {
+    let expr = root;
+    while (ts.isParenthesizedExpression(expr))
+        expr = expr.expression;
+    if (ts.isBinaryExpression(expr)) {
+        if (expr.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+            throw new PabstError(`use ∧ for conjunction at the property's top level, not JS && (in: ${text})`);
+        }
+        if (expr.operatorToken.kind === ts.SyntaxKind.BarBarToken) {
+            throw new PabstError(`use ∨ for disjunction at the property's top level, not JS || (in: ${text})`);
+        }
+    }
+    if (ts.isPrefixUnaryExpression(expr) &&
+        expr.operator === ts.SyntaxKind.ExclamationToken) {
+        throw new PabstError(`use ¬ for negation at the property's top level, not JS ! (in: ${text})`);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A user-facing error: the input (an annotation, formula, or reference) is at
+ * fault, not pabst. The CLI catches these and reports them as exit 2 with a
+ * one-line diagnostic. Anything else escaping the compile front-end is an
+ * internal bug and crashes loudly.
+ */
+export declare class PabstError extends Error {
+    name: string;
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+/**
+ * A user-facing error: the input (an annotation, formula, or reference) is at
+ * fault, not pabst. The CLI catches these and reports them as exit 2 with a
+ * one-line diagnostic. Anything else escaping the compile front-end is an
+ * internal bug and crashes loudly.
+ */
+export class PabstError extends Error {
+    name = "PabstError";
+}

package/dist/extract.d.ts

@@ -0,0 +1,21 @@
+export interface RawAnnotation {
+    propertyName: string;
+    functionName: string;
+    className?: string;
+    isStatic?: boolean;
+    formula: string;
+    line: number;
+}
+export interface ExtractResult {
+    file: string;
+    exports: Set<string>;
+    annotations: RawAnnotation[];
+}
+/** Read a source file from disk and extract its annotations. */
+export declare function extract(file: string): ExtractResult;
+/**
+ * Extract `@ensures` annotations and exported names from already-loaded source
+ * text. `file` is only a label — for diagnostics and the returned `file` field —
+ * so this is pure and testable without touching disk.
+ */
+export declare function extractFromSource(text: string, file: string): ExtractResult;

package/dist/extract.js

@@ -0,0 +1,177 @@
+import ts from "typescript";
+import * as fs from "node:fs";
+import { qualifiedName } from "./qualified-name.js";
+import { PabstError } from "./errors.js";
+// The `@ensures` tag name is matched via the JSDoc AST; this only peels the
+// `{name}` prefix off the tag's comment text, leaving the formula as the rest.
+const ENSURES_NAME = /^\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}([\s\S]*)$/;
+/** Read a source file from disk and extract its annotations. */
+export function extract(file) {
+    return extractFromSource(fs.readFileSync(file, "utf8"), file);
+}
+/**
+ * Extract `@ensures` annotations and exported names from already-loaded source
+ * text. `file` is only a label — for diagnostics and the returned `file` field —
+ * so this is pure and testable without touching disk.
+ */
+export function extractFromSource(text, file) {
+    const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+    const exportsSet = collectExports(sf);
+    const annotations = [];
+    const seen = new Map();
+    const record = (a, key, subject) => {
+        const set = seen.get(key) ?? new Set();
+        if (set.has(a.propertyName)) {
+            throw new PabstError(`duplicate property name '${a.propertyName}' on ${subject} in ${file}`);
+        }
+        set.add(a.propertyName);
+        seen.set(key, set);
+        annotations.push(a);
+    };
+    for (const stmt of sf.statements) {
+        if (ts.isClassDeclaration(stmt)) {
+            collectClassAnnotations(stmt, sf, exportsSet, file, record);
+            continue;
+        }
+        const fnName = functionNameOf(stmt);
+        if (!fnName)
+            continue;
+        for (const m of ensuresComments(stmt, sf)) {
+            record({
+                propertyName: m.propertyName,
+                functionName: fnName,
+                formula: m.formula,
+                line: m.line,
+            }, fnName, `function '${fnName}'`);
+        }
+    }
+    return { file, exports: exportsSet, annotations };
+}
+function ensuresComments(node, sf) {
+    const out = [];
+    for (const tag of ts.getJSDocTags(node)) {
+        if (tag.tagName.escapedText !== "ensures")
+            continue;
+        const comment = ts.getTextOfJSDocComment(tag.comment)?.trim() ?? "";
+        const m = ENSURES_NAME.exec(comment);
+        if (!m)
+            continue;
+        out.push({
+            propertyName: m[1],
+            formula: m[2].trim(),
+            line: sf.getLineAndCharacterOfPosition(tag.pos).line + 1,
+        });
+    }
+    return out;
+}
+function collectClassAnnotations(cls, sf, exportsSet, file, record) {
+    const className = cls.name?.text;
+    for (const member of cls.members) {
+        const matches = ensuresComments(member, sf);
+        if (matches.length === 0)
+            continue;
+        const label = memberLabel(member);
+        if (!className) {
+            throw new PabstError(`@ensures on method '${label}' of an anonymous class in ${file}`);
+        }
+        if (!isEligibleMethod(member)) {
+            throw new PabstError(ineligibleMessage(member, label, className, file));
+        }
+        if (!exportsSet.has(className)) {
+            throw new PabstError(`@ensures on method '${label}' of class '${className}', which is not exported from ${file}`);
+        }
+        const isStatic = hasModifier(member, ts.SyntaxKind.StaticKeyword);
+        const key = qualifiedName(label, className, isStatic);
+        for (const m of matches) {
+            record({
+                propertyName: m.propertyName,
+                functionName: label,
+                className,
+                isStatic,
+                formula: m.formula,
+                line: m.line,
+            }, key, `method '${key}'`);
+        }
+    }
+}
+function isEligibleMethod(member) {
+    if (!ts.isMethodDeclaration(member))
+        return false;
+    if (!ts.isIdentifier(member.name))
+        return false; // computed name or #private
+    if (hasModifier(member, ts.SyntaxKind.PrivateKeyword))
+        return false;
+    if (hasModifier(member, ts.SyntaxKind.ProtectedKeyword))
+        return false;
+    if (hasModifier(member, ts.SyntaxKind.AbstractKeyword))
+        return false;
+    return true;
+}
+function ineligibleMessage(member, label, className, file) {
+    const nonPublic = ts.isMethodDeclaration(member) &&
+        (hasModifier(member, ts.SyntaxKind.PrivateKeyword) ||
+            hasModifier(member, ts.SyntaxKind.ProtectedKeyword) ||
+            ts.isPrivateIdentifier(member.name));
+    if (nonPublic) {
+        return `@ensures on non-public method '${label}' of class '${className}' in ${file}`;
+    }
+    return (`@ensures on unsupported member '${label}' of class '${className}' in ${file} ` +
+        `(accessors, constructors, abstract, and computed-name members are not supported)`);
+}
+function memberLabel(member) {
+    const name = member.name;
+    if (name &&
+        (ts.isIdentifier(name) ||
+            ts.isPrivateIdentifier(name) ||
+            ts.isStringLiteral(name))) {
+        return name.text;
+    }
+    if (ts.isConstructorDeclaration(member))
+        return "constructor";
+    return "<computed>";
+}
+function hasModifier(node, kind) {
+    const mods = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    return mods?.some((m) => m.kind === kind) ?? false;
+}
+function functionNameOf(stmt) {
+    if (ts.isFunctionDeclaration(stmt) && stmt.name)
+        return stmt.name.text;
+    if (ts.isVariableStatement(stmt)) {
+        const decl = stmt.declarationList.declarations[0];
+        if (decl &&
+            ts.isIdentifier(decl.name) &&
+            decl.initializer &&
+            (ts.isArrowFunction(decl.initializer) ||
+                ts.isFunctionExpression(decl.initializer))) {
+            return decl.name.text;
+        }
+    }
+    return undefined;
+}
+function collectExports(sf) {
+    const out = new Set();
+    for (const stmt of sf.statements) {
+        const mods = ts.canHaveModifiers(stmt) ? ts.getModifiers(stmt) : undefined;
+        const isExported = mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+        if (isExported) {
+            if (ts.isFunctionDeclaration(stmt) && stmt.name)
+                out.add(stmt.name.text);
+            else if (ts.isClassDeclaration(stmt) && stmt.name)
+                out.add(stmt.name.text);
+            else if (ts.isVariableStatement(stmt)) {
+                for (const d of stmt.declarationList.declarations) {
+                    if (ts.isIdentifier(d.name))
+                        out.add(d.name.text);
+                }
+            }
+        }
+        if (ts.isExportDeclaration(stmt) &&
+            stmt.exportClause &&
+            ts.isNamedExports(stmt.exportClause)) {
+            for (const e of stmt.exportClause.elements)
+                out.add(e.name.text);
+        }
+    }
+    return out;
+}

package/dist/formula-ast.d.ts

@@ -0,0 +1,26 @@
+export type Formula = {
+    kind: "atom";
+    text: string;
+    js: string;
+} | {
+    kind: "not";
+    arg: Formula;
+} | {
+    kind: "and";
+    left: Formula;
+    right: Formula;
+} | {
+    kind: "or";
+    left: Formula;
+    right: Formula;
+} | {
+    kind: "iff";
+    left: Formula;
+    right: Formula;
+} | {
+    kind: "implication";
+    antecedents: Formula[];
+    consequent: Formula;
+};
+/** All atom executable JS expressions (equation-desugared), left-to-right. */
+export declare function collectAtoms(f: Formula): string[];

package/dist/formula-ast.js

@@ -0,0 +1,18 @@
+/** All atom executable JS expressions (equation-desugared), left-to-right. */
+export function collectAtoms(f) {
+    switch (f.kind) {
+        case "atom":
+            return [f.js];
+        case "not":
+            return collectAtoms(f.arg);
+        case "and":
+        case "or":
+        case "iff":
+            return [...collectAtoms(f.left), ...collectAtoms(f.right)];
+        case "implication":
+            return [
+                ...f.antecedents.flatMap(collectAtoms),
+                ...collectAtoms(f.consequent),
+            ];
+    }
+}

package/dist/formula-lexer.d.ts

@@ -0,0 +1,31 @@
+import ts from "typescript";
+export type FTokenKind = "not" | "and" | "or" | "implies" | "iff" | "open" | "close" | "js";
+export interface FToken {
+    kind: FTokenKind;
+    text: string;
+    start: number;
+    end: number;
+}
+export interface ScannedToken {
+    kind: ts.SyntaxKind;
+    text: string;
+    start: number;
+    end: number;
+}
+/**
+ * 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 declare function scanTokens(text: string, start?: number): Generator<ScannedToken>;
+/** Tokenize a formula body. Glyphs/fallbacks become connective tokens; the rest is js. */
+export declare function lexFormula(body: string): FToken[];
+/** The source text spanned by toks (empty when toks is empty). */
+export declare function sliceText(source: string, toks: readonly {
+    start: number;
+    end: number;
+}[]): string;
+/** A `/` can begin a regex unless the previous token ends a value (then it's division). */
+export declare function regexCanFollow(prev: ts.SyntaxKind | null): boolean;