sensorium-trace 0.18.2__py3-none-any.whl

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 (135) hide show
  1. sensorium/__init__.py +0 -0
  2. sensorium/__main__.py +4 -0
  3. sensorium/_c/rt/sensorium_c_rt.c +1446 -0
  4. sensorium/_typescript/package-lock.json +68 -0
  5. sensorium/_typescript/package.json +39 -0
  6. sensorium/_typescript/src/bindings.mjs +792 -0
  7. sensorium/_typescript/src/cap.mjs +227 -0
  8. sensorium/_typescript/src/capabilities.mjs +40 -0
  9. sensorium/_typescript/src/dbg.mjs +348 -0
  10. sensorium/_typescript/src/escape.mjs +351 -0
  11. sensorium/_typescript/src/focus.mjs +135 -0
  12. sensorium/_typescript/src/hook.mjs +127 -0
  13. sensorium/_typescript/src/index.mjs +1 -0
  14. sensorium/_typescript/src/naming.mjs +63 -0
  15. sensorium/_typescript/src/positions.mjs +37 -0
  16. sensorium/_typescript/src/probe.mjs +246 -0
  17. sensorium/_typescript/src/qualname.mjs +236 -0
  18. sensorium/_typescript/src/redact.mjs +711 -0
  19. sensorium/_typescript/src/register.mjs +15 -0
  20. sensorium/_typescript/src/resolve.mjs +260 -0
  21. sensorium/_typescript/src/rt.mjs +798 -0
  22. sensorium/_typescript/src/setup.mjs +11 -0
  23. sensorium/_typescript/src/tally.mjs +164 -0
  24. sensorium/_typescript/src/tasks.mjs +175 -0
  25. sensorium/_typescript/src/transform.mjs +800 -0
  26. sensorium/_typescript/src/vite.mjs +99 -0
  27. sensorium/c/__init__.py +8 -0
  28. sensorium/c/cc.py +612 -0
  29. sensorium/c/cli.py +60 -0
  30. sensorium/c/convert.py +669 -0
  31. sensorium/c/decode.py +300 -0
  32. sensorium/c/driver.py +365 -0
  33. sensorium/c/dwarf.py +706 -0
  34. sensorium/c/format.py +271 -0
  35. sensorium/c/pkg.py +187 -0
  36. sensorium/c/plan.py +277 -0
  37. sensorium/cli.py +140 -0
  38. sensorium/driver.py +47 -0
  39. sensorium/exit.py +33 -0
  40. sensorium/invocations.py +83 -0
  41. sensorium/limits.py +253 -0
  42. sensorium/mcp/__init__.py +0 -0
  43. sensorium/mcp/audit.py +162 -0
  44. sensorium/mcp/child.py +240 -0
  45. sensorium/mcp/cmd.py +101 -0
  46. sensorium/mcp/jsonrpc.py +172 -0
  47. sensorium/mcp/result.py +187 -0
  48. sensorium/mcp/schema.py +390 -0
  49. sensorium/mcp/server.py +493 -0
  50. sensorium/mcp/tools.py +299 -0
  51. sensorium/paths.py +80 -0
  52. sensorium/query/__init__.py +0 -0
  53. sensorium/query/caps.py +150 -0
  54. sensorium/query/dbg_dialects.py +64 -0
  55. sensorium/query/diff_cmd.py +748 -0
  56. sensorium/query/diff_notes.py +117 -0
  57. sensorium/query/exceptions_c.py +263 -0
  58. sensorium/query/exceptions_cmd.py +788 -0
  59. sensorium/query/exceptions_group.py +571 -0
  60. sensorium/query/exceptions_invocation.py +487 -0
  61. sensorium/query/exceptions_rust.py +683 -0
  62. sensorium/query/exceptions_typescript.py +688 -0
  63. sensorium/query/expr.py +606 -0
  64. sensorium/query/failures_cmd.py +306 -0
  65. sensorium/query/flow_cmd.py +778 -0
  66. sensorium/query/flow_report.py +128 -0
  67. sensorium/query/flow_values.py +195 -0
  68. sensorium/query/fmt.py +280 -0
  69. sensorium/query/frame_cmd.py +237 -0
  70. sensorium/query/grep_cmd.py +156 -0
  71. sensorium/query/help.py +18 -0
  72. sensorium/query/info_cmd.py +527 -0
  73. sensorium/query/info_rust.py +214 -0
  74. sensorium/query/info_typescript.py +261 -0
  75. sensorium/query/js_inspect.py +394 -0
  76. sensorium/query/moves.py +254 -0
  77. sensorium/query/redact_cmd.py +304 -0
  78. sensorium/query/refocus_cmd.py +661 -0
  79. sensorium/query/refocus_env.py +493 -0
  80. sensorium/query/refocus_facts.py +269 -0
  81. sensorium/query/refocus_licence.py +187 -0
  82. sensorium/query/refocus_report.py +327 -0
  83. sensorium/query/refocus_rust.py +537 -0
  84. sensorium/query/refocus_threads.py +197 -0
  85. sensorium/query/refocus_typescript.py +756 -0
  86. sensorium/query/refocus_world.py +666 -0
  87. sensorium/query/runs_cmd.py +213 -0
  88. sensorium/query/rust_debug.py +176 -0
  89. sensorium/query/sites.py +171 -0
  90. sensorium/query/tree_cmd.py +511 -0
  91. sensorium/query/tree_threads.py +168 -0
  92. sensorium/query/vocab.py +723 -0
  93. sensorium/query/watch_cmd.py +657 -0
  94. sensorium/record/__init__.py +0 -0
  95. sensorium/record/boot.py +797 -0
  96. sensorium/record/boot_io.py +141 -0
  97. sensorium/record/budget.py +135 -0
  98. sensorium/record/capture.py +433 -0
  99. sensorium/record/children.py +755 -0
  100. sensorium/record/children_merge.py +179 -0
  101. sensorium/record/elide.py +55 -0
  102. sensorium/record/fingerprint.py +26 -0
  103. sensorium/record/thread_starts.py +261 -0
  104. sensorium/record/tracer.py +798 -0
  105. sensorium/record/tracer_exc.py +199 -0
  106. sensorium/record/tracer_frames.py +618 -0
  107. sensorium/redact.py +304 -0
  108. sensorium/redact_content.py +156 -0
  109. sensorium/redact_key.py +317 -0
  110. sensorium/redact_store.py +502 -0
  111. sensorium/redact_values.py +433 -0
  112. sensorium/store/__init__.py +0 -0
  113. sensorium/store/db.py +284 -0
  114. sensorium/store/gc.py +360 -0
  115. sensorium/store/payloads.py +69 -0
  116. sensorium/store/reader.py +438 -0
  117. sensorium/store/writer.py +283 -0
  118. sensorium/ts/__init__.py +10 -0
  119. sensorium/ts/build.py +783 -0
  120. sensorium/ts/cli.py +130 -0
  121. sensorium/ts/driver.py +472 -0
  122. sensorium/ts/focus.py +146 -0
  123. sensorium/ts/harness.py +314 -0
  124. sensorium/ts/ingest.py +380 -0
  125. sensorium/ts/invocation.py +252 -0
  126. sensorium/ts/pkg.py +167 -0
  127. sensorium/ts/redaction.py +64 -0
  128. sensorium/ts/spool.py +168 -0
  129. sensorium/ts/truncation.py +81 -0
  130. sensorium/ts/wrapper.py +255 -0
  131. sensorium_trace-0.18.2.dist-info/METADATA +245 -0
  132. sensorium_trace-0.18.2.dist-info/RECORD +135 -0
  133. sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
  134. sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
  135. sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,792 @@
