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/cc.py ADDED
@@ -0,0 +1,612 @@
1
+ """``sensorium-cc``: the compiler wrapper and the ``gcc``/``cc``/``clang`` shim.
2
+
3
+ A build sees this process where it expected a compiler. Probe flags
4
+ (``--version``, ``-E``, and the rest of the list in ``_passthrough``) are
5
+ handed to the real compiler unchanged. A compile or a link gets the
6
+ instrument flags appended, so they win over a default earlier in the
7
+ command, and a link also gets the C runtime.
8
+
9
+ The real compiler is never this file and never a shim directory. The
10
+ wrapper is Python, so it is not instrumented.
11
+ """
12
+ from __future__ import annotations
13
+
14
+ import inspect
15
+ import os
16
+ import re
17
+ import shlex
18
+ import subprocess
19
+ import sys
20
+ from pathlib import Path
21
+
22
+ from sensorium.c import pkg
23
+
24
+ #: Appended to every compile and every link. Last, so they override a
25
+ #: default of the opposite flag. Duplicate copies are harmless.
26
+ #: The exclude-file-list entry is gcc only. Clang 21 rejects it as an
27
+ #: unknown argument, so a clang compile does not receive it.
28
+ INSTRUMENT_FLAGS = [
29
+ "-g",
30
+ "-fno-omit-frame-pointer",
31
+ "-fno-inline",
32
+ "-fno-optimize-sibling-calls",
33
+ "-finstrument-functions",
34
+ "-finstrument-functions-exclude-file-list=/usr/include,/usr/lib",
35
+ ]
36
+ _EXCLUDE_FILE_LIST = "-finstrument-functions-exclude-file-list"
37
+
38
+ _SHIM_NAMES = {"gcc", "cc", "clang"}
39
+ _COMPILER_BASENAME = re.compile(r"^(?:gcc|cc|clang|clang-\d+|.+-gcc)$")
40
+ _TAKES_ARG = {
41
+ "-o", "-I", "-L", "-l", "-D", "-U", "-x", "-include", "-imacros",
42
+ "-isystem", "-idirafter", "-iprefix", "-iwithprefix",
43
+ "-iwithprefixbefore", "-isysroot", "-imultilib", "-MF", "-MT", "-MQ",
44
+ "-Xlinker", "-Xpreprocessor", "-Xassembler", "-b", "-B", "-T", "-u",
45
+ "-aux-info", "-include-directory",
46
+ }
47
+ _SCRIPT = os.path.realpath(__file__)
48
+
49
+
50
+ class CompilerError(Exception):
51
+ """The real compiler could not be named or found."""
52
+
53
+
54
+ def instrument_flags(compiler: str) -> list[str]:
55
+ """Instrument flags this compiler accepts.
56
+
57
+ gcc keeps the exclude-file-list entry so inlines from ``/usr/include``
58
+ and ``/usr/lib`` stay out of the trace. Clang has no such flag.
59
+ """
60
+ if _is_clang(compiler):
61
+ return [flag for flag in INSTRUMENT_FLAGS if not _exclude_file_list(flag)]
62
+ return list(INSTRUMENT_FLAGS)
63
+
64
+
65
+ def _compile_args(compiler: str, args: list[str]) -> list[str]:
66
+ """``args`` plus instrument flags, without a flag this compiler rejects.
67
+
68
+ ``CFLAGS`` may already carry the gcc exclude-file-list entry. Drop
69
+ that token when the real compiler is clang, then append the flags
70
+ this compiler accepts.
71
+ """
72
+ if _is_clang(compiler):
73
+ args = [arg for arg in args if not _exclude_file_list(arg)]
74
+ return [*args, *instrument_flags(compiler)]
75
+
76
+
77
+ def _exclude_file_list(arg: str) -> bool:
78
+ return arg == _EXCLUDE_FILE_LIST or arg.startswith(_EXCLUDE_FILE_LIST + "=")
79
+
80
+
81
+ def _is_clang(compiler: str) -> bool:
82
+ """True for clang, including a ``cc`` symlink whose target is clang."""
83
+ names = [os.path.basename(compiler).lower()]
84
+ try:
85
+ linked = os.path.basename(os.path.realpath(compiler)).lower()
86
+ except OSError:
87
+ linked = ""
88
+ if linked and linked not in names:
89
+ names.append(linked)
90
+ return any(name == "clang" or name.startswith("clang-") for name in names)
91
+
92
+
93
+ def main(argv: list[str] | None = None) -> int:
94
+ """Run the real compiler, with instrument flags unless this is a probe.
95
+
96
+ ``argv`` is either a full ``sys.argv`` (program name first) or just the
97
+ arguments after it, as in ``main(["--version"])``. ``None`` reads
98
+ ``sys.argv``, which is what the console script and the shims do.
99
+ """
100
+ try:
101
+ argv0, args = _invocation(argv)
102
+ requested, args = _select_compiler(argv0, args)
103
+ compiler = _resolve(requested, argv0)
104
+ except CompilerError as e:
105
+ print(f"sensorium-cc: error: {e}", file=sys.stderr)
106
+ return 2
107
+ args = _expand_responses(args)
108
+ if _passthrough(args):
109
+ return _invoke([compiler, *args])
110
+ warnings = _warnings(args)
111
+ for line in warnings:
112
+ _emit(line)
113
+ if warnings and _strict():
114
+ return 2
115
+ cmd = [compiler, *_compile_args(compiler, args)]
116
+ linking = _links(args)
117
+ if linking:
118
+ try:
119
+ runtime = pkg.runtime_object()
120
+ except pkg.PackageError as e:
121
+ print(f"sensorium-cc: error: {e}", file=sys.stderr)
122
+ return 2
123
+ if not _has_runtime(args, runtime):
124
+ cmd.append(os.fspath(runtime))
125
+ cmd.extend(["-ldl", "-pthread"])
126
+ status = _invoke(cmd)
127
+ if status == 0 and linking:
128
+ plan_status = _after_link(args)
129
+ if plan_status is not None:
130
+ return plan_status
131
+ return status
132
+
133
+
134
+ def _invocation(argv: list[str] | None) -> tuple[str, list[str]]:
135
+ """``(argv0, args)``. Args-only lists get the running interpreter's argv0.
136
+
137
+ A list whose first element is already a program (a shim named gcc, cc
138
+ or clang, this file, or ``sensorium-cc``) is a full argv. Anything else,
139
+ including ``["--version"]``, is the compiler's own arguments.
140
+ """
141
+ if argv is None:
142
+ full = list(sys.argv)
143
+ elif not argv or argv[0].startswith("-") or not _looks_like_program(argv[0]):
144
+ full = [sys.argv[0], *argv]
145
+ else:
146
+ full = list(argv)
147
+ if not full:
148
+ return "", []
149
+ return full[0], full[1:]
150
+
151
+
152
+ def _looks_like_program(token: str) -> bool:
153
+ base = os.path.basename(token)
154
+ if base in _SHIM_NAMES or base in {"sensorium-cc", "cc.py", "__main__.py"}:
155
+ return True
156
+ try:
157
+ return os.path.isfile(token) and os.path.samefile(token, _SCRIPT)
158
+ except OSError:
159
+ return False
160
+
161
+
162
+ def _select_compiler(argv0: str, args: list[str]) -> tuple[str, list[str]]:
163
+ """Which compiler the user asked for, and the args with that name removed.
164
+
165
+ ``argv[1]`` wins when it is an executable or a compiler basename, which
166
+ is how a launcher (``shim cc /usr/bin/gcc ...``) names the real tool.
167
+ Otherwise a shim invoked as ``gcc``, ``cc`` or ``clang`` asks for that
168
+ tool. Anything else uses ``$SENSORIUM_C_CC`` or ``cc``.
169
+ """
170
+ if args and _is_compiler_token(args[0]):
171
+ return args[0], args[1:]
172
+ base = os.path.basename(argv0) if argv0 else ""
173
+ if base in _SHIM_NAMES:
174
+ if _usable_real_compiler(argv0):
175
+ return argv0, list(args)
176
+ return base, list(args)
177
+ env = os.environ.get("SENSORIUM_C_CC", "")
178
+ if env:
179
+ return env, list(args)
180
+ return "cc", list(args)
181
+
182
+
183
+ def _is_compiler_token(token: str) -> bool:
184
+ if not token or token.startswith("-"):
185
+ return False
186
+ if _COMPILER_BASENAME.match(os.path.basename(token)):
187
+ return True
188
+ return _usable_real_compiler(token) or (
189
+ os.path.isfile(token) and os.access(token, os.X_OK)
190
+ and not os.path.isabs(token) and not _looks_like_wrapper(token))
191
+
192
+
193
+ def _resolve(requested: str, argv0: str) -> str:
194
+ """Absolute path of the real compiler, never this shim and never this file.
195
+
196
+ An absolute real compiler is used as named. ``cc`` and ``gcc`` prefer
197
+ ``$SENSORIUM_C_CC`` when that variable is an absolute compiler, which is
198
+ how a shim named ``cc`` reaches the ``cc`` that was on ``PATH`` before
199
+ the shim directory was prepended. The search skips the shim's directory
200
+ and skips this script, so the wrapper cannot recurse.
201
+ """
202
+ base = os.path.basename(requested) if requested else "cc"
203
+ env_cc = os.environ.get("SENSORIUM_C_CC", "")
204
+ if os.path.isabs(requested) and _usable_real_compiler(requested):
205
+ return os.path.abspath(requested)
206
+ if base in {"cc", "gcc"} and _usable_real_compiler(env_cc):
207
+ return os.path.abspath(env_cc)
208
+ skip = _skip_dirs(argv0)
209
+ for directory in _path_dirs():
210
+ if os.path.abspath(directory) in skip:
211
+ continue
212
+ candidate = os.path.join(directory, base)
213
+ if not _usable_real_compiler(candidate):
214
+ continue
215
+ if _is_this_script(candidate) or _same_file(candidate, argv0):
216
+ continue
217
+ return os.path.abspath(candidate)
218
+ raise CompilerError(
219
+ f"cannot find the real compiler {base!r} on PATH")
220
+
221
+
222
+ def _usable_real_compiler(path: str) -> bool:
223
+ if not path or not os.path.isabs(path):
224
+ return False
225
+ if not (os.path.isfile(path) and os.access(path, os.X_OK)):
226
+ return False
227
+ if _is_this_script(path) or _looks_like_wrapper(path):
228
+ return False
229
+ return True
230
+
231
+
232
+ def _skip_dirs(argv0: str) -> set[str]:
233
+ skipped = set()
234
+ root = os.environ.get("SENSORIUM_C_ROOT")
235
+ if root:
236
+ skipped.add(os.path.abspath(os.path.join(root, "bin")))
237
+ if argv0:
238
+ base = os.path.basename(argv0)
239
+ if base in _SHIM_NAMES or _looks_like_wrapper(argv0):
240
+ skipped.add(os.path.dirname(os.path.abspath(argv0)))
241
+ return skipped
242
+
243
+
244
+ def _path_dirs() -> list[str]:
245
+ raw = os.environ.get("PATH", "")
246
+ dirs = []
247
+ for directory in raw.split(os.pathsep):
248
+ dirs.append(directory or os.curdir)
249
+ return dirs
250
+
251
+
252
+ def _looks_like_wrapper(path: str) -> bool:
253
+ try:
254
+ with open(path, "rb") as fh:
255
+ head = fh.read(400)
256
+ except OSError:
257
+ return False
258
+ return b"sensorium.c.cc" in head or b"sensorium-cc" in head
259
+
260
+
261
+ def _is_this_script(path: str) -> bool:
262
+ try:
263
+ return os.path.realpath(path) == _SCRIPT
264
+ except OSError:
265
+ return False
266
+
267
+
268
+ def _same_file(path: str, other: str) -> bool:
269
+ if not path or not other:
270
+ return False
271
+ try:
272
+ return os.path.samefile(path, other)
273
+ except OSError:
274
+ return os.path.abspath(path) == os.path.abspath(other)
275
+
276
+
277
+ def _passthrough(args: list[str]) -> bool:
278
+ """Probes and preprocess-only commands run the real compiler unchanged.
279
+
280
+ ``-v`` is a probe only when it is the only argument. ``gcc -v file.c``
281
+ is a verbose compile and is instrumented.
282
+ """
283
+ if args == ["-v"]:
284
+ return True
285
+ for arg in args:
286
+ if arg in {"--version", "-dumpmachine", "-dumpversion", "-###",
287
+ "--help", "-E"}:
288
+ return True
289
+ if arg.startswith("-print-") or arg.startswith("--print-"):
290
+ return True
291
+ return False
292
+
293
+
294
+ def _links(args: list[str]) -> bool:
295
+ """True when this command produces a final image (executable or shared).
296
+
297
+ ``-c``, ``-S`` and ``-E`` do not link. A pure ``-M`` / ``-MM`` scan does
298
+ not either (``-MD`` / ``-MMD`` still compile, and are not this case).
299
+ ``-fsyntax-only`` produces no image. ``-shared`` still links.
300
+ """
301
+ if any(arg in {"-c", "-S", "-E", "-fsyntax-only"} for arg in args):
302
+ return False
303
+ if "-M" in args or "-MM" in args:
304
+ return False
305
+ return True
306
+
307
+
308
+ def _warnings(args: list[str]) -> list[str]:
309
+ """One line per reason this build will not yield reliable values.
310
+
311
+ The effective ``-O`` is the last ``-O*`` on the command. No ``-O`` at
312
+ all is ``-O0``. ``-fcf-protection`` other than ``=none`` turns on CET;
313
+ a shadow stack makes the return trampoline record nothing.
314
+ """
315
+ lines = []
316
+ level = _opt_level(args)
317
+ if level not in {"0", "g"}:
318
+ subject = _subject(args)
319
+ lines.append(
320
+ f"sensorium-cc: warning: {subject}: built at -O{level}; "
321
+ "argument and return values are reliable at -O0 or -Og")
322
+ if _cet_on(args):
323
+ lines.append(
324
+ "sensorium-cc: warning: CET/cf-protection is on; a shadow "
325
+ "stack disables return-value recording")
326
+ return lines
327
+
328
+
329
+ def _opt_level(args: list[str]) -> str:
330
+ level = "0"
331
+ for arg in args:
332
+ if not arg.startswith("-O"):
333
+ continue
334
+ suffix = arg[2:]
335
+ # A bare ``-O`` is gcc's ``-O1``.
336
+ level = "1" if suffix == "" else suffix
337
+ return level
338
+
339
+
340
+ def _cet_on(args: list[str]) -> bool:
341
+ chosen = None
342
+ for arg in args:
343
+ if arg == "-fcf-protection" or arg.startswith("-fcf-protection="):
344
+ chosen = arg
345
+ if chosen is None:
346
+ return False
347
+ return chosen != "-fcf-protection=none"
348
+
349
+
350
+ def _strict() -> bool:
351
+ """``SENSORIUM_C_STRICT`` set to anything other than empty or ``0``."""
352
+ value = os.environ.get("SENSORIUM_C_STRICT")
353
+ if value is None or value == "" or value == "0":
354
+ return False
355
+ return True
356
+
357
+
358
+ def _subject(args: list[str]) -> str:
359
+ output = _explicit_output(args)
360
+ if output:
361
+ return output
362
+ first = _first_input(args)
363
+ if first:
364
+ return first
365
+ return "a.out"
366
+
367
+
368
+ def _explicit_output(args: list[str]) -> str | None:
369
+ found = None
370
+ i = 0
371
+ while i < len(args):
372
+ arg = args[i]
373
+ if arg == "-o" and i + 1 < len(args):
374
+ found = args[i + 1]
375
+ i += 2
376
+ continue
377
+ if arg.startswith("-o") and len(arg) > 2:
378
+ found = arg[2:]
379
+ i += 1
380
+ continue
381
+ i += 1
382
+ return found
383
+
384
+
385
+ def _first_input(args: list[str]) -> str | None:
386
+ i = 0
387
+ while i < len(args):
388
+ arg = args[i]
389
+ if arg in _TAKES_ARG:
390
+ i += 2
391
+ continue
392
+ if arg.startswith("-"):
393
+ i += 1
394
+ continue
395
+ return arg
396
+ return None
397
+
398
+
399
+ def _emit(line: str) -> None:
400
+ """Print one warning, and append it to ``$SENSORIUM_C_ROOT`` when set.
401
+
402
+ The file is created mode 0600. A failure to append is itself a warning
403
+ and does not change the compiler's status.
404
+ """
405
+ print(line, file=sys.stderr)
406
+ root = os.environ.get("SENSORIUM_C_ROOT")
407
+ if not root:
408
+ return
409
+ path = os.path.join(root, "build-warnings.txt")
410
+ try:
411
+ fd = os.open(path, os.O_CREAT | os.O_APPEND | os.O_WRONLY, 0o600)
412
+ except OSError as e:
413
+ print(f"sensorium-cc: warning: cannot append {path}: {e.strerror}",
414
+ file=sys.stderr)
415
+ return
416
+ try:
417
+ os.write(fd, (line + "\n").encode())
418
+ finally:
419
+ os.close(fd)
420
+
421
+
422
+ def _has_runtime(args: list[str], runtime: Path) -> bool:
423
+ real = os.path.realpath(runtime)
424
+ for arg in args:
425
+ if arg == os.fspath(runtime) or arg == real:
426
+ return True
427
+ try:
428
+ if os.path.isfile(arg) and os.path.realpath(arg) == real:
429
+ return True
430
+ except OSError:
431
+ continue
432
+ return False
433
+
434
+
435
+ class _PlanFallback(Exception):
436
+ """A symbol plan was written because ``sensorium.c.plan`` is absent.
437
+
438
+ Not a failed link: the image has a readable plan, with empty
439
+ arguments. Strict mode still compiles ``-O0``. A planner that imports
440
+ and then fails is a different error, and strict mode exits 2 for that.
441
+ """
442
+
443
+
444
+ def _after_link(args: list[str]) -> int | None:
445
+ """Write ``<output>.scplan``. ``None`` means keep the compiler's status.
446
+
447
+ A planner that fails prints a warning and still returns the compiler's
448
+ status: the program records calls with empty arguments.
449
+ ``SENSORIUM_C_STRICT`` turns that failure into exit 2. ``-shared`` and
450
+ a normal executable are the same case. Output ``-`` (the compiler
451
+ wrote stdout) has no image to plan.
452
+ """
453
+ output = _explicit_output(args) or "a.out"
454
+ if output == "-":
455
+ _emit("sensorium-cc: warning: link wrote stdout; no capture plan")
456
+ return 2 if _strict() else None
457
+ try:
458
+ _call_plan(output)
459
+ except _PlanFallback:
460
+ _emit(f"sensorium-cc: warning: {output}: sensorium.c.plan is not "
461
+ "available; wrote a symbol plan and argument values will "
462
+ "be empty")
463
+ return None
464
+ except Exception as e:
465
+ detail = " ".join(str(e).split())
466
+ _emit(f"sensorium-cc: warning: {output}: capture plan failed: "
467
+ f"{detail}")
468
+ if _strict():
469
+ return 2
470
+ return None
471
+
472
+
473
+ def _call_plan(output: str) -> None:
474
+ dest = output + ".scplan"
475
+ try:
476
+ from sensorium.c.plan import write_image_plan
477
+ except ImportError as e:
478
+ _write_symbol_plan(output)
479
+ raise _PlanFallback(str(e)) from e
480
+ try:
481
+ params = [
482
+ p for p in inspect.signature(write_image_plan).parameters.values()
483
+ if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
484
+ ]
485
+ except (TypeError, ValueError):
486
+ params = []
487
+ if len(params) >= 2:
488
+ write_image_plan(output, dest)
489
+ else:
490
+ try:
491
+ write_image_plan(output, dest)
492
+ except TypeError:
493
+ write_image_plan(output)
494
+ if not os.path.isfile(dest):
495
+ raise OSError(f"capture plan was not written to {dest}")
496
+
497
+
498
+ def _write_symbol_plan(image: str) -> None:
499
+ """Plan from the ELF symbol table when the DWARF planner is not there.
500
+
501
+ Addresses are ``st_value``, which for a linked image is the
502
+ unrelocated address the runtime adds the load bias to. Parameters are
503
+ empty: without DWARF the slot is not known, and the value is unread.
504
+ """
505
+ from sensorium.c.format import RET_INT, FuncPlan, write_plan
506
+
507
+ addrs = _elf_func_addrs(image)
508
+ if not addrs:
509
+ raise OSError(f"{image}: no function symbols to plan")
510
+ write_plan(image + ".scplan",
511
+ [FuncPlan(addr, RET_INT, 1, 8, ()) for addr in addrs])
512
+
513
+
514
+ def _elf_func_addrs(path: str) -> list[int]:
515
+ """Defined ``STT_FUNC`` values in an ELF64 little-endian image."""
516
+ import struct
517
+
518
+ data = Path(path).read_bytes()
519
+ if len(data) < 64 or data[:4] != b"\x7fELF" or data[4] != 2 or data[5] != 1:
520
+ raise OSError(f"{path}: not a little-endian ELF64 file")
521
+ e_shoff = struct.unpack_from("<Q", data, 40)[0]
522
+ e_shentsize = struct.unpack_from("<H", data, 58)[0]
523
+ e_shnum = struct.unpack_from("<H", data, 60)[0]
524
+ if e_shentsize < 64 or e_shnum == 0:
525
+ raise OSError(f"{path}: no section headers")
526
+ sym_off = None
527
+ for index in range(e_shnum):
528
+ off = e_shoff + index * e_shentsize
529
+ if off + 64 > len(data):
530
+ break
531
+ sh_type = struct.unpack_from("<I", data, off + 4)[0]
532
+ if sh_type == 2: # SHT_SYMTAB
533
+ sym_off = off
534
+ break
535
+ if sym_off is None:
536
+ for index in range(e_shnum):
537
+ off = e_shoff + index * e_shentsize
538
+ sh_type = struct.unpack_from("<I", data, off + 4)[0]
539
+ if sh_type == 11: # SHT_DYNSYM
540
+ sym_off = off
541
+ break
542
+ if sym_off is None:
543
+ raise OSError(f"{path}: no symbol table")
544
+ sh_offset = struct.unpack_from("<Q", data, sym_off + 24)[0]
545
+ sh_size = struct.unpack_from("<Q", data, sym_off + 32)[0]
546
+ sh_entsize = struct.unpack_from("<Q", data, sym_off + 56)[0] or 24
547
+ addrs: list[int] = []
548
+ seen: set[int] = set()
549
+ end = min(len(data), sh_offset + sh_size)
550
+ cursor = sh_offset
551
+ while cursor + 24 <= end:
552
+ st_info = data[cursor + 4]
553
+ st_shndx = struct.unpack_from("<H", data, cursor + 6)[0]
554
+ st_value = struct.unpack_from("<Q", data, cursor + 8)[0]
555
+ if (st_info & 0xF) == 2 and st_shndx != 0 and st_value not in seen:
556
+ if st_value != 0:
557
+ seen.add(st_value)
558
+ addrs.append(st_value)
559
+ cursor += sh_entsize
560
+ return addrs
561
+
562
+
563
+ def _invoke(cmd: list[str]) -> int:
564
+ try:
565
+ completed = subprocess.run(cmd)
566
+ except OSError as e:
567
+ print(f"sensorium-cc: error: cannot run {cmd[0]}: {e.strerror}",
568
+ file=sys.stderr)
569
+ return 2
570
+ code = completed.returncode
571
+ if code < 0:
572
+ return 128 + (-code)
573
+ return code
574
+
575
+
576
+ def _expand_responses(args: list[str], depth: int = 0,
577
+ seen: set[str] | None = None) -> list[str]:
578
+ """Splice ``@file`` arguments the way gcc does, one file at a time.
579
+
580
+ A missing file is left for the real compiler to diagnose. Cycles and
581
+ a deep nest are left unexpanded rather than followed forever.
582
+ """
583
+ if depth > 8:
584
+ return list(args)
585
+ if seen is None:
586
+ seen = set()
587
+ out: list[str] = []
588
+ for arg in args:
589
+ if not (arg.startswith("@") and len(arg) > 1):
590
+ out.append(arg)
591
+ continue
592
+ path = arg[1:]
593
+ if not os.path.isfile(path):
594
+ out.append(arg)
595
+ continue
596
+ real = os.path.realpath(path)
597
+ if real in seen:
598
+ out.append(arg)
599
+ continue
600
+ seen.add(real)
601
+ try:
602
+ text = Path(path).read_text(encoding="utf-8", errors="replace")
603
+ parts = shlex.split(text, posix=True)
604
+ except (OSError, ValueError):
605
+ out.append(arg)
606
+ continue
607
+ out.extend(_expand_responses(parts, depth + 1, seen))
608
+ return out
609
+
610
+
611
+ if __name__ == "__main__":
612
+ sys.exit(main())
sensorium/c/cli.py ADDED
@@ -0,0 +1,60 @@
1
+ """`sensorium c` -- record a C program or a C build.
2
+
3
+ One subcommand. `run` puts compiler shims on `PATH`, spawns the command
4
+ after `--`, and converts whatever that command spooled. The exit status
5
+ is the command's own, including `128 + n` when a signal ended it, because
6
+ a recorder whose status meant something else could not stand in front of
7
+ an existing build.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import argparse
12
+
13
+
14
+ def add_parser(sub) -> None:
15
+ p = sub.add_parser(
16
+ "c",
17
+ help="record a C program or a C build",
18
+ description="Record a C program or a build (make, cmake, meson, or "
19
+ "a plain gcc/clang command) on Linux x86-64. Debug "
20
+ "builds (-O0 or -Og) are the ones whose arguments and "
21
+ "return values can be read back. The command's own "
22
+ "status is the exit status.")
23
+ commands = p.add_subparsers(dest="c_cmd", required=True)
24
+ _add_run_parser(commands)
25
+
26
+
27
+ def _add_run_parser(sub) -> None:
28
+ p = sub.add_parser(
29
+ "run",
30
+ help="record a C program or a build",
31
+ description="Record a C program or a build (make, cmake, meson, or "
32
+ "a plain gcc/clang command) on Linux x86-64. Debug "
33
+ "builds (-O0 or -Og) keep argument and return values; "
34
+ "other optimization levels still record calls. The "
35
+ "command after -- runs as typed. The command's own "
36
+ "status is the exit status. When the command dies on a "
37
+ "signal, that status is 128 plus the signal number, the "
38
+ "same one a shell reports.",
39
+ epilog="exit: the command's own status, or 2 to fix the call")
40
+ p.add_argument(
41
+ "--strict", action="store_true",
42
+ help="refuse to compile a translation unit whose effective -O is "
43
+ "not -O0 or -Og")
44
+ p.add_argument(
45
+ "--no-retval", action="store_true",
46
+ help="do not install the return trampoline "
47
+ "(env SENSORIUM_C_NO_RETVAL=1)")
48
+ p.add_argument(
49
+ "command", nargs=argparse.REMAINDER,
50
+ help="-- followed by the command to record: make, cmake, meson, "
51
+ "or a plain gcc/clang command")
52
+ p.set_defaults(func=run_run)
53
+
54
+
55
+ def run_run(args) -> int:
56
+ # Imported here: the driver does not import this module, but keeping
57
+ # the import late matches the other recorder and leaves `c --help`
58
+ # free of the compiler wrapper.
59
+ from sensorium.c import driver
60
+ return driver.run(args)