tla-ts 0.0.8 → 0.0.9-dev.0dd11f695

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 (119) hide show
  1. package/README.md +30 -0
  2. package/dist/compile.cjs +23 -0
  3. package/dist/compile.js +23 -0
  4. package/dist/deciders.cjs +15 -15
  5. package/dist/deciders.js +40 -40
  6. package/dist/index.cjs +1 -1
  7. package/dist/index.d.cts +98 -19
  8. package/dist/index.d.ts +98 -19
  9. package/dist/index.js +1 -1
  10. package/dist/parallel-worker.cjs +1 -1
  11. package/dist/parallel-worker.js +1 -1
  12. package/dist/prove-worker.cjs +1 -1
  13. package/dist/prove-worker.js +1 -1
  14. package/dist/prove.cjs +116 -36
  15. package/dist/prove.js +116 -36
  16. package/dist/run.cjs +143 -31
  17. package/dist/run.js +143 -31
  18. package/dist/tlapm.cjs +2 -2
  19. package/dist/tlapm.js +1 -1
  20. package/dist/transfer.cjs +128 -106
  21. package/dist/transfer.js +128 -106
  22. package/dist/worker.cjs +7 -7
  23. package/dist/worker.js +7 -7
  24. package/package.json +3 -1
  25. package/src/ast.ts +7 -21
  26. package/src/bags.ts +99 -99
  27. package/src/builtins.ts +44 -75
  28. package/src/bundled-modules.ts +1 -8
  29. package/src/check.ts +605 -311
  30. package/src/cli/options.ts +12 -3
  31. package/src/cli/run.ts +2 -2
  32. package/src/cli/runtime-invariants.ts +135 -0
  33. package/src/cli/shared.ts +20 -9
  34. package/src/cli/tlc-arguments.ts +646 -0
  35. package/src/cli/tlc-usage.ts +362 -0
  36. package/src/cli/tlc.ts +571 -185
  37. package/src/cli/typescript.ts +26 -0
  38. package/src/cli/xml-exporter.ts +4 -10
  39. package/src/codegen.ts +190 -51
  40. package/src/config.ts +101 -68
  41. package/src/coverage.ts +855 -0
  42. package/src/dependencies.ts +340 -24
  43. package/src/dfid.ts +636 -0
  44. package/src/environment.ts +289 -109
  45. package/src/errors.ts +142 -45
  46. package/src/evaluate.ts +734 -980
  47. package/src/exit-codes.ts +37 -1
  48. package/src/index.ts +3 -0
  49. package/src/instances.ts +85 -9
  50. package/src/java-overrides.ts +2 -12
  51. package/src/json-reader.ts +456 -0
  52. package/src/json.ts +262 -139
  53. package/src/levels.ts +2 -3
  54. package/src/lexer.ts +150 -70
  55. package/src/liveness-checker.ts +10 -18
  56. package/src/liveness.ts +122 -64
  57. package/src/parallel-worker.ts +14 -10
  58. package/src/parallel.ts +41 -17
  59. package/src/parser.ts +436 -90
  60. package/src/pcal/ast.ts +7 -28
  61. package/src/pcal/parse.ts +11 -39
  62. package/src/pcal/tokenize.ts +4 -20
  63. package/src/pcal/translate.ts +10 -42
  64. package/src/pcal/validate.ts +3 -21
  65. package/src/pretty-print.ts +1 -2
  66. package/src/prover/smt/solver/solver.ts +31 -27
  67. package/src/randomization.ts +84 -35
  68. package/src/resolve.ts +18 -60
  69. package/src/runtime.ts +11 -4
  70. package/src/sany/builtins.ts +3 -4
  71. package/src/sany/generator.ts +128 -176
  72. package/src/sany/levels.ts +6 -30
  73. package/src/sany/lexer.ts +7 -23
  74. package/src/sany/linter.ts +31 -29
  75. package/src/sany/modules.ts +1 -5
  76. package/src/sany/nodes.ts +4 -28
  77. package/src/sany/parse-error.ts +44 -100
  78. package/src/sany/report.ts +25 -40
  79. package/src/sany/selectors.ts +8 -22
  80. package/src/sany/source.ts +8 -15
  81. package/src/sany/xml.ts +11 -42
  82. package/src/search.ts +550 -150
  83. package/src/simulate.ts +694 -0
  84. package/src/spec-description.ts +167 -49
  85. package/src/standard-definitions.ts +2 -3
  86. package/src/standard-modules.ts +264 -68
  87. package/src/state-graph.ts +51 -18
  88. package/src/subexpressions.ts +31 -5
  89. package/src/successors.ts +269 -85
  90. package/src/symmetry.ts +59 -147
  91. package/src/tableau.ts +1 -2
  92. package/src/tlc/fingerprint.ts +226 -151
  93. package/src/tlc/jar-data.ts +113 -6
  94. package/src/tlc/messages.ts +122 -37
  95. package/src/tlc/order.ts +56 -82
  96. package/src/tlc/random.ts +16 -16
  97. package/src/tlc/replay.ts +564 -212
  98. package/src/tlc/summary.ts +2 -4
  99. package/src/tlc/tlc-operators.ts +81 -36
  100. package/src/tlc/tlcext-operators.ts +138 -117
  101. package/src/tlc/trace-spec.ts +273 -0
  102. package/src/tlc/value-stream.ts +143 -0
  103. package/src/tlc/version.ts +2 -4
  104. package/src/typescript/actions.ts +494 -0
  105. package/src/typescript/collections.ts +615 -0
  106. package/src/typescript/compile.ts +70 -0
  107. package/src/typescript/context.ts +106 -0
  108. package/src/typescript/emit.ts +122 -0
  109. package/src/typescript/expressions.ts +508 -0
  110. package/src/typescript/formula.ts +160 -0
  111. package/src/typescript/functions.ts +295 -0
  112. package/src/typescript/model.ts +164 -0
  113. package/src/typescript/names.ts +116 -0
  114. package/src/typescript/program.ts +51 -0
  115. package/src/typescript/properties.ts +148 -0
  116. package/src/typescript/scope.ts +117 -0
  117. package/src/typescript/steps.ts +175 -0
  118. package/src/typescript/types.ts +178 -0
  119. package/src/values.ts +910 -318
