sensorium-trace 0.18.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sensorium/__init__.py +0 -0
- sensorium/__main__.py +4 -0
- sensorium/_c/rt/sensorium_c_rt.c +1446 -0
- sensorium/_typescript/package-lock.json +68 -0
- sensorium/_typescript/package.json +39 -0
- sensorium/_typescript/src/bindings.mjs +792 -0
- sensorium/_typescript/src/cap.mjs +227 -0
- sensorium/_typescript/src/capabilities.mjs +40 -0
- sensorium/_typescript/src/dbg.mjs +348 -0
- sensorium/_typescript/src/escape.mjs +351 -0
- sensorium/_typescript/src/focus.mjs +135 -0
- sensorium/_typescript/src/hook.mjs +127 -0
- sensorium/_typescript/src/index.mjs +1 -0
- sensorium/_typescript/src/naming.mjs +63 -0
- sensorium/_typescript/src/positions.mjs +37 -0
- sensorium/_typescript/src/probe.mjs +246 -0
- sensorium/_typescript/src/qualname.mjs +236 -0
- sensorium/_typescript/src/redact.mjs +711 -0
- sensorium/_typescript/src/register.mjs +15 -0
- sensorium/_typescript/src/resolve.mjs +260 -0
- sensorium/_typescript/src/rt.mjs +798 -0
- sensorium/_typescript/src/setup.mjs +11 -0
- sensorium/_typescript/src/tally.mjs +164 -0
- sensorium/_typescript/src/tasks.mjs +175 -0
- sensorium/_typescript/src/transform.mjs +800 -0
- sensorium/_typescript/src/vite.mjs +99 -0
- sensorium/c/__init__.py +8 -0
- sensorium/c/cc.py +612 -0
- sensorium/c/cli.py +60 -0
- sensorium/c/convert.py +669 -0
- sensorium/c/decode.py +300 -0
- sensorium/c/driver.py +365 -0
- sensorium/c/dwarf.py +706 -0
- sensorium/c/format.py +271 -0
- sensorium/c/pkg.py +187 -0
- sensorium/c/plan.py +277 -0
- sensorium/cli.py +140 -0
- sensorium/driver.py +47 -0
- sensorium/exit.py +33 -0
- sensorium/invocations.py +83 -0
- sensorium/limits.py +253 -0
- sensorium/mcp/__init__.py +0 -0
- sensorium/mcp/audit.py +162 -0
- sensorium/mcp/child.py +240 -0
- sensorium/mcp/cmd.py +101 -0
- sensorium/mcp/jsonrpc.py +172 -0
- sensorium/mcp/result.py +187 -0
- sensorium/mcp/schema.py +390 -0
- sensorium/mcp/server.py +493 -0
- sensorium/mcp/tools.py +299 -0
- sensorium/paths.py +80 -0
- sensorium/query/__init__.py +0 -0
- sensorium/query/caps.py +150 -0
- sensorium/query/dbg_dialects.py +64 -0
- sensorium/query/diff_cmd.py +748 -0
- sensorium/query/diff_notes.py +117 -0
- sensorium/query/exceptions_c.py +263 -0
- sensorium/query/exceptions_cmd.py +788 -0
- sensorium/query/exceptions_group.py +571 -0
- sensorium/query/exceptions_invocation.py +487 -0
- sensorium/query/exceptions_rust.py +683 -0
- sensorium/query/exceptions_typescript.py +688 -0
- sensorium/query/expr.py +606 -0
- sensorium/query/failures_cmd.py +306 -0
- sensorium/query/flow_cmd.py +778 -0
- sensorium/query/flow_report.py +128 -0
- sensorium/query/flow_values.py +195 -0
- sensorium/query/fmt.py +280 -0
- sensorium/query/frame_cmd.py +237 -0
- sensorium/query/grep_cmd.py +156 -0
- sensorium/query/help.py +18 -0
- sensorium/query/info_cmd.py +527 -0
- sensorium/query/info_rust.py +214 -0
- sensorium/query/info_typescript.py +261 -0
- sensorium/query/js_inspect.py +394 -0
- sensorium/query/moves.py +254 -0
- sensorium/query/redact_cmd.py +304 -0
- sensorium/query/refocus_cmd.py +661 -0
- sensorium/query/refocus_env.py +493 -0
- sensorium/query/refocus_facts.py +269 -0
- sensorium/query/refocus_licence.py +187 -0
- sensorium/query/refocus_report.py +327 -0
- sensorium/query/refocus_rust.py +537 -0
- sensorium/query/refocus_threads.py +197 -0
- sensorium/query/refocus_typescript.py +756 -0
- sensorium/query/refocus_world.py +666 -0
- sensorium/query/runs_cmd.py +213 -0
- sensorium/query/rust_debug.py +176 -0
- sensorium/query/sites.py +171 -0
- sensorium/query/tree_cmd.py +511 -0
- sensorium/query/tree_threads.py +168 -0
- sensorium/query/vocab.py +723 -0
- sensorium/query/watch_cmd.py +657 -0
- sensorium/record/__init__.py +0 -0
- sensorium/record/boot.py +797 -0
- sensorium/record/boot_io.py +141 -0
- sensorium/record/budget.py +135 -0
- sensorium/record/capture.py +433 -0
- sensorium/record/children.py +755 -0
- sensorium/record/children_merge.py +179 -0
- sensorium/record/elide.py +55 -0
- sensorium/record/fingerprint.py +26 -0
- sensorium/record/thread_starts.py +261 -0
- sensorium/record/tracer.py +798 -0
- sensorium/record/tracer_exc.py +199 -0
- sensorium/record/tracer_frames.py +618 -0
- sensorium/redact.py +304 -0
- sensorium/redact_content.py +156 -0
- sensorium/redact_key.py +317 -0
- sensorium/redact_store.py +502 -0
- sensorium/redact_values.py +433 -0
- sensorium/store/__init__.py +0 -0
- sensorium/store/db.py +284 -0
- sensorium/store/gc.py +360 -0
- sensorium/store/payloads.py +69 -0
- sensorium/store/reader.py +438 -0
- sensorium/store/writer.py +283 -0
- sensorium/ts/__init__.py +10 -0
- sensorium/ts/build.py +783 -0
- sensorium/ts/cli.py +130 -0
- sensorium/ts/driver.py +472 -0
- sensorium/ts/focus.py +146 -0
- sensorium/ts/harness.py +314 -0
- sensorium/ts/ingest.py +380 -0
- sensorium/ts/invocation.py +252 -0
- sensorium/ts/pkg.py +167 -0
- sensorium/ts/redaction.py +64 -0
- sensorium/ts/spool.py +168 -0
- sensorium/ts/truncation.py +81 -0
- sensorium/ts/wrapper.py +255 -0
- sensorium_trace-0.18.2.dist-info/METADATA +245 -0
- sensorium_trace-0.18.2.dist-info/RECORD +135 -0
- sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
- sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
- sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
"""One activation completely: args, local timeline, return, children."""
|
|
2
|
+
from sensorium import paths
|
|
3
|
+
from sensorium.exit import ANSWERED, BAD_CALL, NEGATIVE
|
|
4
|
+
from sensorium.query.caps import print_truncated
|
|
5
|
+
from sensorium.query.fmt import (fmt_args, fmt_event, fmt_exc, fmt_value,
|
|
6
|
+
parse_fref, unread_marker)
|
|
7
|
+
from sensorium.query.help import RUN_HELP
|
|
8
|
+
from sensorium.query.tree_cmd import (frame_line, kind_marker,
|
|
9
|
+
unframed_kind, unframed_line)
|
|
10
|
+
from sensorium.query.vocab import terms
|
|
11
|
+
from sensorium.store.reader import Trace
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def add_parser(sub) -> None:
|
|
15
|
+
p = sub.add_parser(
|
|
16
|
+
"frame", help="one activation in full",
|
|
17
|
+
description="Arguments, return or raise, and the per-line locals "
|
|
18
|
+
"timeline when the run was recorded with `--focus`; "
|
|
19
|
+
"frame ids fN come from `exceptions`, `tree` and "
|
|
20
|
+
"`grep`.",
|
|
21
|
+
epilog="exit: 0 yes, 1 no, 2 fix the call, 3 change the recording")
|
|
22
|
+
p.add_argument("run", help=RUN_HELP)
|
|
23
|
+
p.add_argument("frame", nargs="?", default=None, help="frame ref (f12)")
|
|
24
|
+
p.add_argument("--fn", default=None,
|
|
25
|
+
help="qualname of the function: exact match first, else "
|
|
26
|
+
"substring")
|
|
27
|
+
p.add_argument("--nth", type=int, default=1, help="which activation (1-based)")
|
|
28
|
+
p.set_defaults(func=run)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _resolve(trace, args):
|
|
32
|
+
"""Return (frame, error, exit status). `error` is set (and frame is
|
|
33
|
+
None) whenever resolution fails, so `run` can report exactly why
|
|
34
|
+
instead of a single catch-all message -- an out-of-range --nth (<=0, or
|
|
35
|
+
beyond how many activations were actually recorded) must refuse loudly,
|
|
36
|
+
never silently wrap to the wrong activation or raise an uncaught
|
|
37
|
+
IndexError.
|
|
38
|
+
|
|
39
|
+
The status travels WITH the message because the two say the same thing
|
|
40
|
+
and only this function knows which it is: a reference the trace simply
|
|
41
|
+
does not hold is the trace answering "no" (NEGATIVE), while an --nth
|
|
42
|
+
past the end or no reference at all is the call being wrong
|
|
43
|
+
(BAD_CALL). Deciding that in `run` would mean matching on the message
|
|
44
|
+
text, and the text is rewritten whenever it can be made clearer.
|
|
45
|
+
|
|
46
|
+
`--fn` resolves EXACT-first (X9): a code object whose qualname equals
|
|
47
|
+
`--fn` wins outright, even when it also happens to be a substring of
|
|
48
|
+
another qualname this trace holds. Only when no code object matches
|
|
49
|
+
exactly does `--fn` fall back to a substring over the DISTINCT
|
|
50
|
+
qualnames recorded -- one candidate is used as if it had been named
|
|
51
|
+
exactly, more than one is an ambiguous reference (the call is wrong,
|
|
52
|
+
not a coin flip among them) and exits BAD_CALL with every candidate
|
|
53
|
+
listed, and none falls straight through to the ordinary "no recorded
|
|
54
|
+
activations" message below."""
|
|
55
|
+
if args.frame:
|
|
56
|
+
f = trace.frame(parse_fref(args.frame))
|
|
57
|
+
if f is None:
|
|
58
|
+
return (None, f"no such frame: {args.frame} does not exist",
|
|
59
|
+
NEGATIVE)
|
|
60
|
+
return f, None, ANSWERED
|
|
61
|
+
if args.fn:
|
|
62
|
+
fn = args.fn
|
|
63
|
+
codes = [c for c in trace.codes() if c.qualname == fn]
|
|
64
|
+
if not codes:
|
|
65
|
+
distinct = sorted({c.qualname for c in trace.codes()
|
|
66
|
+
if fn in c.qualname})
|
|
67
|
+
if len(distinct) > 1:
|
|
68
|
+
return None, (
|
|
69
|
+
f"--fn {fn!r} is ambiguous: matches "
|
|
70
|
+
+ ", ".join(distinct)
|
|
71
|
+
+ "; give the exact qualname"), BAD_CALL
|
|
72
|
+
if distinct:
|
|
73
|
+
fn = distinct[0]
|
|
74
|
+
codes = [c for c in trace.codes() if c.qualname == fn]
|
|
75
|
+
matches = [f for f in trace.frames()
|
|
76
|
+
if trace.code(f.code_id).qualname == fn]
|
|
77
|
+
# Computed for BOTH branches: one qualname can name several code
|
|
78
|
+
# objects (two modules, a def rebound), and some of them can be
|
|
79
|
+
# coroutines while others are plain functions. Counting only the
|
|
80
|
+
# frames then reports a total `grep` contradicts.
|
|
81
|
+
calls = [e for c in codes for e in trace.unframed_calls(code_id=c.id)]
|
|
82
|
+
kinds = "/".join(sorted({unframed_kind(c) for c in calls}))
|
|
83
|
+
if not matches:
|
|
84
|
+
if calls:
|
|
85
|
+
# Recorded, not framed: the activations are in the trace,
|
|
86
|
+
# as CALL events -- denying them contradicts `grep` on the
|
|
87
|
+
# same trace, which is what v1 did. The kinds are a SET:
|
|
88
|
+
# naming the first call's kind would claim every one of them
|
|
89
|
+
# was that kind.
|
|
90
|
+
return None, (
|
|
91
|
+
f"{fn!r} was recorded as {len(calls)} call(s) but "
|
|
92
|
+
f"not framed ({kinds}): no frame, locals "
|
|
93
|
+
"or children to show; its events: sensorium grep "
|
|
94
|
+
f"{args.run} {fn}"), NEGATIVE
|
|
95
|
+
return None, ("no such frame: no recorded activations of "
|
|
96
|
+
f"{fn!r}"), NEGATIVE
|
|
97
|
+
if not (1 <= args.nth <= len(matches)):
|
|
98
|
+
mixed = (f" and {len(calls)} recorded but unframed ({kinds})"
|
|
99
|
+
if calls else "")
|
|
100
|
+
tail = (f"; its unframed events: sensorium grep {args.run} "
|
|
101
|
+
f"{fn}" if calls else "")
|
|
102
|
+
return None, (
|
|
103
|
+
f"--nth {args.nth} is out of range: {fn!r} has "
|
|
104
|
+
f"{len(matches)} framed activation(s){mixed}; valid --nth "
|
|
105
|
+
f"is 1..{len(matches)} over the framed ones{tail}"), BAD_CALL
|
|
106
|
+
return matches[args.nth - 1], None, ANSWERED
|
|
107
|
+
return (None, "no such frame; give f<id> or --fn QUALNAME [--nth N]",
|
|
108
|
+
BAD_CALL)
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def run(args) -> int:
|
|
112
|
+
trace = Trace.open(paths.find_trace(args.run))
|
|
113
|
+
print_truncated(trace)
|
|
114
|
+
# `status` is carried past the refusal branch and returned at the end:
|
|
115
|
+
# `_resolve` is the one place that decides this command's answer, and a
|
|
116
|
+
# second ANSWERED written down here would be a second place to change.
|
|
117
|
+
f, err, status = _resolve(trace, args)
|
|
118
|
+
if f is None:
|
|
119
|
+
print(err)
|
|
120
|
+
return status
|
|
121
|
+
code = trace.code(f.code_id)
|
|
122
|
+
end = f"e{f.return_event_id}" if f.return_event_id is not None else "?"
|
|
123
|
+
call = trace.event(f.call_event_id)
|
|
124
|
+
task = ""
|
|
125
|
+
if call is not None and call.task_id is not None:
|
|
126
|
+
t = trace.task(call.task_id)
|
|
127
|
+
name = t.name if t is not None else None
|
|
128
|
+
# The parentheses belong to the LABEL, not to the name: a unit whose
|
|
129
|
+
# name could not be read has a whole sentence of its own, and what
|
|
130
|
+
# that sentence says differs by language (`vocab.Terms`).
|
|
131
|
+
label = (f"({name})" if name is not None
|
|
132
|
+
else terms(trace).unnamed_task)
|
|
133
|
+
task = f" task t{call.task_id} {label}"
|
|
134
|
+
# A non-function kind is marked exactly as `tree` marks it -- the SAME
|
|
135
|
+
# function, `tree_cmd.kind_marker`, so the two views cannot drift and
|
|
136
|
+
# the language-keyed label (`[coroutine]` in Python, `[async]` in
|
|
137
|
+
# TypeScript) is decided in one place.
|
|
138
|
+
#
|
|
139
|
+
# The state tail is derived by `frame_state` (spec D2) and shown
|
|
140
|
+
# whenever it says something arc 1's `closed: {closed_by}` did not
|
|
141
|
+
# already say -- a plain function that simply returned, raised, or is
|
|
142
|
+
# still open keeps the byte-identical arc-1 header; every suspension
|
|
143
|
+
# state (and every non-function kind, even one that returned normally)
|
|
144
|
+
# gets its own `state:` segment because "closed: return" alone would
|
|
145
|
+
# hide THAT it suspended along the way.
|
|
146
|
+
state = trace.frame_state(f)
|
|
147
|
+
marker = kind_marker(trace, f.kind)
|
|
148
|
+
show_state = (f.kind != "function"
|
|
149
|
+
or state.state not in ("returned", "raised", "open"))
|
|
150
|
+
# `is not None`, the same rule `tree_cmd._state_tail` keeps: a recorder
|
|
151
|
+
# that records no line on a suspension (`sensorium-ts`) leaves this NULL,
|
|
152
|
+
# and ` at L{None}` would render the literal `LNone` -- a site invented
|
|
153
|
+
# out of an absent record. A line of 0 is not a line any recorder writes,
|
|
154
|
+
# so this changes no existing output.
|
|
155
|
+
state_tail = ((f" state: {state.state}"
|
|
156
|
+
+ (f" at L{state.line}" if state.line is not None else ""))
|
|
157
|
+
if show_state else "")
|
|
158
|
+
print(f"f{f.id} {code.file.rsplit('/', 1)[-1]}:{code.qualname}{marker} "
|
|
159
|
+
f"[e{f.call_event_id}..{end}] thread {f.thread_id}{task} "
|
|
160
|
+
f"depth {f.depth} closed: {f.closed_by or 'open'}{state_tail}")
|
|
161
|
+
if trace.parentage_basis() == "assumed":
|
|
162
|
+
print("parentage: assumed (format-1 trace) -- depth and the parent "
|
|
163
|
+
"chain are v1's last-opened-frame guess")
|
|
164
|
+
call_p = (call.payload or {}) if call else {}
|
|
165
|
+
# "(none)" is only true when the arguments were READ and there were
|
|
166
|
+
# none. When the payload says they went unread, that marker is the whole
|
|
167
|
+
# answer: "(none)" there is a positive claim about the call the trace
|
|
168
|
+
# never made -- the same marker `grep` and `tree` print for this event.
|
|
169
|
+
rendered = fmt_args(call_p.get("args", {}), limit=99)
|
|
170
|
+
marker = unread_marker(call_p)
|
|
171
|
+
print("args: " + (rendered + marker if rendered else marker.lstrip()
|
|
172
|
+
or "(none)"))
|
|
173
|
+
# LINE rows need --focus to be captured at all; YIELD/RESUME rows do
|
|
174
|
+
# not -- they mark a real suspension point regardless. Interleaving both
|
|
175
|
+
# kinds (in event order, since frame_events is ORDER BY id) means a
|
|
176
|
+
# focused coroutine's timeline shows exactly where it parked and resumed
|
|
177
|
+
# alongside its locals, not just the two disconnected facts.
|
|
178
|
+
lines = [e for e in trace.frame_events(f.id)
|
|
179
|
+
if e.kind in ("LINE", "YIELD", "RESUME")]
|
|
180
|
+
line_rows = [e for e in lines if e.kind == "LINE"]
|
|
181
|
+
if line_rows:
|
|
182
|
+
print("timeline:")
|
|
183
|
+
for e in lines:
|
|
184
|
+
# A LINE payload may carry an "unbound" list of names that went
|
|
185
|
+
# out of scope this step (`del x`, or the implicit unbind at the
|
|
186
|
+
# end of `except E as e:`) alongside possibly-empty "deltas".
|
|
187
|
+
# fmt_event already renders both -- reuse it rather than
|
|
188
|
+
# re-deriving the rendering and silently dropping unbound names.
|
|
189
|
+
prefix = "~ " if e.kind in ("YIELD", "RESUME") else ""
|
|
190
|
+
print(" " + prefix + fmt_event(trace, e))
|
|
191
|
+
else:
|
|
192
|
+
mod = code.file.rsplit("/", 1)[-1].removesuffix(".py")
|
|
193
|
+
# The reason a timeline is missing is not the same for every
|
|
194
|
+
# recorder. Rust has had per-statement LINE under
|
|
195
|
+
# `cargo sensorium --focus` since 0.4.0, so its hint names that
|
|
196
|
+
# command. A recorder that produces no LINE events at all says so
|
|
197
|
+
# instead of naming a command that cannot help.
|
|
198
|
+
print("timeline: not captured ("
|
|
199
|
+
+ terms(trace).timeline_hint.format(mod=mod,
|
|
200
|
+
qualname=code.qualname)
|
|
201
|
+
+ ")")
|
|
202
|
+
# Locals were never captured, but a suspension is not a local -- it
|
|
203
|
+
# is still a fact this trace holds, and hiding it because --focus
|
|
204
|
+
# wasn't on THIS frame would be a second, needless loss on top of
|
|
205
|
+
# the first.
|
|
206
|
+
susp_rows = [e for e in lines if e.kind != "LINE"]
|
|
207
|
+
if susp_rows:
|
|
208
|
+
print("timeline (suspensions only):")
|
|
209
|
+
for e in susp_rows:
|
|
210
|
+
print(" ~ " + fmt_event(trace, e))
|
|
211
|
+
if f.closed_by == "unwind":
|
|
212
|
+
# A Rust panic carries the `loc` it fired at, which is not the
|
|
213
|
+
# frame's own line: printing it is the difference between "this
|
|
214
|
+
# frame unwound" and "this frame unwound HERE".
|
|
215
|
+
exc = f.unwind_exc or {}
|
|
216
|
+
loc = exc.get("loc")
|
|
217
|
+
print("unwound: " + (fmt_exc(exc) if f.unwind_exc else "?")
|
|
218
|
+
+ (f" at {loc}" if loc else ""))
|
|
219
|
+
elif f.return_event_id is not None:
|
|
220
|
+
ret = trace.event(f.return_event_id)
|
|
221
|
+
print(f"return: {fmt_value((ret.payload or {}).get('value'))}")
|
|
222
|
+
# Both kinds of callee, merged by event id: a frame whose only callees
|
|
223
|
+
# were coroutines or generators has NO framed children, and listing only
|
|
224
|
+
# those printed "(none)" over calls the trace plainly holds -- the same
|
|
225
|
+
# contradiction with `grep` that `--fn` was fixed for.
|
|
226
|
+
kids = sorted([(ch.call_event_id, "f", ch) for ch in trace.children(f.id)]
|
|
227
|
+
+ [(ev.id, "u", ev) for ev in trace.unframed_calls()
|
|
228
|
+
if (ev.payload or {}).get("parent_frame") == f.id],
|
|
229
|
+
key=lambda k: k[0])
|
|
230
|
+
if kids:
|
|
231
|
+
print(f"children ({len(kids)}):")
|
|
232
|
+
for _eid, kind, obj in kids:
|
|
233
|
+
print(" " + (frame_line(trace, obj) if kind == "f"
|
|
234
|
+
else unframed_line(trace, obj)))
|
|
235
|
+
else:
|
|
236
|
+
print("children: (none)")
|
|
237
|
+
return status
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
"""Search events by qualname or captured-value content.
|
|
2
|
+
|
|
3
|
+
The pattern is a plain substring matched against the *rendered* `fmt_event`
|
|
4
|
+
line, which is what lets one flag search both names and values: the same
|
|
5
|
+
query finds `parse_row` the function and `'carol,x7'` the argument it was
|
|
6
|
+
called with. The rendered line also carries `e<id>` and the kind, so a
|
|
7
|
+
pattern like `RETURN` matches every return -- that is a documented
|
|
8
|
+
consequence of matching what is printed, not a bug.
|
|
9
|
+
|
|
10
|
+
Anything withheld is stated, and the continuation hint is a fully
|
|
11
|
+
instantiated command carrying every filter of the search it continues. A
|
|
12
|
+
hint that dropped `--kind`/`--fn` would resume a *different* search and
|
|
13
|
+
quietly show rows the first page had excluded.
|
|
14
|
+
"""
|
|
15
|
+
import shlex
|
|
16
|
+
|
|
17
|
+
from sensorium import paths
|
|
18
|
+
from sensorium.exit import ANSWERED, BAD_CALL, UNSETTLED
|
|
19
|
+
from sensorium.query.caps import none_status, print_incomplete
|
|
20
|
+
from sensorium.query.fmt import fmt_event, more_note, parse_eref
|
|
21
|
+
from sensorium.query.help import (KIND_HELP, LIMIT_HELP, PATTERN_HELP,
|
|
22
|
+
RUN_HELP)
|
|
23
|
+
from sensorium.store.reader import Trace
|
|
24
|
+
|
|
25
|
+
KINDS = ("CALL", "RETURN", "RAISE", "HANDLED", "LINE")
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def add_parser(sub) -> None:
|
|
29
|
+
p = sub.add_parser(
|
|
30
|
+
"grep", help="search events by name or value",
|
|
31
|
+
description="Every CALL, RETURN, RAISE, HANDLED or LINE event "
|
|
32
|
+
"whose name or rendered value contains the pattern; "
|
|
33
|
+
"`--after` resumes from an event id a previous "
|
|
34
|
+
"answer showed.",
|
|
35
|
+
epilog="exit: 0 yes, 1 no, 2 fix the call, 3 change the recording")
|
|
36
|
+
p.add_argument("run", help=RUN_HELP)
|
|
37
|
+
p.add_argument("pattern", help=PATTERN_HELP)
|
|
38
|
+
p.add_argument("--kind", default=None, choices=KINDS,
|
|
39
|
+
help=KIND_HELP)
|
|
40
|
+
p.add_argument("--fn", default=None,
|
|
41
|
+
help="qualname filter: exact match first, else substring")
|
|
42
|
+
p.add_argument("--after", default=None, help="event ref to resume from")
|
|
43
|
+
p.add_argument("--limit", type=int, default=50,
|
|
44
|
+
help=LIMIT_HELP)
|
|
45
|
+
p.set_defaults(func=run)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def continue_cmd(args, last: int) -> str:
|
|
49
|
+
"""The exact command that shows the next page of *this* search."""
|
|
50
|
+
parts = ["sensorium", "grep", shlex.quote(args.run),
|
|
51
|
+
shlex.quote(args.pattern)]
|
|
52
|
+
if args.kind:
|
|
53
|
+
parts += ["--kind", args.kind]
|
|
54
|
+
if args.fn:
|
|
55
|
+
parts += ["--fn", shlex.quote(args.fn)]
|
|
56
|
+
parts += ["--limit", str(args.limit), "--after", f"e{last}"]
|
|
57
|
+
return " ".join(parts)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def _no_line_capture(trace, args) -> bool:
|
|
61
|
+
"""`--kind LINE` against a run that recorded no LINE event at all.
|
|
62
|
+
|
|
63
|
+
Zero matches here is not the trace saying "no": nothing of that kind was
|
|
64
|
+
ever written down, so the search had nothing to be true or false about.
|
|
65
|
+
The note below and the exit status are the same fact, so both read it
|
|
66
|
+
from here -- deciding the status by matching the note's wording would
|
|
67
|
+
break the next time the wording improves.
|
|
68
|
+
"""
|
|
69
|
+
return args.kind == "LINE" and not trace.counts().get("LINE")
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _empty_note(trace, args, scanned: int, considered: int,
|
|
73
|
+
after: int) -> list[str]:
|
|
74
|
+
"""Zero matches is ambiguous on its own -- say what was searched.
|
|
75
|
+
|
|
76
|
+
Every active filter has to be named. Reporting "scanned 11 event(s); none
|
|
77
|
+
contained 'alice'" when `--fn` removed the three that did contain it
|
|
78
|
+
states a false fact about the trace, so the rows `--fn` took out are
|
|
79
|
+
counted separately and the claim is scoped to what actually remained.
|
|
80
|
+
"""
|
|
81
|
+
where = f" after e{after}" if after else ""
|
|
82
|
+
scope = f" of kind {args.kind}" if args.kind else ""
|
|
83
|
+
head = f"scanned {scanned} event(s){scope}{where}"
|
|
84
|
+
if args.fn is not None:
|
|
85
|
+
lines = [f"{head}; {scanned - considered} excluded by "
|
|
86
|
+
f"--fn {args.fn!r}; none of the remaining {considered} "
|
|
87
|
+
f"contained {args.pattern!r}"]
|
|
88
|
+
else:
|
|
89
|
+
lines = [f"{head}; none contained {args.pattern!r}"]
|
|
90
|
+
if _no_line_capture(trace, args):
|
|
91
|
+
lines.append("this run recorded no LINE events at all: line-level "
|
|
92
|
+
"capture needs --focus MODULE[:QUALNAME] at record time")
|
|
93
|
+
return lines
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def run(args) -> int:
|
|
97
|
+
if args.limit < 1:
|
|
98
|
+
print(f"--limit must be >= 1 (got {args.limit}); "
|
|
99
|
+
"there is no useful zero-row page")
|
|
100
|
+
return BAD_CALL
|
|
101
|
+
after = parse_eref(args.after) if args.after else 0
|
|
102
|
+
trace = Trace.open(paths.find_trace(args.run))
|
|
103
|
+
# Above the rows, because `matches: 0` on such a trace exits 3 and a 3
|
|
104
|
+
# the output does not explain is a number the reader cannot act on.
|
|
105
|
+
print_incomplete(trace, "the events searched below are not all the "
|
|
106
|
+
"events this run had")
|
|
107
|
+
events = trace.events(kind=args.kind, after=after)
|
|
108
|
+
# --fn exact-first (X9): if any candidate event's qualname equals --fn
|
|
109
|
+
# exactly, only exact matches pass; otherwise --fn behaves as it always
|
|
110
|
+
# has, a substring over the qualname. Decided once, over the whole
|
|
111
|
+
# candidate set, so an exact hit later in the scan cannot flip the rule
|
|
112
|
+
# partway through and mix the two behaviours in one run.
|
|
113
|
+
fn_exact = bool(args.fn) and any(
|
|
114
|
+
trace.code(e.code_id).qualname == args.fn
|
|
115
|
+
for e in events if e.code_id is not None)
|
|
116
|
+
shown = total = 0
|
|
117
|
+
scanned = considered = 0
|
|
118
|
+
last = after
|
|
119
|
+
for e in events:
|
|
120
|
+
if e.code_id is None:
|
|
121
|
+
continue
|
|
122
|
+
scanned += 1
|
|
123
|
+
if args.fn:
|
|
124
|
+
qualname = trace.code(e.code_id).qualname
|
|
125
|
+
if fn_exact:
|
|
126
|
+
if qualname != args.fn:
|
|
127
|
+
continue
|
|
128
|
+
elif args.fn not in qualname:
|
|
129
|
+
continue
|
|
130
|
+
considered += 1
|
|
131
|
+
line = fmt_event(trace, e)
|
|
132
|
+
if args.pattern not in line:
|
|
133
|
+
continue
|
|
134
|
+
total += 1
|
|
135
|
+
if shown < args.limit:
|
|
136
|
+
print(line)
|
|
137
|
+
shown += 1
|
|
138
|
+
last = e.id
|
|
139
|
+
clipped = f" (showing {shown})" if shown < total else ""
|
|
140
|
+
print(f"matches: {total}{clipped}")
|
|
141
|
+
if total == 0:
|
|
142
|
+
for note in _empty_note(trace, args, scanned, considered, after):
|
|
143
|
+
print(note)
|
|
144
|
+
if _no_line_capture(trace, args):
|
|
145
|
+
# The recording, not the program, is why there is nothing to
|
|
146
|
+
# show: re-record with --focus and ask again.
|
|
147
|
+
return UNSETTLED
|
|
148
|
+
# Nothing matched. Whether that is the trace answering "none" or a
|
|
149
|
+
# recording that stopped before the match would have been written
|
|
150
|
+
# is the one question `none_status` answers, for every command that
|
|
151
|
+
# can print an empty result.
|
|
152
|
+
return none_status(trace)
|
|
153
|
+
note = more_note(total, shown, continue_cmd(args, last))
|
|
154
|
+
if note:
|
|
155
|
+
print(note)
|
|
156
|
+
return ANSWERED
|
sensorium/query/help.py
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
"""The field help strings more than one query parser prints.
|
|
2
|
+
|
|
3
|
+
Seven strings, six of them shared by two commands or more. They live here
|
|
4
|
+
rather than beside each `add_argument` because they are the same FACT
|
|
5
|
+
said once -- what a run reference is, what `--limit` counts -- and a fact
|
|
6
|
+
copied into eight parsers drifts into eight wordings, which a caller
|
|
7
|
+
reading a tool table meets side by side.
|
|
8
|
+
|
|
9
|
+
Imported absolutely (`from sensorium.query import help as qhelp`), so the
|
|
10
|
+
module name shadows nothing at any call site.
|
|
11
|
+
"""
|
|
12
|
+
RUN_HELP = "run id, a unique prefix of one, or `last` (the newest trace)"
|
|
13
|
+
RUN_A_HELP = "the first run: " + RUN_HELP
|
|
14
|
+
RUN_B_HELP = "the second run: " + RUN_HELP
|
|
15
|
+
LIMIT_HELP = "most rows to print"
|
|
16
|
+
DEPTH_HELP = "levels of the call tree to print below the root"
|
|
17
|
+
PATTERN_HELP = "substring matched against event names and rendered values"
|
|
18
|
+
KIND_HELP = "keep events of this kind only"
|