1
+ // What a statement DID to the names around it, decided syntactically at
2
+ // transform time. `escape.mjs`'s sibling: pure functions over the consumer's
3
+ // own AST, no state, no I/O, and it lives in its own module because
4
+ // `transform.mjs` is at the repository's line ceiling (plan P2).
5
+ //
6
+ // Three questions (spec §3.2, §3.4):
7
+ // writesOf(ts, statement) the names the statement wrote → a row's deltas
8
+ // headBindingsOf(ts, statement) the names a guard binds → the head row
9
+ // declaredIn(ts, statement) the block-scoped names that died → `unbound`
10
+ // with `boundNames`, `headDeclaredOf`, `isGuard`, `isStatementPosition`,
11
+ // `paramNames` and `receiverName` the parts the three are built out of and
12
+ // the splices ask for by name.
13
+ //
14
+ // Nothing here resolves scopes, types or aliases: a name is its spelling. Two
15
+ // rules the whole tier rests on, both plan decisions:
16
+ // * P1 — a guarded statement's OWN row carries its head's assignment targets
17
+ // minus what the head DECLARED. `while ((m = …))` reports `m`'s last write
18
+ // (the one that ended the loop and entered no body); `for (let i …)` does
19
+ // not report `i`, which is dead by then and is `unbound` instead.
20
+ // * P4 — a nested function-like or class body is NEVER walked, and
21
+ // `declaredIn` lists a block's DIRECT declarations only. One row owns each
22
+ // name's write and each name's death; a nested statement has its own row.
23
+ /** @typedef {typeof import('typescript')} TS */
24
+ /** @typedef {import('typescript').Node} Node */
25
+ /** @typedef {import('typescript').Statement} Statement */
26
+ /** @typedef {import('typescript').BindingName} BindingName */
27
+ /** @typedef {import('typescript').VariableDeclarationList} VariableDeclarationList */
28
+ /** @typedef {import('typescript').FunctionLikeDeclaration} FunctionLike */
29
+
30
+ /**
31
+ * A node whose body is a new closure, plus a class body. The walk for
32
+ * assignment targets stops at one: what a callback assigns happens when the
33
+ * callback RUNS, which is not this statement's completion (plan P4). Under a
34
+ * focus the nested function is its own frame with its own rows, so nothing is
35
+ * lost — it is only attributed where it happened.
36
+ *
37
+ * `escape.mjs` keeps its own copy of this list for a different job (which
38
+ * mentions leave a `catch` binding's reach) and `transform.mjs` a third (which
39
+ * nodes become frames), so no file's answer moves another's.
40
+ * @param {TS} ts
41
+ * @param {Node} node
42
+ * @returns {boolean}
43
+ */
44
+ function opensBoundary(ts, node) {
45
+ return (
46
+ ts.isFunctionDeclaration(node) ||
47
+ ts.isFunctionExpression(node) ||
48
+ ts.isArrowFunction(node) ||
49
+ ts.isMethodDeclaration(node) ||
50
+ ts.isConstructorDeclaration(node) ||
51
+ ts.isGetAccessorDeclaration(node) ||
52
+ ts.isSetAccessorDeclaration(node) ||
53
+ ts.isClassDeclaration(node) ||
54
+ ts.isClassExpression(node)
55
+ );
56
+ }
57
+
58
+ /**
59
+ * Whether the token between the two halves of a `BinaryExpression` writes its
60
+ * left side: `=` and the fifteen compound forms. Enumerated rather than taken
61
+ * from a range, because the range is TypeScript's business and this list is the
62
+ * rule (`ts.isAssignmentExpression` is not in the published typings).
63
+ *
64
+ * `&&=`, `||=` and `??=` are here although they may not write: the row reports
65
+ * the binding's value after the statement either way, and the contract says so
66
+ * (spec §3.2).
67
+ * @param {TS} ts
68
+ * @param {import('typescript').SyntaxKind} kind
69
+ * @returns {boolean}
70
+ */
71
+ function isAssignmentToken(ts, kind) {
72
+ const k = ts.SyntaxKind;
73
+ switch (kind) {
74
+ case k.EqualsToken:
75
+ case k.PlusEqualsToken:
76
+ case k.MinusEqualsToken:
77
+ case k.AsteriskEqualsToken:
78
+ case k.SlashEqualsToken:
79
+ case k.PercentEqualsToken:
80
+ case k.AsteriskAsteriskEqualsToken:
81
+ case k.LessThanLessThanEqualsToken:
82
+ case k.GreaterThanGreaterThanEqualsToken:
83
+ case k.GreaterThanGreaterThanGreaterThanEqualsToken:
84
+ case k.AmpersandEqualsToken:
85
+ case k.BarEqualsToken:
86
+ case k.CaretEqualsToken:
87
+ case k.AmpersandAmpersandEqualsToken:
88
+ case k.BarBarEqualsToken:
89
+ case k.QuestionQuestionEqualsToken:
90
+ return true;
91
+ default:
92
+ return false;
93
+ }
94
+ }
95
+
96
+ /**
97
+ * @param {TS} ts
98
+ * @param {Node} node
99
+ * @returns {Node} the node inside however many parentheses
100
+ */
101
+ function unwrap(ts, node) {
102
+ let inner = node;
103
+ while (ts.isParenthesizedExpression(inner)) inner = inner.expression;
104
+ return inner;
105
+ }
106
+
107
+ /**
108
+ * Parentheses, and the type-only wrappers a place can wear (`as`, a type
109
+ * assertion, `!`, `satisfies`). Those wrappers are erased before the program
110
+ * runs, so the spelling that is re-read is the expression inside them.
111
+ * @param {TS} ts
112
+ * @param {Node} node
113
+ * @returns {Node}
114
+ */
115
+ function unwrapPlace(ts, node) {
116
+ let inner = unwrap(ts, node);
117
+ while (
118
+ ts.isParenthesizedExpression(inner) ||
119
+ ts.isAsExpression(inner) ||
120
+ ts.isTypeAssertionExpression(inner) ||
121
+ ts.isNonNullExpression(inner) ||
122
+ ts.isSatisfiesExpression(inner)
123
+ ) {
124
+ inner = unwrap(ts, inner.expression);
125
+ }
126
+ return inner;
127
+ }
128
+
129
+ /**
130
+ * @param {TS} ts
131
+ * @param {Node} node
132
+ * @returns {node is import('typescript').PropertyAccessExpression|import('typescript').ElementAccessExpression}
133
+ */
134
+ function isMemberAccess(ts, node) {
135
+ return ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node);
136
+ }
137
+
138
+ /**
139
+ * Whether re-reading `node` where the probe stands cannot call, assign,
140
+ * update, delete, await or yield. An index that fails this is not named:
141
+ * the probe re-reads the spelling, and a second `i++` would be a different
142
+ * program.
143
+ * @param {TS} ts
144
+ * @param {Node} node
145
+ * @returns {boolean}
146
+ */
147
+ function indexIsReevalSafe(ts, node) {
148
+ const inner = unwrapPlace(ts, node);
149
+ if (ts.isIdentifier(inner) || inner.kind === ts.SyntaxKind.ThisKeyword) return true;
150
+ if (
151
+ ts.isLiteralExpression(inner) ||
152
+ inner.kind === ts.SyntaxKind.NullKeyword ||
153
+ inner.kind === ts.SyntaxKind.TrueKeyword ||
154
+ inner.kind === ts.SyntaxKind.FalseKeyword
155
+ ) {
156
+ return true;
157
+ }
158
+ if (isMemberAccess(ts, inner)) return chainIsReevalSafe(ts, inner);
159
+ // `void` and `typeof` are their own nodes, not prefix unaries.
160
+ if (ts.isVoidExpression(inner) || ts.isTypeOfExpression(inner)) {
161
+ return indexIsReevalSafe(ts, inner.expression);
162
+ }
163
+ if (ts.isPrefixUnaryExpression(inner)) {
164
+ const op = inner.operator;
165
+ const k = ts.SyntaxKind;
166
+ if (
167
+ op === k.PlusToken || op === k.MinusToken || op === k.ExclamationToken ||
168
+ op === k.TildeToken
169
+ ) {
170
+ return indexIsReevalSafe(ts, inner.operand);
171
+ }
172
+ return false;
173
+ }
174
+ if (ts.isBinaryExpression(inner)) {
175
+ if (isAssignmentToken(ts, inner.operatorToken.kind)) return false;
176
+ return indexIsReevalSafe(ts, inner.left) && indexIsReevalSafe(ts, inner.right);
177
+ }
178
+ if (ts.isConditionalExpression(inner)) {
179
+ return indexIsReevalSafe(ts, inner.condition) &&
180
+ indexIsReevalSafe(ts, inner.whenTrue) &&
181
+ indexIsReevalSafe(ts, inner.whenFalse);
182
+ }
183
+ return false;
184
+ }
185
+
186
+ /**
187
+ * A property or element chain whose ultimate base is an identifier or `this`,
188
+ * with no optional `?.` anywhere on it. A call, `new`, `super` or `import.meta`
189
+ * base is not one: re-reading `f().b` would call `f` again.
190
+ * @param {TS} ts
191
+ * @param {Node} node a property or element access
192
+ * @returns {boolean}
193
+ */
194
+ function chainIsReevalSafe(ts, node) {
195
+ let current = node;
196
+ while (isMemberAccess(ts, current)) {
197
+ if (current.questionDotToken) return false;
198
+ if (ts.isElementAccessExpression(current)) {
199
+ const arg = current.argumentExpression;
200
+ if (!arg || !indexIsReevalSafe(ts, arg)) return false;
201
+ }
202
+ current = unwrapPlace(ts, current.expression);
203
+ }
204
+ return ts.isIdentifier(current) || current.kind === ts.SyntaxKind.ThisKeyword;
205
+ }
206
+
207
+ /**
208
+ * @param {TS} ts
209
+ * @param {Node} node
210
+ * @returns {boolean}
211
+ */
212
+ function containsTypeSyntax(ts, node) {
213
+ if (
214
+ ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) ||
215
+ ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node)
216
+ ) {
217
+ return true;
218
+ }
219
+ let found = false;
220
+ ts.forEachChild(node, (child) => {
221
+ if (!found && containsTypeSyntax(ts, child)) found = true;
222
+ });
223
+ return found;
224
+ }
225
+
226
+ /**
227
+ * The index as JavaScript the probe can re-read. A line terminator stays a
228
+ * refusal: collapsing one would change a template literal, and the splice
229
+ * must not insert one. Type syntax left inside the index is the same
230
+ * refusal rather than a guess at the erased spelling.
231
+ * @param {TS} ts
232
+ * @param {Node} node
233
+ * @returns {string|null}
234
+ */
235
+ function spellIndex(ts, node) {
236
+ const inner = unwrapPlace(ts, node);
237
+ if (isMemberAccess(ts, inner)) return spellChain(ts, inner);
238
+ if (ts.isIdentifier(inner)) return inner.text;
239
+ if (inner.kind === ts.SyntaxKind.ThisKeyword) return 'this';
240
+ if (containsTypeSyntax(ts, inner)) return null;
241
+ const text = inner.getText();
242
+ if (text.length === 0 || /[\n\r\u2028\u2029]/.test(text)) return null;
243
+ return text;
244
+ }
245
+
246
+ /**
247
+ * `a.b`, `a[i]`, `this.x`, with type-only wrappers on the base dropped.
248
+ * ` (obj as any).x ` is re-read as `obj.x`: the `as` is gone before the
249
+ * program runs, and inserting it would put type syntax into the splice.
250
+ * @param {TS} ts
251
+ * @param {Node} node a property or element access
252
+ * @returns {string|null}
253
+ */
254
+ function spellChain(ts, node) {
255
+ /** @type {string[]} */
256
+ const parts = [];
257
+ let current = unwrapPlace(ts, node);
258
+ while (isMemberAccess(ts, current)) {
259
+ if (ts.isPropertyAccessExpression(current)) {
260
+ parts.push(`.${current.name.text}`);
261
+ } else {
262
+ const arg = current.argumentExpression;
263
+ if (!arg) return null;
264
+ const index = spellIndex(ts, arg);
265
+ if (index === null) return null;
266
+ parts.push(`[${index}]`);
267
+ }
268
+ current = unwrapPlace(ts, current.expression);
269
+ }
270
+ const base = ts.isIdentifier(current)
271
+ ? current.text
272
+ : current.kind === ts.SyntaxKind.ThisKeyword
273
+ ? 'this'
274
+ : null;
275
+ if (base === null) return null;
276
+ parts.reverse();
277
+ return base + parts.join('');
278
+ }
279
+
280
+ /**
281
+ * The source spelling of a member write the probe can re-read after the
282
+ * statement, or null when re-reading would lie or move a line. A spelling
283
+ * that contains a line terminator is null: the splice must not insert one.
284
+ * @param {TS} ts
285
+ * @param {Node} node
286
+ * @returns {string|null}
287
+ */
288
+ function placeText(ts, node) {
289
+ const inner = unwrapPlace(ts, node);
290
+ if (!isMemberAccess(ts, inner) || !chainIsReevalSafe(ts, inner)) return null;
291
+ return spellChain(ts, inner);
292
+ }
293
+
294
+ /**
295
+ * The names an assignment TARGET binds: the left of an `=`, a `for…of` head's
296
+ * existing binding, an element of either.
297
+ *
298
+ * A property or element access contributes its own spelling (`a.b`, `a[i]`,
299
+ * `this.x`, `a.b.c`) and not the base. Calling `a.b = 1` a write of `a` would
300
+ * be a lie. An optional chain, a call base, `super`, or an index that is not
301
+ * safe to re-read contributes nothing. Everything else is a destructuring
302
+ * shape, and its identifiers are read out of it.
303
+ * @param {TS} ts
304
+ * @param {Node} target
305
+ * @returns {string[]} in source order, duplicates kept for the caller to fold
306
+ */
307
+ function targetNames(ts, target) {
308
+ /** @type {string[]} */
309
+ const out = [];
310
+ /** @param {Node} node */
311
+ const visit = (node) => {
312
+ const inner = unwrap(ts, node);
313
+ if (ts.isIdentifier(inner)) {
314
+ out.push(inner.text);
315
+ return;
316
+ }
317
+ const place = placeText(ts, inner);
318
+ if (place !== null) {
319
+ out.push(place);
320
+ return;
321
+ }
322
+ if (ts.isArrayLiteralExpression(inner)) {
323
+ for (const element of inner.elements) visit(element);
324
+ return;
325
+ }
326
+ if (ts.isObjectLiteralExpression(inner)) {
327
+ for (const property of inner.properties) {
328
+ if (ts.isPropertyAssignment(property)) visit(property.initializer);
329
+ else if (ts.isShorthandPropertyAssignment(property)) out.push(property.name.text);
330
+ else if (ts.isSpreadAssignment(property)) visit(property.expression);
331
+ }
332
+ return;
333
+ }
334
+ if (ts.isSpreadElement(inner)) {
335
+ visit(inner.expression);
336
+ return;
337
+ }
338
+ // `[a = 1] = xs` and `({b: c = 1} = o)`: the default's LEFT is the target.
339
+ if (ts.isBinaryExpression(inner) && inner.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
340
+ visit(inner.left);
341
+ }
342
+ };
343
+ visit(target);
344
+ return out;
345
+ }
346
+
347
+ /**
348
+ * The parts of a class that execute WHERE THE CLASS STANDS, and so belong to
349
+ * the statement's own row: the heritage expressions (`class extends (B = f())`)
350
+ * and every computed member name (`class { [(k = 1)]() {} }`). Both are
351
+ * evaluated when the class definition is, unlike a member body or a field
352
+ * initialiser — which run at call and at construction, and are the boundary
353
+ * `opensBoundary` keeps (fix round 1, controller decision).
354
+ *
355
+ * A `static {}` block also runs at definition time and is NOT walked: it is a
356
+ * member body, and the controller's list names heritage and computed names
357
+ * only. A declared gap, not an oversight.
358
+ * @param {TS} ts
359
+ * @param {import('typescript').ClassLikeDeclaration} node
360
+ * @param {string[]} out
361
+ * @returns {void}
362
+ */
363
+ function collectClassHead(ts, node, out) {
364
+ for (const clause of node.heritageClauses ?? []) {
365
+ for (const type of clause.types) collectTargets(ts, type.expression, out);
366
+ }
367
+ for (const member of node.members) {
368
+ const { name } = member;
369
+ if (name && ts.isComputedPropertyName(name)) collectTargets(ts, name.expression, out);
370
+ }
371
+ }
372
+
373
+ /**
374
+ * Every name assigned or updated anywhere under `node`, at any depth of the
375
+ * statement's OWN expressions — a nested function or class body is not this
376
+ * statement's (plan P4).
377
+ * @param {TS} ts
378
+ * @param {Node} node
379
+ * @param {string[]} out appended to in source order
380
+ * @returns {void}
381
+ */
382
+ function collectTargets(ts, node, out) {
383
+ if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
384
+ collectClassHead(ts, node, out);
385
+ return;
386
+ }
387
+ if (opensBoundary(ts, node)) return;
388
+ if (ts.isBinaryExpression(node) && isAssignmentToken(ts, node.operatorToken.kind)) {
389
+ out.push(...targetNames(ts, node.left));
390
+ } else if (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) {
391
+ const updates =
392
+ node.operator === ts.SyntaxKind.PlusPlusToken ||
393
+ node.operator === ts.SyntaxKind.MinusMinusToken;
394
+ // `++a.b` and `a.b++` name the member; `++x` still names `x`. An unsafe
395
+ // member (`++f().b`) names nothing, the same rule as an assignment.
396
+ if (updates) out.push(...targetNames(ts, node.operand));
397
+ } else if (ts.isDeleteExpression(node)) {
398
+ // After `delete a.b` the probe re-reads `a.b` and gets `undefined`. That
399
+ // is the value the name holds, not a guess at what `delete` returned.
400
+ const place = placeText(ts, node.expression);
401
+ if (place !== null) out.push(place);
402
+ }
403
+ // Both halves are still walked: `arr[i++] = 0` writes no name the target
404
+ // names, and `i` all the same.
405
+ ts.forEachChild(node, (child) => collectTargets(ts, child, out));
406
+ }
407
+
408
+ /**
409
+ * @param {string[]} names
410
+ * @returns {string[]} the same order, each name once
411
+ */
412
+ function unique(names) {
413
+ return [...new Set(names)];
414
+ }
415
+
416
+ /**
417
+ * @param {TS} ts
418
+ * @param {Node} node
419
+ * @param {string[]} [into]
420
+ * @returns {string[]} every name assigned under the node, once each
421
+ */
422
+ function targetsIn(ts, node, into = []) {
423
+ collectTargets(ts, node, into);
424
+ return unique(into);
425
+ }
426
+
427
+ /**
428
+ * Every identifier a binding name binds: a plain name, a nested object or array
429
+ * pattern, a default's binding (not the default's own expression), a rest
430
+ * element. A `_`-prefixed name is one of them — nothing here judges a spelling.
431
+ * @param {TS} ts
432
+ * @param {BindingName} name
433
+ * @returns {string[]} in source order
434
+ */
435
+ export function boundNames(ts, name) {
436
+ /** @type {string[]} */
437
+ const out = [];
438
+ /** @param {BindingName} node */
439
+ const visit = (node) => {
440
+ if (ts.isIdentifier(node)) {
441
+ out.push(node.text);
442
+ return;
443
+ }
444
+ for (const element of node.elements) {
445
+ if (ts.isBindingElement(element)) visit(element.name);
446
+ }
447
+ };
448
+ visit(name);
449
+ return out;
450
+ }
451
+
452
+ /**
453
+ * Not deduplicated, unlike `targetsIn`'s callers, and deliberately: the only
454
+ * way one spelling reaches this twice is a list that DECLARES it twice
455
+ * (`let a = 1, a = 2`), which `tsc` refuses — so a duplicate here would be a
456
+ * program that does not compile, and dropping one would hide it rather than
457
+ * report it. The head-declaration branches that call this are the same.
458
+ * @param {TS} ts
459
+ * @param {VariableDeclarationList} list
460
+ * @returns {string[]} every name the list declares
461
+ */
462
+ function listNames(ts, list) {
463
+ return list.declarations.flatMap((declaration) => boundNames(ts, declaration.name));
464
+ }
465
+
466
+ /**
467
+ * Whether a declaration list dies with its block — the four spellings that
468
+ * bind block-scoped: `let`, `const`, `using` and `await using`. `var` is the
469
+ * one that does not (spec §3.4: function-scoped, never `unbound`).
470
+ *
471
+ * `using` is here by ruling R18 (fix round 1): it is block-scoped in the
472
+ * language, so a fold that kept it alive past its block would report a name the
473
+ * program had already disposed. `AwaitUsing` is named although this
474
+ * TypeScript's enum happens to spell it `Using | Const` (6) — the rule is the
475
+ * four spellings, not an arithmetic accident of one version's flags.
476
+ * @param {TS} ts
477
+ * @param {VariableDeclarationList} list
478
+ * @returns {boolean}
479
+ */
480
+ function isBlockScoped(ts, list) {
481
+ const scoped =
482
+ ts.NodeFlags.Let | ts.NodeFlags.Const | ts.NodeFlags.Using | ts.NodeFlags.AwaitUsing;
483
+ return (list.flags & scoped) !== 0;
484
+ }
485
+
486
+ /**
487
+ * The six statements that guard a body: the ones this recorder wraps, and the
488
+ * ones whose head can bind on entry.
489
+ *
490
+ * The ONE list. `isStatementPosition` reads it to decide whether a node stands
491
+ * in such a guard's body slot, and `probe.mjs` reads it to decide what to
492
+ * splice and (through `isStatementPosition`) which block body is a guard's
493
+ * own. It lived in `probe.mjs` as a second copy until 2026-09-12.
494
+ *
495
+ * A `LabeledStatement` is NOT one (R15): wrapping a labeled loop in a block
496
+ * turns `continue label` into a syntax error, and a labeled body that is
497
+ * itself a guard is spliced as that guard when the visitor reaches it. It
498
+ * holds its body in the same `statement` slot all the same, which is why
499
+ * `isStatementPosition` names it beside these and this predicate does not.
500
+ * @param {TS} ts
501
+ * @param {Node} node
502
+ * @returns {boolean}
503
+ */
504
+ export function isGuard(ts, node) {
505
+ return (
506
+ ts.isIfStatement(node) ||
507
+ ts.isForStatement(node) ||
508
+ ts.isForInStatement(node) ||
509
+ ts.isForOfStatement(node) ||
510
+ ts.isWhileStatement(node) ||
511
+ ts.isDoStatement(node)
512
+ );
513
+ }
514
+
515
+ /**
516
+ * Whether a node stands where a statement of a focused body stands, and so gets
517
+ * a row of its own: a statement of a block, of a `case` or `default` clause, or
518
+ * the single body of a guard written without braces (which Task 4 wraps).
519
+ *
520
+ * This is the one place the PARENT RELATION is written down -- which slot of
521
+ * which parent is a statement's own. `probe.mjs`'s `isGuardBody` derives from
522
+ * it rather than restating it.
523
+ *
524
+ * Module level is not one: module code is never a frame (spec §3.9).
525
+ * @param {TS} ts
526
+ * @param {Node} node
527
+ * @returns {boolean}
528
+ */
529
+ export function isStatementPosition(ts, node) {
530
+ const parent = node.parent;
531
+ if (!parent || !ts.isStatement(node)) return false;
532
+ if (ts.isBlock(parent) || ts.isCaseClause(parent) || ts.isDefaultClause(parent)) return true;
533
+ // An `if` holds its two bodies in named slots; every other guard, and a
534
+ // label, holds its one in `statement`.
535
+ if (ts.isIfStatement(parent)) {
536
+ return parent.thenStatement === node || parent.elseStatement === node;
537
+ }
538
+ if (isGuard(ts, parent) || ts.isLabeledStatement(parent)) {
539
+ return /** @type {{statement?: Node}} */ (parent).statement === node;
540
+ }
541
+ return false;
542
+ }
543
+
544
+ /**
545
+ * The names a statement WROTE when it completed — the `deltas` of its row.
546
+ *
547
+ * A guarded statement's own row carries its head's writes minus the head's
548
+ * declarations (plan P1): the declarations are dead and are `unbound` instead,
549
+ * and what is left is the write no head row ever reported, because the
550
+ * evaluation that made it entered no body (`m = null` ends the `while`; a falsy
551
+ * `if ((x = f()))` runs no branch).
552
+ * @param {TS} ts
553
+ * @param {Node} statement a node in statement position
554
+ * @returns {string[]} in source order, each name once
555
+ */
556
+ export function writesOf(ts, statement) {
557
+ /** @type {string[]} */
558
+ const out = [];
559
+ if (ts.isVariableStatement(statement)) {
560
+ for (const declaration of statement.declarationList.declarations) {
561
+ out.push(...boundNames(ts, declaration.name));
562
+ if (declaration.initializer) collectTargets(ts, declaration.initializer, out);
563
+ }
564
+ } else if (ts.isExpressionStatement(statement)) {
565
+ collectTargets(ts, statement.expression, out);
566
+ } else if (ts.isClassDeclaration(statement)) {
567
+ // It executes where it stands (spec §3.1). An anonymous `export default
568
+ // class` binds no local name and writes nothing. Its HEAD executes there
569
+ // too, so the same rule `collectTargets` applies to a class expression
570
+ // applies to the declaration form (fix round 1).
571
+ if (statement.name) out.push(statement.name.text);
572
+ collectClassHead(ts, statement, out);
573
+ } else if (
574
+ ts.isIfStatement(statement) ||
575
+ ts.isWhileStatement(statement) ||
576
+ ts.isDoStatement(statement) ||
577
+ ts.isSwitchStatement(statement)
578
+ ) {
579
+ collectTargets(ts, statement.expression, out);
580
+ } else if (ts.isForStatement(statement)) {
581
+ const { initializer, condition, incrementor } = statement;
582
+ if (initializer && !ts.isVariableDeclarationList(initializer)) {
583
+ collectTargets(ts, initializer, out);
584
+ }
585
+ if (condition) collectTargets(ts, condition, out);
586
+ if (incrementor) collectTargets(ts, incrementor, out);
587
+ } else if (ts.isForInStatement(statement) || ts.isForOfStatement(statement)) {
588
+ // The head's own binding is not read here: its last value IS the last head
589
+ // row's, because the assignment that ends the loop is the iterator's, not
590
+ // the head's. `xs` in `for (const v of (xs = list()))` is read.
591
+ const { initializer } = statement;
592
+ if (!ts.isVariableDeclarationList(initializer)) collectTargets(ts, initializer, out);
593
+ collectTargets(ts, statement.expression, out);
594
+ }
595
+ const declared = headDeclaredOf(ts, statement);
596
+ return unique(out).filter((name) => !declared.includes(name));
597
+ }
598
+
599
+ /**
600
+ * The names a guard BINDS OR ASSIGNS as it enters its body — the synthetic
601
+ * first row inside the body, once per entry or iteration (spec §3.2).
602
+ *
603
+ * A `switch` discriminant is not one: its assignment mints nothing, declared
604
+ * (§3.9). A `for…of` head over an existing binding IS one — the head assigns to
605
+ * it each iteration, which is what the loop is for.
606
+ * @param {TS} ts
607
+ * @param {Node} statement a guard, or a `CatchClause`
608
+ * @returns {string[]} in source order, each name once
609
+ */
610
+ export function headBindingsOf(ts, statement) {
611
+ if (ts.isForOfStatement(statement) || ts.isForInStatement(statement)) {
612
+ const { initializer } = statement;
613
+ return ts.isVariableDeclarationList(initializer)
614
+ ? listNames(ts, initializer)
615
+ : unique(targetNames(ts, initializer));
616
+ }
617
+ if (ts.isForStatement(statement)) {
618
+ const { initializer } = statement;
619
+ if (!initializer) return [];
620
+ // A C-style head is an ordinary expression evaluated once, so its
621
+ // ASSIGNMENTS are the bindings — unlike a `for…of` head, which IS a target.
622
+ return ts.isVariableDeclarationList(initializer)
623
+ ? listNames(ts, initializer)
624
+ : targetsIn(ts, initializer);
625
+ }
626
+ if (ts.isWhileStatement(statement) || ts.isDoStatement(statement) ||
627
+ ts.isIfStatement(statement)) {
628
+ return targetsIn(ts, statement.expression);
629
+ }
630
+ if (ts.isCatchClause(statement)) {
631
+ const declaration = statement.variableDeclaration;
632
+ return declaration ? boundNames(ts, declaration.name) : [];
633
+ }
634
+ return [];
635
+ }
636
+
637
+ /**
638
+ * The subset of `headBindingsOf` that DECLARES its names, and so kills them
639
+ * when the guard completes: a `let`/`const` in a loop head, a `catch` binding.
640
+ * A `var` head declares a name that outlives the loop, so it is not one — its
641
+ * final value is the guard's row's delta instead (`writesOf`).
642
+ * @param {TS} ts
643
+ * @param {Node} statement a guard, or a `CatchClause`
644
+ * @returns {string[]}
645
+ */
646
+ export function headDeclaredOf(ts, statement) {
647
+ if (ts.isCatchClause(statement)) return headBindingsOf(ts, statement);
648
+ if (
649
+ ts.isForStatement(statement) ||
650
+ ts.isForInStatement(statement) ||
651
+ ts.isForOfStatement(statement)
652
+ ) {
653
+ const { initializer } = statement;
654
+ if (initializer && ts.isVariableDeclarationList(initializer) &&
655
+ isBlockScoped(ts, initializer)) {
656
+ return listNames(ts, initializer);
657
+ }
658
+ }
659
+ return [];
660
+ }
661
+
662
+ /**
663
+ * The block-scoped names a list of statements declares DIRECTLY — not those of
664
+ * a block-like statement among them, which owns its own row and its own deaths
665
+ * (plan P4). A `FunctionDeclaration` is one of them: an ES module is strict, so
666
+ * its binding is the block's.
667
+ * @param {TS} ts
668
+ * @param {readonly Statement[]} statements
669
+ * @param {string[]} out
670
+ * @returns {void}
671
+ */
672
+ function collectDeclared(ts, statements, out) {
673
+ for (const statement of statements) {
674
+ if (ts.isVariableStatement(statement)) {
675
+ if (isBlockScoped(ts, statement.declarationList)) {
676
+ out.push(...listNames(ts, statement.declarationList));
677
+ }
678
+ } else if (ts.isClassDeclaration(statement) || ts.isFunctionDeclaration(statement)) {
679
+ if (statement.name) out.push(statement.name.text);
680
+ }
681
+ }
682
+ }
683
+
684
+ /**
685
+ * @param {TS} ts
686
+ * @param {Node|undefined} body
687
+ * @param {string[]} out
688
+ * @returns {void}
689
+ */
690
+ function collectBlock(ts, body, out) {
691
+ if (body && ts.isBlock(body)) collectDeclared(ts, body.statements, out);
692
+ }
693
+
694
+ /**
695
+ * The block-scoped names that DIE when this statement completes — its row's
696
+ * `unbound` (spec §3.4). Its own direct blocks' declarations, plus whatever its
697
+ * head declared.
698
+ *
699
+ * A statement that is not block-like declares nothing at its own completion:
700
+ * `const y = 1;` writes `y`, and `y` dies with the block that HOLDS it, on that
701
+ * block's row.
702
+ * @param {TS} ts
703
+ * @param {Node} statement a node in statement position
704
+ * @returns {string[]} in source order, each name once
705
+ */
706
+ export function declaredIn(ts, statement) {
707
+ // A label is not a scope: the statement it labels is the one that declares.
708
+ if (ts.isLabeledStatement(statement)) return declaredIn(ts, statement.statement);
709
+ /** @type {string[]} */
710
+ const out = [];
711
+ if (ts.isBlock(statement)) {
712
+ collectDeclared(ts, statement.statements, out);
713
+ } else if (ts.isIfStatement(statement)) {
714
+ collectBlock(ts, statement.thenStatement, out);
715
+ collectBlock(ts, statement.elseStatement, out);
716
+ } else if (
717
+ ts.isForStatement(statement) ||
718
+ ts.isForInStatement(statement) ||
719
+ ts.isForOfStatement(statement) ||
720
+ ts.isWhileStatement(statement) ||
721
+ ts.isDoStatement(statement)
722
+ ) {
723
+ collectBlock(ts, statement.statement, out);
724
+ } else if (ts.isTryStatement(statement)) {
725
+ collectBlock(ts, statement.tryBlock, out);
726
+ if (statement.catchClause) {
727
+ out.push(...headDeclaredOf(ts, statement.catchClause));
728
+ collectBlock(ts, statement.catchClause.block, out);
729
+ }
730
+ collectBlock(ts, statement.finallyBlock, out);
731
+ } else if (ts.isSwitchStatement(statement)) {
732
+ for (const clause of statement.caseBlock.clauses) {
733
+ collectDeclared(ts, clause.statements, out);
734
+ }
735
+ }
736
+ out.push(...headDeclaredOf(ts, statement));
737
+ return unique(out);
738
+ }
739
+
740
+ /**
741
+ * Every name a function's parameters bind, in order. What a CALL carries as
742
+ * its `args` (spec §3.3). A TypeScript `this` parameter is a type and is not
743
+ * read here; the runtime receiver, when a focused method has one, is
744
+ * `receiverName`.
745
+ * @param {TS} ts
746
+ * @param {FunctionLike} fn
747
+ * @returns {string[]}
748
+ */
749
+ export function paramNames(ts, fn) {
750
+ /** @type {string[]} */
751
+ const out = [];
752
+ for (const parameter of fn.parameters) {
753
+ if (ts.isIdentifier(parameter.name) && parameter.name.text === 'this') continue;
754
+ out.push(...boundNames(ts, parameter.name));
755
+ }
756
+ return out;
757
+ }
758
+
759
+ /**
760
+ * The receiver a focused CALL may name `this`, or null.
761
+ *
762
+ * A method, getter, setter or non-derived constructor has a receiver at body
763
+ * entry. An arrow keeps the lexical `this` and is not given a fake parameter.
764
+ * A function declaration or expression is not a method. A derived
765
+ * constructor's body starts before `super()`, where reading `this` throws, so
766
+ * it is not named: the splice stands at the first token of the body.
767
+ * @param {TS} ts
768
+ * @param {FunctionLike} fn
769
+ * @returns {string|null}
770
+ */
771
+ export function receiverName(ts, fn) {
772
+ if (
773
+ ts.isArrowFunction(fn) ||
774
+ ts.isFunctionDeclaration(fn) ||
775
+ ts.isFunctionExpression(fn)
776
+ ) {
777
+ return null;
778
+ }
779
+ const isMethod =
780
+ ts.isMethodDeclaration(fn) ||
781
+ ts.isGetAccessorDeclaration(fn) ||
782
+ ts.isSetAccessorDeclaration(fn) ||
783
+ ts.isConstructorDeclaration(fn);
784
+ if (!isMethod) return null;
785
+ if (ts.isConstructorDeclaration(fn)) {
786
+ const cls = fn.parent;
787
+ const derived = !!cls && (ts.isClassDeclaration(cls) || ts.isClassExpression(cls)) &&
788
+ (cls.heritageClauses ?? []).some((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword);
789
+ if (derived) return null;
790
+ }
791
+ return 'this';
792
+ }