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.
- sensorium/__init__.py +0 -0
- sensorium/__main__.py +4 -0
- sensorium/_c/rt/sensorium_c_rt.c +1446 -0
- sensorium/_typescript/package-lock.json +68 -0
- sensorium/_typescript/package.json +39 -0
- sensorium/_typescript/src/bindings.mjs +792 -0
- sensorium/_typescript/src/cap.mjs +227 -0
- sensorium/_typescript/src/capabilities.mjs +40 -0
- sensorium/_typescript/src/dbg.mjs +348 -0
- sensorium/_typescript/src/escape.mjs +351 -0
- sensorium/_typescript/src/focus.mjs +135 -0
- sensorium/_typescript/src/hook.mjs +127 -0
- sensorium/_typescript/src/index.mjs +1 -0
- sensorium/_typescript/src/naming.mjs +63 -0
- sensorium/_typescript/src/positions.mjs +37 -0
- sensorium/_typescript/src/probe.mjs +246 -0
- sensorium/_typescript/src/qualname.mjs +236 -0
- sensorium/_typescript/src/redact.mjs +711 -0
- sensorium/_typescript/src/register.mjs +15 -0
- sensorium/_typescript/src/resolve.mjs +260 -0
- sensorium/_typescript/src/rt.mjs +798 -0
- sensorium/_typescript/src/setup.mjs +11 -0
- sensorium/_typescript/src/tally.mjs +164 -0
- sensorium/_typescript/src/tasks.mjs +175 -0
- sensorium/_typescript/src/transform.mjs +800 -0
- sensorium/_typescript/src/vite.mjs +99 -0
- sensorium/c/__init__.py +8 -0
- sensorium/c/cc.py +612 -0
- sensorium/c/cli.py +60 -0
- sensorium/c/convert.py +669 -0
- sensorium/c/decode.py +300 -0
- sensorium/c/driver.py +365 -0
- sensorium/c/dwarf.py +706 -0
- sensorium/c/format.py +271 -0
- sensorium/c/pkg.py +187 -0
- sensorium/c/plan.py +277 -0
- sensorium/cli.py +140 -0
- sensorium/driver.py +47 -0
- sensorium/exit.py +33 -0
- sensorium/invocations.py +83 -0
- sensorium/limits.py +253 -0
- sensorium/mcp/__init__.py +0 -0
- sensorium/mcp/audit.py +162 -0
- sensorium/mcp/child.py +240 -0
- sensorium/mcp/cmd.py +101 -0
- sensorium/mcp/jsonrpc.py +172 -0
- sensorium/mcp/result.py +187 -0
- sensorium/mcp/schema.py +390 -0
- sensorium/mcp/server.py +493 -0
- sensorium/mcp/tools.py +299 -0
- sensorium/paths.py +80 -0
- sensorium/query/__init__.py +0 -0
- sensorium/query/caps.py +150 -0
- sensorium/query/dbg_dialects.py +64 -0
- sensorium/query/diff_cmd.py +748 -0
- sensorium/query/diff_notes.py +117 -0
- sensorium/query/exceptions_c.py +263 -0
- sensorium/query/exceptions_cmd.py +788 -0
- sensorium/query/exceptions_group.py +571 -0
- sensorium/query/exceptions_invocation.py +487 -0
- sensorium/query/exceptions_rust.py +683 -0
- sensorium/query/exceptions_typescript.py +688 -0
- sensorium/query/expr.py +606 -0
- sensorium/query/failures_cmd.py +306 -0
- sensorium/query/flow_cmd.py +778 -0
- sensorium/query/flow_report.py +128 -0
- sensorium/query/flow_values.py +195 -0
- sensorium/query/fmt.py +280 -0
- sensorium/query/frame_cmd.py +237 -0
- sensorium/query/grep_cmd.py +156 -0
- sensorium/query/help.py +18 -0
- sensorium/query/info_cmd.py +527 -0
- sensorium/query/info_rust.py +214 -0
- sensorium/query/info_typescript.py +261 -0
- sensorium/query/js_inspect.py +394 -0
- sensorium/query/moves.py +254 -0
- sensorium/query/redact_cmd.py +304 -0
- sensorium/query/refocus_cmd.py +661 -0
- sensorium/query/refocus_env.py +493 -0
- sensorium/query/refocus_facts.py +269 -0
- sensorium/query/refocus_licence.py +187 -0
- sensorium/query/refocus_report.py +327 -0
- sensorium/query/refocus_rust.py +537 -0
- sensorium/query/refocus_threads.py +197 -0
- sensorium/query/refocus_typescript.py +756 -0
- sensorium/query/refocus_world.py +666 -0
- sensorium/query/runs_cmd.py +213 -0
- sensorium/query/rust_debug.py +176 -0
- sensorium/query/sites.py +171 -0
- sensorium/query/tree_cmd.py +511 -0
- sensorium/query/tree_threads.py +168 -0
- sensorium/query/vocab.py +723 -0
- sensorium/query/watch_cmd.py +657 -0
- sensorium/record/__init__.py +0 -0
- sensorium/record/boot.py +797 -0
- sensorium/record/boot_io.py +141 -0
- sensorium/record/budget.py +135 -0
- sensorium/record/capture.py +433 -0
- sensorium/record/children.py +755 -0
- sensorium/record/children_merge.py +179 -0
- sensorium/record/elide.py +55 -0
- sensorium/record/fingerprint.py +26 -0
- sensorium/record/thread_starts.py +261 -0
- sensorium/record/tracer.py +798 -0
- sensorium/record/tracer_exc.py +199 -0
- sensorium/record/tracer_frames.py +618 -0
- sensorium/redact.py +304 -0
- sensorium/redact_content.py +156 -0
- sensorium/redact_key.py +317 -0
- sensorium/redact_store.py +502 -0
- sensorium/redact_values.py +433 -0
- sensorium/store/__init__.py +0 -0
- sensorium/store/db.py +284 -0
- sensorium/store/gc.py +360 -0
- sensorium/store/payloads.py +69 -0
- sensorium/store/reader.py +438 -0
- sensorium/store/writer.py +283 -0
- sensorium/ts/__init__.py +10 -0
- sensorium/ts/build.py +783 -0
- sensorium/ts/cli.py +130 -0
- sensorium/ts/driver.py +472 -0
- sensorium/ts/focus.py +146 -0
- sensorium/ts/harness.py +314 -0
- sensorium/ts/ingest.py +380 -0
- sensorium/ts/invocation.py +252 -0
- sensorium/ts/pkg.py +167 -0
- sensorium/ts/redaction.py +64 -0
- sensorium/ts/spool.py +168 -0
- sensorium/ts/truncation.py +81 -0
- sensorium/ts/wrapper.py +255 -0
- sensorium_trace-0.18.2.dist-info/METADATA +245 -0
- sensorium_trace-0.18.2.dist-info/RECORD +135 -0
- sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
- sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
- 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
|
+
}
|