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
sensorium/c/decode.py ADDED
@@ -0,0 +1,300 @@
1
+ """Decode raw argument and return bytes into sensorium value tags.
2
+
3
+ Types are plain objects built once by ``dwarf.py``. Decoding never touches
4
+ a DIE. Non-finite floats are ``dbg`` strings so the payload stays JSON.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import math
9
+ import struct
10
+
11
+ from sensorium.c.format import RET_INT, RET_MEM, RET_SSE, RET_VOID, STR_CAP
12
+
13
+ _MASK64 = (1 << 64) - 1
14
+ _DEPTH = 4
15
+ _MEMBERS = 16
16
+ _ARRAY = 8
17
+
18
+
19
+ class Member:
20
+ """One struct or union field. ``bit_pos`` is the LSB from the start
21
+ of the value, or None when the bit offset was not in the DWARF."""
22
+
23
+ __slots__ = ("name", "offset", "typ", "bit_size", "bit_pos")
24
+
25
+ def __init__(self, name, offset, typ, bit_size=None, bit_pos=None):
26
+ self.name = name
27
+ self.offset = offset
28
+ self.typ = typ
29
+ self.bit_size = bit_size
30
+ self.bit_pos = bit_pos
31
+
32
+
33
+ class CType:
34
+ """A resolved type. ``eights`` is set only for a register-returned
35
+ aggregate whose eightbytes are not all the same class."""
36
+
37
+ __slots__ = (
38
+ "kind", "size", "name", "signed", "is_cstr", "is_char",
39
+ "enums", "members", "elem", "count", "eights",
40
+ )
41
+
42
+ def __init__(self, kind, size=0, name="", signed=False, is_cstr=False,
43
+ is_char=False, enums=None, members=None, elem=None,
44
+ count=None, eights=None):
45
+ self.kind = kind
46
+ self.size = size
47
+ self.name = name
48
+ self.signed = signed
49
+ self.is_cstr = is_cstr
50
+ self.is_char = is_char
51
+ self.enums = enums
52
+ self.members = members
53
+ self.elem = elem
54
+ self.count = count
55
+ self.eights = eights
56
+
57
+
58
+ VOID = CType("void", 0, "void")
59
+ UNREAD = CType("unread", 0, "?")
60
+
61
+
62
+ def decode_param(typ, raw, slen, sbytes):
63
+ """``raw`` is the parameter's bytes. ``slen`` / ``sbytes`` are the
64
+ ``FLAG_CSTR`` capture: -2 NULL, -1 fault, 0 empty, else the bytes
65
+ before the NUL. Anything else, including a missing slot, is unread."""
66
+ if typ is None or typ.kind in ("void", "unread"):
67
+ return {"k": "unread"}
68
+ raw = raw or b""
69
+ if typ.kind == "ptr" and typ.is_cstr and slen is not None:
70
+ return _cstr(typ, slen, sbytes)
71
+ return _value(typ, raw, 0)
72
+
73
+
74
+ def decode_return(typ, ret_class, rax, rdx, xmm0, xmm1, mem_bytes):
75
+ """None for void. RET_INT packs rax, plus rdx when the value is wider
76
+ than 8 bytes. RET_SSE unpacks xmm0, plus xmm1 when wider than 8, and
77
+ the scalar float path reads f32 or f64 from the low bytes. RET_MEM
78
+ decodes ``mem_bytes``. A short buffer is unread.
79
+
80
+ A struct whose eightbytes use both register files keeps that map on
81
+ the type. The V record always carries rax, rdx, xmm0 and xmm1, so the
82
+ bytes are reassembled from the class of each eightbyte."""
83
+ if typ is None or typ.kind == "void" or ret_class == RET_VOID:
84
+ return None
85
+ if ret_class == RET_MEM:
86
+ buf = mem_bytes or b""
87
+ if typ.size and len(buf) < typ.size:
88
+ return {"k": "unread"}
89
+ return decode_param(typ, buf, None, None)
90
+ if typ.eights:
91
+ raw = _assemble(typ, rax, rdx, xmm0, xmm1)
92
+ elif ret_class == RET_SSE:
93
+ raw = _pack(xmm0)
94
+ if typ.size > 8:
95
+ raw += _pack(xmm1)
96
+ elif ret_class == RET_INT:
97
+ raw = _pack(rax)
98
+ if typ.size > 8:
99
+ raw += _pack(rdx)
100
+ else:
101
+ return {"k": "unread"}
102
+ if typ.size and len(raw) < typ.size:
103
+ return {"k": "unread"}
104
+ return decode_param(typ, raw, None, None)
105
+
106
+
107
+ def _pack(word) -> bytes:
108
+ return struct.pack("<Q", int(word) & _MASK64)
109
+
110
+
111
+ def _assemble(typ, rax, rdx, xmm0, xmm1) -> bytes:
112
+ pools = {"INT": [rax, rdx], "SSE": [xmm0, xmm1]}
113
+ used = {"INT": 0, "SSE": 0}
114
+ out = bytearray(8 * len(typ.eights))
115
+ for i, cls in enumerate(typ.eights):
116
+ if cls not in pools:
117
+ continue
118
+ n = used[cls]
119
+ used[cls] = n + 1
120
+ word = pools[cls][n] if n < 2 else 0
121
+ out[i * 8:i * 8 + 8] = _pack(word)
122
+ if typ.size and typ.size < len(out):
123
+ return bytes(out[:typ.size])
124
+ return bytes(out)
125
+
126
+
127
+ def _cstr(typ, slen, sbytes):
128
+ if slen == -2:
129
+ return {"k": "dbg", "v": f"({typ.name}) NULL"}
130
+ if slen < 0:
131
+ return {"k": "unread", "type": "char *"}
132
+ if slen == 0:
133
+ return {"k": "str", "v": ""}
134
+ blob = sbytes or b""
135
+ if b"\0" in blob:
136
+ blob = blob.split(b"\0", 1)[0]
137
+ cut = False
138
+ else:
139
+ cut = slen >= STR_CAP and len(blob) >= STR_CAP
140
+ text = blob.decode("utf-8", "replace")
141
+ out = {"k": "str", "v": text}
142
+ if cut:
143
+ out["trunc"] = True
144
+ return out
145
+
146
+
147
+ def _scalar(typ, raw, bit_size):
148
+ if typ.kind == "bool":
149
+ n = _int(raw, typ.size, False, bit_size)
150
+ if n is None:
151
+ return {"k": "unread"}
152
+ return {"k": "bool", "v": n != 0}
153
+ if typ.kind == "float":
154
+ return _float(raw, typ.size)
155
+ if typ.kind == "ptr":
156
+ if len(raw) < 8 and typ.size >= 8:
157
+ return {"k": "unread"}
158
+ width = typ.size or 8
159
+ p = int.from_bytes(raw[:width], "little")
160
+ shown = "NULL" if p == 0 else hex(p)
161
+ return {"k": "dbg", "v": f"({typ.name}) {shown}"}
162
+ if typ.kind == "enum":
163
+ n = _int(raw, typ.size, typ.signed, bit_size)
164
+ if n is None:
165
+ return {"k": "unread"}
166
+ name = typ.enums.get(n) if typ.enums else None
167
+ if name is None:
168
+ return {"k": "num", "v": n}
169
+ return {"k": "dbg", "v": name}
170
+ if typ.kind == "int":
171
+ n = _int(raw, typ.size, typ.signed, bit_size)
172
+ if n is None:
173
+ return {"k": "unread"}
174
+ return {"k": "num", "v": n}
175
+ return {"k": "unread"}
176
+
177
+
178
+ def _int(raw, size, signed, bit_size):
179
+ if bit_size:
180
+ if len(raw) < 1:
181
+ return None
182
+ return int.from_bytes(raw, "little", signed=False)
183
+ if size <= 0 or len(raw) < size:
184
+ return None
185
+ return int.from_bytes(raw[:size], "little", signed=signed)
186
+
187
+
188
+ def _float(raw, size):
189
+ if size == 4 and len(raw) >= 4:
190
+ v = struct.unpack("<f", raw[:4])[0]
191
+ elif size == 8 and len(raw) >= 8:
192
+ v = struct.unpack("<d", raw[:8])[0]
193
+ elif size == 16 and len(raw) >= 16:
194
+ return {"k": "dbg", "v": "0x" + raw[:16].hex()}
195
+ else:
196
+ return {"k": "unread"}
197
+ if isinstance(v, float) and math.isnan(v):
198
+ return {"k": "dbg", "v": "nan"}
199
+ if isinstance(v, float) and math.isinf(v):
200
+ return {"k": "dbg", "v": "-inf" if v < 0 else "inf"}
201
+ return {"k": "num", "v": v}
202
+
203
+
204
+ def _bits(raw, bit_pos, bit_size, signed):
205
+ nbytes = (bit_pos + bit_size + 7) // 8
206
+ if bit_pos < 0 or bit_size <= 0 or len(raw) < nbytes:
207
+ return None
208
+ val = int.from_bytes(raw[:nbytes], "little")
209
+ val = (val >> bit_pos) & ((1 << bit_size) - 1)
210
+ if signed and val >> (bit_size - 1):
211
+ val -= 1 << bit_size
212
+ return val
213
+
214
+
215
+ def _value(typ, raw, depth):
216
+ if typ is None or typ.kind in ("void", "unread"):
217
+ return {"k": "unread"}
218
+ raw = raw or b""
219
+ if typ.kind in ("struct", "union"):
220
+ if typ.size and not raw:
221
+ return {"k": "unread"}
222
+ return _aggregate(typ, raw, depth)
223
+ if typ.kind == "array":
224
+ return _array(typ, raw, depth)
225
+ if typ.size and len(raw) < typ.size:
226
+ return {"k": "unread"}
227
+ return _scalar(typ, raw, 0)
228
+
229
+
230
+ def _aggregate(typ, raw, depth):
231
+ if depth >= _DEPTH:
232
+ return {"k": "dbg", "v": f"{typ.name} {{...}}"}
233
+ parts = []
234
+ members = typ.members or ()
235
+ for m in members[:_MEMBERS]:
236
+ parts.append(f"{m.name}={_show(_member(m, raw, depth))}")
237
+ if len(members) > _MEMBERS:
238
+ parts.append("...")
239
+ return {"k": "dbg", "v": f"{typ.name} {{{', '.join(parts)}}}"}
240
+
241
+
242
+ def _member(m, raw, depth):
243
+ if m.bit_size:
244
+ if m.bit_pos is None:
245
+ return {"k": "unread"}
246
+ n = _bits(raw, m.bit_pos, m.bit_size, bool(m.typ and m.typ.signed))
247
+ if n is None:
248
+ return {"k": "unread"}
249
+ if m.typ is not None and m.typ.kind == "enum":
250
+ name = m.typ.enums.get(n) if m.typ.enums else None
251
+ if name is not None:
252
+ return {"k": "dbg", "v": name}
253
+ if m.typ is not None and m.typ.kind == "bool":
254
+ return {"k": "bool", "v": n != 0}
255
+ return {"k": "num", "v": n}
256
+ return _value(m.typ, raw[m.offset:], depth + 1)
257
+
258
+
259
+ def _array(typ, raw, depth):
260
+ elem = typ.elem
261
+ if elem is not None and elem.is_char:
262
+ n = typ.count if typ.count is not None else len(raw)
263
+ blob = raw[:n]
264
+ nul = blob.find(b"\0")
265
+ if nul >= 0:
266
+ blob = blob[:nul]
267
+ return {"k": "str", "v": blob.decode("utf-8", "replace")}
268
+ if elem is None:
269
+ return {"k": "unread"}
270
+ n = typ.count or 0
271
+ es = elem.size or 1
272
+ shown = []
273
+ for i in range(min(n, _ARRAY)):
274
+ shown.append(_show(_value(elem, raw[i * es:(i + 1) * es], depth + 1)))
275
+ if n > _ARRAY:
276
+ shown.append("...")
277
+ return {"k": "dbg", "v": "[" + ", ".join(shown) + "]"}
278
+
279
+
280
+ def _show(v) -> str:
281
+ """Field text inside a struct. A field that did not decode is ``?``.
282
+
283
+ The word ``unread`` is a capture kind, not something to paste into a
284
+ value that did decode: a struct return is one ``dbg`` string, and a
285
+ reader searching that string must not see a failure the field did
286
+ not have.
287
+ """
288
+ if not isinstance(v, dict):
289
+ return "?"
290
+ k = v.get("k")
291
+ if k == "str":
292
+ return '"' + str(v.get("v", "")).replace("\\", "\\\\").replace(
293
+ '"', '\\"') + '"'
294
+ if k == "bool":
295
+ return "true" if v.get("v") else "false"
296
+ if k == "num":
297
+ return str(v.get("v"))
298
+ if k == "dbg":
299
+ return str(v.get("v", "?"))
300
+ return "?"
sensorium/c/driver.py ADDED
@@ -0,0 +1,365 @@
1
+ """``sensorium c run``: shim the compilers, spawn, wait, convert.
2
+
3
+ The command after ``--`` is the user's, typed as they would type it. This
4
+ driver puts ``gcc``, ``cc`` and ``clang`` shims first on ``PATH``, points
5
+ ``CC`` at the ``cc`` shim, and leaves the runtime off ``LDFLAGS`` (the
6
+ wrapper adds it once; a second copy is a duplicate symbol). The exit
7
+ status is the command's own, or ``128 + n`` when a signal ended it.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ import os
13
+ import subprocess
14
+ import sys
15
+ import threading
16
+ import time
17
+ from pathlib import Path
18
+
19
+ from sensorium import paths
20
+ from sensorium.c import cc as cc_mod
21
+
22
+ SPOOL_DIR = "c-spool"
23
+ _SHIMS = ("gcc", "cc", "clang")
24
+
25
+
26
+ def run(args) -> int:
27
+ command = list(getattr(args, "command", None) or [])
28
+ if command and command[0] == "--":
29
+ command = command[1:]
30
+ if not command:
31
+ print("usage: sensorium c run [--strict] [--no-retval] -- "
32
+ "<command> [args...]", file=sys.stderr)
33
+ return 2
34
+ strict = bool(getattr(args, "strict", False))
35
+ no_retval = bool(getattr(args, "no_retval", False))
36
+ inv_id = paths.new_run_id()
37
+ spool = _make_spool(inv_id)
38
+ bindir = spool / "bin"
39
+ bindir.mkdir(mode=0o700)
40
+ for name in _SHIMS:
41
+ _write_shim(bindir / name)
42
+ env = _env(bindir, spool, strict, no_retval)
43
+ compiler_line = _compiler_version(env.get("SENSORIUM_C_CC", ""))
44
+ started = time.time()
45
+ side = {
46
+ "invocation": inv_id,
47
+ "driver_command": command,
48
+ "cwd": os.getcwd(),
49
+ "compiler": compiler_line,
50
+ "start_ts": started,
51
+ "no_retval": no_retval,
52
+ }
53
+ side_path = spool / "side.json"
54
+ _write_json(side_path, side)
55
+ try:
56
+ proc = subprocess.Popen(
57
+ command, env=env, stdin=None,
58
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE)
59
+ except OSError as e:
60
+ print(f"error: cannot start {command[0]}: {e.strerror}",
61
+ file=sys.stderr)
62
+ return 2
63
+ threads = [
64
+ threading.Thread(target=_pump,
65
+ args=(proc.stdout, spool / "stdout.bin",
66
+ _binary(sys.stdout)),
67
+ daemon=False),
68
+ threading.Thread(target=_pump,
69
+ args=(proc.stderr, spool / "stderr.bin",
70
+ _binary(sys.stderr)),
71
+ daemon=False),
72
+ ]
73
+ for thread in threads:
74
+ thread.start()
75
+ side["root_pid"] = proc.pid
76
+ _write_json(side_path, side)
77
+ returncode = proc.wait()
78
+ for thread in threads:
79
+ thread.join()
80
+ ended = time.time()
81
+ if returncode < 0:
82
+ harness = {"signal": -returncode, "basis": "waited"}
83
+ else:
84
+ harness = {"status": returncode, "basis": "waited"}
85
+ side["end_ts"] = ended
86
+ side["harness_exit"] = harness
87
+ warnings = _read_warnings(spool / "build-warnings.txt")
88
+ if warnings is not None:
89
+ side["build_warnings"] = warnings
90
+ _write_json(side_path, side)
91
+ return _finish(spool, inv_id, returncode)
92
+
93
+
94
+ def _make_spool(inv_id: str) -> Path:
95
+ """``<trace root>/c-spool/<invocation>``, each level mode 0700.
96
+
97
+ One ``mkdir(parents=True, mode=0o700)`` would leave the store root,
98
+ which holds ``redaction.key``, at the platform default. An existing
99
+ directory is not chmod'ed.
100
+ """
101
+ root = paths.trace_root()
102
+ root.mkdir(parents=True, exist_ok=True, mode=0o700)
103
+ parent = root / SPOOL_DIR
104
+ parent.mkdir(exist_ok=True, mode=0o700)
105
+ spool = parent / inv_id
106
+ spool.mkdir(exist_ok=True, mode=0o700)
107
+ return spool
108
+
109
+
110
+ def _write_shim(path: Path) -> None:
111
+ """A Python script whose argv0 is ``gcc``, ``cc`` or ``clang``.
112
+
113
+ The shebang is this interpreter. The body calls
114
+ ``sensorium.c.cc.main``, so the wrapper sees the shim's argv0 and
115
+ chooses the real compiler from that name.
116
+ """
117
+ exe = sys.executable or "/usr/bin/python3"
118
+ text = (
119
+ f"#!{exe}\n"
120
+ "import sys\n"
121
+ "from sensorium.c.cc import main\n"
122
+ "sys.exit(main())\n"
123
+ )
124
+ path.write_text(text, encoding="utf-8")
125
+ path.chmod(0o755)
126
+
127
+
128
+ def _env(bindir: Path, spool: Path, strict: bool, no_retval: bool) -> dict:
129
+ """The child's environment. The real ``cc`` is resolved first.
130
+
131
+ ``SENSORIUM_C_CC`` is the previous ``CC`` when that value is an
132
+ absolute path, otherwise the absolute ``cc`` found on the original
133
+ ``PATH`` (before the shim directory is prepended). ``LDFLAGS`` is
134
+ left alone: the wrapper links the runtime, and a second copy is a
135
+ duplicate symbol.
136
+ """
137
+ original_path = os.environ.get("PATH", "")
138
+ previous_cc = os.environ.get("CC", "")
139
+ if os.path.isabs(previous_cc) and _real_compiler(previous_cc):
140
+ real_cc = previous_cc
141
+ else:
142
+ real_cc = _which_cc(original_path)
143
+ env = dict(os.environ)
144
+ env["PATH"] = os.fspath(bindir) + os.pathsep + original_path
145
+ env["CC"] = os.fspath(bindir / "cc")
146
+ env["SENSORIUM_C_CC"] = real_cc
147
+ env["SENSORIUM_C_ROOT"] = os.fspath(spool)
148
+ if strict:
149
+ env["SENSORIUM_C_STRICT"] = "1"
150
+ else:
151
+ env.pop("SENSORIUM_C_STRICT", None)
152
+ if no_retval:
153
+ env["SENSORIUM_C_NO_RETVAL"] = "1"
154
+ else:
155
+ env.pop("SENSORIUM_C_NO_RETVAL", None)
156
+ flags = " ".join(cc_mod.instrument_flags(real_cc))
157
+ env["CFLAGS"] = _append_flags(env.get("CFLAGS", ""), flags)
158
+ env["CMAKE_C_COMPILER_LAUNCHER"] = os.fspath(bindir / "cc")
159
+ env["CMAKE_C_FLAGS"] = _append_flags(env.get("CMAKE_C_FLAGS", ""), flags)
160
+ return env
161
+
162
+
163
+ def _append_flags(existing: str, flags: str) -> str:
164
+ existing = existing.strip()
165
+ if not existing:
166
+ return flags
167
+ return existing + " " + flags
168
+
169
+
170
+ def _which_cc(path: str) -> str:
171
+ for directory in path.split(os.pathsep):
172
+ if not directory:
173
+ directory = os.curdir
174
+ candidate = os.path.join(directory, "cc")
175
+ if _real_compiler(candidate):
176
+ return os.path.abspath(candidate)
177
+ return "cc"
178
+
179
+
180
+ def _real_compiler(path: str) -> bool:
181
+ if not (os.path.isfile(path) and os.access(path, os.X_OK)):
182
+ return False
183
+ try:
184
+ with open(path, "rb") as fh:
185
+ head = fh.read(400)
186
+ except OSError:
187
+ return False
188
+ return b"sensorium.c.cc" not in head and b"sensorium-cc" not in head
189
+
190
+
191
+ def _compiler_version(compiler: str) -> str:
192
+ if not compiler:
193
+ return "unknown"
194
+ try:
195
+ completed = subprocess.run(
196
+ [compiler, "--version"], capture_output=True, text=True,
197
+ timeout=30)
198
+ except (OSError, subprocess.TimeoutExpired):
199
+ return "unknown"
200
+ text = completed.stdout or completed.stderr or ""
201
+ lines = text.splitlines()
202
+ return lines[0] if lines else "unknown"
203
+
204
+
205
+ def _binary(stream):
206
+ return getattr(stream, "buffer", stream)
207
+
208
+
209
+ def _pump(pipe, dest: Path, parent) -> None:
210
+ """Copy a pipe to the parent stream and to ``dest`` as bytes arrive."""
211
+ if pipe is None:
212
+ return
213
+ fd = os.open(dest, os.O_CREAT | os.O_WRONLY | os.O_TRUNC, 0o600)
214
+ try:
215
+ while True:
216
+ block = pipe.read(1 << 16)
217
+ if not block:
218
+ break
219
+ os.write(fd, block)
220
+ if parent is None:
221
+ continue
222
+ try:
223
+ parent.write(block)
224
+ parent.flush()
225
+ except Exception:
226
+ parent = None
227
+ finally:
228
+ os.close(fd)
229
+ pipe.close()
230
+
231
+
232
+ def _read_warnings(path: Path) -> list[str] | None:
233
+ if not path.is_file():
234
+ return None
235
+ try:
236
+ text = path.read_text(encoding="utf-8", errors="replace")
237
+ except OSError:
238
+ return None
239
+ return text.splitlines()
240
+
241
+
242
+ def _write_json(path: Path, payload: dict) -> None:
243
+ text = json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
244
+ tmp = path.with_name(path.name + ".tmp")
245
+ fd = os.open(tmp, os.O_CREAT | os.O_WRONLY | os.O_TRUNC, 0o600)
246
+ try:
247
+ os.write(fd, text.encode())
248
+ finally:
249
+ os.close(fd)
250
+ os.replace(tmp, path)
251
+
252
+
253
+ def _finish(spool: Path, inv_id: str, returncode: int) -> int:
254
+ shown = _shown_exit(returncode)
255
+ status = 128 + (-returncode) if returncode < 0 else returncode
256
+ if not _pid_dirs(spool):
257
+ print(f"invocation: {inv_id} traces: 0 exit: {shown}", flush=True)
258
+ print("sensorium c: no instrumented process ran (the command did "
259
+ "not start a binary linked with the C runtime)",
260
+ file=sys.stderr)
261
+ return status
262
+ try:
263
+ from sensorium.c.convert import convert_root
264
+ except ImportError as e:
265
+ return _convert_failed(e, returncode, shown)
266
+ try:
267
+ result = convert_root(spool)
268
+ except Exception as e:
269
+ return _convert_failed(e, returncode, shown)
270
+ try:
271
+ runs = _runs_from(result)
272
+ except (TypeError, ValueError) as e:
273
+ return _convert_failed(e, returncode, shown)
274
+ for run_id, trace in runs:
275
+ print(f"run: {run_id}", flush=True)
276
+ print(f"trace: {trace}", flush=True)
277
+ print(f"invocation: {inv_id} traces: {len(runs)} exit: {shown}",
278
+ flush=True)
279
+ return status
280
+
281
+
282
+ def _convert_failed(exc: BaseException, returncode: int, shown: str) -> int:
283
+ """Exit 2. A failed command is reported as well, not replaced."""
284
+ print(f"error: {exc}", file=sys.stderr)
285
+ if returncode != 0:
286
+ print(f"sensorium c: command exited with {shown}", file=sys.stderr)
287
+ return 2
288
+
289
+
290
+ def _shown_exit(returncode: int) -> str:
291
+ if returncode < 0:
292
+ return f"signal {-returncode}"
293
+ return str(returncode)
294
+
295
+
296
+ def _pid_dirs(spool: Path) -> list[Path]:
297
+ """Immediate children whose names are process ids.
298
+
299
+ ``bin`` and the driver's own files are not pid directories. Nothing
300
+ in here means the command never started a binary linked with the
301
+ runtime, which is not by itself a bad call.
302
+ """
303
+ found = []
304
+ try:
305
+ children = list(spool.iterdir())
306
+ except OSError:
307
+ return found
308
+ for child in children:
309
+ if child.is_dir() and child.name.isdigit():
310
+ found.append(child)
311
+ found.sort(key=lambda p: int(p.name))
312
+ return found
313
+
314
+
315
+ def _runs_from(result) -> list[tuple[str, Path]]:
316
+ """Run ids and trace paths from whatever ``convert_root`` returned.
317
+
318
+ Accepted shapes: a list of run ids, a list of ``*.db`` paths, a list
319
+ of ``(run_id, path)`` pairs, a list of objects or dicts with
320
+ ``run_id`` and ``trace``, or a mapping of run id to path.
321
+ """
322
+ if result is None:
323
+ return []
324
+ if isinstance(result, dict):
325
+ if "runs" in result and not any(
326
+ key in result for key in ("run_id", "id", "trace")):
327
+ return _runs_from(result["runs"])
328
+ if "run_id" in result or "trace" in result or "id" in result:
329
+ return [_one_run(result)]
330
+ out = []
331
+ for key, value in result.items():
332
+ out.append(_one_run((key, value)))
333
+ return out
334
+ if isinstance(result, (str, Path)):
335
+ return [_one_run(result)]
336
+ out = []
337
+ for item in result:
338
+ out.append(_one_run(item))
339
+ return out
340
+
341
+
342
+ def _one_run(item) -> tuple[str, Path]:
343
+ if isinstance(item, tuple) and len(item) == 2:
344
+ run_id, trace = item
345
+ return str(run_id), Path(trace)
346
+ if isinstance(item, (str, Path)):
347
+ text = os.fspath(item)
348
+ path = Path(text)
349
+ if text.endswith(".db"):
350
+ return path.stem, path
351
+ return text, paths.traces_dir() / f"{text}.db"
352
+ run_id = getattr(item, "run_id", None)
353
+ trace = getattr(item, "trace", None)
354
+ if trace is None:
355
+ trace = getattr(item, "path", None)
356
+ if isinstance(item, dict):
357
+ run_id = item.get("run_id", item.get("id", run_id))
358
+ trace = item.get("trace", item.get("path", trace))
359
+ if run_id is None and trace is not None:
360
+ run_id = Path(trace).stem
361
+ if run_id is None:
362
+ raise ValueError(f"convert_root returned {item!r}, which has no run id")
363
+ if trace is None:
364
+ trace = paths.traces_dir() / f"{run_id}.db"
365
+ return str(run_id), Path(trace)