@@ -18,29 +18,20 @@ import type { TlcVersion } from "../tlc/version";
18
18
  interface SanyReport {
19
19
  text: string;
20
20
  isFailed: boolean;
21
- // The specification SANY analyzes, which has errors when SANY rejects it.
22
21
  specification?: SanySpecification;
23
22
  }
24
23
 
25
- // Where SANY reads a module from: a file of its own, the file of the root module, which holds the
26
- // root module's inner modules too, or the files of its standard modules.
27
24
  export type SanyModuleOrigin = "file" | "root file" | "standard";
28
25
 
29
26
  export interface SanyReportOptions {
30
- // The file name SANY's caller gives it, which it prints in its messages about the specification.
31
27
  fileName?: string;
32
- // TLC runs SANY to print the file it parses each module from, as describeFile names it, and each
33
- // module it analyzes and lints.
34
28
  describeFile?: (moduleName: string, origin: SanyModuleOrigin) => string;
35
- // tla2sany.xml.XMLExporter runs SANY with its validAstSettings, which neither lint the modules
36
- // nor validate their PlusCal, and prints only SANY's errors.
37
29
  isXmlExport?: boolean;
38
30
  version?: TlcVersion;
39
- // The modules TLC adds to the root module's EXTENDS for its post conditions.
40
31
  rootExtendees?: string[];
41
- // Prints what SANY prints as it goes, before the report holds all of it.
32
+ suppressedCodes?: number[];
33
+ errorCodes?: number[];
42
34
  onPrint?: (text: string) => void;
43
- // Prints what TLC 1.7.4's SANY prints to its error stream as it goes.
44
35
  onPrintError?: (text: string) => void;
45
36
  }
46
37
 
@@ -54,11 +45,9 @@ interface Validation {
54
45
  isError: boolean;
55
46
  }
56
47
 
57
- // ErrorDetails.toString.
58
48
  const formatMessage = (message: SanyMessage) =>
59
49
  `${formatSanyLocation(message.location)}\n\n${message.text}`;
60
50
 
61
- // Errors.toString: the errors and then the warnings of a phase of SANY.
62
51
  const formatErrors = (messages: SanyMessage[]) => {
63
52
  const errors = messages.filter((message) => !message.isWarning);
64
53
  const warnings = messages.filter((message) => message.isWarning);
@@ -70,7 +59,8 @@ const formatErrors = (messages: SanyMessage[]) => {
70
59
  ].join("");
71
60
  };
72
61
 
