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
sensorium/ts/cli.py
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
"""`sensorium ts` -- the TypeScript recorder's own subcommands.
|
|
2
|
+
|
|
3
|
+
Two subcommands. `run` records a test run: it recognises the harness, wires
|
|
4
|
+
it, spawns the command as typed, waits, and converts what the run spooled.
|
|
5
|
+
`ingest` is the second half of that on its own, over a spool directory a run
|
|
6
|
+
already left behind -- deterministic and re-runnable, so a driver killed
|
|
7
|
+
between the harness's exit and the conversion leaves nothing that cannot be
|
|
8
|
+
finished by hand.
|
|
9
|
+
|
|
10
|
+
Every word printed by this file is about test files, containers and the
|
|
11
|
+
harness that ran them. Nothing here borrows a word from another recorder's
|
|
12
|
+
machinery: a reader who meets `asyncio` or `cargo` in a TypeScript command's
|
|
13
|
+
help has been told about something that is not there.
|
|
14
|
+
"""
|
|
15
|
+
import argparse
|
|
16
|
+
import sys
|
|
17
|
+
|
|
18
|
+
from sensorium import exit as ex
|
|
19
|
+
from sensorium import paths
|
|
20
|
+
from sensorium.ts import ingest, invocation
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def add_parser(sub) -> None:
|
|
24
|
+
p = sub.add_parser("ts", help="record and read a TypeScript test run",
|
|
25
|
+
description="Record a TypeScript or JavaScript test "
|
|
26
|
+
"run under vitest or node --test; read "
|
|
27
|
+
"back what actually ran.")
|
|
28
|
+
ts = p.add_subparsers(dest="ts_cmd", required=True)
|
|
29
|
+
_add_run_parser(ts)
|
|
30
|
+
_add_ingest_parser(ts)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _add_run_parser(sub) -> None:
|
|
34
|
+
p = sub.add_parser(
|
|
35
|
+
"run", help="record a test run under vitest or node --test",
|
|
36
|
+
description="Record one test run. Give the harness command after "
|
|
37
|
+
"`--`, exactly as you would type it; the recorder wires "
|
|
38
|
+
"itself in and takes the wiring out again when the run "
|
|
39
|
+
"ends.",
|
|
40
|
+
epilog="exit: the harness's own status, or 2 to fix the call")
|
|
41
|
+
p.add_argument("--tier", choices=("off", "call"), default="call",
|
|
42
|
+
help="what the recorder emits: `call` records calls, "
|
|
43
|
+
"returns and awaits; `off` records nothing (the "
|
|
44
|
+
"control arm -- the same code still runs)")
|
|
45
|
+
p.add_argument("--focus", action="append", default=[], metavar="SPEC",
|
|
46
|
+
help="a function to record per statement: <qualname> or "
|
|
47
|
+
"<file>:<qualname>, as tree prints it; repeatable")
|
|
48
|
+
p.add_argument("--jobs", type=int, default=None, metavar="N",
|
|
49
|
+
help="how many spools to convert at once (default: one "
|
|
50
|
+
"per core)")
|
|
51
|
+
p.add_argument("--refocus-of", default=None, metavar="RUN",
|
|
52
|
+
help="the run this recording re-runs one flag deeper; "
|
|
53
|
+
"stamps refocus_of into every trace of the "
|
|
54
|
+
"invocation (set by `sensorium refocus`)")
|
|
55
|
+
p.add_argument("--max-events", default=None,
|
|
56
|
+
help="stop storing events after this many (0 is unlimited)")
|
|
57
|
+
p.add_argument("--max-bytes", default=None,
|
|
58
|
+
help="stop storing events after the trace reaches this "
|
|
59
|
+
"size, for example 8M (0 is unlimited)")
|
|
60
|
+
p.add_argument("--max-calls", default=None,
|
|
61
|
+
help="store at most this many calls of each function; "
|
|
62
|
+
"later calls are counted and marked elided "
|
|
63
|
+
"(0 is unlimited)")
|
|
64
|
+
p.add_argument("--no-cap", action="store_true",
|
|
65
|
+
help="record without an event, size, or per-function cap")
|
|
66
|
+
p.add_argument("command", nargs=argparse.REMAINDER,
|
|
67
|
+
help="-- followed by the harness command: vitest run …, "
|
|
68
|
+
"npx vitest run …, node --test …")
|
|
69
|
+
p.set_defaults(func=run_run)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def run_run(args) -> int:
|
|
73
|
+
if args.jobs is not None and args.jobs < 1:
|
|
74
|
+
print(f"--jobs must be >= 1 (got {args.jobs})", file=sys.stderr)
|
|
75
|
+
return ex.BAD_CALL
|
|
76
|
+
# Imported here and not above: the driver imports this module back for
|
|
77
|
+
# its own reporting, and one of the two has to be the late one.
|
|
78
|
+
from sensorium.ts import driver
|
|
79
|
+
return driver.run(args)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _add_ingest_parser(sub) -> None:
|
|
83
|
+
p = sub.add_parser(
|
|
84
|
+
"ingest", help="turn a recorded spool directory into traces",
|
|
85
|
+
description="Convert every spool a recorded run left behind -- one "
|
|
86
|
+
"per container -- into one trace each.",
|
|
87
|
+
epilog="exit: 0 every spool converted, 2 fix the call or the "
|
|
88
|
+
"directory")
|
|
89
|
+
p.add_argument("spool_dir",
|
|
90
|
+
help="the directory the run wrote its spools into")
|
|
91
|
+
p.add_argument("--jobs", type=int, default=None, metavar="N",
|
|
92
|
+
help="how many spools to convert at once (default: one "
|
|
93
|
+
"per core)")
|
|
94
|
+
p.set_defaults(func=run_ingest)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def run_ingest(args) -> int:
|
|
98
|
+
if args.jobs is not None and args.jobs < 1:
|
|
99
|
+
print(f"--jobs must be >= 1 (got {args.jobs})", file=sys.stderr)
|
|
100
|
+
return ex.BAD_CALL
|
|
101
|
+
try:
|
|
102
|
+
summaries = ingest.ingest_dir(args.spool_dir, paths.trace_root(),
|
|
103
|
+
jobs=args.jobs)
|
|
104
|
+
# Read back rather than passed down: `ingest_dir` returns what
|
|
105
|
+
# happened to the SPOOLS, and the invocation is a property of the
|
|
106
|
+
# directory, not of any of them.
|
|
107
|
+
invocation_id = invocation.read_invocation(args.spool_dir).invocation
|
|
108
|
+
except (ingest.IngestError, invocation.InvocationError) as e:
|
|
109
|
+
print(f"error: {e}", file=sys.stderr)
|
|
110
|
+
return ex.BAD_CALL
|
|
111
|
+
return _report(summaries, invocation_id)
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def _report(summaries, invocation_id: str, harness: str | None = None) -> int:
|
|
115
|
+
"""One line per spool, then the invocation and what it converted to.
|
|
116
|
+
|
|
117
|
+
A refused spool takes the place of its own `run:` line rather than being
|
|
118
|
+
collected at the end, so the order on screen is the order on disk and a
|
|
119
|
+
reader can see which container is missing from the count.
|
|
120
|
+
|
|
121
|
+
`harness` is the ending the driver WITNESSED, and only a driver has one:
|
|
122
|
+
an ingest of a directory read the same fact out of a file, which is a
|
|
123
|
+
different claim, and the line does not make it.
|
|
124
|
+
"""
|
|
125
|
+
for summary in summaries:
|
|
126
|
+
print(summary.line())
|
|
127
|
+
converted = [s for s in summaries if s.refused is None]
|
|
128
|
+
tail = "" if harness is None else f" harness exit: {harness}"
|
|
129
|
+
print(f"invocation: {invocation_id} traces: {len(converted)}{tail}")
|
|
130
|
+
return ex.ANSWERED if len(converted) == len(summaries) else ex.BAD_CALL
|
sensorium/ts/driver.py
ADDED
|
@@ -0,0 +1,472 @@
|
|
|
1
|
+
"""`sensorium ts run`: recognise, wire, spawn, wait, convert.
|
|
2
|
+
|
|
3
|
+
The order is the design, and every step of it is there because the step
|
|
4
|
+
before it can fail in a way that would otherwise leave something behind:
|
|
5
|
+
|
|
6
|
+
--refocus-of refused before the Node check: it is about the
|
|
7
|
+
call and nothing else, so a bad link costs no
|
|
8
|
+
version probe and no spawn
|
|
9
|
+
node --version refused below 24 (D2) before anything is minted
|
|
10
|
+
the package refused uninstalled before anything is minted
|
|
11
|
+
recognise refused before a spool directory exists
|
|
12
|
+
the root's typescript refused once the plan names the root, and still
|
|
13
|
+
before anything is minted
|
|
14
|
+
--focus resolved against the root by the recorder's own
|
|
15
|
+
resolver, and refused there
|
|
16
|
+
the caps resolved before anything is minted: a bad size is
|
|
17
|
+
a bad call, and the harness then sees only integers
|
|
18
|
+
mint, invocation.json the record of what is about to be spawned
|
|
19
|
+
the wrapper two files, in a `finally` from here on
|
|
20
|
+
spawn, wait the harness's stdio is the user's; the driver
|
|
21
|
+
only holds the clock
|
|
22
|
+
harness.json written whether the harness passed or failed --
|
|
23
|
+
the run an agent most wants to read is the red one
|
|
24
|
+
remove the wrapper on every path, exception included
|
|
25
|
+
ingest one trace per container, into the same store
|
|
26
|
+
|
|
27
|
+
The driver never applies the query CLI's 0/1/2/3 table to itself: it exits
|
|
28
|
+
with the harness's own status, and `128 + n` when a signal ended it. A
|
|
29
|
+
recorder whose exit status meant something different from the command it
|
|
30
|
+
wrapped could not be put in front of an existing command line at all.
|
|
31
|
+
"""
|
|
32
|
+
import importlib.metadata
|
|
33
|
+
import json
|
|
34
|
+
import os
|
|
35
|
+
import re
|
|
36
|
+
import signal
|
|
37
|
+
import subprocess
|
|
38
|
+
import sys
|
|
39
|
+
import time
|
|
40
|
+
from collections.abc import Sequence
|
|
41
|
+
from pathlib import Path
|
|
42
|
+
|
|
43
|
+
from sensorium import exit as ex
|
|
44
|
+
from sensorium import paths, redact
|
|
45
|
+
from sensorium.ts import focus as focus_mod
|
|
46
|
+
from sensorium.ts import harness as harness_mod
|
|
47
|
+
from sensorium.ts import ingest, invocation, pkg as pkg_mod, wrapper
|
|
48
|
+
|
|
49
|
+
#: Where a run's spools live, under the trace store. One directory per
|
|
50
|
+
#: invocation, named by it, holding the record, the spools and the marker.
|
|
51
|
+
SPOOL_DIR = "spool"
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class LinkError(Exception):
|
|
55
|
+
"""`--refocus-of` named something this store cannot link to. A refusal
|
|
56
|
+
like every other bad call, and the FIRST of them: the value is about
|
|
57
|
+
the call and nothing else, so it is settled before the Node version,
|
|
58
|
+
the package and `recognise` -- none of which could make a bad link
|
|
59
|
+
good, and all of which cost something to ask."""
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
class SpawnError(Exception):
|
|
63
|
+
"""The harness binary could not be started at all. `recognise` reads a
|
|
64
|
+
command and does not check that the program exists -- which `vitest`
|
|
65
|
+
runs is the user's choice, and resolving it there would resolve a
|
|
66
|
+
different one -- so this is where a name that is not a program is
|
|
67
|
+
found, and it is a refusal like every other bad call."""
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def run(args) -> int:
|
|
71
|
+
"""The `ts run` verb. See the module docstring for the order."""
|
|
72
|
+
command = list(getattr(args, "command", []))
|
|
73
|
+
if command and command[0] == "--":
|
|
74
|
+
command = command[1:]
|
|
75
|
+
try:
|
|
76
|
+
link = _refocus_link(getattr(args, "refocus_of", None))
|
|
77
|
+
except LinkError as e:
|
|
78
|
+
return _refuse(str(e))
|
|
79
|
+
try:
|
|
80
|
+
node = pkg_mod.check_node()
|
|
81
|
+
package = pkg_mod.locate()
|
|
82
|
+
pkg_mod.check(package)
|
|
83
|
+
except pkg_mod.PackageError as e:
|
|
84
|
+
return _refuse(str(e))
|
|
85
|
+
cwd = Path.cwd()
|
|
86
|
+
plan = harness_mod.recognise(command, cwd)
|
|
87
|
+
if isinstance(plan, harness_mod.Refusal):
|
|
88
|
+
return _refuse(plan.message)
|
|
89
|
+
# After `recognise`, because only the plan knows the root -- and still
|
|
90
|
+
# before anything is minted.
|
|
91
|
+
try:
|
|
92
|
+
pkg_mod.check_root(plan.root)
|
|
93
|
+
except pkg_mod.PackageError as e:
|
|
94
|
+
return _refuse(str(e))
|
|
95
|
+
# And after THAT, because resolving a focus parses the root's files with
|
|
96
|
+
# the root's own TypeScript. Still nothing minted: a focus that selects
|
|
97
|
+
# nothing is a call to fix, and a half-recorded run of it would be a
|
|
98
|
+
# recording of a question nobody asked (spec section 2.2).
|
|
99
|
+
focus = list(args.focus or [])
|
|
100
|
+
resolution = None
|
|
101
|
+
if any(spec.strip() == "" for spec in focus):
|
|
102
|
+
# An empty spec has an empty qualname, and an empty qualname is a
|
|
103
|
+
# prefix of every name there is: dropped it does nothing, honoured
|
|
104
|
+
# it records the whole program. Neither is what was typed.
|
|
105
|
+
return _refuse("--focus was given nothing to name: a spec is a "
|
|
106
|
+
"<qualname> or a <file>:<qualname>")
|
|
107
|
+
if focus:
|
|
108
|
+
try:
|
|
109
|
+
# `node` here is the VERSION `check_node` read, not a program:
|
|
110
|
+
# the resolver runs the same `node` on PATH the harness will.
|
|
111
|
+
resolution = focus_mod.resolve(plan.root, package, focus)
|
|
112
|
+
except pkg_mod.PackageError as e:
|
|
113
|
+
return _refuse(str(e))
|
|
114
|
+
bad = focus_mod.refusals(resolution, plan.root)
|
|
115
|
+
if bad:
|
|
116
|
+
return _refuse(*bad)
|
|
117
|
+
from sensorium.limits import LimitsError
|
|
118
|
+
try:
|
|
119
|
+
_caps(args)
|
|
120
|
+
except LimitsError as e:
|
|
121
|
+
return _refuse(str(e))
|
|
122
|
+
try:
|
|
123
|
+
return _record(plan, package, node, cwd, args, focus, resolution,
|
|
124
|
+
link)
|
|
125
|
+
except (wrapper.WrapperError, SpawnError) as e:
|
|
126
|
+
return _refuse(str(e))
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def _refuse(*messages: str) -> int:
|
|
130
|
+
"""One line on stderr per refusal, exit 2, nothing left behind. Every
|
|
131
|
+
refusal this driver makes before the harness is spawned goes through
|
|
132
|
+
here, so they are one shape and not six -- and a call with two mistakes
|
|
133
|
+
in it is told both, rather than sent round the loop twice."""
|
|
134
|
+
for message in messages:
|
|
135
|
+
print(f"error: {message}", file=sys.stderr)
|
|
136
|
+
return ex.BAD_CALL
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def _refocus_link(value: str | None) -> str | None:
|
|
140
|
+
"""The run id `--refocus-of` names, or None where it was not given.
|
|
141
|
+
|
|
142
|
+
One trailing `.db` is stripped rather than refused: the store holds
|
|
143
|
+
`<id>.db` files, so that is what tab-completion and a copied `ls` line
|
|
144
|
+
hand a person, and the id inside it is unambiguous.
|
|
145
|
+
|
|
146
|
+
Both refusals end `nothing was run.` because that is the fact the
|
|
147
|
+
caller needs: this check happens before anything is minted or spawned,
|
|
148
|
+
so a re-run refused here has left no half-recording behind to clean up.
|
|
149
|
+
The second names the STORE, not the file it looked for -- a person
|
|
150
|
+
given the directory can list it; a person given a path that does not
|
|
151
|
+
exist has been told what they already knew.
|
|
152
|
+
"""
|
|
153
|
+
if value is None:
|
|
154
|
+
return None
|
|
155
|
+
run_id = value[:-3] if value.endswith(".db") else value
|
|
156
|
+
if not paths.is_valid_run_id(run_id):
|
|
157
|
+
# `../x`, `a/b`, `.`: an id flows straight into `traces_dir() /
|
|
158
|
+
# f"{id}.db"`, so one that is not a single path component would
|
|
159
|
+
# read outside the store. The value is echoed AS GIVEN, suffix and
|
|
160
|
+
# all, because that is what the caller typed and has to correct.
|
|
161
|
+
raise LinkError(f"--refocus-of {value} is not a run id; "
|
|
162
|
+
"nothing was run.")
|
|
163
|
+
if not (paths.traces_dir() / f"{run_id}.db").is_file():
|
|
164
|
+
raise LinkError(f"--refocus-of {run_id} names no trace in "
|
|
165
|
+
f"{paths.trace_root()}; nothing was run.")
|
|
166
|
+
return run_id
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def _record(plan, package: Path, node: str, cwd: Path, args,
|
|
170
|
+
focus: Sequence[str], resolution,
|
|
171
|
+
link: str | None = None) -> int:
|
|
172
|
+
"""Everything from the mint to the conversion."""
|
|
173
|
+
inv_id = paths.new_run_id()
|
|
174
|
+
# One level at a time, 0700 each, for `paths.traces_dir()`'s reason:
|
|
175
|
+
# `Path.mkdir(parents=True, mode=...)` applies the mode to the directory
|
|
176
|
+
# it NAMES and gives every parent it creates on the way the default, so
|
|
177
|
+
# a single `spool.mkdir(parents=True, mode=0o700)` would leave
|
|
178
|
+
# `<store>/spool` -- and the store root above it, where `redaction.key`
|
|
179
|
+
# lives -- at 0775. Measured at 0775 by E16 part A (H2). An existing
|
|
180
|
+
# directory is never chmod'ed: the user's own store is theirs.
|
|
181
|
+
root = paths.trace_root()
|
|
182
|
+
root.mkdir(parents=True, exist_ok=True, mode=0o700)
|
|
183
|
+
(root / SPOOL_DIR).mkdir(exist_ok=True, mode=0o700)
|
|
184
|
+
spool = root / SPOOL_DIR / inv_id
|
|
185
|
+
spool.mkdir(exist_ok=True, mode=0o700)
|
|
186
|
+
config = (wrapper.home(plan.root) /
|
|
187
|
+
f"{inv_id}{wrapper.CONFIG_SUFFIX}"
|
|
188
|
+
if plan.kind == "vitest" else None)
|
|
189
|
+
_write_record(spool, plan, inv_id, node, package, config, focus,
|
|
190
|
+
[] if resolution is None else resolution.matched_specs,
|
|
191
|
+
None if resolution is None else resolution.wall,
|
|
192
|
+
refocus_of=link)
|
|
193
|
+
|
|
194
|
+
files: tuple = ()
|
|
195
|
+
try:
|
|
196
|
+
if plan.kind == "vitest":
|
|
197
|
+
files = wrapper.write(plan.root, inv_id, package,
|
|
198
|
+
plan.user_config)
|
|
199
|
+
argv = plan.vitest_command(files[0])
|
|
200
|
+
else:
|
|
201
|
+
argv = plan.node_command(package / "src" / "register.mjs")
|
|
202
|
+
try:
|
|
203
|
+
ending = _spawn(argv,
|
|
204
|
+
_env(spool, inv_id, plan, package, args.tier,
|
|
205
|
+
focus, args=args),
|
|
206
|
+
cwd)
|
|
207
|
+
except OSError as e:
|
|
208
|
+
# Nothing ran, so there is nothing to convert and nothing to
|
|
209
|
+
# keep: the record of an invocation that never happened would
|
|
210
|
+
# be listed by `runs` forever.
|
|
211
|
+
_discard(spool)
|
|
212
|
+
raise SpawnError(
|
|
213
|
+
f"{argv[0]} could not be started: {e.strerror}") from None
|
|
214
|
+
invocation.write_record(
|
|
215
|
+
spool / invocation.HARNESS_FILE,
|
|
216
|
+
json.dumps(ending.to_json(), indent=2) + "\n")
|
|
217
|
+
finally:
|
|
218
|
+
wrapper.remove(files)
|
|
219
|
+
return _convert(spool, inv_id, ending, getattr(args, "jobs", None),
|
|
220
|
+
args.tier)
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def _discard(spool: Path) -> None:
|
|
224
|
+
"""Take back a spool directory nothing was recorded into, and the
|
|
225
|
+
`spool/` above it when this invocation is what made it. Stops at a
|
|
226
|
+
directory another invocation is still using, exactly as
|
|
227
|
+
`wrapper.remove` does."""
|
|
228
|
+
for path in sorted(spool.iterdir()):
|
|
229
|
+
path.unlink(missing_ok=True)
|
|
230
|
+
for directory in (spool, spool.parent):
|
|
231
|
+
try:
|
|
232
|
+
directory.rmdir()
|
|
233
|
+
except OSError:
|
|
234
|
+
return
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
# -- the record --------------------------------------------------------------
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
def _write_record(spool: Path, plan, inv_id: str, node: str, package: Path,
|
|
241
|
+
config: Path | None, focus: Sequence[str] = (),
|
|
242
|
+
focus_matched: Sequence[str] = (),
|
|
243
|
+
resolver_wall_s: float | None = None,
|
|
244
|
+
refocus_of: str | None = None) -> None:
|
|
245
|
+
"""`invocation.json`, written BEFORE the harness is spawned.
|
|
246
|
+
|
|
247
|
+
It is the only thing that can say what a spool directory came out of: a
|
|
248
|
+
container knows its own pid and its own environment, but not which
|
|
249
|
+
command produced it and not where the project root is.
|
|
250
|
+
"""
|
|
251
|
+
record = invocation.Invocation(
|
|
252
|
+
invocation=inv_id, harness=plan.kind,
|
|
253
|
+
harness_args=list(plan.harness_args), root=str(plan.root),
|
|
254
|
+
# `plan.argv` is the tokens as typed, kept whole by `recognise`
|
|
255
|
+
# before `_consume` takes `--root`/`--config` out and before either
|
|
256
|
+
# `vitest_command`/`node_command` re-issues anything. That is the
|
|
257
|
+
# one list a reader can be shown and recognise as their own (R26).
|
|
258
|
+
command=list(plan.argv),
|
|
259
|
+
cwd=str(Path.cwd()), argv=list(plan.argv), env_hash=_env_hash(),
|
|
260
|
+
start_ts=time.time(), wrapper="" if config is None else str(config),
|
|
261
|
+
vitest=_vitest_version(plan), node=node,
|
|
262
|
+
driver_version=_driver_version(),
|
|
263
|
+
recorder=f"sensorium-ts {pkg_mod.version(package)}",
|
|
264
|
+
# Both, and always: the specs as typed and the functions they
|
|
265
|
+
# selected. A reader of this directory should not have to know which
|
|
266
|
+
# driver version wrote it to know that nothing was focused.
|
|
267
|
+
focus=list(focus), focus_matched=list(focus_matched),
|
|
268
|
+
# What resolving them cost, so an instrument can time the resolver
|
|
269
|
+
# without timing the driver around it. `None` where no focus was
|
|
270
|
+
# given: the resolver did not run, and 0.0 would say it did.
|
|
271
|
+
resolver_wall_s=resolver_wall_s,
|
|
272
|
+
# The run this one re-runs, validated before anything was minted.
|
|
273
|
+
# `None` is a command a person typed, and the converter then writes
|
|
274
|
+
# no `refocus_of` key at all: an absent key is what every reader of
|
|
275
|
+
# a trace branches on.
|
|
276
|
+
refocus_of=refocus_of)
|
|
277
|
+
invocation.write_record(spool / invocation.INVOCATION_FILE,
|
|
278
|
+
json.dumps(record.to_json(), indent=2) + "\n")
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
def _env_hash() -> str:
|
|
282
|
+
"""A digest of the DRIVER's environment, by the recipe both this
|
|
283
|
+
recorder's halves use (`invocation.env_hash`).
|
|
284
|
+
|
|
285
|
+
The driver's and not the harness's: the harness's differs from it by the
|
|
286
|
+
variables written two functions below, which are the recorder's own and
|
|
287
|
+
would make every invocation's hash unique by construction -- the
|
|
288
|
+
redaction key most of all, which is 64 characters no two stores share.
|
|
289
|
+
"""
|
|
290
|
+
return invocation.env_hash(os.environ)
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def _driver_version() -> str:
|
|
294
|
+
try:
|
|
295
|
+
return importlib.metadata.version("sensorium-trace")
|
|
296
|
+
except importlib.metadata.PackageNotFoundError:
|
|
297
|
+
return "sensorium (uninstalled source tree)"
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
def _vitest_version(plan) -> str | None:
|
|
301
|
+
"""Which vitest the consumer's tree holds, or None.
|
|
302
|
+
|
|
303
|
+
None for `node --test`, which has no vitest, and None for a vitest run
|
|
304
|
+
whose package cannot be read -- an absent version is written as no key
|
|
305
|
+
at all by the converter, never as an empty string.
|
|
306
|
+
"""
|
|
307
|
+
if plan.kind != "vitest":
|
|
308
|
+
return None
|
|
309
|
+
manifest = plan.root / "node_modules" / "vitest" / "package.json"
|
|
310
|
+
try:
|
|
311
|
+
text = manifest.read_text(encoding="utf-8")
|
|
312
|
+
except OSError:
|
|
313
|
+
return None
|
|
314
|
+
m = re.search(r'"version"\s*:\s*"([^"]*)"', text)
|
|
315
|
+
return m.group(1) if m else None
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
def _env(spool: Path, inv_id: str, plan, package: Path, tier: str,
|
|
319
|
+
focus: Sequence[str], args=None) -> dict:
|
|
320
|
+
"""The harness's environment: the driver's own, plus what the recorder
|
|
321
|
+
inside the harness cannot work out for itself.
|
|
322
|
+
|
|
323
|
+
`SENSORIUM_FOCUS` is set only when there IS a focus, and holds the specs
|
|
324
|
+
as typed, joined by the separator. One variable answers for all three
|
|
325
|
+
readers inside the harness -- the Vite plugin, the loader hook and the
|
|
326
|
+
runtime -- and an EMPTY one is not the same as an absent one to the last
|
|
327
|
+
of them: the runtime declares `line` and `locals` from its presence, and
|
|
328
|
+
an empty value would declare capabilities nothing was going to write.
|
|
329
|
+
|
|
330
|
+
It is the one inherited variable this driver overrides rather than
|
|
331
|
+
passes on. A `SENSORIUM_FOCUS` left in a shell would otherwise focus a
|
|
332
|
+
run whose own record says `focus: []` -- the recording would carry
|
|
333
|
+
statement rows nobody asked for, and the record beside it would deny it.
|
|
334
|
+
|
|
335
|
+
`SENSORIUM_REDACT_KEY` is the eighth, and the one the harness could not
|
|
336
|
+
work out even in principle: the runtime only ever PARSES a key, because
|
|
337
|
+
creating one means a directory, a temporary, a link and a race and the
|
|
338
|
+
runtime is linked into somebody else's test suite (design section 3). So
|
|
339
|
+
the STORE's key -- the same `<trace root>/redaction.key` the Python
|
|
340
|
+
recorder and `cargo-sensorium` use, minted here on first use -- is handed
|
|
341
|
+
down as hex. Set only when there IS a key: absent and malformed read
|
|
342
|
+
identically to the runtime, and an unkeyed store POPS whatever the
|
|
343
|
+
launching shell was carrying, because a key from some other store would
|
|
344
|
+
have the recorder write digests nothing here can verify.
|
|
345
|
+
|
|
346
|
+
The three cap variables are resolved here, once, from the command, the
|
|
347
|
+
environment and the store config, and written as integers. The runtime
|
|
348
|
+
reads the numbers and does not open the config. ``0`` is unlimited. A
|
|
349
|
+
value already in the environment is overwritten: the command wins, then
|
|
350
|
+
the environment, then the config, then the default.
|
|
351
|
+
"""
|
|
352
|
+
env = dict(os.environ,
|
|
353
|
+
SENSORIUM_SPOOL=str(spool),
|
|
354
|
+
SENSORIUM_TIER=tier,
|
|
355
|
+
SENSORIUM_TS_ROOT=str(plan.root),
|
|
356
|
+
SENSORIUM_TS_PKG=str(package),
|
|
357
|
+
SENSORIUM_INVOCATION=inv_id,
|
|
358
|
+
SENSORIUM_MANIFEST_DIR=str(spool / ingest.MANIFEST_DIR))
|
|
359
|
+
if focus:
|
|
360
|
+
env["SENSORIUM_FOCUS"] = focus_mod.SEP.join(focus)
|
|
361
|
+
else:
|
|
362
|
+
env.pop("SENSORIUM_FOCUS", None)
|
|
363
|
+
key = redact.Key.load_or_create(paths.trace_root())
|
|
364
|
+
if key.material is None:
|
|
365
|
+
env.pop(redact.KEY_VAR, None)
|
|
366
|
+
else:
|
|
367
|
+
env[redact.KEY_VAR] = key.material.hex()
|
|
368
|
+
limits = _caps(args)
|
|
369
|
+
env["SENSORIUM_MAX_EVENTS"] = str(limits.max_events)
|
|
370
|
+
env["SENSORIUM_MAX_BYTES"] = str(limits.max_bytes)
|
|
371
|
+
env["SENSORIUM_MAX_CALLS"] = str(limits.max_calls)
|
|
372
|
+
return env
|
|
373
|
+
|
|
374
|
+
|
|
375
|
+
def _caps(args):
|
|
376
|
+
"""The cap for this run. ``args`` may be None when a caller of `_env`
|
|
377
|
+
has no command object; the environment and the config still apply."""
|
|
378
|
+
from sensorium.limits import resolve
|
|
379
|
+
return resolve(
|
|
380
|
+
max_events=getattr(args, "max_events", None),
|
|
381
|
+
max_bytes=getattr(args, "max_bytes", None),
|
|
382
|
+
max_calls=getattr(args, "max_calls", None),
|
|
383
|
+
no_cap=bool(getattr(args, "no_cap", False)),
|
|
384
|
+
)
|
|
385
|
+
|
|
386
|
+
|
|
387
|
+
# -- the run -----------------------------------------------------------------
|
|
388
|
+
|
|
389
|
+
|
|
390
|
+
def _spawn(argv: list[str], env: dict, cwd: Path) -> invocation.HarnessExit:
|
|
391
|
+
"""Run the harness with the caller's own stdio and wait for it.
|
|
392
|
+
|
|
393
|
+
Inherited stdio, not captured: the harness's output is what the user
|
|
394
|
+
came for, it is often interactive, and a recorder that buffered a
|
|
395
|
+
ten-minute test run would look like a hang.
|
|
396
|
+
"""
|
|
397
|
+
start = time.time()
|
|
398
|
+
completed = subprocess.run(argv, env=env, cwd=cwd)
|
|
399
|
+
end = time.time()
|
|
400
|
+
if completed.returncode < 0:
|
|
401
|
+
name = signal.Signals(-completed.returncode).name
|
|
402
|
+
return invocation.HarnessExit(None, name, start, end)
|
|
403
|
+
return invocation.HarnessExit(completed.returncode, None, start, end)
|
|
404
|
+
|
|
405
|
+
|
|
406
|
+
def _status(ending: invocation.HarnessExit) -> int:
|
|
407
|
+
"""The driver's own exit status: the harness's, `128 + n` on a signal --
|
|
408
|
+
the number a shell reports for exactly that death."""
|
|
409
|
+
if ending.signal is not None:
|
|
410
|
+
return 128 + int(signal.Signals[ending.signal])
|
|
411
|
+
return ending.status or 0
|
|
412
|
+
|
|
413
|
+
|
|
414
|
+
def _ending(ending: invocation.HarnessExit) -> str:
|
|
415
|
+
"""How the run line says the harness ended. `basis` is always `waited`
|
|
416
|
+
and is printed: it is the one exit fact in a TypeScript recording that
|
|
417
|
+
somebody actually witnessed."""
|
|
418
|
+
if ending.signal is not None:
|
|
419
|
+
return f"signal {ending.signal} (waited)"
|
|
420
|
+
return f"{ending.status} (waited)"
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
def _convert(spool: Path, inv_id: str, ending, jobs: int | None,
|
|
424
|
+
tier: str) -> int:
|
|
425
|
+
"""One trace per container, then the run's own lines.
|
|
426
|
+
|
|
427
|
+
A spool the converter refuses prints its refusal and does NOT change the
|
|
428
|
+
exit status: the status belongs to the harness. An ingest that could not
|
|
429
|
+
start at all is the exception -- there is no recording to report, and
|
|
430
|
+
exit 2 says the call or the directory has to be fixed. Where the WRAPPER
|
|
431
|
+
is what refused, its own sentence is printed instead of the converter's
|
|
432
|
+
(R41): only it knows why the run recorded nothing.
|
|
433
|
+
|
|
434
|
+
At tier `off` there is nothing to convert BY DESIGN -- the transform
|
|
435
|
+
still runs, the runtime emits nothing, and the invocation's whole value
|
|
436
|
+
is the harness's own wall time. So the empty directory is reported as
|
|
437
|
+
the zero it is, and never as the failure it would be at tier `call`,
|
|
438
|
+
where an empty directory means the recorder was wired in and recorded
|
|
439
|
+
nothing.
|
|
440
|
+
"""
|
|
441
|
+
from sensorium.ts import cli as ts_cli
|
|
442
|
+
if tier == "off":
|
|
443
|
+
ts_cli._report([], inv_id, harness=_ending(ending))
|
|
444
|
+
return _after(_status(ending))
|
|
445
|
+
try:
|
|
446
|
+
summaries = ingest.ingest_dir(spool, paths.trace_root(), jobs=jobs)
|
|
447
|
+
except (ingest.IngestError, invocation.InvocationError) as e:
|
|
448
|
+
# The wrapper's own refusal FIRST (R41). "nothing was recorded, or
|
|
449
|
+
# the recorder wrote somewhere else" is what this looks like from
|
|
450
|
+
# here, and it names neither the cause nor the fix; the config that
|
|
451
|
+
# refused knows both, and left the sentence behind.
|
|
452
|
+
return _refuse(wrapper.refusal(spool) or str(e))
|
|
453
|
+
ts_cli._report(summaries, inv_id, harness=_ending(ending))
|
|
454
|
+
return _after(_status(ending))
|
|
455
|
+
|
|
456
|
+
|
|
457
|
+
def _after(status: int) -> int:
|
|
458
|
+
"""The harness status, after the store applies its retention rule.
|
|
459
|
+
|
|
460
|
+
``maybe_auto`` is a no-op when no rule is configured. A failure is
|
|
461
|
+
printed and does not replace the status: the status belongs to the
|
|
462
|
+
harness.
|
|
463
|
+
"""
|
|
464
|
+
try:
|
|
465
|
+
from sensorium.store.gc import maybe_auto
|
|
466
|
+
note = maybe_auto()
|
|
467
|
+
except Exception as e:
|
|
468
|
+
print(f"sensorium: gc failed: {e}", file=sys.stderr)
|
|
469
|
+
return status
|
|
470
|
+
if note:
|
|
471
|
+
print(note, file=sys.stderr)
|
|
472
|
+
return status
|