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,15 @@
|
|
|
1
|
+
// `node --import <pkg>/src/register.mjs --test <file.ts>`.
|
|
2
|
+
//
|
|
3
|
+
// Nothing here transforms anything: it installs `hook.mjs` on Node's loader
|
|
4
|
+
// thread and checks, once, that the two things the hook cannot invent are set.
|
|
5
|
+
// A missing variable refuses by name here rather than letting the run finish
|
|
6
|
+
// green with an empty spool — a recorder that records nothing must say so.
|
|
7
|
+
import { register } from 'node:module';
|
|
8
|
+
|
|
9
|
+
for (const name of ['SENSORIUM_TS_ROOT', 'SENSORIUM_TS_PKG']) {
|
|
10
|
+
if (!process.env[name]) {
|
|
11
|
+
throw new Error(`sensorium-ts: ${name} is not set; refusing to register a hook with no scope`);
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
register(new URL('./hook.mjs', import.meta.url));
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
// What `--focus` selects, answered BEFORE the run. `node src/resolve.mjs`,
|
|
2
|
+
// reading the root and the specs from the environment, one JSON line out.
|
|
3
|
+
//
|
|
4
|
+
// The driver runs this and refuses on what comes back, so the caller learns a
|
|
5
|
+
// mistyped spec in the second it takes to walk the tree rather than in the
|
|
6
|
+
// minutes it takes to run a suite that recorded the wrong thing — or nothing.
|
|
7
|
+
// A focus that matched nothing is the worst of the two: the transform would
|
|
8
|
+
// splice no statement probes at all, the runtime would still declare `line`,
|
|
9
|
+
// and the trace would say the recorder looked and found nothing to say.
|
|
10
|
+
//
|
|
11
|
+
// It reuses the transform's OWN pass one (`sitesOf`) and the same matcher the
|
|
12
|
+
// transform splices with (`focus.mjs`), so the two cannot disagree about what a
|
|
13
|
+
// spec selects. Nothing here splices, writes, or runs the consumer's code: it
|
|
14
|
+
// reads files and parses them.
|
|
15
|
+
//
|
|
16
|
+
// Environment (all three set by the driver; the first two are required here):
|
|
17
|
+
// SENSORIUM_TS_ROOT the project directory to walk
|
|
18
|
+
// SENSORIUM_FOCUS the specs, joined by the unit separator
|
|
19
|
+
// SENSORIUM_TS_PKG this package — unread: this script's imports are its own
|
|
20
|
+
// siblings, and it is exported only so the resolver's
|
|
21
|
+
// environment is the harness's
|
|
22
|
+
//
|
|
23
|
+
// Exit 0 with one JSON line on stdout, ALWAYS — an unmatched spec is an answer,
|
|
24
|
+
// not a failure, and the driver is what turns it into a refusal. Exit 2 with one
|
|
25
|
+
// line on stderr is reserved for a call this script cannot make sense of at all:
|
|
26
|
+
// a missing variable, a root that is not a directory, a consumer with no
|
|
27
|
+
// TypeScript to parse with.
|
|
28
|
+
import fs from 'node:fs';
|
|
29
|
+
import { createRequire } from 'node:module';
|
|
30
|
+
import path from 'node:path';
|
|
31
|
+
import { pathToFileURL } from 'node:url';
|
|
32
|
+
|
|
33
|
+
import { closest, parseSpec, specMatches, specsFromEnv } from './focus.mjs';
|
|
34
|
+
import { ANONYMOUS } from './qualname.mjs';
|
|
35
|
+
import { classify, sitesOf } from './transform.mjs';
|
|
36
|
+
|
|
37
|
+
/** Directories the walk never enters: dependencies, and our own workspace. */
|
|
38
|
+
const SKIP_DIRS = new Set(['node_modules', '.sensorium']);
|
|
39
|
+
|
|
40
|
+
/** How many names an unmatched spec is offered. */
|
|
41
|
+
const SUGGESTIONS = 3;
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* One line on stderr and exit 2. The caller is the driver, which prints this
|
|
45
|
+
* verbatim behind its own `error:`, so it is a sentence and not a stack.
|
|
46
|
+
* @param {string} message
|
|
47
|
+
* @returns {never}
|
|
48
|
+
*/
|
|
49
|
+
function refuse(message) {
|
|
50
|
+
process.stderr.write(`${message}\n`);
|
|
51
|
+
process.exit(2);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Every file under `dir`, recursively, in name order.
|
|
56
|
+
*
|
|
57
|
+
* A SYMLINK is not followed — neither a linked directory (a cycle is a hang,
|
|
58
|
+
* and `node_modules` is full of them) nor a linked file, whose real path is
|
|
59
|
+
* walked already when it is under the root and is not this recorder's business
|
|
60
|
+
* when it is not.
|
|
61
|
+
* @param {string} dir
|
|
62
|
+
* @returns {Generator<string>}
|
|
63
|
+
*/
|
|
64
|
+
function* walk(dir) {
|
|
65
|
+
/** @type {fs.Dirent[]} */
|
|
66
|
+
let entries;
|
|
67
|
+
try {
|
|
68
|
+
entries = fs.readdirSync(dir, { withFileTypes: true });
|
|
69
|
+
} catch {
|
|
70
|
+
// A directory that cannot be read is not a reason to refuse a focus the
|
|
71
|
+
// rest of the tree can answer: it offers no files, and the walk goes on.
|
|
72
|
+
return;
|
|
73
|
+
}
|
|
74
|
+
for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
|
|
75
|
+
const full = path.join(dir, entry.name);
|
|
76
|
+
if (entry.isDirectory()) {
|
|
77
|
+
if (!SKIP_DIRS.has(entry.name)) yield* walk(full);
|
|
78
|
+
} else if (entry.isFile()) {
|
|
79
|
+
yield full;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Pass one over every eligible file under the root.
|
|
86
|
+
*
|
|
87
|
+
* `deps` is how a test hands this a `sitesOf` that THROWS: the consumer's own
|
|
88
|
+
* TypeScript parses files this recorder did not write, and a throw from it
|
|
89
|
+
* used to take the whole resolution down — a focus nobody could resolve
|
|
90
|
+
* because one file in the tree was unreadable. It is now counted with the
|
|
91
|
+
* unparsable and named on stderr, so the numbers still reconcile and the
|
|
92
|
+
* subtraction is not silent.
|
|
93
|
+
* @param {string} root
|
|
94
|
+
* @param {typeof import('typescript')} ts
|
|
95
|
+
* @param {{sitesOf: typeof sitesOf}} [deps]
|
|
96
|
+
* @returns {{eligible: {rel: string, qualname: string, line: number, kind: string,
|
|
97
|
+
* deferred: boolean}[],
|
|
98
|
+
* excluded: {rel: string, qualname: string, line: number, reason: string}[],
|
|
99
|
+
* scanned: number, unparsable: number}}
|
|
100
|
+
*/
|
|
101
|
+
export function survey(root, ts, deps = { sitesOf }) {
|
|
102
|
+
/** @type {{rel: string, qualname: string, line: number, kind: string, deferred: boolean}[]} */
|
|
103
|
+
const eligible = [];
|
|
104
|
+
/** @type {{rel: string, qualname: string, line: number, reason: string}[]} */
|
|
105
|
+
const excluded = [];
|
|
106
|
+
let scanned = 0;
|
|
107
|
+
let unparsable = 0;
|
|
108
|
+
for (const file of walk(root)) {
|
|
109
|
+
if (classify(file, root) !== 'transform') continue;
|
|
110
|
+
scanned += 1;
|
|
111
|
+
/** @type {string} */
|
|
112
|
+
let code;
|
|
113
|
+
try {
|
|
114
|
+
code = fs.readFileSync(file, 'utf8');
|
|
115
|
+
} catch {
|
|
116
|
+
// Counted with the unparsable: either way the file offered no sites,
|
|
117
|
+
// and a resolver that dropped it silently would make `files_scanned`
|
|
118
|
+
// a number nobody could reconcile.
|
|
119
|
+
unparsable += 1;
|
|
120
|
+
continue;
|
|
121
|
+
}
|
|
122
|
+
const rel = path.relative(root, file).split(path.sep).join('/');
|
|
123
|
+
/** @type {ReturnType<typeof sitesOf>} */
|
|
124
|
+
let out;
|
|
125
|
+
try {
|
|
126
|
+
out = deps.sitesOf(code, file, { root, ts });
|
|
127
|
+
} catch (e) {
|
|
128
|
+
unparsable += 1;
|
|
129
|
+
process.stderr.write(`resolve: ${rel}: ${/** @type {Error} */ (e).message}\n`);
|
|
130
|
+
continue;
|
|
131
|
+
}
|
|
132
|
+
if (out === null) continue;
|
|
133
|
+
if (out.excluded['parse-error']) {
|
|
134
|
+
unparsable += 1;
|
|
135
|
+
continue;
|
|
136
|
+
}
|
|
137
|
+
for (const site of out.sites) {
|
|
138
|
+
eligible.push({
|
|
139
|
+
rel: out.rel,
|
|
140
|
+
qualname: site.qualname,
|
|
141
|
+
line: site.line,
|
|
142
|
+
kind: site.kind,
|
|
143
|
+
// Whether the seal moves this function's wrapper (§4.2): a fact about
|
|
144
|
+
// its shape, asked before the run like every other thing here.
|
|
145
|
+
deferred: site.deferred,
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
for (const site of out.excludedSites) {
|
|
149
|
+
excluded.push({ rel: out.rel, qualname: site.qualname, line: site.line, reason: site.reason });
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
return { eligible, excluded, scanned, unparsable };
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* The names an unmatched spec is offered, in order.
|
|
157
|
+
*
|
|
158
|
+
* A name with an `<anonymous>` segment is left out: it is not a name the
|
|
159
|
+
* caller can type back (`<` is the shell's, and an anonymous function carries
|
|
160
|
+
* no ordinal to tell it from its siblings), and a suggestion nobody can retype
|
|
161
|
+
* is worse than none — it fills the three slots a usable name wanted.
|
|
162
|
+
* @param {{qualname: string}[]} eligible
|
|
163
|
+
* @param {string} spec
|
|
164
|
+
* @returns {string[]}
|
|
165
|
+
*/
|
|
166
|
+
function suggestions(eligible, spec) {
|
|
167
|
+
const names = [...new Set(eligible.map((site) => site.qualname))]
|
|
168
|
+
.filter((name) => !name.split('.').includes(ANONYMOUS));
|
|
169
|
+
if (names.length === 0) return [];
|
|
170
|
+
return closest(names, parseSpec(spec).qualname, SUGGESTIONS);
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* @param {{rel: string, qualname: string, line: number, reason: string}[]} hits
|
|
175
|
+
* @returns {Record<string, number>} how many of each reason, for the refusal
|
|
176
|
+
*/
|
|
177
|
+
function reasonsOf(hits) {
|
|
178
|
+
/** @type {Record<string, number>} */
|
|
179
|
+
const reasons = {};
|
|
180
|
+
for (const hit of hits) reasons[hit.reason] = (reasons[hit.reason] ?? 0) + 1;
|
|
181
|
+
return reasons;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
function main() {
|
|
185
|
+
const rootVar = process.env.SENSORIUM_TS_ROOT;
|
|
186
|
+
if (!rootVar) refuse('SENSORIUM_TS_ROOT names no directory: the resolver walks a project root');
|
|
187
|
+
const root = path.resolve(/** @type {string} */ (rootVar));
|
|
188
|
+
if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
|
|
189
|
+
refuse(`${root} is not a directory: the resolver walks a project root`);
|
|
190
|
+
}
|
|
191
|
+
const specs = specsFromEnv(process.env.SENSORIUM_FOCUS ?? '');
|
|
192
|
+
if (specs.length === 0) {
|
|
193
|
+
refuse('SENSORIUM_FOCUS names no spec: the resolver answers a focus, and there is none');
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
// The consumer's own TypeScript, resolved from the ROOT exactly as the
|
|
197
|
+
// loader hook and the Vite plugin resolve it: the sites this reports are
|
|
198
|
+
// the sites the transform will find, or they are somebody else's AST.
|
|
199
|
+
const require = createRequire(path.join(root, 'package.json'));
|
|
200
|
+
/** @type {typeof import('typescript')} */
|
|
201
|
+
let ts;
|
|
202
|
+
try {
|
|
203
|
+
ts = require('typescript');
|
|
204
|
+
} catch {
|
|
205
|
+
refuse(`${root} has no typescript in node_modules: the resolver reads the same AST the `
|
|
206
|
+
+ 'transform will, and there is none here to read it with');
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
const { eligible, excluded, scanned, unparsable } = survey(root, /** @type {any} */ (ts));
|
|
210
|
+
|
|
211
|
+
/** @type {{rel: string, qualname: string, line: number, kind: string, deferred: boolean}[]} */
|
|
212
|
+
const matched = [];
|
|
213
|
+
const seen = new Set();
|
|
214
|
+
/** @type {{spec: string, closest: string[]}[]} */
|
|
215
|
+
const unmatched = [];
|
|
216
|
+
/** @type {{spec: string, reasons: Record<string, number>}[]} */
|
|
217
|
+
const excludedOnly = [];
|
|
218
|
+
for (const spec of specs) {
|
|
219
|
+
const hits = eligible.filter((site) => specMatches(spec, site.rel, site.qualname));
|
|
220
|
+
if (hits.length > 0) {
|
|
221
|
+
// One entry per FUNCTION, not per spec: two specs that name the same
|
|
222
|
+
// function focus it once, and `focus_matched` says so once.
|
|
223
|
+
for (const hit of hits) {
|
|
224
|
+
const key = `${hit.rel}:${hit.qualname}:${hit.line}`;
|
|
225
|
+
if (seen.has(key)) continue;
|
|
226
|
+
seen.add(key);
|
|
227
|
+
matched.push(hit);
|
|
228
|
+
}
|
|
229
|
+
continue;
|
|
230
|
+
}
|
|
231
|
+
const skipped = excluded.filter((site) => specMatches(spec, site.rel, site.qualname));
|
|
232
|
+
if (skipped.length > 0) excludedOnly.push({ spec, reasons: reasonsOf(skipped) });
|
|
233
|
+
else unmatched.push({ spec, closest: suggestions(eligible, spec) });
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
process.stdout.write(`${JSON.stringify({
|
|
237
|
+
matched,
|
|
238
|
+
unmatched,
|
|
239
|
+
excluded_only: excludedOnly,
|
|
240
|
+
files_scanned: scanned,
|
|
241
|
+
files_unparsable: unparsable,
|
|
242
|
+
})}\n`);
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
// Run only as the script the driver starts, never as the module a test
|
|
246
|
+
// imports for `survey`: `main` reads the environment and exits, and an import
|
|
247
|
+
// that did that would refuse the test run rather than answer it. The entry
|
|
248
|
+
// path is realpath'd because Node resolves the main module through symlinks
|
|
249
|
+
// and `import.meta.url` is the resolved one.
|
|
250
|
+
function invokedDirectly() {
|
|
251
|
+
const entry = process.argv[1];
|
|
252
|
+
if (!entry) return false;
|
|
253
|
+
try {
|
|
254
|
+
return pathToFileURL(fs.realpathSync(entry)).href === import.meta.url;
|
|
255
|
+
} catch {
|
|
256
|
+
return false;
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
if (invokedDirectly()) main();
|