@bytewaveco/pudding 0.0.0-stage → 0.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,24 @@
1
+ import type { Binder, Expr, Scalar } from "./ir.ts";
2
+ export interface Assignments {
3
+ /** True when every possible input is visited. */
4
+ exhaustive: boolean;
5
+ each(visit: (env: Map<string, Scalar>) => boolean | void): void;
6
+ }
7
+ /** Inputs to try: every combination when the space is small enough, otherwise a sample. */
8
+ export declare function assignments(binders: readonly Binder[], pool: Pool, budget: number): Assignments;
9
+ /** Values worth trying for unbounded inputs, beyond the standard ones. */
10
+ export interface Pool {
11
+ strings: string[];
12
+ integers: bigint[];
13
+ }
14
+ /**
15
+ * The constants a law mentions and their neighbours. A condition such as
16
+ * `n === 424242n` is only ever true at a value no generic sample contains.
17
+ */
18
+ export declare function valuePool(expressions: readonly Expr[]): Pool;
19
+ export declare function findInput(binders: readonly Binder[], condition: Expr): {
20
+ found: Map<string, Scalar> | undefined;
21
+ exhaustive: boolean;
22
+ };
23
+ export declare function showInputs(binders: readonly Binder[], env: Map<string, Scalar>): Record<string, string>;
24
+ export declare function showValue(e: Expr, env: Map<string, Scalar>, num?: boolean): string;
package/dist/search.js ADDED
@@ -0,0 +1,137 @@
1
+ // Choosing inputs to try: for counterexamples, for witnesses that a condition
2
+ // can hold, and for executing laws against the real code. Nothing here ever
3
+ // accepts a law; it only explains verdicts and looks for disagreement.
4
+ import * as ir from "./ir.js";
5
+ const SEARCH_BUDGET = 60_000;
6
+ function generator(seed) {
7
+ return () => {
8
+ seed = (seed + 0x6d2b79f5) | 0;
9
+ let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
10
+ t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
11
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
12
+ };
13
+ }
14
+ const INTEGERS = [0n, 1n, -1n, 2n, -2n, 3n, -3n, 5n, 7n, 10n, -10n, 99n, 100n, -100n, 101n, 2n ** 31n, -(2n ** 31n), 2n ** 53n + 1n];
15
+ function randomInteger(random) {
16
+ const kind = random();
17
+ if (kind < 0.5)
18
+ return BigInt(Math.floor(random() * 41) - 20);
19
+ if (kind < 0.85)
20
+ return BigInt(Math.floor(random() * 2_000_001) - 1_000_000);
21
+ return BigInt(Math.floor((random() - 0.5) * 2 ** 53)) * BigInt(Math.floor(random() * 2 ** 20) + 1);
22
+ }
23
+ /** Inputs to try: every combination when the space is small enough, otherwise a sample. */
24
+ export function assignments(binders, pool, budget) {
25
+ const strings = pool.strings;
26
+ const integers = (b) => {
27
+ const [low, high] = b.range ?? [undefined, undefined];
28
+ const edges = low === undefined ? [] : [low, low + 1n, high - 1n, high, (low + high) / 2n];
29
+ return [...new Set([...INTEGERS, ...pool.integers, ...edges].filter(value => low === undefined || (value >= low && value <= high)))];
30
+ };
31
+ const pools = binders.map(b => b.domain ?? (b.ty === "int" ? integers(b) : b.ty === "bool" ? [true, false] : strings));
32
+ const total = pools.reduce((n, pool) => n * pool.length, 1);
33
+ const finite = binders.every(b => b.domain);
34
+ const grid = total <= budget;
35
+ return {
36
+ exhaustive: finite && grid,
37
+ each(visit) {
38
+ const env = new Map();
39
+ if (grid) {
40
+ const index = pools.map(() => 0);
41
+ for (let n = 0; n < total; n++) {
42
+ binders.forEach((b, i) => env.set(b.name, pools[i][index[i]]));
43
+ if (visit(env))
44
+ return;
45
+ for (let i = pools.length - 1; i >= 0 && ++index[i] === pools[i].length; i--)
46
+ index[i] = 0;
47
+ }
48
+ }
49
+ if (finite && grid)
50
+ return;
51
+ const random = generator(0x9e3779b9);
52
+ const draws = Math.min(budget, 5_000);
53
+ for (let n = 0; n < draws; n++) {
54
+ binders.forEach((b, i) => {
55
+ const pool = pools[i];
56
+ const fromPool = b.domain || b.ty !== "int" || random() < 0.2;
57
+ const drawn = fromPool ? pool[Math.floor(random() * pool.length)] : randomInteger(random);
58
+ // A value outside an input's bounds is not an input at all.
59
+ const inside = !b.range || typeof drawn !== "bigint" || (drawn >= b.range[0] && drawn <= b.range[1]);
60
+ env.set(b.name, inside ? drawn : pool[Math.floor(random() * pool.length)]);
61
+ });
62
+ if (visit(env))
63
+ return;
64
+ }
65
+ },
66
+ };
67
+ }
68
+ /**
69
+ * The constants a law mentions and their neighbours. A condition such as
70
+ * `n === 424242n` is only ever true at a value no generic sample contains.
71
+ */
72
+ export function valuePool(expressions) {
73
+ const literals = new Set();
74
+ for (const e of expressions)
75
+ ir.integerLiterals(e, literals);
76
+ const integers = [...literals].slice(0, 64).flatMap(value => [value, value - 1n, value + 1n]);
77
+ return { strings: stringPool(expressions), integers };
78
+ }
79
+ /** Strings worth trying for an unbounded string input: the literals in play and their pieces. */
80
+ function stringPool(expressions) {
81
+ const literals = new Set();
82
+ for (const e of expressions)
83
+ ir.stringLiterals(e, literals);
84
+ const pool = new Set(["", "a", "b", ...literals]);
85
+ for (const literal of literals) {
86
+ for (const token of literal.split(/[^\p{L}\p{N}]+/u))
87
+ pool.add(token);
88
+ const chars = [...literal];
89
+ for (let n = 1; n < chars.length && n <= 12; n++) {
90
+ pool.add(chars.slice(0, n).join(""));
91
+ pool.add(chars.slice(-n).join(""));
92
+ }
93
+ }
94
+ return [...pool].slice(0, 96);
95
+ }
96
+ function truthy(e, env) {
97
+ try {
98
+ return ir.evaluate(e, env) === true;
99
+ }
100
+ catch (error) {
101
+ if (error instanceof ir.EvaluationError)
102
+ return false;
103
+ throw error;
104
+ }
105
+ }
106
+ export function findInput(binders, condition) {
107
+ if (condition === ir.TRUE)
108
+ return { found: new Map(), exhaustive: true };
109
+ const free = ir.freeVariables(condition);
110
+ const used = binders.filter(b => free.has(b.name));
111
+ const space = assignments(used, valuePool([condition]), SEARCH_BUDGET);
112
+ let found;
113
+ space.each(env => {
114
+ if (!truthy(condition, env))
115
+ return false;
116
+ found = new Map(env);
117
+ return true;
118
+ });
119
+ return { found, exhaustive: space.exhaustive };
120
+ }
121
+ export function showInputs(binders, env) {
122
+ const shown = {};
123
+ for (const binder of binders) {
124
+ const value = env.get(binder.name);
125
+ if (value !== undefined)
126
+ shown[binder.label] = ir.showScalar(value, binder.num);
127
+ }
128
+ return shown;
129
+ }
130
+ export function showValue(e, env, num = false) {
131
+ try {
132
+ return ir.showScalar(ir.evaluate(e, env), num);
133
+ }
134
+ catch {
135
+ return "(throws)";
136
+ }
137
+ }
@@ -0,0 +1,247 @@
1
+ import { type Checker, type Program } from "typescript/unstable/sync";
2
+ import { type Node, type SourceFile } from "typescript/unstable/ast";
3
+ import type { Binder, Expr, Obligation, Scalar } from "./ir.ts";
4
+ export interface Location {
5
+ file: string;
6
+ line: number;
7
+ column: number;
8
+ }
9
+ export declare class Unsupported extends Error {
10
+ readonly node: Node | undefined;
11
+ constructor(message: string, node?: Node);
12
+ }
13
+ /** How to build the runtime argument of a law callback from its inputs. */
14
+ export type ArgShape = {
15
+ k: "binder";
16
+ name: string;
17
+ } | {
18
+ k: "const";
19
+ value: Scalar;
20
+ num?: boolean;
21
+ } | {
22
+ k: "record";
23
+ fields: [string, ArgShape][];
24
+ } | {
25
+ k: "array";
26
+ items: ArgShape[];
27
+ };
28
+ export interface LawInstance {
29
+ /** What is known about the inputs beyond their types, such as the bounds of an integer. */
30
+ assumptions: Expr[];
31
+ /** Inputs this instance fixes to one value, because the translation had to know it. */
32
+ fixed: Map<string, Expr>;
33
+ binders: Binder[];
34
+ arg: ArgShape | undefined;
35
+ obligations: Obligation[];
36
+ }
37
+ export interface Law {
38
+ name: string;
39
+ file: string;
40
+ line: number;
41
+ column: number;
42
+ /** Position among the `law()` calls of the file. */
43
+ index: number;
44
+ /** `skip` and `todo` laws are listed but not checked. */
45
+ mode: "run" | "skip" | "todo";
46
+ /** A Lean tactic script supplied by the author for symbolic obligations. */
47
+ proof: string | undefined;
48
+ /** One instance per alternative of a union-typed input. */
49
+ instances: LawInstance[];
50
+ /** Constants met while translating, so inputs can be aimed at them even when translation stops early. */
51
+ mentioned: Expr[];
52
+ /** Every `expect()` in the law and in the functions it calls, keyed by `file:line:column`. */
53
+ expectSites: Map<string, {
54
+ file: string;
55
+ line: number;
56
+ column: number;
57
+ text: string;
58
+ }>;
59
+ /** Set when the law could not be translated. */
60
+ problem: ({
61
+ kind: "unsupported" | "invalid";
62
+ message: string;
63
+ } & Location) | undefined;
64
+ }
65
+ export declare function locate(node: Node): Location;
66
+ export declare class Translator {
67
+ /** Source files whose code was read while translating. */
68
+ readonly reached: Set<string>;
69
+ private readonly checker;
70
+ private readonly program;
71
+ private readonly moduleName;
72
+ private readonly constants;
73
+ private readonly mutationChecked;
74
+ private stack;
75
+ private pc;
76
+ /** Every reassignable variable that is live, so their values can be saved and merged around branches. */
77
+ private cells;
78
+ /** For each function being evaluated, the names it assigns to anywhere in its body. */
79
+ private assigned;
80
+ private steps;
81
+ /** How many merges of variable state are in progress in the function being evaluated. */
82
+ private merging;
83
+ /** Module constants whose initializers are being evaluated, innermost last. */
84
+ private loading;
85
+ private mentioned;
86
+ private sites;
87
+ private scanned;
88
+ private readonly importing;
89
+ private readonly exportsUsed;
90
+ /** Set when some file of the program replaces part of a built-in, which the models of built-ins cannot see. */
91
+ private tampering;
92
+ private readonly facts;
93
+ private instance;
94
+ constructor(program: Program, checker: Checker, moduleName: string);
95
+ /**
96
+ * Translate every law of a file. `selected` decides by full name which laws
97
+ * to check; the rest are reported as skipped without being read.
98
+ */
99
+ translateFile(file: SourceFile, selected?: (name: string) => boolean): Law[];
100
+ private skip;
101
+ /** The `law` or `describe` call a statement makes, with its `.skip`, `.only` or `.todo` modifier. */
102
+ private testCall;
103
+ /**
104
+ * The export of this library that an identifier refers to, if any. Decided
105
+ * by following the name to its import, because a local declaration can
106
+ * reuse any of these names and the code being read may be in any module.
107
+ */
108
+ private libraryExport;
109
+ /**
110
+ * Walk the statements of a law file or of a `describe` callback. At the top
111
+ * level, declarations are resolved on demand through the checker; inside
112
+ * `describe` they are local, so they are evaluated into `env` as they appear.
113
+ */
114
+ private translateBlock;
115
+ private isCallTo;
116
+ private translateLaw;
117
+ /**
118
+ * Record the expectations a called function contains, so one that is never
119
+ * reached is noticed like one written in the law itself. Only files that
120
+ * import this library can contain any.
121
+ */
122
+ private noteExpectations;
123
+ private collectExpectSites;
124
+ private shapeOf;
125
+ /** Split union alternatives so that each result has one fixed structure. */
126
+ private expand;
127
+ private instantiate;
128
+ private valueOf;
129
+ private relabel;
130
+ /** Whether a call is rooted in `expect(...)`, however the chain after it is written. */
131
+ /**
132
+ * Whether a call is to the `expect` this library exports, and not to
133
+ * something else that happens to have its name. Decided by where the name
134
+ * was imported from, since the code being read may be in any module.
135
+ */
136
+ private isExpect;
137
+ private startsWithExpect;
138
+ private expectStatement;
139
+ /** Whether two values are equal as `toEqual` sees it, or as `toBe` does when `identity` is set. */
140
+ private equal;
141
+ private emit;
142
+ /**
143
+ * The value of an expression where the translation cannot go on without
144
+ * one. Inputs this instance has fixed are filled in; if that is not enough,
145
+ * the caller's refusal is raised in a form that lets the law be split.
146
+ */
147
+ private settle;
148
+ private under;
149
+ private save;
150
+ /** Put variables and bindings back to a saved state, forgetting any declared since. */
151
+ private restore;
152
+ /**
153
+ * Evaluate both sides of a condition and merge their results. Each side
154
+ * starts from the same variable state. The state afterwards is the state
155
+ * before: an expression cannot assign, and a statement branch evaluated
156
+ * this way has already run to the end of its function on both sides.
157
+ */
158
+ private branch;
159
+ /**
160
+ * Run two branches that both continue past the condition, then make every
161
+ * variable hold the value of whichever branch was taken. The code after
162
+ * the condition is then evaluated once, not once per branch.
163
+ */
164
+ private mergeStates;
165
+ private merge;
166
+ /** Apply an operation to a value, distributing over conditional values. */
167
+ private over;
168
+ /** What a function's body does that affects how it is evaluated, computed once per function. */
169
+ private factsOf;
170
+ private declare;
171
+ /**
172
+ * Bind the names of a pattern. A name becomes a reassignable variable only
173
+ * if the enclosing function assigns to it somewhere; everything else stays
174
+ * an immutable binding, which keeps closures over it exact.
175
+ */
176
+ private bind;
177
+ private call;
178
+ /**
179
+ * Evaluate a block in its own scope. Entering a block makes its function
180
+ * declarations callable at once, and puts its `const` and `let` names in
181
+ * scope before they hold a value, exactly as JavaScript does; reading one
182
+ * early is an error there and is refused here.
183
+ */
184
+ private block;
185
+ private enter;
186
+ /**
187
+ * Evaluate statements from index `i`. `flow.next` continues after the list.
188
+ * A branch that can leave early is evaluated together with everything that
189
+ * follows it; a branch that cannot is evaluated alone and its variables are
190
+ * merged, so straight-line code costs one pass.
191
+ */
192
+ private exec;
193
+ /** A statement that is an expression: an assignment, an assertion, or a call made for the assertions inside it. */
194
+ private effect;
195
+ private assignable;
196
+ private scalarOf;
197
+ private bool;
198
+ private wellFormed;
199
+ private evalExpr;
200
+ /** A literal from the source, remembered as a value worth trying as an input. */
201
+ private note;
202
+ /** The value a name stands for: a local binding, or else a module-level declaration. */
203
+ private read;
204
+ /**
205
+ * A value that depends on a condition, reduced by what is already known on
206
+ * this path. After `if (x !== undefined)`, a variable that holds something
207
+ * or undefined depending on that very test holds the something.
208
+ */
209
+ private settled;
210
+ /**
211
+ * `a === b` for two values. Values of different kinds are never equal, and
212
+ * a number is a different kind from a bigint even when both are whole.
213
+ */
214
+ private strictEqual;
215
+ private isPlain;
216
+ private refuseEquality;
217
+ private binary;
218
+ /** `+ - * / %` and the comparisons, on values already evaluated. */
219
+ private arithmetic;
220
+ private elementAccess;
221
+ private callExpression;
222
+ /** The `Math` functions that keep whole numbers whole. */
223
+ /**
224
+ * Refuse to model a built-in if any file of the program writes to one, as
225
+ * in `Math.abs = ...` or a patched prototype: the name would no longer mean
226
+ * what the model assumes. Installed packages are not examined.
227
+ */
228
+ private assertBuiltinsIntact;
229
+ private math;
230
+ /** `String(x)` and `x.toString()` for the scalars whose text Lean and JavaScript agree on. */
231
+ private text;
232
+ /** Whether an identifier refers to a global from TypeScript's own library files. */
233
+ private isBuiltin;
234
+ private arrayMethod;
235
+ private isNamespace;
236
+ /** Resolve a name that is not a local variable to its module-level declaration. */
237
+ private global;
238
+ /**
239
+ * Refuse a module constant whose contents may differ from its initializer
240
+ * by the time a law runs. Only two kinds of code run before then: the
241
+ * module's own loading, and whatever the law calls (which is translated,
242
+ * and refused if it changes anything in place). So the value is stable
243
+ * unless the file changes it by name, hands it to something while loading,
244
+ * or runs its own functions while loading.
245
+ */
246
+ private assertStable;
247
+ }