tla-ts 0.0.10-dev.28c823e4b → 0.0.10-dev.b4a856304

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.
Files changed (68) hide show
  1. package/dist/index.cjs +1 -1
  2. package/dist/index.d.cts +0 -34
  3. package/dist/index.d.ts +0 -34
  4. package/dist/index.js +1 -1
  5. package/dist/parallel-worker.cjs +1 -1
  6. package/dist/parallel-worker.js +1 -1
  7. package/dist/prove.cjs +43 -43
  8. package/dist/prove.js +47 -47
  9. package/dist/run.cjs +30 -30
  10. package/dist/run.js +33 -33
  11. package/dist/transfer.cjs +38 -38
  12. package/dist/transfer.js +39 -39
  13. package/package.json +1 -1
  14. package/src/ast.ts +5 -0
  15. package/src/bags.ts +5 -2
  16. package/src/builtins.ts +8 -1
  17. package/src/check.ts +193 -128
  18. package/src/cli/run.ts +2 -0
  19. package/src/cli/runtime-invariants.ts +7 -8
  20. package/src/cli/shared.ts +4 -0
  21. package/src/cli/tlc-arguments.ts +30 -24
  22. package/src/cli/tlc-usage.ts +3 -2
  23. package/src/evaluate.ts +102 -26
  24. package/src/java-overrides.ts +9 -4
  25. package/src/json-reader.ts +2 -1
  26. package/src/json.ts +11 -4
  27. package/src/levels.ts +15 -7
  28. package/src/lexer.ts +83 -72
  29. package/src/liveness-checker.ts +106 -77
  30. package/src/liveness.ts +34 -10
  31. package/src/parallel.ts +33 -26
  32. package/src/parser.ts +226 -163
  33. package/src/pcal/ast.ts +65 -53
  34. package/src/pcal/parse.ts +191 -144
  35. package/src/pcal/tokenize.ts +115 -91
  36. package/src/pcal/translate.ts +98 -83
  37. package/src/pcal/validate.ts +50 -48
  38. package/src/pretty-print.ts +6 -6
  39. package/src/randomization.ts +4 -1
  40. package/src/resolve.ts +70 -12
  41. package/src/runtime.ts +18 -11
  42. package/src/sany/builtins.ts +3 -1
  43. package/src/sany/generator.ts +127 -74
  44. package/src/sany/levels.ts +9 -5
  45. package/src/sany/lexer.ts +44 -40
  46. package/src/sany/linter.ts +1 -0
  47. package/src/search.ts +1 -1
  48. package/src/simulate.ts +59 -50
  49. package/src/spec-description.ts +34 -23
  50. package/src/standard-definitions.ts +3 -0
  51. package/src/standard-modules.ts +12 -1
  52. package/src/state-graph.ts +8 -1
  53. package/src/subexpressions.ts +47 -38
  54. package/src/successors.ts +35 -14
  55. package/src/symmetry.ts +19 -4
  56. package/src/tlc/fingerprint.ts +21 -15
  57. package/src/tlc/jar-data.ts +1 -0
  58. package/src/tlc/messages.ts +21 -2
  59. package/src/tlc/order.ts +38 -20
  60. package/src/tlc/random.ts +30 -18
  61. package/src/tlc/replay.ts +33 -13
  62. package/src/tlc/summary.ts +45 -36
  63. package/src/tlc/tlc-operators.ts +14 -4
  64. package/src/tlc/tlcext-operators.ts +15 -11
  65. package/src/tlc/trace-spec.ts +4 -0
  66. package/src/tlc/value-stream.ts +13 -9
  67. package/src/tlc/version.ts +1 -0
  68. package/src/values.ts +181 -74
