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,351 @@
1
+ // The escape rule: what a `catch` binding's own body DID with the value, decided
2
+ // syntactically at transform time and written on the record as a `how` word. It
3
+ // is Rust's `escape.rs` transferred (rung 3's R2) with JavaScript's logging
4
+ // family in place of the macro list, and it lives in its own module because
5
+ // `transform.mjs` is at the repository's line ceiling (plan P2).
6
+ //
7
+ // Four questions, four exports, no state:
8
+ // catchHow(ts, clause) a `catch (e) { … }` clause (spec §2.1)
9
+ // callbackHow(ts, arg) the argument of `.catch(…)`/`.then(x, …)` (§2.2)
10
+ // finallyCompletes(ts, block) a `finally` block that discards (§2.3)
11
+ // deferredExit(ts, fn) a function that returns THROUGH a finally
12
+ // (2026-09-12 §4.2, the seal)
13
+ //
14
+ // Nothing here resolves scopes, types or aliases: an identifier that SPELLS the
15
+ // binding's name is a mention of it, shadowed or not. The rule errs towards
16
+ // `escaped` — the word that says "this recorder does not claim a swallow" — so
17
+ // an unresolved shadow costs a report, never a false accusation. ONE place errs
18
+ // the other way, deliberately and declared: `isLogged` climbs THROUGH
19
+ // intermediate calls inside a `console` argument, so `console.log(sanitize(e))`
20
+ // reads `catch` and a helper that STORES `e` and returns text is read as a
21
+ // swallow (spec §14 R6, `../HONESTY-BLIND-SPOTS.md` item 20).
22
+ /** @typedef {typeof import('typescript')} TS */
23
+ /** @typedef {import('typescript').Node} Node */
24
+ /** @typedef {import('typescript').CatchClause} CatchClause */
25
+ /** @typedef {import('typescript').Block} Block */
26
+ /** @typedef {import('typescript').Expression} Expression */
27
+ /** @typedef {import('typescript').FunctionLikeDeclaration} FunctionLike */
28
+
29
+ /**
30
+ * The console members a mention may be an argument of and still count as
31
+ * swallowed. Log-and-continue is the archetypal swallow: the failure never
32
+ * reached the caller, and the log is where it went. `console.table` and friends
33
+ * are NOT here — the rule names its family rather than matching `console.*`.
34
+ */
35
+ export const LOGGING = new Set(['log', 'error', 'warn', 'info', 'debug', 'trace']);
36
+
37
+ /**
38
+ * A node whose body is a new closure. The walk up from a mention stops at one:
39
+ * a closure KEEPS the binding, so what it does with it is not this clause's
40
+ * verdict to make (§2.1, "a mention inside a nested function body escapes").
41
+ * Classes are here for the same reason a function is — a method body is a
42
+ * closure — and `transform.mjs` keeps its own predicate for a different job
43
+ * (which nodes become frames), so neither file's answer moves the other's.
44
+ * @param {TS} ts
45
+ * @param {Node} node
46
+ * @returns {boolean}
47
+ */
48
+ function opensClosure(ts, node) {
49
+ return (
50
+ ts.isFunctionDeclaration(node) ||
51
+ ts.isFunctionExpression(node) ||
52
+ ts.isArrowFunction(node) ||
53
+ ts.isMethodDeclaration(node) ||
54
+ ts.isConstructorDeclaration(node) ||
55
+ ts.isGetAccessorDeclaration(node) ||
56
+ ts.isSetAccessorDeclaration(node) ||
57
+ ts.isClassDeclaration(node) ||
58
+ ts.isClassExpression(node)
59
+ );
60
+ }
61
+
62
+ /**
63
+ * Whether an identifier spelled like the binding is a READ of it. Two spellings
64
+ * name something else entirely: the property in `other.e`, and the key in
65
+ * `{ e: 1 }`. A shorthand `{ e }` is a read — it is the value, not a key.
66
+ * @param {TS} ts
67
+ * @param {import('typescript').Identifier} node
68
+ * @returns {boolean}
69
+ */
70
+ function isRead(ts, node) {
71
+ const parent = node.parent;
72
+ if (!parent) return true;
73
+ if (ts.isPropertyAccessExpression(parent) && parent.name === node) return false;
74
+ if (ts.isPropertyAssignment(parent) && parent.name === node) return false;
75
+ return true;
76
+ }
77
+
78
+ /**
79
+ * `console.log`, `console.error`, … — the callee of a logging call.
80
+ * @param {TS} ts
81
+ * @param {Expression} callee
82
+ * @returns {boolean}
83
+ */
84
+ function isLoggingCallee(ts, callee) {
85
+ return (
86
+ ts.isPropertyAccessExpression(callee) &&
87
+ ts.isIdentifier(callee.expression) &&
88
+ callee.expression.text === 'console' &&
89
+ LOGGING.has(callee.name.text)
90
+ );
91
+ }
92
+
93
+ /**
94
+ * Whether a mention went to a log and nowhere else: walking UP from it, a
95
+ * logging call whose ARGUMENTS the mention lies inside (a bare `e`, a template
96
+ * literal, `String(e)`, `e.message` — anything the argument is built out of).
97
+ *
98
+ * The walk stops at `root` and at a closure boundary above the mention, and
99
+ * finding nothing is an escape. It climbs THROUGH intermediate calls on
100
+ * purpose: `console.error(String(e))` is the spec's own example of a log, and
101
+ * the value of a call that is itself a logging argument goes to the log with it.
102
+ * @param {TS} ts
103
+ * @param {Node} mention
104
+ * @param {Node} root the clause block or callback body the walk may not leave
105
+ * @returns {boolean}
106
+ */
107
+ function isLogged(ts, mention, root) {
108
+ let prev = mention;
109
+ let node = mention.parent;
110
+ while (node) {
111
+ if (opensClosure(ts, node)) return false;
112
+ if (
113
+ ts.isCallExpression(node) &&
114
+ node.arguments.indexOf(/** @type {any} */ (prev)) !== -1 &&
115
+ isLoggingCallee(ts, node.expression)
116
+ ) {
117
+ return true;
118
+ }
119
+ if (node === root) return false;
120
+ prev = node;
121
+ node = node.parent;
122
+ }
123
+ return false;
124
+ }
125
+
126
+ /**
127
+ * Whether anything under `node` reads the binding at all, at any depth.
128
+ * @param {TS} ts
129
+ * @param {Node} node
130
+ * @param {string} name
131
+ * @returns {boolean}
132
+ */
133
+ function hasMention(ts, node, name) {
134
+ if (ts.isIdentifier(node) && node.text === name && isRead(ts, node)) return true;
135
+ let found = false;
136
+ ts.forEachChild(node, (child) => {
137
+ found = found || hasMention(ts, child, name);
138
+ });
139
+ return found;
140
+ }
141
+
142
+ /**
143
+ * `throw e;` — a throw whose operand, after any parentheses, is the binding
144
+ * ITSELF. A traced exit and not an escape (ruled 2026-09-10 at Task 6): the
145
+ * value does not reach anything, it leaves the same way it arrived, and the
146
+ * RAISE the throw writes carries the same serial, so the rule module reads the
147
+ * pair as a hop (spec §3.3 rule 2) and judges the rethrow on its own block.
148
+ * Counting this mention made rule 3's escaping conjunct bar EVERY `throw e`
149
+ * from a swallow, which contradicts §6.1's `rethrow_hop` row and R4.
150
+ *
151
+ * ONE rule, TWO syntaxes: it holds for a `catch` clause's binding (§2.1) and
152
+ * for a rejection callback's parameter (§2.2) alike, because §2.2 defines the
153
+ * callback word as §2.1's rule applied to that parameter, and a rethrow from a
154
+ * handler carries the serial exactly as a clause's does. Both `catchHow` and
155
+ * `callbackHow` therefore ask for it (ruled 2026-09-10, fix round 2).
156
+ *
157
+ * `throw e.cause`, `throw wrap(e)` and `throw new Wrapped(e)` are NOT this:
158
+ * their operand is something built out of the binding, so the binding reached a
159
+ * property access or a call and the escape stands.
160
+ * @param {TS} ts
161
+ * @param {Node} node
162
+ * @param {string} name
163
+ * @returns {boolean}
164
+ */
165
+ function isBareRethrow(ts, node, name) {
166
+ if (!ts.isThrowStatement(node) || !node.expression) return false;
167
+ let operand = node.expression;
168
+ while (ts.isParenthesizedExpression(operand)) operand = operand.expression;
169
+ return ts.isIdentifier(operand) && operand.text === name;
170
+ }
171
+
172
+ /**
173
+ * Whether the binding escapes the body: any mention of it that is not logged
174
+ * and is not a bare rethrow.
175
+ *
176
+ * A closure is not descended into and is not judged by what it does with the
177
+ * value — it KEEPS it, so a mention anywhere inside one is an escape however
178
+ * that closure logs it. An expression body that is itself a closure is read the
179
+ * same way, which is why the check comes before the walk rather than inside it.
180
+ * The bare-rethrow exclusion is at closure depth 0 ONLY, for the same reason:
181
+ * `retry(() => { throw e; })` hands the binding to a closure that may run
182
+ * later, elsewhere, or never, and that is an escape whatever it then throws.
183
+ *
184
+ * Both callers pass `rethrowExits`, so the exclusion is written once and asked
185
+ * for twice rather than duplicated per syntax; the parameter stays explicit so
186
+ * a third caller has to say which rule it wants rather than inherit one.
187
+ * @param {TS} ts
188
+ * @param {Node} root
189
+ * @param {string} name
190
+ * @param {boolean} rethrowExits whether `throw <name>;` is a traced exit
191
+ * @returns {boolean}
192
+ */
193
+ function escapes(ts, root, name, rethrowExits = false) {
194
+ if (opensClosure(ts, root)) return hasMention(ts, root, name);
195
+ let escaped = false;
196
+ /** @param {Node} node */
197
+ const visit = (node) => {
198
+ if (escaped) return;
199
+ if (opensClosure(ts, node)) {
200
+ escaped = hasMention(ts, node, name);
201
+ return;
202
+ }
203
+ // Neither a mention nor a subtree to walk: the operand IS the binding, and
204
+ // descending would find that identifier and call it an escape.
205
+ if (rethrowExits && isBareRethrow(ts, node, name)) return;
206
+ if (ts.isIdentifier(node) && node.text === name && isRead(ts, node)) {
207
+ escaped = !isLogged(ts, node, root);
208
+ return;
209
+ }
210
+ ts.forEachChild(node, visit);
211
+ };
212
+ visit(root);
213
+ return escaped;
214
+ }
215
+
216
+ /**
217
+ * A `catch` clause's `how` (§2.1). An empty block is the sink it always was,
218
+ * whatever it bound; a clause with no binding can let nothing out; a
219
+ * destructuring binding is an escape, because the runtime never sees what it
220
+ * bound and this rule will not guess. A bare `throw e;` at closure depth 0 is
221
+ * a traced exit and not a mention, so the clause is decided by whatever ELSE
222
+ * its body does with the binding (`isBareRethrow`, ruled 2026-09-10).
223
+ * @param {TS} ts
224
+ * @param {CatchClause} clause
225
+ * @returns {'catch'|'catch_escaped'|'sink_empty_catch'}
226
+ */
227
+ export function catchHow(ts, clause) {
228
+ if (clause.block.statements.length === 0) return 'sink_empty_catch';
229
+ const declared = clause.variableDeclaration;
230
+ if (!declared) return 'catch';
231
+ if (!ts.isIdentifier(declared.name)) return 'catch_escaped';
232
+ return escapes(ts, clause.block, declared.name.text, true) ? 'catch_escaped' : 'catch';
233
+ }
234
+
235
+ /**
236
+ * A rejection handler's `how` (§2.2), from the SHAPE of the argument alone.
237
+ * Anything that is not an inline function is opaque: a handler defined
238
+ * elsewhere has its own frame, and whether it swallows is not this splice's to
239
+ * say. An empty body is a sink whichever spelling wrote it. The parameter is
240
+ * read by §2.1's rule, the bare-rethrow exclusion included: a handler that
241
+ * rethrows what it was given is a hop, in either spelling (`isBareRethrow`).
242
+ * @param {TS} ts
243
+ * @param {Node} arg
244
+ * @returns {'sink_empty_catch_callback'|'catch_callback'|'catch_callback_escaped'|'catch_callback_opaque'}
245
+ */
246
+ export function callbackHow(ts, arg) {
247
+ if (!ts.isArrowFunction(arg) && !ts.isFunctionExpression(arg)) return 'catch_callback_opaque';
248
+ const body = arg.body;
249
+ if (ts.isBlock(body) && body.statements.length === 0) return 'sink_empty_catch_callback';
250
+ const param = arg.parameters[0];
251
+ if (!param) return 'catch_callback';
252
+ if (!ts.isIdentifier(param.name)) return 'catch_callback_escaped';
253
+ return escapes(ts, body, param.name.text, true) ? 'catch_callback_escaped' : 'catch_callback';
254
+ }
255
+
256
+ /**
257
+ * A loop or a `switch` written INSIDE the `finally` block: a `break` or
258
+ * `continue` it encloses stays in the block and discards nothing.
259
+ * @param {TS} ts
260
+ * @param {Node} node
261
+ * @returns {boolean}
262
+ */
263
+ function catchesJump(ts, node) {
264
+ return (
265
+ ts.isForStatement(node) ||
266
+ ts.isForInStatement(node) ||
267
+ ts.isForOfStatement(node) ||
268
+ ts.isWhileStatement(node) ||
269
+ ts.isDoStatement(node) ||
270
+ ts.isSwitchStatement(node)
271
+ );
272
+ }
273
+
274
+ /**
275
+ * Whether a `finally` block COMPLETES — leaves by `return`, `break` or
276
+ * `continue` — and so discards whatever was travelling through the frame
277
+ * (§2.3). A `return` counts anywhere at closure depth 0; a `break` or
278
+ * `continue` only where nothing inside the block catches it, because a `break`
279
+ * that stays inside the `finally` discards nothing.
280
+ *
281
+ * Two shapes this reads as NOT completing that do complete: a `continue` inside
282
+ * a `switch` in the block (a `switch` catches `break`, not `continue`), and a
283
+ * LABELLED jump to a loop outside the block. Both under-count — the sink goes
284
+ * unrecorded rather than claimed — and both are named in HONESTY.
285
+ * @param {TS} ts
286
+ * @param {Block} block
287
+ * @returns {boolean}
288
+ */
289
+ export function finallyCompletes(ts, block) {
290
+ let found = false;
291
+ /** @param {Node} node @param {boolean} caught */
292
+ const visit = (node, caught) => {
293
+ if (found || opensClosure(ts, node)) return;
294
+ if (ts.isReturnStatement(node)) {
295
+ found = true;
296
+ return;
297
+ }
298
+ if (!caught && (ts.isBreakStatement(node) || ts.isContinueStatement(node))) {
299
+ found = true;
300
+ return;
301
+ }
302
+ const inside = caught || catchesJump(ts, node);
303
+ ts.forEachChild(node, (child) => visit(child, inside));
304
+ };
305
+ ts.forEachChild(block, (child) => visit(child, false));
306
+ return found;
307
+ }
308
+
309
+ /**
310
+ * Whether a function's OWN body returns from inside a `try` that has a
311
+ * `finally` (2026-09-12 design §4.2) — the shape that gets the DEFERRED exit:
312
+ * `return x` pends the value, the wrapper's own `finally` seals the frame, and
313
+ * the program's `finally` therefore runs while the frame is still open.
314
+ *
315
+ * The walk stops at every closure for `finallyCompletes`'s reason: a return a
316
+ * nested function, arrow or method makes is ITS exit, and its frame's lifetime
317
+ * is not this one's. It carries one fact down — whether some enclosing `try`
318
+ * with a `finally` still has to run one — and a `TryStatement` sets that fact
319
+ * for its `tryBlock` and its `catchClause` only. Its `finallyBlock` is handed
320
+ * the fact UNCHANGED: a return written there is a return no further finally of
321
+ * that try guards, so it counts only where an OUTER try-with-finally encloses
322
+ * it, which is the same question asked one level up.
323
+ *
324
+ * Every other function is byte-identical to 0.3.0's (R2), so this is the one
325
+ * predicate that decides whether a wrapper moves at all.
326
+ * @param {TS} ts
327
+ * @param {FunctionLike} fn
328
+ * @returns {boolean}
329
+ */
330
+ export function deferredExit(ts, fn) {
331
+ if (!fn.body) return false;
332
+ let deferred = false;
333
+ /** @param {Node} node @param {boolean} guarded */
334
+ const visit = (node, guarded) => {
335
+ if (deferred || opensClosure(ts, node)) return;
336
+ if (ts.isReturnStatement(node)) {
337
+ deferred = guarded;
338
+ return;
339
+ }
340
+ if (ts.isTryStatement(node)) {
341
+ const inside = guarded || !!node.finallyBlock;
342
+ visit(node.tryBlock, inside);
343
+ if (node.catchClause) visit(node.catchClause, inside);
344
+ if (node.finallyBlock) visit(node.finallyBlock, guarded);
345
+ return;
346
+ }
347
+ ts.forEachChild(node, (child) => visit(child, guarded));
348
+ };
349
+ ts.forEachChild(fn.body, (child) => visit(child, false));
350
+ return deferred;
351
+ }
@@ -0,0 +1,135 @@
1
+ // Which functions a `--focus` spec selects. One rule, asked at three moments:
2
+ // by the resolver before the run (Task 5), by the transform while it splices
3
+ // (Task 4), and by the reader's `--at` in Python (Task 7) — which is a SECOND
4
+ // implementation of this file, pinned to it by one example table
5
+ // (`../test/fixtures/site-spellings.json`), because a spelling a reader cannot
6
+ // repeat is a spelling the recorder should not have accepted (spec §4.3).
7
+ //
8
+ // A spec is `<qualname>` or `<file>:<qualname>` (spec §2.1). The qualname is
9
+ // what `tree` prints — `Fog.compute`, `outer.inner`, `refresh`, `default` — and
10
+ // a value naming a CONTAINER selects everything under it on a `.` boundary,
11
+ // which is the only way to name an anonymous function (`<anonymous>` carries no
12
+ // ordinal, and `<` is the shell's). The file part narrows and is optional. No
13
+ // globs, no regexes, no line numbers.
14
+ //
15
+ // No state and no I/O: strings in, verdicts out.
16
+ import path from 'node:path';
17
+
18
+ /** @typedef {{file: string|null, qualname: string}} Spec */
19
+
20
+ /**
21
+ * The unit separator, written as an escape so no editor strips it. The driver
22
+ * joins the specs with it into one `SENSORIUM_FOCUS` variable, because a spec
23
+ * may hold a path, a dot and a colon, and this is the one byte it cannot.
24
+ */
25
+ export const SEP = '\x1f';
26
+
27
+ /**
28
+ * The specs an environment value carries. An empty value is no focus at all,
29
+ * and an empty FIELD is dropped rather than kept: `''` as a spec would have an
30
+ * empty qualname, and `qualnameMatches` would then select every function in
31
+ * the root — the one mistake that turns a focus into a whole-program recording.
32
+ * @param {string} value
33
+ * @returns {string[]}
34
+ */
35
+ export function specsFromEnv(value) {
36
+ return value.split(SEP).filter((spec) => spec !== '');
37
+ }
38
+
39
+ /**
40
+ * A spec's two parts, split at the FIRST colon: a Windows drive letter is not a
41
+ * spelling here, and a later colon belongs to the qualname it appears in.
42
+ * @param {string} spec
43
+ * @returns {Spec}
44
+ */
45
+ export function parseSpec(spec) {
46
+ const cut = spec.indexOf(':');
47
+ if (cut === -1) return { file: null, qualname: spec };
48
+ return { file: spec.slice(0, cut), qualname: spec.slice(cut + 1) };
49
+ }
50
+
51
+ /**
52
+ * Whether a function's qualname is selected by a spec's qualname part: the name
53
+ * itself, or a container of it on a `.` boundary. `Fog` selects `Fog.compute`;
54
+ * `Fog` does not select `Fogs.compute`, and `compute` selects neither — this is
55
+ * a prefix rule, so a member is reached by naming its container, never by
56
+ * naming the member alone.
57
+ * @param {string} qualname
58
+ * @param {string} want
59
+ * @returns {boolean}
60
+ */
61
+ export function qualnameMatches(qualname, want) {
62
+ return qualname === want || qualname.startsWith(`${want}.`);
63
+ }
64
+
65
+ /**
66
+ * Whether a root-relative path is selected by a spec's file part: the path
67
+ * itself (`src/lib/cache.ts`), the basename (`cache.ts`), or the stem
68
+ * (`cache`, the basename without its LAST extension). A directory segment is
69
+ * not a spelling, and neither is part of a path.
70
+ * @param {string} rel root-relative, in the platform's own separators
71
+ * @param {string} want
72
+ * @returns {boolean}
73
+ */
74
+ export function fileMatches(rel, want) {
75
+ if (rel === want) return true;
76
+ const base = path.basename(rel);
77
+ if (base === want) return true;
78
+ const ext = path.extname(base);
79
+ return ext !== '' && base.slice(0, -ext.length) === want;
80
+ }
81
+
82
+ /**
83
+ * Whether a spec selects the function at `rel` named `qualname`. The file part
84
+ * only ever NARROWS: a spec without one selects every matching qualname under
85
+ * the root, which is what a bare `--focus load` means and what `focus_matched`
86
+ * then lists.
87
+ * @param {string} spec
88
+ * @param {string} rel
89
+ * @param {string} qualname
90
+ * @returns {boolean}
91
+ */
92
+ export function specMatches(spec, rel, qualname) {
93
+ const { file, qualname: want } = parseSpec(spec);
94
+ if (file !== null && !fileMatches(rel, file)) return false;
95
+ return qualnameMatches(qualname, want);
96
+ }
97
+
98
+ /**
99
+ * @param {string[]} parts
100
+ * @param {string[]} want
101
+ * @returns {number} how many WHOLE trailing segments the two share
102
+ */
103
+ function sharedTail(parts, want) {
104
+ let shared = 0;
105
+ while (
106
+ shared < parts.length &&
107
+ shared < want.length &&
108
+ parts[parts.length - 1 - shared] === want[want.length - 1 - shared]
109
+ ) {
110
+ shared += 1;
111
+ }
112
+ return shared;
113
+ }
114
+
115
+ /**
116
+ * The suggestions a refusal names: the eligible qualnames sharing the longest
117
+ * trailing run of `.`-separated segments with the spec's qualname part, most
118
+ * first, ties by name. A candidate sharing NOTHING is still a suggestion — the
119
+ * clause is dropped only when the root holds no eligible function at all (spec
120
+ * §2.2), because a reader who mistyped the container needs the list most.
121
+ * @param {string[]} eligible every qualname the root offers
122
+ * @param {string} want the spec's qualname part, after `parseSpec`
123
+ * @param {number} [limit]
124
+ * @returns {string[]} at most `limit` names
125
+ */
126
+ export function closest(eligible, want, limit = 3) {
127
+ const parts = want.split('.');
128
+ const scored = eligible.map((name) => ({ name, shared: sharedTail(name.split('.'), parts) }));
129
+ scored.sort((a, b) => {
130
+ if (a.shared !== b.shared) return b.shared - a.shared;
131
+ if (a.name === b.name) return 0;
132
+ return a.name < b.name ? -1 : 1;
133
+ });
134
+ return scored.slice(0, limit).map((entry) => entry.name);
135
+ }
@@ -0,0 +1,127 @@
1
+ // The `node --test` loader hook. It is `register.mjs` that installs it; this is
2
+ // the module that runs on the loader thread.
3
+ //
4
+ // ONE job, for an ES MODULE under `SENSORIUM_TS_ROOT`: instrument the source the
5
+ // consumer wrote — TypeScript types and all, because the transform positions
6
+ // itself against the consumer's own AST — and hand it back under the format
7
+ // NODE reported for it. THIS HOOK ERASES NOTHING. `module-typescript` goes back
8
+ // as `module-typescript`, and Node strips it with the stripper plain
9
+ // `node --test` already uses; `module` goes back as `module` and is loaded as
10
+ // written. So `.ts` and `.mts` are stripped alike, and a construct Node's
11
+ // strip-only mode rejects (`enum`, `namespace`, parameter properties) fails
12
+ // IDENTICALLY plain and hooked, with Node's own error — which is R37 carried
13
+ // one step further: Node decides the format AND the erasure. The consumer's own
14
+ // TypeScript stays `require`d because the TRANSFORM parses against it; that was
15
+ // never the stripper's.
16
+ //
17
+ // `.tsx`/`.jsx` cannot reach this hook under `node --test` at all — Node's own
18
+ // loader throws `ERR_UNKNOWN_FILE_EXTENSION` from `nextLoad` before `load` sees
19
+ // the file — so such a file is outside NODE's scope here, not an exclusion of
20
+ // ours, and is not counted: the hook never decided anything about it. It is not
21
+ // made loadable either. A recorder that made an unloadable file load would be
22
+ // changing the program, which is the one thing this one promises not to do.
23
+ // (`classify()` still calls `.tsx`/`.jsx` eligible — that is the vitest
24
+ // plugin's scope, where they load.)
25
+ //
26
+ // A transform result whose `code` is null is 'ours, untouched, counted' (R10):
27
+ // the file did not parse, so it is loaded exactly as it was written and Node
28
+ // reports the syntax error itself, rather than this hook reporting a mangled
29
+ // one. A THROW from the transform is R10a — it refuses to splice blind — and
30
+ // reaches the consumer: a file this hook cannot vouch for is not quietly
31
+ // loaded unrecorded.
32
+ //
33
+ // The default load is called with the context it was given, never with
34
+ // `format: 'module'` forced into it: a `.js` in a package with no `"type"`
35
+ // field is CommonJS, and forcing it to ESM spliced an `import` header into a
36
+ // file full of `require` calls and broke a test suite that passes without
37
+ // this recorder — while `HONESTY.md` §7 promised such a file was "excluded
38
+ // and counted". A CommonJS result (`commonjs`, `commonjs-typescript`) passes
39
+ // through `excluded()` untouched and counted. Measured on node v24.16.0,
40
+ // `nextLoad` reports what Node itself would use and hands back the source AS
41
+ // WRITTEN: `commonjs` (with a null source — the CJS loader reads the file
42
+ // itself) for a detected-CommonJS `.js` and for `.cjs`; `commonjs-typescript`
43
+ // for a detected-CommonJS `.ts`/`.cts`, types intact; `module` for `.mjs`; and
44
+ // `module-typescript` for an ESM `.ts` or `.mts`, types intact. Nothing arrives
45
+ // here pre-stripped, which is the one thing the forced format was there to
46
+ // prevent.
47
+ import { createRequire } from 'node:module';
48
+ import path from 'node:path';
49
+ import { fileURLToPath, pathToFileURL } from 'node:url';
50
+
51
+ import { specsFromEnv } from './focus.mjs';
52
+ import * as tally from './tally.mjs';
53
+ import { classify, transformSource } from './transform.mjs';
54
+
55
+ /** The consumer's project directory: what is in scope to instrument. */
56
+ const ROOT = path.resolve(process.env.SENSORIUM_TS_ROOT ?? '');
57
+ /** This package's directory: where the runtime every edited file imports lives. */
58
+ const PKG = path.resolve(process.env.SENSORIUM_TS_PKG ?? '');
59
+ /** Where the counts and the per-file manifests go, or '' when nobody asked. */
60
+ const MANIFEST_DIR = tally.dir();
61
+ /**
62
+ * The functions to record statements for, `[]` for none. Read at module load,
63
+ * as ROOT and PKG are: this hook is installed by `--import` before the program
64
+ * starts, so the environment the driver set is already complete. The RUNTIME
65
+ * reads the same variable in the same process and declares `line` from it, so
66
+ * one variable answers for both halves (spec §2.3).
67
+ */
68
+ const FOCUS = specsFromEnv(process.env.SENSORIUM_FOCUS ?? '');
69
+
70
+ /** One specifier for the runtime, so one instance answers for the process (R16). */
71
+ const RT_PATH = pathToFileURL(path.join(PKG, 'src', 'rt.mjs')).href;
72
+
73
+ const require = createRequire(path.join(ROOT, 'package.json'));
74
+ /** The consumer's own TypeScript — the compiler its build already trusts. */
75
+ const ts = /** @type {typeof import('typescript')} */ (require('typescript'));
76
+
77
+ /** The formats this transform must not touch: its header is an `import`. */
78
+ const COMMONJS_FORMATS = new Set(['commonjs', 'commonjs-typescript']);
79
+
80
+ /**
81
+ * Count one file this hook declined, and write the counts out.
82
+ *
83
+ * Written after every decision rather than on exit: an `exit` listener
84
+ * registered from a loader hook never fires (measured — see `tally.mjs`), so
85
+ * an exit-time write from this thread would write nothing at all.
86
+ * @template T
87
+ * @param {string} file absolute path
88
+ * @param {T} loaded the default load's own result, handed straight back
89
+ * @returns {T}
90
+ */
91
+ function excluded(file, loaded) {
92
+ tally.exclude(file, 'commonjs');
93
+ if (MANIFEST_DIR) tally.write(MANIFEST_DIR, tally.containerTally());
94
+ return loaded;
95
+ }
96
+
97
+ /**
98
+ * @param {string} url
99
+ * @param {object} context
100
+ * @param {(url: string, context: object) => Promise<{format?: string, source?: string|ArrayBuffer|Uint8Array}>} nextLoad
101
+ * @returns {Promise<{format?: string, source?: string|ArrayBuffer|Uint8Array, shortCircuit?: boolean}>}
102
+ */
103
+ export async function load(url, context, nextLoad) {
104
+ if (!url.startsWith('file:')) return nextLoad(url, context);
105
+ const file = fileURLToPath(url);
106
+ const kind = classify(file, ROOT);
107
+ if (kind === 'skip') return nextLoad(url, context);
108
+ // `.cjs` and `.cts` are CommonJS by their extension; Node names the rest.
109
+ if (kind === 'commonjs') return excluded(file, await nextLoad(url, context));
110
+ const loaded = await nextLoad(url, context);
111
+ if (COMMONJS_FORMATS.has(loaded.format ?? '')) return excluded(file, loaded);
112
+
113
+ const src = loaded.source;
114
+ const code = typeof src === 'string' ? src : Buffer.from(/** @type {any} */ (src)).toString('utf8');
115
+ // A throw from here is the transform refusing to splice blind (R10a) and it
116
+ // must reach the consumer: a file this hook cannot vouch for is not quietly
117
+ // loaded unrecorded.
118
+ const out = transformSource(code, file, { root: ROOT, ts, rtPath: RT_PATH, focus: FOCUS });
119
+ if (out === null) return loaded;
120
+ tally.record(file, out, MANIFEST_DIR);
121
+ if (MANIFEST_DIR) tally.write(MANIFEST_DIR, tally.containerTally());
122
+ // Node's own format goes back with the edited source: `module-typescript`
123
+ // is stripped by the stripper plain `node --test` already uses, `module`
124
+ // is loaded as written. This hook erases nothing.
125
+ const edited = out.code !== null ? out.code : code;
126
+ return { format: loaded.format, source: edited, shortCircuit: true };
127
+ }
@@ -0,0 +1 @@
1
+ export const VERSION = '0.6.2';
@@ -0,0 +1,63 @@
1
+ // What a task is CALLED. Four branches and nothing else: the harness's own name
2
+ // for the test now running, the lexical chain the transform read off the source,
3
+ // which of the two wins, and whether they disagreed (spec §4, D4).
4
+ //
5
+ // Split out of `rt.mjs` 2026-09-12 (S5 rung 4's debts) — a pure move, no rule
6
+ // changed. The runtime keeps the tier gate: `rt.nameProvider` is still the only
7
+ // way a consumer registers a provider, and it refuses when the recorder is off.
8
+ // This module holds the provider itself and the rule that reads it, so the name
9
+ // question can be answered — and read — without the spool, the frame stack and
10
+ // the signal handlers around it.
11
+
12
+ /** @typedef {{name: string, basis: 'vitest'|'title', conflict: boolean}} Named */
13
+
14
+ /** The name a task gets when its title is not a string at all. */
15
+ export const UNNAMED = '<unnamed: title not a string>';
16
+
17
+ /** @type {(() => unknown)|null} */
18
+ let provider = null;
19
+
20
+ /**
21
+ * Register the harness's own name for the test now running. The vitest setup
22
+ * file supplies `() => expect.getState().currentTestName ?? null`; under
23
+ * `node --test` there is no provider and the lexical name is the name.
24
+ * @param {unknown} fn
25
+ * @returns {void}
26
+ */
27
+ export function setProvider(fn) {
28
+ provider = typeof fn === 'function' ? /** @type {() => unknown} */ (fn) : null;
29
+ }
30
+
31
+ /** @param {unknown} title @returns {string} */
32
+ export const titleOf = (title) => (typeof title === 'string' ? title : UNNAMED);
33
+
34
+ /**
35
+ * The four branches of the naming rule (spec §4, D4).
36
+ * @param {string} title
37
+ * @param {string} lexical
38
+ * @param {number} flags
39
+ * @returns {Named}
40
+ */
41
+ export function nameFor(title, lexical, flags) {
42
+ const provided = ask();
43
+ if (typeof provided !== 'string') return { name: lexical, basis: 'title', conflict: false };
44
+ // The cross-check is only possible where the transform saw a plain string
45
+ // literal that is not a `.each` template. A `.concurrent` task's provider
46
+ // name is uncheckable for a different reason, and the ledger says so.
47
+ const checkable = (flags & 1) !== 0 && (flags & 2) === 0;
48
+ if (checkable && !provided.endsWith(title)) {
49
+ return { name: lexical, basis: 'title', conflict: true };
50
+ }
51
+ return { name: provided, basis: 'vitest', conflict: false };
52
+ }
53
+
54
+ /** @returns {unknown} the provider's name, or null when there is none to ask */
55
+ export function ask() {
56
+ if (!provider) return null;
57
+ try {
58
+ return provider();
59
+ } catch {
60
+ // `expect.getState()` outside a test throws; that is not this run's news.
61
+ return null;
62
+ }
63
+ }