73
- // tla2sany.semantic.StandardModules: SANY lints the modules other than these.
62
+ const RECORD_FIELD_CLASH = 4802;
63
+
74
64
  const UNLINTED_MODULES = new Set([
75
65
  "FiniteSets",
76
66
  "Sequences",
@@ -83,7 +73,6 @@ const UNLINTED_MODULES = new Set([
83
73
  "TLC",
84
74
  ]);
85
75
 
86
- // The modules a module and its inner modules extend, other than its inner modules.
87
76
  const getExtendees = (module: Module) => {
88
77
  const innerNames = new Set<string>();
89
78
  const extendees: string[] = [];
@@ -107,15 +96,11 @@ const parseValidatedModule = (text: string) => {
107
96
  }
108
97
  };
109
98
 
110
- // ParseUnit.parseFile: SANY names the specification by the root module once it parses it.
111
99
  export const getSanyModuleName = (text: string, version?: TlcVersion) =>
112
100
  version === "1.7.4" && getSany174LexicalError(text) !== undefined
113
101
  ? undefined
114
102
  : parseValidatedModule(text)?.name;
115
103
 
116
- // What SANY prints while TLC runs it on the specification in rootPath, and whether SANY rejects the
117
- // specification. loadModule finds the source of the other modules, and SANY's standard modules fill
118
- // in the rest.
119
104
  export const getSanyReport = (
120
105
  rootPath: string,
121
106
  loadModule: (name: string) => string | undefined,
@@ -145,14 +130,11 @@ export const getSanyReport = (
145
130
  [rootName, existsSync(rootPath) ? "file" : "standard"],
146
131
  ]);
147
132
  const isFailed = { value: false };
148
- // The messages of SANY's parsing phase, which come from its validation of PlusCal, and whether
149
- // SANY has printed them and whether one is an error that ends its run before semantic analysis.
150
133
  const parseMessages: SanyMessage[] = [];
151
134
  const parsePhase = { isReported: false, isAborted: false };
152
135
  const session = createPcalSession(createPcalParams(), log);
153
136
  const loadedModules = new Map<string, LoadedModule>();
154
- // TLC 1.7.4's SpecObj.validateParseUnit prints what it finds, which follows the file SANY parses
155
- // next, as SANY validates a module once it parses the module or one that extends it.
137
+ // TLC 1.7.4's SpecObj.validateParseUnit prints what it finds after the file SANY parses next.
156
138
  const validations: Validation[] = [];
157
139
  const printValidations = () =>
158
140
  validations
@@ -160,7 +142,7 @@ export const getSanyReport = (
160
142
  .forEach((validation) =>
161
143
  validation.isError ? options.onPrintError?.(`${validation.text}\n`) : log(validation.text),
162
144
  );
163
- // SpecObj.validateParseUnit: Errors.addMessage drops a message it already has.
145
+ // Errors.addMessage drops a message it already has.
164
146
  const validate = (moduleName: string) => {
165
147
  const loaded = loadedModules.get(moduleName);
166
148
  const range = loaded?.module.location.range;
@@ -205,9 +187,8 @@ export const getSanyReport = (
205
187
  if (parseMessages.some((message) => message.text === text)) return;
206
188
  parseMessages.push({ location: moduleName, text, isWarning });
207
189
  };
208
- // SpecObj.loadSpec validates the root module once it parses, and a module each time SANY
209
- // resolves another module's EXTENDS of it, which the report does when the generator loads it,
210
- // and for a module loaded earlier, when the generator loads a module that extends it.
190
+ // SANY validates the root module once it parses, and a module each time it resolves another
191
+ // module's EXTENDS of it.
211
192
  const loadValidatedModule = (moduleName: string, text: string) => {
212
193
  if (options.isXmlExport || loadedModules.has(moduleName)) return;
213
194
  const module = parseValidatedModule(text);
@@ -221,8 +202,8 @@ export const getSanyReport = (
221
202
  .filter((extendee) => extendee !== moduleName && loadedModules.has(extendee))
222
203
  .forEach(validate);
223
204
  };
224
- // SANY.frontEndParse: once SANY has loaded the specification, it prints the warnings of its
225
- // parsing phase, and when there are errors, every message, and stops.
205
+ // Once SANY has loaded the specification, it prints its parsing phase's warnings, or, when there
206
+ // are errors, every message, and stops.
226
207
  const reportParseMessages = () => {
227
208
  printValidations();
228
209
  if (parsePhase.isReported) return;
@@ -255,8 +236,8 @@ export const getSanyReport = (
255
236
  return text ?? standard;
256
237
  };
257
238
  const generate = () => {
258
- // HACK: SANY reports a fatal error of its parsing phase by the exception it throws, so the
259
- // report catches the TlaSyntaxError the generator throws for one.
239
+ // HACK: SANY reports a fatal parsing error by the exception it throws, so the report catches the
240
+ // TlaSyntaxError the generator throws for one.
260
241
  try {
261
242
  if (source === undefined) {
262
243
  throw new TlaSanyFatalError(`Cannot find source file for module ${name}`, undefined);
@@ -282,8 +263,7 @@ export const getSanyReport = (
282
263
  log(`Semantic processing of module ${moduleName}`);
283
264
  }
284
265
  },
285
- // SANY.frontEndSemanticAnalysis: after each module, SANY level-checks it if there are no
286
- // errors yet, then prints every message so far.
266
+ // After each module, SANY level-checks it if there are no errors yet, then prints every message.
287
267
  onModule: (module, messages) => {
288
268
  if (parsePhase.isAborted) return;
289
269
  if (messages.every((message) => message.isWarning))
@@ -305,8 +285,7 @@ export const getSanyReport = (
305
285
  });
306
286
  } catch (error) {
307
287
  isFailed.value = true;
308
- // SANY.frontEndParse turns a Java exception of its validation of PlusCal into a fatal
309
- // error, printing the exception and its messages so far.
288
+ // SANY turns a Java exception of its PlusCal validation into a fatal error.
310
289
  if (error instanceof PcalRuntimeError) {
311
290
  log(`\nFatal errors while parsing TLA+ spec in file ${name}\n`);
312
291
  log(error.message);
@@ -315,8 +294,8 @@ export const getSanyReport = (
315
294
  }
316
295
  if (!(error instanceof TlaSanyFatalError)) throw error;
317
296
  const fatal = { location: error.location, text: error.message, isWarning: false };
318
- // TLC 1.7.4's ParseException.getShortMessage fails on an error at the first token, which has
319
- // no image.
297
+ // TLC 1.7.4's ParseException.getShortMessage fails on an error at the first token, which has no
298
+ // image.
320
299
  const isImageless = isTlc174 && error.parseError?.includes(' and token "" ');
321
300
  if (error.parseError !== undefined && !isImageless && !isToolOutputDiscarded) {
322
301
  log(error.parseError);
@@ -340,12 +319,18 @@ export const getSanyReport = (
340
319
  };
341
320
  const specification = generate();
342
321
  if (specification !== undefined) reportParseMessages();
343
- // SANY.frontEndLinting: when SANY accepts the specification, it lints the modules that are not
344
- // its standard modules, then prints the warnings. TLC 1.7.4's SANY has no linter.
322
+ // SANY lints only a specification it accepts, and TLC 1.7.4's SANY has no linter.
345
323
  if (specification !== undefined && !isFailed.value && !options.isXmlExport && !isTlc174) {
346
324
  const linted = specification.modules.filter((module) => !UNLINTED_MODULES.has(module.name));
347
325
  if (describeFile) linted.forEach((module) => log(`Linting of module ${module.name}`));
348
- linted.flatMap(lintSanyModule).forEach((warning) => log(`${formatMessage(warning)}\n\n\n`));
326
+ const warnings = options.suppressedCodes?.includes(RECORD_FIELD_CLASH)
327
+ ? []
328
+ : linted.flatMap(lintSanyModule);
329
+ const prefix = options.errorCodes?.includes(RECORD_FIELD_CLASH)
330
+ ? "Warning treated as error: "
331
+ : "";
332
+ warnings.forEach((warning) => log(`${prefix}${formatMessage(warning)}\n\n\n`));
333
+ if (prefix && warnings.length > 0) isFailed.value = true;
349
334
  }
350
335
  return {
351
336
  text: lines.join(""),
@@ -21,18 +21,15 @@ import {
21
21
  type ThmOrAssumpDefNode,
22
22
  } from "./nodes";
23
23
 
24
- // A port of SANY's Generator.selectorToNode, which turns a name such as Op(a)!lab(b)!:!2 into the
25
- // semantic node it names, following the Subexpression algorithm of SANY's Subexpression.tla.
24
+ // A port of SANY's Generator.selectorToNode, following the algorithm of SANY's Subexpression.tla.
26
25
 
27
- // An operand selector !i is the number i, and the other selectors are named after SANY's NameSel,
28
- // NullSel, GGSel, LLSel, ColonSel and AtSel.
26
+ // Named after SANY's NameSel, NullSel, GGSel, LLSel, ColonSel and AtSel; !i is the number i.
29
27
  type SelectorOp = number | "Name" | "Null" | ">>" | "<<" | ":" | "@";
30
28
 
31
29
  export interface SelectorItem {
32
30
  op: SelectorOp;
33
31
  name: string;
34
32
  args: Expression[] | undefined;
35
- // Where SANY locates the selector and its parenthesized arguments, when known.
36
33
  location?: SanyLocation;
37
34
  argsLocation?: SanyLocation;
38
35
  }
@@ -62,10 +59,7 @@ interface SelectorGenerator {
62
59
  createLambda: (params: FormalParamNode[], body: ExprNode, location: SanyLocation) => OpDefNode;
63
60
  copySubstIn: (prefix: SubstInNode, body: ExprNode) => SubstInNode;
64
61
  getBuiltin: (name: string) => OpDefNode;
65
- // Errors.addMessage for an error SANY recovers from, and the null node SANY returns after one.
66
62
  addError: (location: SanyLocation, text: string) => OpApplNode;
67
- // Generator.illegalLabelRef and illegalAPPosRef: whether the node being generated lies outside
68
- // the scope of a declaration that a label or a clause of an ASSUME/PROVE lies in.
69
63
  isOutOfLabelScope: (label: LabelNode) => boolean;
70
64
  isOutOfClauseScope: (assumeProve: AssumeProveNode, position: number) => boolean;
71
65
  }
@@ -80,8 +74,8 @@ const PROOF_STEP_OPERATORS = new Map([
80
74
  ["$Suffices", "SUFFICES"],
81
75
  ]);
82
76
 
83
- // The parts of a name like I!Op or Op!lab, except for an operator such as !! that contains a "!".
84
- const getNameParts = (name: string) => {
77
+ const getNameParts = (name: string): string[] => {
78
+ if (name.length > 3 && name.endsWith("!!!")) return [...getNameParts(name.slice(0, -3)), "!!"];
85
79
  const parts = name.split("!");
86
80
  return parts.some((part) => part.length === 0) ? [name] : parts;
87
81
  };
@@ -125,19 +119,14 @@ export const getSelectorItems = (expression: Expression): SelectorItem[] | undef
125
119
  return undefined;
126
120
  };
127
121
 
128
- // A selector SANY parses as a GeneralId rather than an OpApplication: one whose last part is not a
129
- // name with arguments.
130
122
  export const isGeneralId = (items: SelectorItem[]) => {
131
123
  const last = items[items.length - 1];
132
124
  return last.op !== "Name" || last.args === undefined;
133
125
  };
134
126
 
135
- // SANY's selectorItemToString, which names an operand selector after the argument it selects.
136
127
  const getSelectorItemName = (item: SelectorItem) =>
137
128
  typeof item.op === "number" ? `argument selector ${item.name}` : item.name;
138
129
 
139
- // Subexpression.tla's ArgNum: the human number of the operand that a selector picks out of an
140
- // expression with arity operands, or -1.
141
130
  const getArgNumber = (op: SelectorOp, arity: number) => {
142
131
  if (typeof op === "number") return op > 0 && op <= arity ? op : -1;
143
132
  if (op === "<<") return arity > 0 ? 1 : -1;
@@ -147,7 +136,6 @@ const getArgNumber = (op: SelectorOp, arity: number) => {
147
136
 
148
137
  type Mode = "FindingOpName" | "FollowingLabels" | "FindingSubExpr";
149
138
 
150
- // The state of Generator.selectorToNode as it walks the items.
151
139
  interface SelectorWalk {
152
140
  name: string | undefined;
153
141
  nameLocation: SanyLocation | undefined;
@@ -176,13 +164,11 @@ const isSymbol = (node: LevelNode | SymbolNode): node is SymbolNode =>
176
164
  const getQuantifierSymbols = (node: OpApplNode) =>
177
165
  (node.bounded?.length ?? 0) > 0 ? (node.bounded ?? []).flat() : (node.unbounded ?? []);
178
166
 
179
- // Generator.extendedBy: a name's location grown to the end of its next part.
180
167
  const extendLocation = (name: SanyLocation | undefined, part: SanyLocation): SanyLocation =>
181
168
  name === undefined ? part : { ...name, endLine: part.endLine, endColumn: part.endColumn };
182
169
 
183
- // selectorToNode: with expectedArity 0 the expression a selector names, with a positive one the
184
- // operator argument, and with -1 the definition a DEF clause names. A fact can also be an
185
- // ASSUME/PROVE, a NEW clause or a module instance.
170
+ // With expectedArity 0 a selector names an expression, with a positive one an operator argument,
171
+ // and with -1 the definition a DEF clause names.
186
172
  export const createSelectorResolver =
187
173
  (generator: SelectorGenerator) =>
188
174
  (
@@ -255,8 +241,8 @@ export const createSelectorResolver =
255
241
  walk.index++;
256
242
  }
257
243
  }
258
- // TLC 1.7.4's SANY names only the last item of a selector it can't resolve, as
259
- // selectorItemToString does, which fails on an argument selector that isn't a number.
244
+ // TLC 1.7.4's SANY names only the last item of a selector it can't resolve, which fails on an
245
+ // argument selector that isn't a number.
260
246
  if (symbol === undefined && generator.version === "1.7.4") {
261
247
  const last = items.length - 1;
262
248
  return generator.addError(
@@ -5,8 +5,8 @@ import { getTabStop } from "./lexer";
5
5
  import { getSanyParseError } from "./parse-error";
6
6
  import type { SanyLocation } from "./nodes";
7
7
 
8
- // The tokens of one file, to find the locations SANY gives to names, brackets and parentheses that
9
- // the syntax tree of tla-ts leaves out, and the comments SANY attaches to definitions.
8
+ // Finds the locations SANY gives to the names, brackets and parentheses that the tla-ts syntax
9
+ // tree leaves out, and the comments SANY attaches to definitions.
10
10
  export interface SourceFile {
11
11
  name: string;
12
12
  source: string;
@@ -48,7 +48,6 @@ export const isToken = (file: SourceFile, index: number, text: string) =>
48
48
  file.tokens[index].text === text &&
49
49
  file.tokens[index].kind !== "String";
50
50
 
51
- // The number of tokens, in source order, before a position, or at or before it when isAtCounted.
52
51
  const countTokensBefore = (file: SourceFile, position: SourceLocation, isAtCounted: boolean) => {
53
52
  let low = 0;
54
53
  let high = file.tokens.length;
@@ -65,12 +64,10 @@ const countTokensBefore = (file: SourceFile, position: SourceLocation, isAtCount
65
64
  return low;
66
65
  };
67
66
 
68
- // The index of the first token at or after a position.
69
67
  export const getTokenIndex = (file: SourceFile, position: SourceLocation) =>
70
68
  file.tokenIndexes.get(getPositionKey(position.line, position.column)) ??
71
69
  Math.min(countTokensBefore(file, position, false), file.tokens.length - 1);
72
70
 
73
- // The index of the last token at or before a position.
74
71
  const getEndTokenIndex = (file: SourceFile, position: SourceLocation) =>
75
72
  Math.max(countTokensBefore(file, position, true) - 1, 0);
76
73
 
@@ -99,8 +96,8 @@ export const getRangeSpan = (file: SourceFile, range: SourceRange): TokenSpan =>
99
96
  end: getEndTokenIndex(file, range.end),
100
97
  });
101
98
 
102
- // The tokens of an expression. Some nodes, such as a tuple in a subscript, have no range, so their
103
- // span runs from their first token to the bracket that closes it.
99
+ // Some nodes, such as a tuple in a subscript, have no range, so their span runs from their first
100
+ // token to the bracket that closes it.
104
101
  export const getExpressionSpan = (file: SourceFile, expression: Expression): TokenSpan => {
105
102
  const range = expression.location.range;
106
103
  if (range) return getRangeSpan(file, range);
@@ -108,8 +105,7 @@ export const getExpressionSpan = (file: SourceFile, expression: Expression): Tok
108
105
  return { start, end: getMatchingIndex(file, start) };
109
106
  };
110
107
 
111
- // The span with the parentheses around it, as SANY locates a parenthesized operand by its
112
- // parentheses.
108
+ // SANY locates a parenthesized operand by its parentheses.
113
109
  export const getParenthesizedSpan = (file: SourceFile, span: TokenSpan): TokenSpan => {
114
110
  const start = span.start - 1;
115
111
  const end = span.end + 1;
@@ -123,8 +119,8 @@ export const getParenthesizedSpan = (file: SourceFile, span: TokenSpan): TokenSp
123
119
  return span;
124
120
  };
125
121
 
126
- // SANY's parser keeps the parentheses around an argument of an operator, which the span of the
127
- // argument's expression leaves out. Those of the operator's own arguments follow its name.
122
+ // SANY's parser keeps the parentheses around an operator's argument. Those of the operator's own
123
+ // arguments follow its name.
128
124
  export const getArgumentSpan = (file: SourceFile, span: TokenSpan): TokenSpan => {
129
125
  const start = span.start - 1;
130
126
  const end = span.end + 1;
@@ -157,7 +153,6 @@ const getOffset = (file: SourceFile, line: number, column: number) => {
157
153
  return offset;
158
154
  };
159
155
 
160
- // The token as the source spells it, where the token's text is the name of the operator.
161
156
  export const getTokenSource = (file: SourceFile, index: number) => {
162
157
  const token = file.tokens[index];
163
158
  const start = getOffset(file, token.line, token.column);
@@ -179,8 +174,7 @@ export const isBoxToken = (file: SourceFile, index: number) => {
179
174
  };
180
175
 
181
176
  // HACK: the tla-ts parser has no []ASSUME or []PROVE, so it parses the source with each such []
182
- // blanked out, which keeps every other token where it was. SANY's parser takes them only in an
183
- // ASSUME/PROVE, which unboxing hides.
177
+ // blanked out, which keeps every other token where it was.
184
178
  export const getUnboxedSource = (source: string) => {
185
179
  const file = createSourceFile("", source);
186
180
  const unboxed = file.tokens.reduce((text, token, index) => {
@@ -194,7 +188,6 @@ export const getUnboxedSource = (source: string) => {
194
188
  return unboxed;
195
189
  };
196
190
 
197
- // The comments between a token and the one before it, which SANY's parser attaches to the token.
198
191
  export const getPreComments = (file: SourceFile, index: number) => {
199
192
  const previous = file.tokens[index - 1];
200
193
  const token = file.tokens[index];
package/src/sany/xml.ts CHANGED
@@ -25,7 +25,6 @@ import {
25
25
  type UseOrHideNode,
26
26
  } from "./nodes";
27
27
 
28
- // XMLExporterExitCode, and the status Java exits with on an exception that nothing catches.
29
28
  export const XML_EXPORT_EXIT_CODE = {
30
29
  uncaughtException: 1,
31
30
  argsParsingFailure: 1,
@@ -40,7 +39,6 @@ interface XmlElement {
40
39
  children: XmlElement[];
41
40
  }
42
41
 
43
- // The exception that SANY's XMLExporter throws for a node of a kind it can't export.
44
42
  const getUnsupportedKind = (kind: number) =>
45
43
  `java.lang.IllegalArgumentException: unsupported kind: ${kind} in xml export`;
46
44
 
@@ -62,14 +60,13 @@ const XML_ENTITIES: Record<string, string> = {
62
60
  "\r": "&#13;",
63
61
  };
64
62
 
65
- // Java's serializer also writes a character outside the Basic Multilingual Plane, which a Java
66
- // string holds as two chars, as a character reference.
63
+ // Java's serializer writes a character outside the BMP, two chars in Java, as a character
64
+ // reference.
67
65
  const escapeXml = (text: string) =>
68
66
  text.replace(/[&<>\r]|[\u{10000}-\u{10FFFF}]/gu, (character) =>
69
67
  character.length === 2 ? `&#${character.codePointAt(0)};` : XML_ENTITIES[character],
70
68
  );
71
69
 
72
- // A character outside XML 1.0's Char production.
73
70
  const UNREPRESENTABLE_CHARACTER = /[^\t\n\r\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/u;
74
71
 
75
72
  interface UnrepresentableCharacter {
@@ -77,8 +74,6 @@ interface UnrepresentableCharacter {
77
74
  character: string;
78
75
  }
79
76
 
80
- // XMLExporter.findUnrepresentableCharacterData: the first element, in document order, whose
81
- // character data XML 1.0 cannot represent, with the character.
82
77
  const findUnrepresentable = (element: XmlElement): UnrepresentableCharacter | undefined => {
83
78
  const character = (element.cdata ?? element.text)?.match(UNREPRESENTABLE_CHARACTER)?.[0];
84
79
  if (character !== undefined) return { tag: element.tag, character };
@@ -89,7 +84,6 @@ const findUnrepresentable = (element: XmlElement): UnrepresentableCharacter | un
89
84
  return undefined;
90
85
  };
91
86
 
92
- // The lines of Java's identity Transformer, which pretty prints with an indent amount of 2.
93
87
  const printElement = (
94
88
  element: XmlElement,
95
89
  depth: number,
@@ -97,8 +91,6 @@ const printElement = (
97
91
  lines: string[],
98
92
  ): void => {
99
93
  const indent = " ".repeat(depth * indentAmount);
100
- // An element whose text or character data is empty has no content, like an element without
101
- // children.
102
94
  if (element.cdata) {
103
95
  const data = element.cdata.replaceAll("]]>", "]]]]><![CDATA[>");
104
96
  lines.push(`${indent}<${element.tag}><![CDATA[${data}]]></${element.tag}>`);
@@ -155,15 +147,11 @@ const getReferenceTag = (node: ContextNode) => {
155
147
  }
156
148
  };
157
149
 
158
- // A frame of the Java stack of TLC 1.7.4's XMLExporter, in package tla2sany, with the node that
159
- // the frame reports when an exception unwinds it.
160
150
  interface JavaFrame {
161
151
  at: string;
162
152
  failedFor?: string;
163
153
  }
164
154
 
165
- // A call by which TLC 1.7.4's XMLExporter exports an expression that may be the null SANY generates
166
- // for an operator it can't resolve, and how the JVM names that null.
167
155
  interface JavaExpressionCall extends JavaFrame {
168
156
  nullType: string;
169
157
  nullValue: string;
@@ -268,7 +256,6 @@ const JAVA_CALLS = {
268
256
  defStep: { at: "semantic.DefStepNode.getLevelElement(DefStepNode.java:99)" },
269
257
  } satisfies Record<string, JavaFrame | JavaExpressionCall>;
270
258
 
271
- // The calls by which TLC 1.7.4's XMLExporter exports the parts of a SubstInNode or APSubstInNode.
272
259
  const SUBST_IN_CALLS = {
273
260
  SubstIn: {
274
261
  subst: { at: "semantic.SubstInNode.getLevelElement(SubstInNode.java:530)" },
@@ -295,11 +282,8 @@ const SUBST_IN_CALLS = {
295
282
  const SEMANTIC_EXPORT = "semantic.SemanticNode.export(SemanticNode.java:379)";
296
283
  const LEVEL_EXPORT = "semantic.LevelNode.getSemanticElement(LevelNode.java:333)";
297
284
  const UNSUPPORTED_KIND_FRAME = { at: "semantic.OpDefNode.getSymbolElement(OpDefNode.java:1424)" };
298
- // Where SANY's builtin operators, such as nullODN, are.
299
285
  const IN_BUILTINS = formatSanyLocation("--TLA+ BUILTINS--");
300
286
 
301
- // The frames of the export of a node by reference in TLC 1.7.4's XMLExporter, down to the export
302
- // of its definition, which reports the node.
303
287
  const getDefinitionFrames = (kind: ContextNode["kind"], location: string): JavaFrame[] => {
304
288
  const [exportAt, putLine, definitionAt] =
305
289
  kind === "Theorem"
@@ -328,8 +312,8 @@ const getDefinitionFrames = (kind: ContextNode["kind"], location: string): JavaF
328
312
  ];
329
313
  };
330
314
 
331
- // java.util.HashMap, which holds SymbolContext's entries, and lists them by the bucket of their
332
- // Integer key, and the entries of a bucket in the order they were added.
315
+ // java.util.HashMap lists SymbolContext's entries by the bucket of their Integer key, and a
316
+ // bucket's entries in the order they were added.
333
317
  const getHashMapCapacity = (size: number, capacity = 16): number =>
334
318
  size > capacity * 0.75 ? getHashMapCapacity(size, capacity * 2) : capacity;
335
319
 
@@ -350,7 +334,6 @@ const TRAILING_WHITESPACE =
350
334
  // eslint-disable-next-line no-control-regex
351
335
  /[\t-\r\x1C-\x20\u1680\u2000-\u2006\u2008-\u200A\u2028\u2029\u205F\u3000]+$/;
352
336
 
353
- // SyntaxTreeNode.unboxComment: the lines of a comment boxed in (** and **), without the box.
354
337
  const unboxComment = (text: string) => {
355
338
  const start = text.indexOf("(**");
356
339
  const end = text.lastIndexOf("**)");
@@ -370,8 +353,7 @@ const unboxComment = (text: string) => {
370
353
  .join("\n");
371
354
  };
372
355
 
373
- // SyntaxTreeNode.unboxBackslashStarComment: the lines of a comment, without the \* that starts
374
- // them, when at least half of them start with one.
356
+ // SANY strips the \* only when at least half of the lines start with one.
375
357
  const unboxBackslashStarComment = (text: string) => {
376
358
  const lines = splitLines(text);
377
359
  const isCommentLine = (line: string) => trimJava(line).startsWith("\\*");
@@ -387,31 +369,24 @@ const unboxBackslashStarComment = (text: string) => {
387
369
 
388
370
  export interface XmlExportOptions {
389
371
  version: TlcVersion;
390
- // -r: only the root module, and only the declarations and definitions a module makes itself.
391
372
  isRestricted: boolean;
392
- // -u: the pre-comments without the boxes and \* that format them.
393
373
  isUncommented: boolean;
394
- // -t: the XML on one line.
395
374
  isTerse: boolean;
396
375
  }
397
376
 
398
- // The XML of SANY's XMLExporter: every module of the specification, and a context with an entry
399
- // for each symbol, theorem and assumption that the modules refer to.
400
377
  const exportSpecification = (
401
378
  modules: ModuleNode[],
402
379
  root: ModuleNode,
403
380
  options: XmlExportOptions,
404
381
  ) => {
405
- // TLC 1.7.4's XMLExporter writes fewer elements, which keeps their nodes out of the context.
406
382
  const isTlc174 = options.version === "1.7.4";
407
- // SymbolContext: SANY marks a node's UID as exported before it exports the node's definition,
408
- // which can export other definitions, and adds the definition to its entries after them.
383
+ // SANY marks a node's UID as exported before it exports the node's definition, which can export
384
+ // other definitions, and adds the definition to its entries after them.
409
385
  const keys = new Set<number>();
410
386
  const entries = new Map<number, XmlElement>();
411
387
  // SymbolContext's OTHER_BUG flag, which every copy of the context shares, so that from the first
412
388
  // CASE with an OTHER arm on, a node missing its first operand exports it as $Other.
413
389
  const otherBug = { isSet: false };
414
- // The Java stack of TLC 1.7.4's XMLExporter as it exports the current node, outermost first.
415
390
  const javaStack: JavaFrame[] = [];
416
391
 
417
392
  const withFrames = <Result>(frames: JavaFrame[], run: () => Result) => {
@@ -422,8 +397,8 @@ const exportSpecification = (
422
397
  return result;
423
398
  };
424
399
 
425
- // TLC 1.7.4's XMLExporter reports the exception at each node it unwinds before the JVM reports
426
- // it uncaught.
400
+ // TLC 1.7.4's XMLExporter reports the exception at each node it unwinds before the JVM reports it
401
+ // uncaught.
427
402
  const getJavaException = (exception: string, frames: JavaFrame[]) => {
428
403
  const trace = [...javaStack, ...frames].reverse();
429
404
  const stackTrace = [exception, ...trace.map((frame) => `\tat tla2sany.${frame.at}`)].join("\n");
@@ -640,10 +615,8 @@ const exportSpecification = (
640
615
  }
641
616
  };
642
617
 
643
- // The children of a ModuleNode element after its name, built in the order SANY builds them so
644
- // that the context entries they add appear in the same order.
618
+ // Built in SANY's order, so that the context entries they add appear in the same order.
645
619
  const exportModuleChildren = (module: ModuleNode): XmlElement[] => {
646
- // XMLExporter's filter for -r: a declaration or definition that the module makes itself.
647
620
  const isExported = (node: OpDeclNode | OpDefNode) =>
648
621
  !options.isRestricted || node.module === module;
649
622
  return [
@@ -689,7 +662,7 @@ const exportSpecification = (
689
662
 
690
663
  const exportApplication = (node: OpApplNode) => {
691
664
  // TLC 1.7.4's XMLExporter exports a specification with semantic errors, and fails on the
692
- // operator of the node that SANY puts where it found one.
665
+ // operator of the node SANY puts where it found one.
693
666
  if (node.isNull && isTlc174) {
694
667
  throw getJavaException(getUnsupportedKind(0), [
695
668
  JAVA_CALLS.operator,
@@ -748,7 +721,6 @@ const exportSpecification = (
748
721
  ? getReference(fact, call)
749
722
  : exportExpression(fact, call);
750
723
 
751
- // SemanticNode.export reports an exception that unwinds the export of a node.
752
724
  const exportExpression = (
753
725
  node: ExportedNode,
754
726
  call: JavaFrame | JavaExpressionCall,
@@ -987,9 +959,6 @@ const exportSpecification = (
987
959
 
988
960
  type ExportedNode = LevelNode | InstanceNode | UseOrHideNode | ProofPartNode;
989
961
 
990
- // The specification SANY accepts, level-checked, as SANY's tla2sany.xml.XMLExporter prints it
991
- // with -o and the given options: every module the root module depends on, the standard modules
992
- // among them, with the level of every expression.
993
962
  export const exportSanyXml = (
994
963
  specification: SanySpecification,
995
964
  options: XmlExportOptions = {