package/src/successors.ts CHANGED
@@ -114,11 +114,13 @@ const assign = (partial: State, index: number, value: Value) => {
114
114
  const getComputation = (run: Run) =>
115
115
  run.isInit ? "initial states" : run.isEnabled ? "ENABLED" : "next states";
116
116
 
117
+ // TLC fails with an unexpected exception when it fails to compute the next states or ENABLED.
117
118
  const createRunError = (run: Run, message: string) => {
118
119
  const error = new TlaEvaluationError(message);
119
120
  return run.isInit ? error : setExitCode(error, EXIT_STATUS.error);
120
121
  };
121
122
 
123
+ // TLC words this differently for a literal it walks to rather than evaluates.
122
124
  const getNonBooleanMessage = (
123
125
  run: Run,
124
126
  value: Value,
@@ -134,6 +136,7 @@ const getNonBooleanMessage = (
134
136
  return `In computing ${getComputation(run)}, TLC expected a boolean expression,\nbut instead found ${formatValue(value)}.\n${node}`;
135
137
  };
136
138
 
139
+ // TLC words an IF whose condition isn't a boolean differently for each computation.
137
140
  const getIfConditionMessage = (run: Run, value: Value, expression: Expression) => {
138
141
  const kind = getKindString(value);
139
142
  const range = describeRange(expression);
@@ -148,6 +151,7 @@ const holds = (run: Run, expression: Expression, context: Context) =>
148
151
 
149
152
  const CORE_OPERATOR_NAMES = new Set(CORE_OPERATORS.map((operator) => operator.name));
150
153
 
154
+ // TLC's initial states evaluate a built-in operator for its value, and report it in a plain message.
151
155
  const isBuiltInOperation = (expression: Expression) =>
152
156
  expression.kind === "Apply"
153
157
  ? CORE_OPERATOR_NAMES.has(expression.operator)
@@ -309,7 +313,8 @@ const isGuard = (expression: Expression, environment: Environment, isInit: boole
309
313
 
310
314
  const NO_NAMES: ReadonlySet<string> = new Set();
311
315
 
312
- const getReadLocals = (
316
+ // Undefined when the expression applies a local operator, whose body may assign variables.
317
+ export const getReadLocals = (
313
318
  expression: Expression,
314
319
  bound: ReadonlySet<string>,
315
320
  ): string[] | undefined => {
@@ -318,18 +323,19 @@ const getReadLocals = (
318
323
  return bound.has(expression.name) ? [] : [expression.name];
319
324
  }
320
325
  const names: string[] = [];
321
- let isReadOnly = true;
326
+ const result = { isReadOnly: true };
322
327
  mapChildren(expression, (child, childNames) => {
323
- const childLocals = isReadOnly
328
+ const childLocals = result.isReadOnly
324
329
  ? getReadLocals(child, childNames.length === 0 ? bound : new Set([...bound, ...childNames]))
325
330
  : [];
326
331
  if (childLocals) names.push(...childLocals);
327
- else isReadOnly = false;
332
+ else result.isReadOnly = false;
328
333
  return child;
329
334
  });
330
- return isReadOnly ? names : undefined;
335
+ return result.isReadOnly ? names : undefined;
331
336
  };
332
337
 
338
+ // TLC generates a successor per disjunct and witness, so only an expression without any is a guard.
333
339
  const hasBranches = (
334
340
  expression: Expression,
335
341
  environment: Environment,
@@ -372,6 +378,7 @@ const toConjunct = (
372
378
  return { kind: "Branch", expression, runner: getRunner(expression, environment, isInit) };
373
379
  };
374
380
 
381
+ // Leading guards that read no inner bound hold for every inner binding, so they run once.
375
382
  const getHoistedGuards = (expression: QuantifierExpression, environment: Environment) => {
376
383
  if (expression.bounds.length < 2 || expression.body.kind !== "And") return undefined;
377
384
  const names = expression.bounds.flatMap((bound) =>
@@ -415,6 +422,8 @@ const compileConjunction = (
415
422
  context ??= getContext(run, scope, current);
416
423
  for (let rest = index; rest < conjuncts.length; rest++) {
417
424
  const conjunct = conjuncts[rest];
425
+ // Tool#getNextStates0 takes this shortcut with warnings on, though its comment says the
426
+ // shortcut skips the warning for a changed UNCHANGED variable. tla-ts still warns.
418
427
  const state = run.current;
419
428
  const changed =
420
429
  state && conjunct.kind === "Unchanged"
@@ -576,6 +585,8 @@ const compileDynamicAssignment = (
576
585
  };
577
586
  };
578
587
 
588
+ // TLC walks the body of an applied function that is still lazy, which it evaluates as it
589
+ // computes the initial states eagerly, and otherwise applies it.
579
590
  const compileFunctionAction = (
580
591
  expression: Expression & { kind: "FunctionApplication" },
581
592
  environment: Environment,
@@ -635,6 +646,7 @@ const compileUnchanged = (expression: Expression, environment: Environment): Run
635
646
  return;
636
647
  }
637
648
  const context = getContext(run, scope, partial);
649
+ // Tool#enabledUnchanged fails on an operator application, as its comment says.
638
650
  if (run.isEnabled && expression.kind === "Apply") {
639
651
  const operator = resolveApplyOperator(expression, context);
640
652
  if (operator?.kind === "Closure" && operator.params.length === expression.args.length) {
@@ -666,10 +678,10 @@ const compileCall = (
666
678
  if (global?.kind === "Builtin") return guard;
667
679
  if (global?.kind === "Closure") {
668
680
  const bindArguments = compileArgumentScope(global, expression.args, environment);
669
- let bodyRunner: Runner | undefined;
681
+ const compiled = { body: undefined as Runner | undefined };
670
682
  return (run, scope, partial, action, isFixed, onComplete) => {
671
- bodyRunner ??= getRunner(global.body, environment, isInit);
672
- bodyRunner(
683
+ compiled.body ??= getRunner(global.body, environment, isInit);
684
+ compiled.body(
673
685
  run,
674
686
  bindArguments(getContext(run, scope, partial)),
675
687
  partial,
@@ -706,7 +718,7 @@ const compileIdentifier = (
706
718
  const definition = isLocallyResolved(expression)
707
719
  ? undefined
708
720
  : getZeroArityBody(expression.name, environment);
709
- let bodyRunner: Runner | undefined;
721
+ const compiled = { body: undefined as Runner | undefined };
710
722
  return (run, scope, partial, action, isFixed, onComplete) => {
711
723
  const binding = lookupScope(scope, expression.name);
712
724
  if (binding?.kind === "Thunk" && !binding.isReleased) {
@@ -720,6 +732,8 @@ const compileIdentifier = (
720
732
  );
721
733
  return;
722
734
  }
735
+ // TLC computed a constant definition at startup, so it looks up its value. It walks the body
736
+ // of the configured INIT or NEXT, which isn't a reference in the source and has no range.
723
737
  if (
724
738
  binding ||
725
739
  !definition ||
@@ -728,11 +742,14 @@ const compileIdentifier = (
728
742
  guard(run, scope, partial, action, isFixed, onComplete);
729
743
  return;
730
744
  }
731
- bodyRunner ??= getRunner(definition.body, environment, isInit);
732
- bodyRunner(run, undefined, partial, isFixed ? action : definition.name, isFixed, onComplete);
745
+ compiled.body ??= getRunner(definition.body, environment, isInit);
746
+ compiled.body(run, undefined, partial, isFixed ? action : definition.name, isFixed, onComplete);
733
747
  };
734
748
  };
735
749
 
750
+ // A disjunction of PlusCal actions skips the operands whose label guard, such as
751
+ // pc[self] = "L1", is false. TLC evaluates guards before the label's guard, so a skipped
752
+ // operand still runs them, for their errors.
736
753
  interface LabelGuard {
737
754
  variable: number;
738
755
  argument: string;
@@ -757,6 +774,7 @@ const toLabelGuard = (expression: Expression, environment: Environment) => {
757
774
  const getConjuncts = (expression: Expression): Expression[] =>
758
775
  expression.kind === "And" ? expression.operands.flatMap(getConjuncts) : [expression];
759
776
 
777
+ // An operand with another conjunct first, such as an assignment, runs in full.
760
778
  const isLeadingGuard = (expression: Expression, environment: Environment) =>
761
779
  (expression.kind === "Identifier" ||
762
780
  (expression.kind === "Apply" &&
@@ -1075,6 +1093,7 @@ const compileAction = (
1075
1093
  const arm = arms.find((candidate) => {
1076
1094
  const value = evaluate(candidate.condition, context);
1077
1095
  if (typeof value === "boolean") return value;
1096
+ // TLC leaves out the space before the kind under ENABLED.
1078
1097
  throw createRunError(
1079
1098
  run,
1080
1099
  `In computing ${getComputation(run)}, a non-boolean expression${run.isEnabled ? "" : " "}(${getKindString(value)}) was used as a guard condition of a CASE.\n${describeNode(candidate.source)}`,
@@ -1114,6 +1133,7 @@ const compileAction = (
1114
1133
  return compileUnchanged(expression.expression, environment);
1115
1134
  case "AngleAction": {
1116
1135
  const body = getChildRunner(expression.action);
1136
+ // TLC compares the whole subscript of <<A>>_v, unlike UNCHANGED's, which it splits.
1117
1137
  const unchanged: Expression = {
1118
1138
  kind: "Unchanged",
1119
1139
  expression: expression.subscript,
@@ -1205,6 +1225,7 @@ export const isEnabled = (expression: Expression, context: Context): boolean =>
1205
1225
  );
1206
1226
  }
1207
1227
  const environment = context.environment;
1228
+ // TLC computes ENABLED again with its call stack recorded as it computes successors.
1208
1229
  if (environment.callStack) return replayEnabled(expression, context.scope, state, environment);
1209
1230
  const run: Run = {
1210
1231
  environment,
@@ -1215,6 +1236,7 @@ export const isEnabled = (expression: Expression, context: Context): boolean =>
1215
1236
  generator: undefined,
1216
1237
  successors: 0,
1217
1238
  };
1239
+ // TLC stops computing ENABLED at the first successor, so it skips the rest of the action.
1218
1240
  getRunner(expression, environment, false)(
1219
1241
  run,
1220
1242
  context.scope,
@@ -1257,6 +1279,7 @@ export const forEachInitialState = (
1257
1279
  run.isStopped = onIncomplete([...partial]);
1258
1280
  return;
1259
1281
  }
1282
+ // TLC reports an initial state that isn't completely specified as an illegal state.
1260
1283
  throw setExitCode(new TlaIllegalStateError([...partial]), EXIT_STATUS.error);
1261
1284
  }
1262
1285
  run.isStopped = onState(partial);
@@ -1310,9 +1333,7 @@ export const forEachSuccessor = (
1310
1333
  (partial, action) => {
1311
1334
  if (run.isStopped) return;
1312
1335
  if (!isComplete(partial)) {
1313
- const missing = environment.variables.filter(
1314
- (_name, index) => partial[index] === undefined,
1315
- );
1336
+ const missing = environment.variables.filter((_, index) => partial[index] === undefined);
1316
1337
  throw new TlaIncompleteSuccessorError(
1317
1338
  `Successor state is not completely specified by action ${action ?? "Next"}. The following variables are not assigned: ${missing.join(", ")}`,
1318
1339
  partial,
package/src/symmetry.ts CHANGED
@@ -39,6 +39,8 @@ const composePermutations = (first: Images, second: Images) => {
39
39
  return composed;
40
40
  };
41
41
 
42
+ // Tool#getSymmetryPerms fails with a RuntimeException as TLC starts, which TLC reports as one it
43
+ // did not expect.
42
44
  const createSymmetryError = (message: string) =>
43
45
  setExitCode(new TlaEvaluationError(`${UNEXPECTED_EXCEPTION}${message}`), EXIT_STATUS.error);
44
46
 
@@ -55,6 +57,7 @@ const toImages = (value: Value) => {
55
57
  return permutation;
56
58
  };
57
59
 
60
+ // SyntaxTreeNode.getHumanReadableImage, which joins the tokens of an expression without spaces.
58
61
  const getBoundImage = (pattern: BoundPattern, set: Expression | undefined) => {
59
62
  const names = pattern.kind === "Name" ? pattern.name : `<<${pattern.names.join(",")}>>`;
60
63
  return set ? `${names}\\in${getExpressionImage(set)}` : names;
@@ -119,6 +122,8 @@ export const getSymmetryGroup = (
119
122
  if (!elements.every(isFunctionValue)) {
120
123
  throw createSymmetryError("The symmetry values must be function records.");
121
124
  }
125
+ // Tool#getSymmetryPerms warns about each permuted set with fewer than two elements, by the name
126
+ // the config substitutes for it. As many permuted sets as permutations means none has two.
122
127
  const body = definition.body;
123
128
  const permutedSets =
124
129
  body.kind === "Apply" ? body.args : body.kind === "SetEnumeration" ? body.elements : [];
@@ -148,22 +153,24 @@ export const getSymmetryGroup = (
148
153
  if (permutation.size > 0) group.set(getPermutationKey(permutation), permutation);
149
154
  });
150
155
  const generators = [...group.values()];
151
- let frontierStart = 0;
152
- while (frontierStart < group.size) {
156
+ const frontier = { start: 0 };
157
+ while (frontier.start < group.size) {
153
158
  const members = [...group.values()];
154
159
  const end = members.length;
155
160
  generators.forEach((generator) =>
156
- members.slice(frontierStart, end).forEach((member) => {
161
+ members.slice(frontier.start, end).forEach((member) => {
157
162
  const composed = composePermutations(generator, member);
158
163
  const key = getPermutationKey(composed);
159
164
  if (composed.size > 0 && !group.has(key)) group.set(key, composed);
160
165
  }),
161
166
  );
162
- frontierStart = end;
167
+ frontier.start = end;
163
168
  }
164
169
  const movedNames = new Set(
165
170
  [...group.values()].flatMap((images) => [...images.values()].map((image) => image.name)),
166
171
  );
172
+ // Only a permutation of a constant that TLC holds as an enumerated set is checked. TLC binds a
173
+ // constant the config substitutes with <- to the definition, which it skips.
167
174
  const substitutedNames = new Set(substitutions.map((substitution) => substitution.name));
168
175
  warnSmallSets(
169
176
  permutedSets.filter((node) => {
@@ -197,6 +204,8 @@ const permuteElements = (elements: Value[], images: Images) => {
197
204
  return undefined;
198
205
  };
199
206
 
207
+ // A permutation maps distinct elements to distinct elements and keeps the elements it doesn't move
208
+ // in order, so it sorts only the moved ones and merges them back.
200
209
  const permuteSortedElements = (elements: Value[], images: Images) => {
201
210
  const kept: Value[] = [];
202
211
  const moved: Value[] = [];
@@ -222,6 +231,8 @@ const permuteSortedElements = (elements: Value[], images: Images) => {
222
231
  return merged;
223
232
  };
224
233
 
234
+ // Value#permute: the value with each model value replaced by its image. A value the permutation
235
+ // doesn't move is returned itself, so that comparing it with itself stops at identity.
225
236
  const permuteValue = (value: Value, images: Images): Value => {
226
237
  if (typeof value !== "object") return value;
227
238
  const kind = value.kind;
@@ -238,6 +249,8 @@ const permuteValue = (value: Value, images: Images): Value => {
238
249
  const permuted = createFunction(
239
250
  domain.map((key, index): [Value, Value] => [key, range[index]]),
240
251
  );
252
+ // A permutation often maps the domain to itself, such as a function over the symmetric set.
253
+ // Sharing the original domain array lets comparisons with other images skip the domain.
241
254
  const isSameDomain = permuted.domain.every(
242
255
  (key, index) => key === functionValue.domain[index],
243
256
  );
@@ -253,6 +266,8 @@ const permuteValue = (value: Value, images: Images): Value => {
253
266
  return elements ? createSet(elements) : set;
254
267
  };
255
268
 
269
+ // TLC permutes the state under each permutation, variable by variable, and moves on to the next
270
+ // permutation as soon as a variable's image is larger than the smallest state's.
256
271
  export const getRepresentative = (
257
272
  state: Value[],
258
273
  permutations: Images[],
@@ -143,9 +143,9 @@ const POLYNOMIALS = [
143
143
  0x91f5a5fa9c5515a5n,
144
144
  ];
145
145
 
146
- let selectedPolynomial = POLYNOMIALS[0];
146
+ const selected = { polynomial: POLYNOMIALS[0] };
147
147
 
148
- export const getFingerprintPolynomial = () => selectedPolynomial;
148
+ export const getFingerprintPolynomial = () => selected.polynomial;
149
149
 
150
150
  const SLICE_HIGH_0 = new Int32Array(256);
151
151
  const SLICE_HIGH_1 = new Int32Array(256);
@@ -155,8 +155,8 @@ const SLICE_LOW_0 = new Int32Array(256);
155
155
  const SLICE_LOW_1 = new Int32Array(256);
156
156
  const SLICE_LOW_2 = new Int32Array(256);
157
157
  const SLICE_LOW_3 = new Int32Array(256);
158
- let initialHigh = 0;
159
- let initialLow = 0;
158
+ // The polynomial's high and low 32 bits, which avoid a BigInt operation for every byte.
159
+ const initial = { high: 0, low: 0 };
160
160
  let high = 0;
161
161
  let low = 0;
162
162
 
@@ -166,9 +166,12 @@ const extendByte = (byte: number) => {
166
166
  high = (high >>> 8) ^ SLICE_HIGH_0[index];
167
167
  };
168
168
 
169
+ // Extending is linear over GF(2), so extending by four bytes at once shifts the fingerprint by a
170
+ // word and adds, for each of the four, the fingerprint from zero of that byte followed by the zero
171
+ // bytes that come after it: SLICE_HIGH_k and SLICE_LOW_k hold them for k zero bytes after.
169
172
  export const setFingerprintPolynomial = (index: number) => {
170
173
  const polynomial = POLYNOMIALS[index];
171
- selectedPolynomial = polynomial;
174
+ selected.polynomial = polynomial;
172
175
  const powers: bigint[] = [];
173
176
  for (let power = 1n << 63n; powers.length < 72;) {
174
177
  powers.push(power);
@@ -195,8 +198,8 @@ export const setFingerprintPolynomial = (index: number) => {
195
198
  highs[zeros][byte] = (previousHigh[byte] >>> 8) ^ SLICE_HIGH_0[index];
196
199
  }
197
200
  }
198
- initialHigh = Number(BigInt.asIntN(32, polynomial >> 32n));
199
- initialLow = Number(BigInt.asIntN(32, polynomial));
201
+ initial.high = Number(BigInt.asIntN(32, polynomial >> 32n));
202
+ initial.low = Number(BigInt.asIntN(32, polynomial));
200
203
  };
201
204
 
202
205
  setFingerprintPolynomial(0);
@@ -218,6 +221,8 @@ const SET_ENUM_VALUE = 5;
218
221
  const FCN_RCD_VALUE = 9;
219
222
  const MODEL_VALUE = 21;
220
223
 
224
+ // Returns how many bytes it extends the fingerprint by. A model value extends it with its
225
+ // UniqueString token, which TLC numbers from 1 in intern order.
221
226
  const extendScalar = (value: boolean | number | string | ModelValue) => {
222
227
  if (typeof value === "boolean") {
223
228
  extendByte(BOOL_VALUE);
@@ -268,26 +273,27 @@ const extendValue = (value: Value) => {
268
273
  }
269
274
  };
270
275
 
276
+ // Evaluating a lazy value can fingerprint another, so this restores the fingerprint it interrupts.
271
277
  export const getTlcFingerprint = (state: Value[]) => {
272
- const outerHigh = high;
273
- const outerLow = low;
274
- high = initialHigh;
275
- low = initialLow;
278
+ const outer = { high, low };
279
+ high = initial.high;
280
+ low = initial.low;
276
281
  for (const value of state) extendValue(value);
277
282
  const fingerprint = (BigInt(high >>> 0) << 32n) | BigInt(low >>> 0);
278
- high = outerHigh;
279
- low = outerLow;
283
+ high = outer.high;
284
+ low = outer.low;
280
285
  return fingerprint;
281
286
  };
282
287
 
283
288
  export const getTlcFingerprints = (states: Value[][], order: number[]) => {
284
289
  const fingerprints = new BigInt64Array(states.length);
290
+ // Each fingerprint's low and high words, as a BigInt64Array is little-endian.
285
291
  const words = new Int32Array(fingerprints.buffer);
286
292
  const outerHigh = high;
287
293
  const outerLow = low;
288
294
  states.forEach((state, position) => {
289
- high = initialHigh;
290
- low = initialLow;
295
+ high = initial.high;
296
+ low = initial.low;
291
297
  for (const index of order) extendValue(state[index]);
292
298
  words[2 * position] = low;
293
299
  words[2 * position + 1] = high;
@@ -931,6 +931,7 @@ _PrintCounts == PrintT(_Counts)
931
931
  ],
932
932
  ]);
933
933
 
934
+ // As java.lang.reflect.Method prints them in TLC's errors.
934
935
  export const TLC_JAVA_METHODS = new Map([
935
936
  [
936
937
  "Bags",
@@ -125,6 +125,9 @@ export const formatMessage = (isTool: boolean, code: number, level: MessageLevel
125
125
  ? `@!@!@STARTMSG ${code}:${level} @!@!@\n${text}\n@!@!@ENDMSG ${code} @!@!@`
126
126
  : `${LEVEL_PREFIXES[level]}${text}`;
127
127
 
128
+ // With -tool, TLC wraps each message in markers of its code and level, and leaves lines such as
129
+ // Print's bare. A warning prints once, -nowarning drops it, and without -tool the first one
130
+ // says how to drop them.
128
131
  export const createMessagePrinter = (
129
132
  isTool: boolean,
130
133
  isWarningEnabled = true,
@@ -155,9 +158,12 @@ export const createMessagePrinter = (
155
158
  };
156
159
  };
157
160
 
161
+ // TLC 1.7.4's message for a missing initial predicate also blames a parameterized INSTANCE.
158
162
  export const MISSING_INIT_174 =
159
163
  "The configuration file did not specify the initial state predicate.\nCan also be caused by trying to run TLC on a specification from\na module imported with a parameterized INSTANCE statement.";
160
164
 
165
+ // isEvalException: whether TLC throws the message as an EvalException, not a TLCRuntimeException.
166
+ // TLC's -tool output wraps such a message in its own markers even inside another message.
161
167
  const CODED_MESSAGES: [code: number, template: string, isEvalException: boolean][] = [
162
168
  [1005, STACK_OVERFLOW_MESSAGE, false],
163
169
  [
@@ -337,10 +343,12 @@ interface CodedMessage {
337
343
  isEvalException: boolean;
338
344
  }
339
345
 
340
- let codedMessagePatterns: { pattern: RegExp; message: CodedMessage }[] | undefined;
346
+ const codedMessagePatterns = {
347
+ value: undefined as { pattern: RegExp; message: CodedMessage }[] | undefined,
348
+ };
341
349
 
342
350
  const getCodedMessagePatterns = () =>
343
- (codedMessagePatterns ??= CODED_MESSAGES.map(([code, template, isEvalException]) => ({
351
+ (codedMessagePatterns.value ??= CODED_MESSAGES.map(([code, template, isEvalException]) => ({
344
352
  pattern: new RegExp(
345
353
  `^${template
346
354
  .split(/%\d+%/)
@@ -350,6 +358,8 @@ const getCodedMessagePatterns = () =>
350
358
  message: { code, isEvalException },
351
359
  })));
352
360
 
361
+ // Plain messages that read like coded ones: the overflows of SetOfFcnsValue and SetOfTuplesValue,
362
+ // SetPredValue's tuple membership, and Tool#enabled's for ~> and -+->.
353
363
  const UNCODED_MESSAGE_PATTERN =
354
364
  /^Overflow when computing the number of elements in( |:\n\[(?![A-Za-z0-9_]+: ))|\nis an element of a set of \d+-tuples\.$|^In computing ENABLED, TLC encountered a temporal formula \(a (~> b|-\+-> formula)\)\./;
355
365
 
@@ -358,10 +368,13 @@ export const getCodedMessage = (text: string): CodedMessage | undefined =>
358
368
  ? undefined
359
369
  : getCodedMessagePatterns().find((item) => item.pattern.test(text))?.message;
360
370
 
371
+ // Only a standard module's Java code throws an EvalException; Assert.fail throws the other kind.
361
372
  export const isEvalException = (error: TlaEvaluationError) =>
362
373
  error instanceof TlaModuleError || getCodedMessage(error.message)?.isEvalException === true;
363
374
 
375
+ // The messages that end with the message of the error they report, after this text.
364
376
  const INNER_MESSAGE_PREFIXES = new Map([
377
+ // "The exception was a <class>\n: "
365
378
  [1000, "\n: "],
366
379
  [2105, "failed.\n"],
367
380
  [2154, "but it produced the following error:\n"],
@@ -371,6 +384,7 @@ const INNER_MESSAGE_PREFIXES = new Map([
371
384
  [2405, "failed.\n"],
372
385
  ]);
373
386
 
387
+ // TLC's message holds the inner error's text as TLC printed it, markers included.
374
388
  export const formatInnerMessage = (code: number, text: string, isTool: boolean) => {
375
389
  const prefix = isTool ? INNER_MESSAGE_PREFIXES.get(code) : undefined;
376
390
  const index = prefix === undefined ? -1 : text.indexOf(prefix);
@@ -426,12 +440,14 @@ const WRONG_INVOCATION_EXCEPTION = getUnexpectedException("util.WrongInvocationE
426
440
 
427
441
  const UNEXPECTED_HEADLINE = UNEXPECTED_EXCEPTION.slice(0, UNEXPECTED_EXCEPTION.indexOf("\n"));
428
442
 
443
+ // TLC 1.7.4 wraps an error in adding a successor in a RuntimeException naming its class.
429
444
  const WRAPPED_EVAL_EXCEPTION = `${UNEXPECTED_EXCEPTION}tlc2.tool.EvalException: `;
430
445
  const WRAPPED_RUNTIME_EXCEPTION = `${UNEXPECTED_EXCEPTION}util.Assert$TLCRuntimeException: `;
431
446
 
432
447
  export const getWrappedException = (error: TlaEvaluationError) =>
433
448
  isEvalException(error) ? WRAPPED_EVAL_EXCEPTION : WRAPPED_RUNTIME_EXCEPTION;
434
449
 
450
+ // TLC reports an EvalException, or a TLCRuntimeException without its own message, as unexpected.
435
451
  export const withUnexpectedException = <Result>(compute: () => Result) => {
436
452
  try {
437
453
  return compute();
@@ -461,6 +477,8 @@ const formatErrorMessage = (error: TlaEvaluationError, isTool: boolean): string
461
477
  return `${prefix}${formatNestedMessage(message.slice(prefix.length), isTool)}`;
462
478
  };
463
479
 
480
+ // TLC reports an error with a headline by its message's code, and one that escapes the next
481
+ // states with an EvalException's code, or as an unexpected exception.
464
482
  export interface FailureMessage {
465
483
  code: number;
466
484
  message: string;
@@ -480,6 +498,7 @@ export const getFailureMessage = (
480
498
  toolMessage: formatErrorMessage(error, true),
481
499
  };
482
500
  }
501
+ // TLC prints a StackOverflowError by its code in the next states, as plain text in the initial.
483
502
  if (error instanceof TlaStackOverflowError) {
484
503
  return {
485
504
  code: isNextState ? MESSAGE_CODE.stackOverflow : MESSAGE_CODE.general,
package/src/tlc/order.ts CHANGED
@@ -1,3 +1,4 @@
1
+ // Reproduces TLC's string order, by first interning, and its variable order, from SANY's context.
1
2
  import type { Module, SourceLocation } from "../ast";
2
3
  import type { ConfigValue, ModelConfig } from "../config";
3
4
  import { createMissingModuleError } from "../errors";
@@ -27,6 +28,7 @@ interface SymbolEntry {
27
28
  interface SymbolTable {
28
29
  put: (entry: SymbolEntry) => void;
29
30
  inserted: SymbolEntry[];
31
+ // Where the entries the module adds itself start, after those of the modules it extends.
30
32
  ownStart: number;
31
33
  enumerate: () => SymbolEntry[];
32
34
  }
@@ -63,6 +65,8 @@ const getJavaHash = (text: string) => {
63
65
  return hash;
64
66
  };
65
67
 
68
+ // java.util.Hashtable as SANY's Context uses it: capacity 11, load factor 0.75, new entries at
69
+ // the head of their bucket, and enumeration from the last bucket, each from tail to head.
66
70
  const createSymbolTable = (): SymbolTable => {
67
71
  let buckets: SymbolEntry[][] = Array.from({ length: 11 }, () => []);
68
72
  let threshold = 8;
@@ -150,6 +154,7 @@ type ModuleSearch = (
150
154
  visited: Set<string>,
151
155
  ) => [ModuleReferences, string] | undefined;
152
156
 
157
+ // In the order SANY's SpecObj walks them to decide which module to parse next.
153
158
  const getModuleReferences = (
154
159
  tokens: Token[],
155
160
  unit: string | undefined,
@@ -174,10 +179,10 @@ const getModuleReferences = (
174
179
  innerModules.set(name, inner.references);
175
180
  references.inner.push(inner.references);
176
181
  index = inner.end;
182
+ } else if (tokens[index - 1]?.text === ".") {
183
+ // A record field named EXTENDS or INSTANCE, as in r.EXTENDS or [r EXCEPT !.INSTANCE = 0].
177
184
  continue;
178
- }
179
- if (tokens[index - 1]?.text === ".") continue;
180
- if (token.text === "EXTENDS") {
185
+ } else if (token.text === "EXTENDS") {
181
186
  const names = getDeclarations(tokens, index + 1);
182
187
  references.extends.push(...names);
183
188
  names.forEach((name) => allExtends.add(name));
@@ -204,6 +209,8 @@ const STRING_ESCAPES: Record<string, string> = {
204
209
  "\f": "\\f",
205
210
  };
206
211
 
212
+ // SANY reads <1>2 and ---- MODULE as one token each, and interns a string literal with its
213
+ // quotes, its contents only during semantic analysis.
207
214
  const getParsedTexts = (tokens: Token[]) => {
208
215
  const texts: string[] = [];
209
216
  for (let index = 0; index < tokens.length; index++) {
@@ -229,6 +236,7 @@ const getParsedTexts = (tokens: Token[]) => {
229
236
  return texts;
230
237
  };
231
238
 
239
+ // A module starts with ---- MODULE Name, so its third token is its name.
232
240
  const getModuleName = (tokens: Token[]) => tokens[2]?.text;
233
241
 
234
242
  const getRanges = (tokens: Token[]) => {
@@ -256,17 +264,19 @@ interface ModuleText {
256
264
  getModule: () => Module;
257
265
  }
258
266
 
267
+ // Read and parsed once, for every order and for the environment that evaluates it.
259
268
  const readModuleText = (text: string | undefined): ModuleText => {
260
269
  const tokens = text === undefined ? [] : tokenize(text);
261
- let parsedModule: Module | undefined;
270
+ const parsed = { module: undefined as Module | undefined };
262
271
  return {
263
272
  tokens,
264
273
  ranges: getRanges(tokens),
265
274
  getModule: () =>
266
- (parsedModule ??= text === undefined ? parseModule("") : parseModuleTokens(text, tokens)),
275
+ (parsed.module ??= text === undefined ? parseModule("") : parseModuleTokens(text, tokens)),
267
276
  };
268
277
  };
269
278
 
279
+ // A module without a source has no tokens.
270
280
  const createModuleSet = (source: string, loadModule: ModuleLoader) => {
271
281
  const files = new Map<string, ParsedModule>();
272
282
  const nestedModules = new Map<string, ParsedModule>();
@@ -288,12 +298,11 @@ const createModuleSet = (source: string, loadModule: ModuleLoader) => {
288
298
  TLC_MODULE_SOURCES.get(name) ??
289
299
  SANY_STANDARD_MODULES.get(name) ??
290
300
  extractModule(source, name));
291
- const moduleText = readText(text);
292
- const tokens = moduleText.tokens;
293
- const range = moduleText.ranges.get(getModuleName(tokens) ?? "") ?? { start: 0, end: 0 };
294
- const file = { tokens, ...range, getModule: moduleText.getModule };
301
+ const { tokens, ranges, getModule } = readText(text);
302
+ const range = ranges.get(getModuleName(tokens) ?? "") ?? { start: 0, end: 0 };
303
+ const file = { tokens, ...range, getModule };
295
304
  files.set(name ?? "", file);
296
- moduleText.ranges.forEach((nestedRange, nestedName) => {
305
+ ranges.forEach((nestedRange, nestedName) => {
297
306
  if (nestedRange.start === range.start || nestedModules.has(nestedName)) return;
298
307
  nestedModules.set(nestedName, {
299
308
  tokens,
@@ -311,6 +320,7 @@ const createModuleSet = (source: string, loadModule: ModuleLoader) => {
311
320
  };
312
321
  };
313
322
 
323
+ // The root module's context is under undefined.
314
324
  type ModuleSet = ReturnType<typeof createModuleSet>["getParsed"];
315
325
 
316
326
  const createContexts = (getParsed: ModuleSet) => {
@@ -336,12 +346,13 @@ const createContexts = (getParsed: ModuleSet) => {
336
346
  : [],
337
347
  ),
338
348
  );
339
- let depth = 0;
340
- tokens.slice(unit.start, unit.end).forEach((token, offset) => {
349
+ const depth = { value: 0 };
350
+ tokens.slice(unit.start, unit.end).forEach((_, offset) => {
341
351
  const index = unit.start + offset;
352
+ const token = tokens[index];
342
353
  if (token.kind === "Separator" && tokens[index + 1]?.text === "MODULE") {
343
- depth++;
344
- if (depth === 2) {
354
+ depth.value++;
355
+ if (depth.value === 2) {
345
356
  const name = tokens[index + 2].text;
346
357
  units.push({
347
358
  location: getLocation(token),
@@ -350,8 +361,8 @@ const createContexts = (getParsed: ModuleSet) => {
350
361
  }
351
362
  return;
352
363
  }
353
- if (token.kind === "ModuleEnd") depth--;
354
- if (depth !== 1 || token.kind !== "Keyword") return;
364
+ if (token.kind === "ModuleEnd") depth.value--;
365
+ if (depth.value !== 1 || token.kind !== "Keyword") return;
355
366
  const isDeclaration = declarationKeywords.has(`${token.line}:${token.column}`);
356
367
  if (isDeclaration && (token.text === "CONSTANT" || token.text === "CONSTANTS")) {
357
368
  declare(index, "constant");
@@ -451,6 +462,8 @@ const createContexts = (getParsed: ModuleSet) => {
451
462
  };
452
463
  };
453
464
 
465
+ // In order: config values, TLC's startup strings, each module's tokens as SpecObj.loadSpec
466
+ // parses them, string literals in semantic analysis order, and TLCGet's names.
454
467
  const getStringOrder = (getParsed: ModuleSet, config: ModelConfig): string[] => {
455
468
  const order = new Set<string>();
456
469
  const intern = (text: string) => {
@@ -526,6 +539,7 @@ const getStringOrder = (getParsed: ModuleSet, config: ModelConfig): string[] =>
526
539
  dependencies.set(module.unit, [...(dependencies.get(module.unit) ?? []), name]);
527
540
  if (parsedUnits.has(name)) continue;
528
541
  parsedUnits.add(name);
542
+ // SANY stops at the first module it can't find, in the order it reads them.
529
543
  if (getParsed(name).tokens.length === 0) {
530
544
  const importer = module.unit ?? getModuleName(getParsed(undefined).tokens);
531
545
  throw createMissingModuleError(name, importer);
@@ -554,7 +568,11 @@ const getStringOrder = (getParsed: ModuleSet, config: ModelConfig): string[] =>
554
568
 
555
569
  export interface TlcOrder {
556
570
  getStringOrder: (config: ModelConfig) => string[];
571
+ // The reverse of the root module's context enumeration, in which TLC compares variables and
572
+ // checks that the configuration assigns each constant.
557
573
  getDeclarationOrder: (kind: "variable" | "constant") => string[];
574
+ // In the order TLC computes constant definitions at startup. An INSTANCE adds those of the
575
+ // module it instantiates in the order that module's Hashtable enumerates them.
558
576
  createDefinitionOrder: () => (name: string | undefined) => string[];
559
577
  parseModule: (source: string) => Module;
560
578
  }
@@ -575,11 +593,11 @@ export const createTlcOrder = (source: string, loadModule: ModuleLoader): TlcOrd
575
593
  .reverse(),
576
594
  parseModule: modules.parseText,
577
595
  createDefinitionOrder: () => {
578
- const moduleContexts = getContexts();
579
- moduleContexts.getContext(undefined);
596
+ const { getContext, getOwnEntries } = getContexts();
597
+ // The root module's context finds the modules nested in the files it extends or instantiates.
598
+ getContext(undefined);
580
599
  return (name) =>
581
- moduleContexts
582
- .getOwnEntries(name)
600
+ getOwnEntries(name)
583
601
  .filter((entry) => entry.kind === "definition")
584
602
  .map((entry) => entry.name);
585
603
  },