sensorium-trace 0.18.2__py3-none-any.whl

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