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,227 @@
|
|
|
1
|
+
// Per-run caps. 0 is unlimited. The driver resolves the command, the
|
|
2
|
+
// environment and the store config and exports integers; this module only
|
|
3
|
+
// reads those numbers. An unset variable is the built-in default.
|
|
4
|
+
//
|
|
5
|
+
// The first `maxCalls` activations of each function are stored. Further
|
|
6
|
+
// activations of that function, and every activation once the event or byte
|
|
7
|
+
// estimate is hit, are counted and not stored. A frame that is not stored is
|
|
8
|
+
// still pushed, so a child sees `parent.elided` and the whole subtree is
|
|
9
|
+
// counted rather than written under a parent id the spool never recorded.
|
|
10
|
+
// A throw materializes the raising frame and each elided ancestor,
|
|
11
|
+
// outermost first, as a skeleton CALL (no arguments). Each one spends an
|
|
12
|
+
// elided count, which is why a failure still answers.
|
|
13
|
+
|
|
14
|
+
/** @typedef {{elided: number, file: number, c: number, kept: number, reason: string}} Slot */
|
|
15
|
+
/** @typedef {{elided?: boolean, file?: number, c?: number, id?: number}} CapFrame */
|
|
16
|
+
|
|
17
|
+
export const DEFAULT_MAX_EVENTS = 100000;
|
|
18
|
+
export const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
|
|
19
|
+
export const DEFAULT_MAX_CALLS = 1024;
|
|
20
|
+
|
|
21
|
+
/** Kinds the converter turns into event rows. The cap counts those. */
|
|
22
|
+
const EVENT_KINDS = new Set(['CALL', 'RETURN', 'LINE', 'YIELD', 'RESUME', 'RAISE', 'HANDLED']);
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* @param {string|undefined} text
|
|
26
|
+
* @param {number} fallback
|
|
27
|
+
* @returns {number}
|
|
28
|
+
*/
|
|
29
|
+
function readCap(text, fallback) {
|
|
30
|
+
if (text === undefined || text === null || String(text).trim() === '') return fallback;
|
|
31
|
+
const n = Number(String(text).trim());
|
|
32
|
+
if (!Number.isFinite(n) || n < 0) return fallback;
|
|
33
|
+
return Math.trunc(n);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* @param {NodeJS.ProcessEnv} [env]
|
|
38
|
+
* @returns {{maxEvents: number, maxBytes: number, maxCalls: number}}
|
|
39
|
+
*/
|
|
40
|
+
export function limitsFromEnv(env = process.env) {
|
|
41
|
+
return {
|
|
42
|
+
maxEvents: readCap(env.SENSORIUM_MAX_EVENTS, DEFAULT_MAX_EVENTS),
|
|
43
|
+
maxBytes: readCap(env.SENSORIUM_MAX_BYTES, DEFAULT_MAX_BYTES),
|
|
44
|
+
maxCalls: readCap(env.SENSORIUM_MAX_CALLS, DEFAULT_MAX_CALLS),
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* @param {{maxEvents: number, maxBytes: number, maxCalls: number}} limits
|
|
50
|
+
*/
|
|
51
|
+
export function createBudget(limits) {
|
|
52
|
+
/** @type {Map<string, Slot>} */
|
|
53
|
+
const hot = new Map();
|
|
54
|
+
/** @type {Map<string, number>} */
|
|
55
|
+
const keptN = new Map();
|
|
56
|
+
/** @type {string[]} */
|
|
57
|
+
const hits = [];
|
|
58
|
+
const hitset = new Set();
|
|
59
|
+
let failuresKept = 0;
|
|
60
|
+
let events = 0;
|
|
61
|
+
let bytes = 0;
|
|
62
|
+
|
|
63
|
+
/** @param {number} file @param {number} c */
|
|
64
|
+
const keyOf = (file, c) => `${file}:${c}`;
|
|
65
|
+
|
|
66
|
+
/** @param {string} name */
|
|
67
|
+
function mark(name) {
|
|
68
|
+
if (!hitset.has(name)) {
|
|
69
|
+
hitset.add(name);
|
|
70
|
+
hits.push(name);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* @param {number} file
|
|
76
|
+
* @param {number} c
|
|
77
|
+
* @param {string} reason
|
|
78
|
+
* @returns {Slot}
|
|
79
|
+
*/
|
|
80
|
+
function slotFor(file, c, reason) {
|
|
81
|
+
const key = keyOf(file, c);
|
|
82
|
+
let slot = hot.get(key);
|
|
83
|
+
if (!slot) {
|
|
84
|
+
slot = { elided: 0, file, c, kept: keptN.get(key) ?? 0, reason };
|
|
85
|
+
hot.set(key, slot);
|
|
86
|
+
}
|
|
87
|
+
return slot;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** @param {Slot} slot */
|
|
91
|
+
function drop(slot) {
|
|
92
|
+
slot.elided += 1;
|
|
93
|
+
if (slot.elided === 1) mark(slot.reason);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
return {
|
|
97
|
+
limits,
|
|
98
|
+
/**
|
|
99
|
+
* @param {string} kind
|
|
100
|
+
* @param {number} nbytes
|
|
101
|
+
*/
|
|
102
|
+
note(kind, nbytes) {
|
|
103
|
+
bytes += nbytes;
|
|
104
|
+
if (EVENT_KINDS.has(kind)) events += 1;
|
|
105
|
+
},
|
|
106
|
+
/**
|
|
107
|
+
* A reason string when this activation must not be stored, else null.
|
|
108
|
+
* A hot function takes the fast path: the slot already says why.
|
|
109
|
+
* @param {{elided?: boolean, reason?: string|null}|null} parent
|
|
110
|
+
* @param {number} file
|
|
111
|
+
* @param {number} c
|
|
112
|
+
* @returns {string|null}
|
|
113
|
+
*/
|
|
114
|
+
hiding(parent, file, c) {
|
|
115
|
+
// A child of an elided frame is counted, not stored. That does not
|
|
116
|
+
// use up the child's own quota: a later call with a recorded parent
|
|
117
|
+
// is judged on its own caps.
|
|
118
|
+
if (parent && parent.elided) {
|
|
119
|
+
const reason = parent.reason || 'max_calls';
|
|
120
|
+
drop(slotFor(file, c, reason));
|
|
121
|
+
return reason;
|
|
122
|
+
}
|
|
123
|
+
const key = keyOf(file, c);
|
|
124
|
+
const n = keptN.get(key) ?? 0;
|
|
125
|
+
/** @type {string[]} */
|
|
126
|
+
const reasons = [];
|
|
127
|
+
if (limits.maxCalls && n >= limits.maxCalls) reasons.push('max_calls');
|
|
128
|
+
if (limits.maxEvents && events >= limits.maxEvents) reasons.push('max_events');
|
|
129
|
+
if (limits.maxBytes && bytes >= limits.maxBytes) reasons.push('max_bytes');
|
|
130
|
+
if (!reasons.length) return null;
|
|
131
|
+
for (const reason of reasons) mark(reason);
|
|
132
|
+
const existing = hot.get(key);
|
|
133
|
+
if (existing) {
|
|
134
|
+
drop(existing);
|
|
135
|
+
return existing.reason;
|
|
136
|
+
}
|
|
137
|
+
hot.set(key, { elided: 1, file, c, kept: n, reason: reasons[0] });
|
|
138
|
+
return reasons[0];
|
|
139
|
+
},
|
|
140
|
+
/**
|
|
141
|
+
* A call that was stored. Arms the per-function quota once it is full.
|
|
142
|
+
* A slot opened earlier, because this function was under an elided
|
|
143
|
+
* parent, keeps its elided count and gains this stored call.
|
|
144
|
+
* @param {number} file
|
|
145
|
+
* @param {number} c
|
|
146
|
+
*/
|
|
147
|
+
kept(file, c) {
|
|
148
|
+
const key = keyOf(file, c);
|
|
149
|
+
const n = (keptN.get(key) ?? 0) + 1;
|
|
150
|
+
keptN.set(key, n);
|
|
151
|
+
const slot = hot.get(key);
|
|
152
|
+
if (slot) slot.kept += 1;
|
|
153
|
+
else if (limits.maxCalls && n >= limits.maxCalls) {
|
|
154
|
+
hot.set(key, { elided: 0, file, c, kept: n, reason: 'max_calls' });
|
|
155
|
+
}
|
|
156
|
+
},
|
|
157
|
+
/**
|
|
158
|
+
* Spend one elided count so the skeleton CALL is written once.
|
|
159
|
+
* @param {number} file
|
|
160
|
+
* @param {number} c
|
|
161
|
+
* @returns {boolean}
|
|
162
|
+
*/
|
|
163
|
+
noteFailure(file, c) {
|
|
164
|
+
const slot = hot.get(keyOf(file, c));
|
|
165
|
+
if (!slot || slot.elided <= 0) return false;
|
|
166
|
+
slot.elided -= 1;
|
|
167
|
+
slot.kept += 1;
|
|
168
|
+
failuresKept += 1;
|
|
169
|
+
return true;
|
|
170
|
+
},
|
|
171
|
+
/**
|
|
172
|
+
* Outermost elided ancestor first, then the throwing frame.
|
|
173
|
+
* @param {CapFrame} frame
|
|
174
|
+
* @param {CapFrame[]} stack
|
|
175
|
+
* @param {(frame: CapFrame, parent: CapFrame|null) => void} emitCall
|
|
176
|
+
*/
|
|
177
|
+
materialize(frame, stack, emitCall) {
|
|
178
|
+
if (!frame) return;
|
|
179
|
+
/** @type {CapFrame[]} */
|
|
180
|
+
const chain = [];
|
|
181
|
+
const idx = stack.lastIndexOf(frame);
|
|
182
|
+
if (idx < 0) {
|
|
183
|
+
if (frame.elided) chain.push(frame);
|
|
184
|
+
} else {
|
|
185
|
+
for (let i = idx; i >= 0 && stack[i].elided; i--) chain.push(stack[i]);
|
|
186
|
+
}
|
|
187
|
+
for (let i = chain.length - 1; i >= 0; i--) {
|
|
188
|
+
const cur = chain[i];
|
|
189
|
+
if (!cur.elided || cur.file === undefined || cur.c === undefined) continue;
|
|
190
|
+
if (!this.noteFailure(cur.file, cur.c)) continue;
|
|
191
|
+
const at = stack.lastIndexOf(cur);
|
|
192
|
+
const below = at > 0 ? stack[at - 1] : null;
|
|
193
|
+
const parent = below && !below.elided ? below : null;
|
|
194
|
+
cur.elided = false;
|
|
195
|
+
emitCall(cur, parent);
|
|
196
|
+
}
|
|
197
|
+
},
|
|
198
|
+
/** @returns {Record<string, unknown>|null} */
|
|
199
|
+
report() {
|
|
200
|
+
let callsElided = 0;
|
|
201
|
+
/** @type {{file: number, c: number, elided: number, kept: number}[]} */
|
|
202
|
+
const elisions = [];
|
|
203
|
+
for (const slot of hot.values()) {
|
|
204
|
+
callsElided += slot.elided;
|
|
205
|
+
if (slot.elided > 0) {
|
|
206
|
+
elisions.push({ file: slot.file, c: slot.c, elided: slot.elided, kept: slot.kept });
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
if (callsElided <= 0) return null;
|
|
210
|
+
/** @type {Record<string, unknown>} */
|
|
211
|
+
const rec = {
|
|
212
|
+
e: 'ELISION',
|
|
213
|
+
hit: hits.slice(),
|
|
214
|
+
maxEvents: limits.maxEvents,
|
|
215
|
+
maxBytes: limits.maxBytes,
|
|
216
|
+
maxCalls: limits.maxCalls,
|
|
217
|
+
eventsRecorded: events,
|
|
218
|
+
callsElided,
|
|
219
|
+
elisions,
|
|
220
|
+
};
|
|
221
|
+
if (failuresKept) rec.failuresKept = failuresKept;
|
|
222
|
+
return rec;
|
|
223
|
+
},
|
|
224
|
+
};
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
export const budget = createBudget(limitsFromEnv());
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
// What this recorder declares it produces, and nothing else.
|
|
2
|
+
//
|
|
3
|
+
// Its own module because `rt.mjs` is at the repo's 800-line ceiling and this
|
|
4
|
+
// is the one block in it that answers a question of its own: what a READER
|
|
5
|
+
// may ask of a trace this runtime wrote. The declaration is the runtime's
|
|
6
|
+
// word — a spool whose BOOT lacks a key reads `false` for every one of them,
|
|
7
|
+
// so what is missing is a record and not a permission — and it belongs to
|
|
8
|
+
// the recorder rather than to the converter for that reason (§2.4).
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* What this recorder DECLARES it produces, written into every BOOT record and
|
|
12
|
+
* passed through by the converter (§2.4). A spool whose BOOT lacks a key reads
|
|
13
|
+
* `false`, so a trace this recorder did not write is still refused — what it
|
|
14
|
+
* lacks is a record, not a permission.
|
|
15
|
+
*
|
|
16
|
+
* `err_flow` says the throw-flow rows are complete enough to be judged: every
|
|
17
|
+
* `throw` statement, every `catch` clause with the transform's verdict about
|
|
18
|
+
* its binding, every rejection handler and every `finally` that discards a
|
|
19
|
+
* throw in flight.
|
|
20
|
+
*
|
|
21
|
+
* `object_identity` says every captured object carries an `oid` that is the
|
|
22
|
+
* same number wherever that object is seen again and is never given to a
|
|
23
|
+
* second one. It does not depend on a focus: a RETURN's value is captured at
|
|
24
|
+
* every tier this recorder records at, so the identity is there to follow
|
|
25
|
+
* whether or not any statement was.
|
|
26
|
+
*
|
|
27
|
+
* `line` and `locals` say the LINE rows exist — one per completed statement of
|
|
28
|
+
* a focused function, carrying the names it wrote and the names out of scope
|
|
29
|
+
* at it. Both are declared exactly when `SENSORIUM_FOCUS` is non-empty: with
|
|
30
|
+
* no focus nothing was instrumented for statements and there are no such rows,
|
|
31
|
+
* and a reader told otherwise would report "no hits" for a search that never
|
|
32
|
+
* had anything to search.
|
|
33
|
+
* @param {string} focus the run's `SENSORIUM_FOCUS`, empty when there was none
|
|
34
|
+
* @returns {Record<string, boolean>}
|
|
35
|
+
*/
|
|
36
|
+
export function capabilities(focus) {
|
|
37
|
+
return focus === ''
|
|
38
|
+
? { err_flow: true, object_identity: true }
|
|
39
|
+
: { err_flow: true, object_identity: true, line: true, locals: true };
|
|
40
|
+
}
|
|
@@ -0,0 +1,348 @@
|
|
|
1
|
+
// Reading values out of the program under test, without trusting them. Both
|
|
2
|
+
// exports take a value the consumer produced — a return value, a thrown thing —
|
|
3
|
+
// and hand back a small JSON object the wire can carry. `dbg` and `exc` do not throw:
|
|
4
|
+
// a recorder that dies on a hostile object has changed the program it was
|
|
5
|
+
// supposed to observe. What cannot be read is SAID to be unread; nothing here
|
|
6
|
+
// invents a value it did not obtain.
|
|
7
|
+
//
|
|
8
|
+
// Rule v1 (§2.3) reaches these texts from two directions. A capture `dbg`
|
|
9
|
+
// makes is ruled by NAME where it has one — `redact.mjs`'s `redactCaptures`
|
|
10
|
+
// and `redactReturn`, which `rt.mjs` puts between every capture here and the
|
|
11
|
+
// wire — and by the content rule where the name fires on nothing. A thrown
|
|
12
|
+
// MESSAGE has no name to be asked about, so `exc` applies the content rule
|
|
13
|
+
// itself, here, before the text is written.
|
|
14
|
+
import util from 'node:util';
|
|
15
|
+
|
|
16
|
+
import { content, current, redactCaptures } from './redact.mjs';
|
|
17
|
+
|
|
18
|
+
/** The byte budget one captured value gets on the wire (design §4). */
|
|
19
|
+
const CAP = 200;
|
|
20
|
+
|
|
21
|
+
/** The one inspection this recorder does, pinned by `rt.test.mjs` (`dbg caps`). */
|
|
22
|
+
const INSPECT = {
|
|
23
|
+
depth: 2,
|
|
24
|
+
maxArrayLength: 8,
|
|
25
|
+
maxStringLength: 100,
|
|
26
|
+
breakLength: Infinity,
|
|
27
|
+
compact: true,
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
// State only. At depth 0 a fulfilled string and a rejection's stack are still
|
|
31
|
+
// inlined, so the capture keeps the state word and drops the rest.
|
|
32
|
+
// `maxStringLength: 0` stops a long fulfilled string from being copied into
|
|
33
|
+
// that check. No `then`: a reaction would observe a pending promise and would
|
|
34
|
+
// handle a rejection the program left unhandled.
|
|
35
|
+
const PROMISE_INSPECT = {
|
|
36
|
+
depth: 0,
|
|
37
|
+
maxStringLength: 0,
|
|
38
|
+
customInspect: false,
|
|
39
|
+
showHidden: false,
|
|
40
|
+
compact: true,
|
|
41
|
+
breakLength: Infinity,
|
|
42
|
+
colors: false,
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* What the rule withheld, on the capture it took it from (§4.2): `by` is
|
|
47
|
+
* `name` for a value taken whole and `content` for a span replaced inside
|
|
48
|
+
* one, and `digest` is the HMAC of what was taken — `null` for a span,
|
|
49
|
+
* because a partial cannot honestly commit to the whole.
|
|
50
|
+
* @typedef {{by: string, digest: string|null}} Redacted
|
|
51
|
+
*/
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* A value this recorder read, as the wire carries it. `oid` and `type` are on
|
|
55
|
+
* the capture of an OBJECT or a function and on nothing else: a primitive has
|
|
56
|
+
* no identity to carry and this recorder does not invent one for it.
|
|
57
|
+
* @typedef {{k: 'dbg', v: string, trunc: boolean, oid?: number, type?: string,
|
|
58
|
+
* redacted?: Redacted}} Dbg
|
|
59
|
+
*/
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* What one captured value is on the wire. A value it could not read is
|
|
63
|
+
* `unread` whole — an oid there would say it knows WHICH object it failed to
|
|
64
|
+
* read.
|
|
65
|
+
* @typedef {Dbg|{k: 'unread'}} Captured
|
|
66
|
+
*/
|
|
67
|
+
|
|
68
|
+
/** Serials are per value, not per record: a rethrown OBJECT keeps its own. */
|
|
69
|
+
let nextSerial = 1;
|
|
70
|
+
/** @type {WeakMap<object, number>} */
|
|
71
|
+
const serials = new WeakMap();
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* The identity a captured object carries, and the counter that mints it.
|
|
75
|
+
*
|
|
76
|
+
* Deliberately NOT the exception map above (P12). The two number different
|
|
77
|
+
* populations — every object a capture reads, against every value a throw
|
|
78
|
+
* carried — and one shared counter would put `oid` and `serial` in the same
|
|
79
|
+
* sequence, which reads as a relation between two records that have none. Held
|
|
80
|
+
* weakly, so remembering an identity never keeps an object alive; minted once
|
|
81
|
+
* per object and never reused, so one number means one object for the life of
|
|
82
|
+
* the container and the same object wherever it is seen again.
|
|
83
|
+
*/
|
|
84
|
+
let nextOid = 1;
|
|
85
|
+
/** @type {WeakMap<object, number>} */
|
|
86
|
+
const oids = new WeakMap();
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* @param {object} o
|
|
90
|
+
* @returns {number} minted once per object, never reused
|
|
91
|
+
*/
|
|
92
|
+
function oidOf(o) {
|
|
93
|
+
let id = oids.get(o);
|
|
94
|
+
if (id === undefined) {
|
|
95
|
+
id = nextOid++;
|
|
96
|
+
oids.set(o, id);
|
|
97
|
+
}
|
|
98
|
+
return id;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* @param {unknown} v
|
|
103
|
+
* @returns {v is object}
|
|
104
|
+
*/
|
|
105
|
+
function isObject(v) {
|
|
106
|
+
return v !== null && (typeof v === 'object' || typeof v === 'function');
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* @param {object} v
|
|
111
|
+
* @returns {string}
|
|
112
|
+
*/
|
|
113
|
+
function ctorName(v) {
|
|
114
|
+
// A throwing getter is not a timer. Falling through lets `inspect` read the
|
|
115
|
+
// value and `typeOf` report `unread`.
|
|
116
|
+
try {
|
|
117
|
+
const ctor = /** @type {{constructor?: unknown}} */ (v).constructor;
|
|
118
|
+
return typeof ctor === 'function' && typeof ctor.name === 'string' ? ctor.name : '';
|
|
119
|
+
} catch {
|
|
120
|
+
return '';
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* @param {object} v
|
|
126
|
+
* @param {string} name
|
|
127
|
+
* @returns {boolean}
|
|
128
|
+
*/
|
|
129
|
+
function hasMethod(v, name) {
|
|
130
|
+
try {
|
|
131
|
+
return typeof /** @type {Record<string, unknown>} */ (v)[name] === 'function';
|
|
132
|
+
} catch {
|
|
133
|
+
return false;
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Node's `Timeout` (`setTimeout` / `setInterval`). It is not a thenable.
|
|
139
|
+
* @param {unknown} v
|
|
140
|
+
* @returns {boolean}
|
|
141
|
+
*/
|
|
142
|
+
function isTimeout(v) {
|
|
143
|
+
return isObject(v) && ctorName(v) === 'Timeout' && hasMethod(v, 'ref') && hasMethod(v, 'refresh');
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Node's `Immediate` (`setImmediate`).
|
|
148
|
+
* @param {unknown} v
|
|
149
|
+
* @returns {boolean}
|
|
150
|
+
*/
|
|
151
|
+
function isImmediate(v) {
|
|
152
|
+
return isObject(v) && ctorName(v) === 'Immediate' && hasMethod(v, 'ref') && hasMethod(v, 'hasRef');
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* A real promise: `then` is a function, and the value is one this process
|
|
157
|
+
* treats as a Promise. An arbitrary thenable is left to `inspect`.
|
|
158
|
+
* @param {unknown} v
|
|
159
|
+
* @returns {v is Promise<unknown>}
|
|
160
|
+
*/
|
|
161
|
+
function isPromise(v) {
|
|
162
|
+
if (!isObject(v) || !util.types.isPromise(v)) return false;
|
|
163
|
+
return typeof /** @type {{then?: unknown}} */ (v).then === 'function';
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/**
|
|
167
|
+
* `Promise { <pending> }`, `Promise { <fulfilled> }`, or `Promise { <rejected> }`.
|
|
168
|
+
* The state word is the prefix of `inspect`, never a fulfilled value that
|
|
169
|
+
* happens to mention the same word.
|
|
170
|
+
* @param {string} text
|
|
171
|
+
* @returns {string}
|
|
172
|
+
*/
|
|
173
|
+
function promiseSummary(text) {
|
|
174
|
+
const mark = /^[^{]*\{\s*<(pending|rejected)>/.exec(text);
|
|
175
|
+
if (mark !== null && (mark[1] === 'pending' || mark[1] === 'rejected')) {
|
|
176
|
+
return `Promise { <${mark[1]}> }`;
|
|
177
|
+
}
|
|
178
|
+
// Fulfilled inspect names Promise and no state word. If it names neither,
|
|
179
|
+
// the state could not be read, so the capture is the one word `Promise`.
|
|
180
|
+
return text.includes('Promise') ? 'Promise { <fulfilled> }' : 'Promise';
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* A short stand-in for a Promise, Timeout, or Immediate, or null when `v`
|
|
185
|
+
* is an ordinary value. Timers are recognized first so their inspect, which
|
|
186
|
+
* prints `_idleNext` and symbols, is never the capture. A promise's
|
|
187
|
+
* fulfillment is not walked, so a promise of a timer stays a promise summary.
|
|
188
|
+
* @param {unknown} v
|
|
189
|
+
* @returns {string|null}
|
|
190
|
+
*/
|
|
191
|
+
function summaryOf(v) {
|
|
192
|
+
if (isTimeout(v)) return 'Timeout';
|
|
193
|
+
if (isImmediate(v)) return 'Immediate';
|
|
194
|
+
if (!isPromise(v)) return null;
|
|
195
|
+
return promiseSummary(util.inspect(v, PROMISE_INSPECT));
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* Capture a value — a RETURN's, a focused CALL's argument, a statement's delta.
|
|
200
|
+
* @param {unknown} v
|
|
201
|
+
* @returns {Captured}
|
|
202
|
+
*/
|
|
203
|
+
export function dbg(v) {
|
|
204
|
+
// The common case — an instrumented function that returns nothing — never
|
|
205
|
+
// reaches the inspector.
|
|
206
|
+
if (v === undefined) return { k: 'dbg', v: 'undefined', trunc: false };
|
|
207
|
+
let text;
|
|
208
|
+
try {
|
|
209
|
+
// Summarize before the byte cap, so a timer or a promise is the short
|
|
210
|
+
// text and `trunc` stays false.
|
|
211
|
+
text = summaryOf(v) ?? util.inspect(v, INSPECT);
|
|
212
|
+
} catch {
|
|
213
|
+
return { k: 'unread' };
|
|
214
|
+
}
|
|
215
|
+
const { v: text_, trunc } = cap(text);
|
|
216
|
+
/** @type {Dbg} */
|
|
217
|
+
const out = { k: 'dbg', v: text_, trunc };
|
|
218
|
+
const t = typeof v;
|
|
219
|
+
// `null` is `typeof "object"` and is a primitive all the same.
|
|
220
|
+
if (v !== null && (t === 'object' || t === 'function')) {
|
|
221
|
+
out.oid = oidOf(/** @type {object} */ (v));
|
|
222
|
+
out.type = typeOf(v);
|
|
223
|
+
}
|
|
224
|
+
return out;
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/**
|
|
228
|
+
* The byte budget, applied to any string this recorder puts on the wire that
|
|
229
|
+
* the CONSUMER supplied — an inspected value, a test name the harness handed
|
|
230
|
+
* us (R14). The cut falls between characters and never through one, so a
|
|
231
|
+
* truncated capture is still text; what was cut is always declared.
|
|
232
|
+
* @param {string} text
|
|
233
|
+
* @returns {{v: string, trunc: boolean}}
|
|
234
|
+
*/
|
|
235
|
+
export function cap(text) {
|
|
236
|
+
if (Buffer.byteLength(text) <= CAP) return { v: text, trunc: false };
|
|
237
|
+
let bytes = 0;
|
|
238
|
+
let end = 0;
|
|
239
|
+
for (const ch of text) {
|
|
240
|
+
const width = Buffer.byteLength(ch);
|
|
241
|
+
if (bytes + width > CAP) break;
|
|
242
|
+
bytes += width;
|
|
243
|
+
end += ch.length;
|
|
244
|
+
}
|
|
245
|
+
return { v: text.slice(0, end), trunc: true };
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* Describe a thrown or rejected value. Both strings it reads came from the
|
|
250
|
+
* consumer, so both are capped (R14a) and a cut is DECLARED in the contract's
|
|
251
|
+
* own spelling (TRACE-FORMAT §5): `trunc` for a cut message, `type_trunc` for a
|
|
252
|
+
* cut type name, each absent when nothing was cut — which is what tells a
|
|
253
|
+
* reader that a text is a whole identity and may be compared as one.
|
|
254
|
+
* @param {*} e the value the program threw
|
|
255
|
+
* @param {'throw'|'rejection'} kind how it arrived
|
|
256
|
+
* @returns {Record<string, unknown>} `{kind, type, msg, serial}` and the flags
|
|
257
|
+
*/
|
|
258
|
+
export function exc(e, kind) {
|
|
259
|
+
const type = cap(typeOf(e));
|
|
260
|
+
const msg = cap(msgOf(e));
|
|
261
|
+
// A message is a sentence the program wrote, not a value with an identity,
|
|
262
|
+
// so the CONTENT rule is the only one it meets (§2.3) — the span goes and
|
|
263
|
+
// the sentence around it stays. `trunc` is untouched by that: the text WAS
|
|
264
|
+
// clipped, and a span inside it was replaced.
|
|
265
|
+
const found = current().knobs.off ? { text: msg.v, hit: false } : content(msg.v);
|
|
266
|
+
/** @type {Record<string, unknown>} */
|
|
267
|
+
const out = { kind, type: type.v, msg: found.text, serial: serialOf(e) };
|
|
268
|
+
if (msg.trunc) out.trunc = true;
|
|
269
|
+
if (type.trunc) out.type_trunc = true;
|
|
270
|
+
if (found.hit) out.redacted = { by: 'content', digest: null };
|
|
271
|
+
return out;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/**
|
|
275
|
+
* The constructor's name for an object or a function, `typeof` for a primitive
|
|
276
|
+
* (`null` included, which is `object`), and `unread` when the object lies about
|
|
277
|
+
* its own constructor.
|
|
278
|
+
* @param {*} e
|
|
279
|
+
* @returns {string}
|
|
280
|
+
*/
|
|
281
|
+
function typeOf(e) {
|
|
282
|
+
const t = typeof e;
|
|
283
|
+
if (e === null || (t !== 'object' && t !== 'function')) return t;
|
|
284
|
+
try {
|
|
285
|
+
const name = e.constructor?.name;
|
|
286
|
+
return typeof name === 'string' ? name : 'unread';
|
|
287
|
+
} catch {
|
|
288
|
+
return 'unread';
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
/**
|
|
293
|
+
* `e.message` where there is one, the value's own string form otherwise, and
|
|
294
|
+
* `<unread>` when either read throws — a getter that raises, an object with no
|
|
295
|
+
* prototype, a Symbol.
|
|
296
|
+
* @param {*} e
|
|
297
|
+
* @returns {string}
|
|
298
|
+
*/
|
|
299
|
+
function msgOf(e) {
|
|
300
|
+
try {
|
|
301
|
+
const t = typeof e;
|
|
302
|
+
if (e !== null && (t === 'object' || t === 'function') && 'message' in e) {
|
|
303
|
+
return String(e.message);
|
|
304
|
+
}
|
|
305
|
+
return String(e);
|
|
306
|
+
} catch {
|
|
307
|
+
return '<unread>';
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/**
|
|
312
|
+
* One serial per thrown OBJECT, minted once and remembered weakly, so a rethrow
|
|
313
|
+
* is followable; a fresh one for every primitive, because two equal strings are
|
|
314
|
+
* not the same throw and this recorder will not claim they are.
|
|
315
|
+
* @param {*} e
|
|
316
|
+
* @returns {number}
|
|
317
|
+
*/
|
|
318
|
+
function serialOf(e) {
|
|
319
|
+
const t = typeof e;
|
|
320
|
+
if (e === null || (t !== 'object' && t !== 'function')) return nextSerial++;
|
|
321
|
+
let serial = serials.get(e);
|
|
322
|
+
if (serial === undefined) {
|
|
323
|
+
serial = nextSerial++;
|
|
324
|
+
serials.set(e, serial);
|
|
325
|
+
}
|
|
326
|
+
return serial;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* A `[name, value, name, value, ...]` list, as the map the wire carries.
|
|
331
|
+
* Names are the transform's; values are the program's, so every value goes
|
|
332
|
+
* through `dbg` and no name does. An odd list throws: the transform emits
|
|
333
|
+
* both halves, and dropping the trailing name would hide a splice defect.
|
|
334
|
+
* The runtime calls this only for a call it is going to store.
|
|
335
|
+
* @param {unknown[]} pairs
|
|
336
|
+
* @returns {Record<string, Captured>}
|
|
337
|
+
*/
|
|
338
|
+
export function captures(pairs) {
|
|
339
|
+
if (pairs.length % 2 !== 0) throw new TypeError('captures: an odd pairs list — ' + pairs.length + ' entries');
|
|
340
|
+
/** @type {Record<string, Captured>} */
|
|
341
|
+
const out = {};
|
|
342
|
+
for (let i = 0; i + 1 < pairs.length; i += 2) {
|
|
343
|
+
out[/** @type {string} */ (pairs[i])] = dbg(pairs[i + 1]);
|
|
344
|
+
}
|
|
345
|
+
// Rule v1's NAME half, before the record exists, so the plaintext of a
|
|
346
|
+
// secret-shaped name never reaches the disk.
|
|
347
|
+
return redactCaptures(out);
|
|
348
|
+
}
|