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,37 @@
1
+ // Two questions about where a node SITS in its source file, asked by both the
2
+ // rewriter and the focus tier's probes: which line a position is on, and
3
+ // whether a statement ended with a `;` of its own.
4
+ //
5
+ // Split out of `transform.mjs` 2026-09-12 (S5 rung 4's debts) to break the
6
+ // `transform.mjs ⇄ probe.mjs` import cycle — a pure move, both functions
7
+ // unchanged. The cycle was safe (hoisted declarations, called only during a
8
+ // transform, never while either module was being evaluated) and it was still a
9
+ // cycle: a reader tracing `probe.mjs` was sent back into the file that had just
10
+ // called it. Neither function touches the splice plan or the manifest, so
11
+ // neither owed the rewriter anything; they belong to the source file.
12
+
13
+ /** @typedef {import('typescript').SourceFile} SourceFile */
14
+ /** @typedef {import('typescript').Node} Node */
15
+ /** @typedef {import('./transform.mjs').Splicer} Splicer */
16
+
17
+ /**
18
+ * @param {SourceFile} sf
19
+ * @param {number} pos
20
+ * @returns {number} the 1-based line
21
+ */
22
+ export function lineOf(sf, pos) {
23
+ return sf.getLineAndCharacterOfPosition(pos).line + 1;
24
+ }
25
+
26
+ /**
27
+ * A bare `return` or `yield` that ASI terminated is now an expression, and the
28
+ * next line would join it: `return\n(g)()` would call our `ret(...)` result
29
+ * instead of returning. A statement-level one is given the semicolon the source
30
+ * left to ASI — always legal there, and never inserted twice (R12).
31
+ * @param {Splicer} ctx
32
+ * @param {Node} statement the whole statement the splice terminates
33
+ * @returns {string} `';'` when the statement has none of its own
34
+ */
35
+ export function terminatorFor(ctx, statement) {
36
+ return ctx.sf.text[statement.end - 1] === ';' ? '' : ';';
37
+ }
@@ -0,0 +1,246 @@
1
+ // The focus tier's splices: the rows a FOCUSED function's body writes as it
2
+ // runs. `transform.mjs`'s visitor calls `spliceFocused` for every node inside
3
+ // such a function, and this module decides what — if anything — that node owes
4
+ // the record (spec §3.1–§3.4).
5
+ //
6
+ // Three splices, and nothing else:
7
+ // * a STATEMENT ROW after every statement that completes normally, carrying
8
+ // the names it wrote (`writesOf`) and the block-scoped names that died with
9
+ // it (`declaredIn`);
10
+ // * a HEAD ROW as the first statement inside a guard's body, carrying the
11
+ // names the guard bound as it entered (`headBindingsOf`) — once per entry
12
+ // or iteration;
13
+ // * a WRAP, `{…}`, around a guard body written without braces, so the body's
14
+ // own row runs only when the body does (plan P2: appended after a bare
15
+ // body, a probe would run unconditionally — Rust's A1, transferred).
16
+ //
17
+ // It owns no name rules: `bindings.mjs` answers every "which names" question
18
+ // and this file only asks. It owns no positions either — `lineOf` and
19
+ // `terminatorFor` are `positions.mjs`'s, which `transform.mjs` reads from too.
20
+ // This module names `transform.mjs` for one TYPE and nothing at runtime, so the
21
+ // graph through `src/` is acyclic (`test/graph.test.mjs`).
22
+ //
23
+ // Two orderings the whole file rests on, both measured (see the tests):
24
+ // * `prependRight` renders EARLIER-registered content to the RIGHT of later
25
+ // content at one offset. So a statement's row is registered BEFORE the
26
+ // statement's children are visited (plan P3) — a descendant's closer
27
+ // (`await p` as a whole statement: the suspension rewrite's `),0))`) then
28
+ // lands INSIDE the probe rather than after it — and a guard's own row is
29
+ // registered before its body's wrap, so at the one offset where a guard,
30
+ // its wrap and its last statement all end, the output reads
31
+ // `stmt;<stmt row>}<guard row>`.
32
+ // * `appendLeft` renders in registration order, so a `catch` clause's head
33
+ // row follows the HANDLED that `spliceCatch` registered first.
34
+ import {
35
+ declaredIn,
36
+ headBindingsOf,
37
+ isGuard,
38
+ isStatementPosition,
39
+ writesOf,
40
+ } from './bindings.mjs';
41
+ import { lineOf, terminatorFor } from './positions.mjs';
42
+
43
+ /** @typedef {typeof import('typescript')} TS */
44
+ /** @typedef {import('typescript').Node} Node */
45
+ /** @typedef {import('typescript').Statement} Statement */
46
+ /** @typedef {import('./transform.mjs').Splicer} Splicer */
47
+
48
+ /**
49
+ * A `[name, value, …]` argument list, spelled for the runtime: the names are
50
+ * the transform's own (JSON strings) and the values are the program's own
51
+ * identifiers or member spellings (`a.b`, `this.x`), read where the splice stands.
52
+ * @param {string[]} names
53
+ * @returns {string} the list's contents, without its brackets
54
+ */
55
+ export function pairsOf(names) {
56
+ return names.flatMap((name) => [JSON.stringify(name), name]).join(',');
57
+ }
58
+
59
+ /**
60
+ * @param {TS} ts
61
+ * @param {Node} node
62
+ * @returns {boolean} whether the node carries a `declare` modifier of its own
63
+ */
64
+ function isDeclared(ts, node) {
65
+ const modifiers = /** @type {{modifiers?: readonly import('typescript').ModifierLike[]}} */ (
66
+ node
67
+ ).modifiers;
68
+ return !!modifiers && modifiers.some((m) => m.kind === ts.SyntaxKind.DeclareKeyword);
69
+ }
70
+
71
+ /**
72
+ * Whether a node is a guard's BLOCK body, whose completion is the guard's own.
73
+ *
74
+ * Such a block mints no row: the guard's row is minted at the same moment and
75
+ * `declaredIn` already reports the block's dead names on it, so a second row
76
+ * would report one completion twice and pop the same names twice. A bare body
77
+ * is different — it is an ordinary statement inside the block this recorder
78
+ * synthesised, and it keeps its row.
79
+ *
80
+ * A LABELED body is not one either: the label mints nothing of its own (R16),
81
+ * so its body statement must. That falls out of `isGuard` rather than being
82
+ * said twice: a label is not a guard.
83
+ *
84
+ * DERIVED, not restated. Which slot of which parent holds a statement is
85
+ * written down once, in `bindings.isStatementPosition`; this asks the two
86
+ * extra questions that make such a position a guard's BLOCK body — that the
87
+ * node is a block, and that the parent is one of the six. Both predicates
88
+ * spelled the parent relation themselves until 2026-09-12, which is two
89
+ * places for one rule to be wrong in.
90
+ * @param {TS} ts
91
+ * @param {Node} node
92
+ * @returns {boolean}
93
+ */
94
+ function isGuardBody(ts, node) {
95
+ const parent = node.parent;
96
+ return !!parent && ts.isBlock(node) && isGuard(ts, parent) &&
97
+ isStatementPosition(ts, node);
98
+ }
99
+
100
+ /**
101
+ * Whether a node in statement position owes the record a row of its own.
102
+ *
103
+ * The completions mint none: `return`, `throw`, `break` and `continue` never
104
+ * complete normally, and each one's exit is already the RETURN, the UNWIND or
105
+ * the enclosing statement's row (spec §3.1). A `FunctionDeclaration` is hoisted
106
+ * and executes nowhere in particular. An `EmptyStatement` is not a statement
107
+ * anybody wrote. A `LabeledStatement` is a label, not a step (R16).
108
+ *
109
+ * The type-only three mint none either (R17): an interface, a type alias and
110
+ * anything `declare`d are ERASED before the program runs, so a row for one
111
+ * would name a line that never ran. An `enum` and a `class` are not erased —
112
+ * they execute where they stand — and both keep their row.
113
+ * @param {TS} ts
114
+ * @param {Node} node
115
+ * @returns {boolean}
116
+ */
117
+ function mintsRow(ts, node) {
118
+ if (
119
+ ts.isReturnStatement(node) ||
120
+ ts.isThrowStatement(node) ||
121
+ ts.isBreakStatement(node) ||
122
+ ts.isContinueStatement(node) ||
123
+ ts.isFunctionDeclaration(node) ||
124
+ ts.isEmptyStatement(node) ||
125
+ ts.isLabeledStatement(node) ||
126
+ ts.isInterfaceDeclaration(node) ||
127
+ ts.isTypeAliasDeclaration(node) ||
128
+ isDeclared(ts, node)
129
+ ) {
130
+ return false;
131
+ }
132
+ return !isGuardBody(ts, node);
133
+ }
134
+
135
+ /**
136
+ * One completed statement's row, after the statement (spec §3.1).
137
+ *
138
+ * It carries the semicolon the source left to ASI when the statement has none
139
+ * of its own — a block-like statement ends in `}`, and `}__srt.line(…)` would
140
+ * be read as a call on whatever the block produced.
141
+ * @param {Splicer} ctx
142
+ * @param {Node} node a node in statement position that mints a row
143
+ * @returns {void}
144
+ */
145
+ function spliceStatement(ctx, node) {
146
+ const { ts, sf, s } = ctx;
147
+ const line = lineOf(sf, node.getStart(sf));
148
+ const deltas = pairsOf(writesOf(ts, node));
149
+ const gone = declaredIn(ts, node);
150
+ const tail = gone.length > 0 ? `,${JSON.stringify(gone)}` : '';
151
+ s.prependRight(node.end, `${terminatorFor(ctx, node)}__srt.line(__sf,${line},[${deltas}]${tail});`);
152
+ }
153
+
154
+ /**
155
+ * A guard's body: the head row inside it, and the braces a bare one needs.
156
+ * @param {Splicer} ctx
157
+ * @param {Node} body the body statement
158
+ * @param {string} headRow the row to open the body with, or '' for none
159
+ * @returns {void}
160
+ */
161
+ function spliceBody(ctx, body, headRow) {
162
+ const { ts, sf, s } = ctx;
163
+ if (ts.isBlock(body)) {
164
+ if (headRow !== '') s.appendLeft(body.getStart(sf) + 1, headRow);
165
+ return;
166
+ }
167
+ // Registered BEFORE the body is visited, so the body's own row renders
168
+ // inside these braces rather than after them.
169
+ s.appendLeft(body.getStart(sf), `{${headRow}`);
170
+ s.prependRight(body.end, '}');
171
+ }
172
+
173
+ /**
174
+ * A guard's head row, and its bodies.
175
+ *
176
+ * The head row says: this body was ENTERED, and these are the names the guard
177
+ * bound to enter it (spec §3.2). Two bodies are wrapped and given none, for the
178
+ * one reason — the head had not run when the body started, so a row there would
179
+ * publish a value the guard never bound:
180
+ *
181
+ * * an `else` branch (R21). A falsy test entered nothing, and what its head
182
+ * WROTE reaches the record on the `if`'s own completion row (plan P1).
183
+ * * a `do…while` body (R23). The test runs AFTER the body, so the first row
184
+ * would publish whatever the name held before the loop, and every later one
185
+ * the PREVIOUS iteration's test value — both of them dressed as an entry.
186
+ * `writesOf` puts the test's assignment targets on the `do`'s completion
187
+ * row, so nothing is lost by leaving the body's top silent.
188
+ *
189
+ * A `switch` has no body to enter and no head row at all (spec §3.2, §3.9).
190
+ * @param {Splicer} ctx
191
+ * @param {Node} node a guard
192
+ * @returns {void}
193
+ */
194
+ function spliceGuard(ctx, node) {
195
+ const { ts, sf } = ctx;
196
+ const heads = ts.isDoStatement(node) ? [] : headBindingsOf(ts, node);
197
+ const headRow = heads.length > 0
198
+ ? `__srt.line(__sf,${lineOf(sf, node.getStart(sf))},[${pairsOf(heads)}]);`
199
+ : '';
200
+ if (ts.isIfStatement(node)) {
201
+ spliceBody(ctx, node.thenStatement, headRow);
202
+ if (node.elseStatement) spliceBody(ctx, node.elseStatement, '');
203
+ return;
204
+ }
205
+ spliceBody(ctx, /** @type {{statement: Statement}} */ (/** @type {unknown} */ (node)).statement,
206
+ headRow);
207
+ }
208
+
209
+ /**
210
+ * A `catch` clause's binding, as the body's first row.
211
+ *
212
+ * It follows the HANDLED `spliceCatch` registered on the same offset — the
213
+ * visitor reaches the clause's own splice first, and `appendLeft` renders in
214
+ * registration order. A clause with no binding has nothing to report: the
215
+ * runtime's own `__sce` is not a name the program wrote.
216
+ * @param {Splicer} ctx
217
+ * @param {import('typescript').CatchClause} node
218
+ * @returns {void}
219
+ */
220
+ function spliceCatchHead(ctx, node) {
221
+ const { ts, sf, s } = ctx;
222
+ const heads = headBindingsOf(ts, node);
223
+ if (heads.length === 0) return;
224
+ const line = lineOf(sf, node.getStart(sf));
225
+ s.appendLeft(node.block.getStart(sf) + 1, `__srt.line(__sf,${line},[${pairsOf(heads)}]);`);
226
+ }
227
+
228
+ /**
229
+ * Every splice a node inside a focused function owes, in the one order the
230
+ * offsets allow: the node's own row FIRST, then its bodies. A guard and its
231
+ * last statement can end on the same offset, and the row registered first is
232
+ * the one rendered last — which is what puts the guard's row outside the brace
233
+ * its wrap closes.
234
+ * @param {Splicer} ctx
235
+ * @param {Node} node a node whose enclosing frame is focused
236
+ * @returns {void}
237
+ */
238
+ export function spliceFocused(ctx, node) {
239
+ const { ts } = ctx;
240
+ if (ts.isCatchClause(node)) {
241
+ spliceCatchHead(ctx, node);
242
+ return;
243
+ }
244
+ if (isStatementPosition(ts, node) && mintsRow(ts, node)) spliceStatement(ctx, node);
245
+ if (isGuard(ts, node)) spliceGuard(ctx, node);
246
+ }
@@ -0,0 +1,236 @@
1
+ // One job: name a function-like node the way JavaScript's own tools would.
2
+ //
3
+ // Design §2.4. The name is file-local and carries no Python ceremony: a nested
4
+ // function is `outer.inner`, not `outer.<locals>.inner`; a function with no name
5
+ // and no binding is `<anonymous>` with NO ordinal, because an ordinal would move
6
+ // every later anonymous function's key when one is inserted above it — the very
7
+ // move-fragility `diff --ignore-moves` exists to absorb.
8
+ //
9
+ // A direct callback of `test`, `it`, `describe`, or `suite` is named from that
10
+ // call (`it("adds")`, nested as `describe("math").it("adds")`). The callee in
11
+ // the name is the root identifier, and only a string or no-substitution
12
+ // template title counts. Every other nameless function stays `<anonymous>`.
13
+
14
+ /** @typedef {typeof import('typescript')} TS */
15
+ /** @typedef {import('typescript').Node} Node */
16
+
17
+ export const ANONYMOUS = '<anonymous>';
18
+
19
+ /** Roots of a test or suite call. The name keeps this root, never `skip` or `each`. */
20
+ const TEST_ROOTS = new Set(['test', 'it', 'describe', 'suite']);
21
+
22
+ /**
23
+ * The dotted text of `a.b.c`, or null when a segment is not a plain name.
24
+ * A leading `module.exports`, `exports` or `this` is dropped, so
25
+ * `module.exports.x` is named `x` and `this.onTick` is named `onTick`.
26
+ * @param {TS} ts
27
+ * @param {import('typescript').Expression} expr
28
+ * @returns {string|null}
29
+ */
30
+ function dottedName(ts, expr) {
31
+ /** @type {string[]} */
32
+ const parts = [];
33
+ let cur = expr;
34
+ for (;;) {
35
+ if (ts.isPropertyAccessExpression(cur)) {
36
+ parts.unshift(cur.name.text);
37
+ cur = cur.expression;
38
+ continue;
39
+ }
40
+ if (ts.isIdentifier(cur)) {
41
+ parts.unshift(cur.text);
42
+ break;
43
+ }
44
+ if (cur.kind === ts.SyntaxKind.ThisKeyword) {
45
+ parts.unshift('this');
46
+ break;
47
+ }
48
+ return null;
49
+ }
50
+ if (parts.length > 2 && parts[0] === 'module' && parts[1] === 'exports') parts.splice(0, 2);
51
+ while (parts.length > 1 && (parts[0] === 'this' || parts[0] === 'exports')) parts.shift();
52
+ return parts.join('.');
53
+ }
54
+
55
+ /**
56
+ * The text of a declaration name that is spelled, not computed.
57
+ * @param {TS} ts
58
+ * @param {Node|undefined} name
59
+ * @returns {string|null}
60
+ */
61
+ function spelledName(ts, name) {
62
+ if (!name) return null;
63
+ if (
64
+ ts.isIdentifier(name) ||
65
+ ts.isPrivateIdentifier(name) ||
66
+ ts.isStringLiteral(name) ||
67
+ ts.isNumericLiteral(name)
68
+ ) {
69
+ return name.text;
70
+ }
71
+ return null;
72
+ }
73
+
74
+ /**
75
+ * The identifier chain of a call's callee, the same walk `tasks.mjs` uses for
76
+ * a task boundary. `it.skip` is `['it', 'skip']` and `test.each(rows)` is
77
+ * `['test', 'each']`. A tagged `test.each` is the same chain.
78
+ * @param {TS} ts
79
+ * @param {import('typescript').Expression} callee
80
+ * @returns {string[]|null}
81
+ */
82
+ function calleeChain(ts, callee) {
83
+ /** @type {string[]} */
84
+ const chain = [];
85
+ let cur = callee;
86
+ for (;;) {
87
+ if (ts.isCallExpression(cur)) { cur = cur.expression; continue; }
88
+ if (ts.isTaggedTemplateExpression(cur)) { cur = cur.tag; continue; }
89
+ if (ts.isPropertyAccessExpression(cur)) {
90
+ chain.unshift(cur.name.text);
91
+ cur = cur.expression;
92
+ continue;
93
+ }
94
+ if (ts.isIdentifier(cur)) { chain.unshift(cur.text); return chain; }
95
+ return null;
96
+ }
97
+ }
98
+
99
+ /**
100
+ * @param {TS} ts
101
+ * @param {Node} node
102
+ * @returns {node is import('typescript').StringLiteral | import('typescript').NoSubstitutionTemplateLiteral}
103
+ */
104
+ function isLiteralTitle(ts, node) {
105
+ return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node);
106
+ }
107
+
108
+ /**
109
+ * `"` and `\` become escapes so the printed name stays one token.
110
+ * @param {string} text
111
+ * @returns {string}
112
+ */
113
+ function escapeTitle(text) {
114
+ return text.replace(/[\\"]/g, (ch) => `\\${ch}`);
115
+ }
116
+
117
+ /**
118
+ * The name of a direct callback of `test`/`it`/`describe`/`suite`, or null.
119
+ * The callback is argument 2 when argument 1 is an object literal
120
+ * (`test(name, options, fn)`), otherwise argument 1. A computed title, a
121
+ * parenthesized callback, or any other callee stays unnamed here.
122
+ * @param {TS} ts
123
+ * @param {Node} node
124
+ * @returns {string|null}
125
+ */
126
+ function testCallbackName(ts, node) {
127
+ const parent = node.parent;
128
+ if (!parent || !ts.isCallExpression(parent)) return null;
129
+ const chain = calleeChain(ts, parent.expression);
130
+ if (!chain || !TEST_ROOTS.has(chain[0])) return null;
131
+ const args = parent.arguments;
132
+ const title = args[0];
133
+ if (!title || !isLiteralTitle(ts, title)) return null;
134
+ const hasOptions = args.length > 1 && ts.isObjectLiteralExpression(args[1]);
135
+ if (args[hasOptions ? 2 : 1] !== node) return null;
136
+ // A dot inside a title is still a focus boundary.
137
+ return `${chain[0]}("${escapeTitle(title.text)}")`;
138
+ }
139
+
140
+ /**
141
+ * The name of the binding a nameless function is attached to: a variable, an
142
+ * object property, a class field, an assignment target, a test or suite
143
+ * callback, or `default` for an `export default` expression.
144
+ * @param {TS} ts
145
+ * @param {Node} node
146
+ * @returns {string|null}
147
+ */
148
+ function bindingName(ts, node) {
149
+ const called = testCallbackName(ts, node);
150
+ if (called !== null) return called;
151
+ const parent = node.parent;
152
+ if (!parent) return null;
153
+ if (ts.isVariableDeclaration(parent) || ts.isPropertyAssignment(parent) ||
154
+ ts.isPropertyDeclaration(parent)) {
155
+ return spelledName(ts, parent.name);
156
+ }
157
+ if (ts.isBinaryExpression(parent) &&
158
+ parent.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
159
+ parent.right === node) {
160
+ const assigned = dottedName(ts, parent.left);
161
+ // `module.exports = fn` is the whole module's default export, named as
162
+ // `export default` is; `module.exports.x = fn` keeps the property's name.
163
+ return assigned === 'module.exports' ? 'default' : assigned;
164
+ }
165
+ if (ts.isExportAssignment(parent)) return 'default';
166
+ return null;
167
+ }
168
+
169
+ /**
170
+ * @param {TS} ts
171
+ * @param {Node} node
172
+ * @returns {boolean} whether the node is an anonymous `export default` declaration
173
+ */
174
+ function isDefaultExport(ts, node) {
175
+ const modifiers = /** @type {{modifiers?: readonly import('typescript').ModifierLike[]}} */ (node)
176
+ .modifiers;
177
+ return !!modifiers && modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
178
+ }
179
+
180
+ /**
181
+ * The function's own name, before any container prefix.
182
+ * @param {TS} ts
183
+ * @param {Node} node a function-like node
184
+ * @returns {string}
185
+ */
186
+ function ownName(ts, node) {
187
+ const spelled = spelledName(ts, /** @type {{name?: Node}} */ (node).name);
188
+ if (spelled !== null) return spelled;
189
+ if (ts.isConstructorDeclaration(node)) return 'constructor';
190
+ if (isDefaultExport(ts, node)) return 'default';
191
+ return bindingName(ts, node) ?? ANONYMOUS;
192
+ }
193
+
194
+ /**
195
+ * The name a class or namespace contributes to the names inside it.
196
+ * @param {TS} ts
197
+ * @param {Node} node
198
+ * @returns {string|null}
199
+ */
200
+ function containerName(ts, node) {
201
+ if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
202
+ return spelledName(ts, node.name) ?? bindingName(ts, node);
203
+ }
204
+ if (ts.isModuleDeclaration(node) && ts.isIdentifier(node.name)) return node.name.text;
205
+ return null;
206
+ }
207
+
208
+ /**
209
+ * The file-local qualified name of a function-like node.
210
+ *
211
+ * `qualnames` holds the already-computed name of every function-like node seen
212
+ * so far; because the AST is walked outermost-first, every enclosing function of
213
+ * `node` is already in it, and the walk stops at the nearest one — that is what
214
+ * makes a nested function `outer.inner` rather than a full container path.
215
+ * @param {TS} ts
216
+ * @param {Node} node a function-like node
217
+ * @param {Map<Node, string>} qualnames
218
+ * @returns {string}
219
+ */
220
+ export function qualnameFor(ts, node, qualnames) {
221
+ /** @type {string[]} */
222
+ const parts = [];
223
+ let parent = node.parent;
224
+ while (parent) {
225
+ const enclosing = qualnames.get(parent);
226
+ if (enclosing !== undefined) {
227
+ parts.unshift(enclosing);
228
+ break;
229
+ }
230
+ const container = containerName(ts, parent);
231
+ if (container !== null) parts.unshift(container);
232
+ parent = parent.parent;
233
+ }
234
+ parts.push(ownName(ts, node));
235
+ return parts.join('.');
236
+ }