sensorium-trace 0.18.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. sensorium/__init__.py +0 -0
  2. sensorium/__main__.py +4 -0
  3. sensorium/_c/rt/sensorium_c_rt.c +1446 -0
  4. sensorium/_typescript/package-lock.json +68 -0
  5. sensorium/_typescript/package.json +39 -0
  6. sensorium/_typescript/src/bindings.mjs +792 -0
  7. sensorium/_typescript/src/cap.mjs +227 -0
  8. sensorium/_typescript/src/capabilities.mjs +40 -0
  9. sensorium/_typescript/src/dbg.mjs +348 -0
  10. sensorium/_typescript/src/escape.mjs +351 -0
  11. sensorium/_typescript/src/focus.mjs +135 -0
  12. sensorium/_typescript/src/hook.mjs +127 -0
  13. sensorium/_typescript/src/index.mjs +1 -0
  14. sensorium/_typescript/src/naming.mjs +63 -0
  15. sensorium/_typescript/src/positions.mjs +37 -0
  16. sensorium/_typescript/src/probe.mjs +246 -0
  17. sensorium/_typescript/src/qualname.mjs +236 -0
  18. sensorium/_typescript/src/redact.mjs +711 -0
  19. sensorium/_typescript/src/register.mjs +15 -0
  20. sensorium/_typescript/src/resolve.mjs +260 -0
  21. sensorium/_typescript/src/rt.mjs +798 -0
  22. sensorium/_typescript/src/setup.mjs +11 -0
  23. sensorium/_typescript/src/tally.mjs +164 -0
  24. sensorium/_typescript/src/tasks.mjs +175 -0
  25. sensorium/_typescript/src/transform.mjs +800 -0
  26. sensorium/_typescript/src/vite.mjs +99 -0
  27. sensorium/c/__init__.py +8 -0
  28. sensorium/c/cc.py +612 -0
  29. sensorium/c/cli.py +60 -0
  30. sensorium/c/convert.py +669 -0
  31. sensorium/c/decode.py +300 -0
  32. sensorium/c/driver.py +365 -0
  33. sensorium/c/dwarf.py +706 -0
  34. sensorium/c/format.py +271 -0
  35. sensorium/c/pkg.py +187 -0
  36. sensorium/c/plan.py +277 -0
  37. sensorium/cli.py +140 -0
  38. sensorium/driver.py +47 -0
  39. sensorium/exit.py +33 -0
  40. sensorium/invocations.py +83 -0
  41. sensorium/limits.py +253 -0
  42. sensorium/mcp/__init__.py +0 -0
  43. sensorium/mcp/audit.py +162 -0
  44. sensorium/mcp/child.py +240 -0
  45. sensorium/mcp/cmd.py +101 -0
  46. sensorium/mcp/jsonrpc.py +172 -0
  47. sensorium/mcp/result.py +187 -0
  48. sensorium/mcp/schema.py +390 -0
  49. sensorium/mcp/server.py +493 -0
  50. sensorium/mcp/tools.py +299 -0
  51. sensorium/paths.py +80 -0
  52. sensorium/query/__init__.py +0 -0
  53. sensorium/query/caps.py +150 -0
  54. sensorium/query/dbg_dialects.py +64 -0
  55. sensorium/query/diff_cmd.py +748 -0
  56. sensorium/query/diff_notes.py +117 -0
  57. sensorium/query/exceptions_c.py +263 -0
  58. sensorium/query/exceptions_cmd.py +788 -0
  59. sensorium/query/exceptions_group.py +571 -0
  60. sensorium/query/exceptions_invocation.py +487 -0
  61. sensorium/query/exceptions_rust.py +683 -0
  62. sensorium/query/exceptions_typescript.py +688 -0
  63. sensorium/query/expr.py +606 -0
  64. sensorium/query/failures_cmd.py +306 -0
  65. sensorium/query/flow_cmd.py +778 -0
  66. sensorium/query/flow_report.py +128 -0
  67. sensorium/query/flow_values.py +195 -0
  68. sensorium/query/fmt.py +280 -0
  69. sensorium/query/frame_cmd.py +237 -0
  70. sensorium/query/grep_cmd.py +156 -0
  71. sensorium/query/help.py +18 -0
  72. sensorium/query/info_cmd.py +527 -0
  73. sensorium/query/info_rust.py +214 -0
  74. sensorium/query/info_typescript.py +261 -0
  75. sensorium/query/js_inspect.py +394 -0
  76. sensorium/query/moves.py +254 -0
  77. sensorium/query/redact_cmd.py +304 -0
  78. sensorium/query/refocus_cmd.py +661 -0
  79. sensorium/query/refocus_env.py +493 -0
  80. sensorium/query/refocus_facts.py +269 -0
  81. sensorium/query/refocus_licence.py +187 -0
  82. sensorium/query/refocus_report.py +327 -0
  83. sensorium/query/refocus_rust.py +537 -0
  84. sensorium/query/refocus_threads.py +197 -0
  85. sensorium/query/refocus_typescript.py +756 -0
  86. sensorium/query/refocus_world.py +666 -0
  87. sensorium/query/runs_cmd.py +213 -0
  88. sensorium/query/rust_debug.py +176 -0
  89. sensorium/query/sites.py +171 -0
  90. sensorium/query/tree_cmd.py +511 -0
  91. sensorium/query/tree_threads.py +168 -0
  92. sensorium/query/vocab.py +723 -0
  93. sensorium/query/watch_cmd.py +657 -0
  94. sensorium/record/__init__.py +0 -0
  95. sensorium/record/boot.py +797 -0
  96. sensorium/record/boot_io.py +141 -0
  97. sensorium/record/budget.py +135 -0
  98. sensorium/record/capture.py +433 -0
  99. sensorium/record/children.py +755 -0
  100. sensorium/record/children_merge.py +179 -0
  101. sensorium/record/elide.py +55 -0
  102. sensorium/record/fingerprint.py +26 -0
  103. sensorium/record/thread_starts.py +261 -0
  104. sensorium/record/tracer.py +798 -0
  105. sensorium/record/tracer_exc.py +199 -0
  106. sensorium/record/tracer_frames.py +618 -0
  107. sensorium/redact.py +304 -0
  108. sensorium/redact_content.py +156 -0
  109. sensorium/redact_key.py +317 -0
  110. sensorium/redact_store.py +502 -0
  111. sensorium/redact_values.py +433 -0
  112. sensorium/store/__init__.py +0 -0
  113. sensorium/store/db.py +284 -0
  114. sensorium/store/gc.py +360 -0
  115. sensorium/store/payloads.py +69 -0
  116. sensorium/store/reader.py +438 -0
  117. sensorium/store/writer.py +283 -0
  118. sensorium/ts/__init__.py +10 -0
  119. sensorium/ts/build.py +783 -0
  120. sensorium/ts/cli.py +130 -0
  121. sensorium/ts/driver.py +472 -0
  122. sensorium/ts/focus.py +146 -0
  123. sensorium/ts/harness.py +314 -0
  124. sensorium/ts/ingest.py +380 -0
  125. sensorium/ts/invocation.py +252 -0
  126. sensorium/ts/pkg.py +167 -0
  127. sensorium/ts/redaction.py +64 -0
  128. sensorium/ts/spool.py +168 -0
  129. sensorium/ts/truncation.py +81 -0
  130. sensorium/ts/wrapper.py +255 -0
  131. sensorium_trace-0.18.2.dist-info/METADATA +245 -0
  132. sensorium_trace-0.18.2.dist-info/RECORD +135 -0
  133. sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
  134. sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
  135. sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,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();