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,657 @@
|
|
|
1
|
+
"""A predicate at every recorded site, and how close the run came to it.
|
|
2
|
+
|
|
3
|
+
WHAT THIS COMMAND CLAIMS
|
|
4
|
+
------------------------
|
|
5
|
+
A SITE is one recorded event in a matching frame: a CALL, carrying that
|
|
6
|
+
activation's arguments, or a LINE, carrying that frame's locals folded
|
|
7
|
+
forward. At each site the predicate is applied to the state the trace records
|
|
8
|
+
there, and the site lands in exactly one bucket: HIT, miss, could-not-check,
|
|
9
|
+
or errored. Nothing is skipped, and every bucket is counted in one tally line.
|
|
10
|
+
|
|
11
|
+
WHAT IT REFUSES TO CLAIM
|
|
12
|
+
------------------------
|
|
13
|
+
That an invariant held. It cannot: a trace holds what was recorded, and
|
|
14
|
+
between two recorded sites the program ran code this command never saw. So
|
|
15
|
+
`hits: 0` is never printed on its own. It is always accompanied by a verdict
|
|
16
|
+
that says which of three different things happened --
|
|
17
|
+
|
|
18
|
+
* every recorded site was evaluated and none satisfied the predicate
|
|
19
|
+
(a fact about the recording, still not a proof about the run),
|
|
20
|
+
* some sites could not be evaluated, so the question is open, or
|
|
21
|
+
* NOTHING was checked at all, and `hits: 0` means "could not evaluate".
|
|
22
|
+
|
|
23
|
+
-- and by the count of sites it could not check, with the reason. The tally
|
|
24
|
+
line carries every bucket (`sites` = `evaluated` + `not-captured` + `errors`)
|
|
25
|
+
so the arithmetic is checkable rather than trusted. A user reading "0 hits"
|
|
26
|
+
as "the invariant held" when the truth was "I could not check" is the single
|
|
27
|
+
worst outcome this command has, and every design choice below is aimed at it.
|
|
28
|
+
|
|
29
|
+
That includes a hole that short-circuiting leaves open: a name the trace has
|
|
30
|
+
no record of ANYWHERE is absorbed silently by `and`/`or` and never reaches
|
|
31
|
+
the not-captured count. `print_never_recorded` closes it, above the verdict,
|
|
32
|
+
and the verdict refuses to come back clean while such a name is in play.
|
|
33
|
+
|
|
34
|
+
FOLDING STATE FORWARD, AND THE KEY THAT MAKES IT HONEST
|
|
35
|
+
-------------------------------------------------------
|
|
36
|
+
LINE payloads carry only the locals whose capture CHANGED. To know what was
|
|
37
|
+
in scope at a site, this command folds those deltas forward through the
|
|
38
|
+
frame. A local that goes AWAY produces no delta -- so a fold that reads
|
|
39
|
+
`deltas` alone keeps a deleted variable alive at its last value for the rest
|
|
40
|
+
of the frame, and reports a HIT on a variable that no longer exists.
|
|
41
|
+
|
|
42
|
+
The tracer emits a sibling `unbound` list for exactly this consumer, and it
|
|
43
|
+
is not a rare case: `del x` does it, and the implicit unbind that ends every
|
|
44
|
+
`except E as e:` block does it far more often. Measured on a three-pass loop
|
|
45
|
+
whose handler rebinds `e` to an int, ignoring `unbound` turns one true hit
|
|
46
|
+
into three. A LINE event may also carry EMPTY deltas and a non-empty
|
|
47
|
+
`unbound` -- a `del` on a line that changes nothing else -- so such an event
|
|
48
|
+
is a site like any other and is never skipped for having no deltas.
|
|
49
|
+
|
|
50
|
+
TRUNCATION
|
|
51
|
+
----------
|
|
52
|
+
A clipped string capture is a PREFIX; comparing it, or taking its length, is
|
|
53
|
+
a claim about characters the trace does not hold. Those sites are refused and
|
|
54
|
+
counted, not quietly answered. Container captures are unaffected: their
|
|
55
|
+
recorded length is exact even when the sample was capped, and nothing here
|
|
56
|
+
reads a `sample` key (a depth-capped capture omits it entirely).
|
|
57
|
+
"""
|
|
58
|
+
import shlex
|
|
59
|
+
from dataclasses import dataclass
|
|
60
|
+
from enum import Enum, auto
|
|
61
|
+
|
|
62
|
+
from sensorium import paths, redact
|
|
63
|
+
from sensorium.exit import ANSWERED, BAD_CALL, NEGATIVE, UNSETTLED
|
|
64
|
+
from sensorium.query.caps import print_incomplete, require
|
|
65
|
+
from sensorium.query.expr import (CLIPPED, CONTAINER, NO_LENGTH, NO_VALUE,
|
|
66
|
+
NOT_CAPTURED, OUT_OF_SCOPE, REDACTED,
|
|
67
|
+
REDACTED_REASON, TRUNCATED, EvalError,
|
|
68
|
+
ExprError, NotCaptured, _Sized,
|
|
69
|
+
compile_expr, resolve)
|
|
70
|
+
from sensorium.query.dbg_dialects import for_trace
|
|
71
|
+
from sensorium.query.fmt import fmt_event, fmt_value, more_note, parse_eref
|
|
72
|
+
from sensorium.query.help import LIMIT_HELP, RUN_HELP
|
|
73
|
+
from sensorium.query.sites import ( # noqa: F401 (re-exported)
|
|
74
|
+
_qual_matches, rerun_command, spell_site)
|
|
75
|
+
from sensorium.query.sites import site_matches as _site_matches
|
|
76
|
+
from sensorium.query.vocab import terms
|
|
77
|
+
from sensorium.store.reader import Trace
|
|
78
|
+
|
|
79
|
+
_MAX_LISTED_CODES = 20
|
|
80
|
+
_MAX_LISTED_ERRORS = 5
|
|
81
|
+
|
|
82
|
+
#: What a state line says for a name the redaction rule took. One constant
|
|
83
|
+
#: because two places read it -- `_render`, which prints it at a site, and
|
|
84
|
+
#: `_guidance`, which quotes it so a reader who never reaches a hit knows
|
|
85
|
+
#: what the words will be. Two literals would drift, and a test or a vector
|
|
86
|
+
#: needle that matched only the quoted one would pin nothing about the
|
|
87
|
+
#: renderer.
|
|
88
|
+
REDACTED_STATE = "<redacted; no comparable value>"
|
|
89
|
+
|
|
90
|
+
CLAIM = (
|
|
91
|
+
"a site is one RECORDED event in a matching frame: a CALL (its arguments)",
|
|
92
|
+
"or a LINE (that frame's locals, folded forward and dropped again when a",
|
|
93
|
+
"name goes out of scope). Whatever ran between two recorded sites",
|
|
94
|
+
"was not checked, and code this run never recorded is not in this trace.",
|
|
95
|
+
)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def add_parser(sub) -> None:
|
|
99
|
+
p = sub.add_parser(
|
|
100
|
+
"watch", help="predicate over captured state",
|
|
101
|
+
description="A gdb-style watchpoint evaluated after the fact at "
|
|
102
|
+
"every recorded site of one function; needs a "
|
|
103
|
+
"`--focus` recording, and NOTHING WAS CHECKED is a "
|
|
104
|
+
"refusal, never a pass.",
|
|
105
|
+
epilog="exit: 0 yes, 1 no, 2 fix the call, 3 change the recording")
|
|
106
|
+
p.add_argument("run", help=RUN_HELP)
|
|
107
|
+
p.add_argument("--at", required=True, help="module:qualname or qualname")
|
|
108
|
+
p.add_argument("--expr", required=True,
|
|
109
|
+
help="names, literals, one comparison, and/or/not, "
|
|
110
|
+
"arithmetic, len(name)")
|
|
111
|
+
p.add_argument("--after", default=None, help="event ref to resume from")
|
|
112
|
+
p.add_argument("--limit", type=int, default=20,
|
|
113
|
+
help=LIMIT_HELP)
|
|
114
|
+
p.add_argument("--misses", type=int, default=5, dest="misses",
|
|
115
|
+
help="how many near-misses to show when nothing hit")
|
|
116
|
+
p.set_defaults(func=run)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
# -- selecting sites -------------------------------------------------------
|
|
120
|
+
def site_matches(code, at: str, trace) -> bool:
|
|
121
|
+
"""Whether `--at` selects this code object -- `query/sites`' rule.
|
|
122
|
+
|
|
123
|
+
A delegation and not a copy: the same rule decides what `--at` selects,
|
|
124
|
+
what the no-match listing prints and what `--focus` would re-record, and
|
|
125
|
+
a second implementation here is how those three drift apart.
|
|
126
|
+
"""
|
|
127
|
+
return _site_matches(code, at, trace)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
@dataclass(frozen=True)
|
|
131
|
+
class Site:
|
|
132
|
+
"""One recorded event, with the state the predicate sees there."""
|
|
133
|
+
event: object
|
|
134
|
+
env: dict # name -> resolved value (or a marker saying why not)
|
|
135
|
+
caps: dict # name -> the raw capture behind it, for rendering
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def _bind(env: dict, caps: dict, deltas: dict, wanted: set,
|
|
139
|
+
dialect=None) -> None:
|
|
140
|
+
for n, v in deltas.items():
|
|
141
|
+
if n in wanted:
|
|
142
|
+
env[n] = resolve(v, dialect)
|
|
143
|
+
caps[n] = v
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def sites_for(trace, code_ids, wanted: set, dialect=None) -> list[Site]:
|
|
147
|
+
"""Every recorded site in the matching frames, state folded forward.
|
|
148
|
+
|
|
149
|
+
Only the predicate's own names are tracked, which bounds the copy per
|
|
150
|
+
site and keeps a wide frame from carrying its whole scope into memory.
|
|
151
|
+
|
|
152
|
+
`dialect` is which formatter wrote this trace's `dbg` captures. Absent,
|
|
153
|
+
a rendered capture is read as Rust's -- today's behaviour for every
|
|
154
|
+
caller that predates the second dialect (ruling R2, extending P10).
|
|
155
|
+
"""
|
|
156
|
+
frames = sorted((f for cid in code_ids for f in trace.frames(code_id=cid)),
|
|
157
|
+
key=lambda f: f.id)
|
|
158
|
+
out: list[Site] = []
|
|
159
|
+
for f in frames:
|
|
160
|
+
env: dict = {}
|
|
161
|
+
caps: dict = {}
|
|
162
|
+
call = trace.event(f.call_event_id)
|
|
163
|
+
if call is not None:
|
|
164
|
+
_bind(env, caps, (call.payload or {}).get("args", {}), wanted,
|
|
165
|
+
dialect)
|
|
166
|
+
out.append(Site(call, dict(env), dict(caps)))
|
|
167
|
+
for e in trace.frame_events(f.id):
|
|
168
|
+
if e.kind != "LINE":
|
|
169
|
+
continue
|
|
170
|
+
p = e.payload or {}
|
|
171
|
+
_bind(env, caps, p.get("deltas", {}), wanted, dialect)
|
|
172
|
+
# THE fold that makes this command honest -- see the module
|
|
173
|
+
# docstring. Never conditional on there being deltas: a `del` on
|
|
174
|
+
# an otherwise inert line records an empty `deltas` and this list.
|
|
175
|
+
for n in p.get("unbound", []):
|
|
176
|
+
env.pop(n, None)
|
|
177
|
+
caps.pop(n, None)
|
|
178
|
+
out.append(Site(e, dict(env), dict(caps)))
|
|
179
|
+
out.sort(key=lambda s: s.event.id)
|
|
180
|
+
return out
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
# -- applying the predicate ------------------------------------------------
|
|
184
|
+
@dataclass
|
|
185
|
+
class Outcome:
|
|
186
|
+
hits: list
|
|
187
|
+
near: list # (margin, Site), closest first
|
|
188
|
+
misses: int
|
|
189
|
+
unavailable: dict # (name, reason) -> site count
|
|
190
|
+
errors: list # (Site, EvalError)
|
|
191
|
+
|
|
192
|
+
@property
|
|
193
|
+
def evaluated(self) -> int:
|
|
194
|
+
return len(self.hits) + self.misses
|
|
195
|
+
|
|
196
|
+
@property
|
|
197
|
+
def not_captured(self) -> int:
|
|
198
|
+
return sum(self.unavailable.values())
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
def evaluate(sites: list[Site], expr) -> Outcome:
|
|
202
|
+
out = Outcome([], [], 0, {}, [])
|
|
203
|
+
for s in sites:
|
|
204
|
+
try:
|
|
205
|
+
got = expr.eval(s.env)
|
|
206
|
+
except NotCaptured as nc:
|
|
207
|
+
key = (nc.name, nc.reason)
|
|
208
|
+
out.unavailable[key] = out.unavailable.get(key, 0) + 1
|
|
209
|
+
continue
|
|
210
|
+
except EvalError as ee:
|
|
211
|
+
out.errors.append((s, ee))
|
|
212
|
+
continue
|
|
213
|
+
if got:
|
|
214
|
+
out.hits.append(s)
|
|
215
|
+
continue
|
|
216
|
+
out.misses += 1
|
|
217
|
+
m = expr.margin(s.env)
|
|
218
|
+
if m is not None:
|
|
219
|
+
out.near.append((m, s))
|
|
220
|
+
out.near.sort(key=lambda t: (t[0], t[1].event.id))
|
|
221
|
+
return out
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
# -- rendering -------------------------------------------------------------
|
|
225
|
+
def _render(name: str, site: Site) -> str:
|
|
226
|
+
if name not in site.env:
|
|
227
|
+
return "<not in scope>"
|
|
228
|
+
v = site.env[name]
|
|
229
|
+
cap = site.caps.get(name) or {}
|
|
230
|
+
if v is REDACTED:
|
|
231
|
+
# NOT `fmt_value(cap)`, which is right for a listing and wrong
|
|
232
|
+
# here: `<redacted #01234567>` names WHICH value was taken, and
|
|
233
|
+
# what a predicate's state line has to say is that there was
|
|
234
|
+
# nothing to compare it with.
|
|
235
|
+
return REDACTED_STATE
|
|
236
|
+
if v is NOT_CAPTURED:
|
|
237
|
+
return f"<{cap.get('type', 'object')}; no comparable value>"
|
|
238
|
+
if v is TRUNCATED:
|
|
239
|
+
return f"<clipped to {len(cap.get('v', ''))} chars>"
|
|
240
|
+
if isinstance(v, _Sized):
|
|
241
|
+
return f"<{cap.get('type', 'container')} of length {v.n}>"
|
|
242
|
+
return fmt_value(cap)
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
def state_of(expr, site: Site) -> str:
|
|
246
|
+
return " ".join(f"{n}={_render(n, site)}" for n in sorted(expr.names))
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
def refocus_cmd(trace, codes) -> str:
|
|
250
|
+
"""The exact command that re-records this run with these frames' locals.
|
|
251
|
+
|
|
252
|
+
`query/sites`' template, instantiated from this trace's own meta: the
|
|
253
|
+
command differs per recorder (`sensorium run`, `sensorium ts run`,
|
|
254
|
+
`cargo sensorium`) and naming the wrong one sends the reader to a
|
|
255
|
+
second refusal. Python's bytes are unchanged, and `tests/test_watch.py`
|
|
256
|
+
is the fence around them.
|
|
257
|
+
"""
|
|
258
|
+
return rerun_command(trace, codes)
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
def _unframed(trace, c) -> bool:
|
|
262
|
+
"""Coroutine/generator code: CALL events recorded, no frame ever opened.
|
|
263
|
+
|
|
264
|
+
One predicate for both callers below, so the note and the flag that
|
|
265
|
+
rewrites the NEVER RECORDED block can never disagree about which code
|
|
266
|
+
objects they are talking about -- the block's "(see the line above the
|
|
267
|
+
verdict)" points at a line only this decides to print.
|
|
268
|
+
"""
|
|
269
|
+
return (bool(trace.unframed_calls(code_id=c.id))
|
|
270
|
+
and not trace.frames(code_id=c.id))
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
def unframed_note(trace, codes) -> list[str]:
|
|
274
|
+
"""Which of the `--at` matches are coroutine/generator code -- recorded
|
|
275
|
+
as calls, never framed, so they contribute NO site. Returned as
|
|
276
|
+
(lines, all_unframed) would be two things; callers get the lines and
|
|
277
|
+
test `all_unframed_codes` separately."""
|
|
278
|
+
unf = [c for c in codes if _unframed(trace, c)]
|
|
279
|
+
if not unf:
|
|
280
|
+
return []
|
|
281
|
+
names = ", ".join(c.qualname for c in unf)
|
|
282
|
+
if len(unf) == len(codes):
|
|
283
|
+
return [f"--at matched only coroutine/generator code ({names}), which "
|
|
284
|
+
"opens no frame in this version: watch sites are frames, so "
|
|
285
|
+
"there are no sites here at all, and refocusing cannot change "
|
|
286
|
+
"that"]
|
|
287
|
+
return [f"{len(unf)} of the {len(codes)} matched code object(s) ({names}) "
|
|
288
|
+
"are coroutine/generator code: recorded as calls, never framed, "
|
|
289
|
+
"and contributed no site"]
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def all_unframed_codes(trace, codes) -> bool:
|
|
293
|
+
return bool(codes) and all(_unframed(trace, c) for c in codes)
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
def _guidance(reason: str, name: str, ever: bool, has_line: bool,
|
|
297
|
+
trace, codes, all_unframed: bool = False) -> list[str]:
|
|
298
|
+
"""What to actually do about a name that could not be evaluated.
|
|
299
|
+
|
|
300
|
+
The distinction that matters most: a name recorded at OTHER sites in
|
|
301
|
+
these frames is a scope fact, and telling a reader to refocus there sends
|
|
302
|
+
them to re-record a run that already holds what they need.
|
|
303
|
+
"""
|
|
304
|
+
if reason == CONTAINER:
|
|
305
|
+
return ["its length was recorded and its contents only sampled; "
|
|
306
|
+
"compare the length instead"]
|
|
307
|
+
if reason == NO_VALUE:
|
|
308
|
+
return ["only its type and repr were recorded, so there is nothing to "
|
|
309
|
+
"compare; refocusing cannot change that"]
|
|
310
|
+
if reason == NO_LENGTH:
|
|
311
|
+
return ["what the trace holds there is the value itself -- a number, "
|
|
312
|
+
"a bool, or a rendering the recorder could only format -- "
|
|
313
|
+
"and none of those carries a recorded length; compare the "
|
|
314
|
+
"name itself instead"]
|
|
315
|
+
if reason == REDACTED_REASON:
|
|
316
|
+
# Ahead of the `ever` branch below, which would otherwise call this
|
|
317
|
+
# a scope fact and send a reader hunting a binding bug that is not
|
|
318
|
+
# there: the name IS captured at these sites, and the rule took
|
|
319
|
+
# what was in it.
|
|
320
|
+
return ["the redaction rule took it at the recorder, before "
|
|
321
|
+
"anything reached disk, so no re-reading of this trace "
|
|
322
|
+
f"holds a value; a state line shows such a name as "
|
|
323
|
+
f"{REDACTED_STATE}",
|
|
324
|
+
# The REMEDY, not just the diagnosis. The rule runs at
|
|
325
|
+
# record time, so the only thing that changes this answer
|
|
326
|
+
# is recording again with the name allowed -- and the
|
|
327
|
+
# allow list is compared after the same normalisation the
|
|
328
|
+
# rule uses, so the binding's own spelling is the value to
|
|
329
|
+
# set. Named in one command with the re-run, because
|
|
330
|
+
# exporting the variable and forgetting to re-record is
|
|
331
|
+
# the obvious way to follow this advice and get nowhere.
|
|
332
|
+
f"re-record with that name allowed, where its value is "
|
|
333
|
+
f"not a secret: export {redact.ALLOW_VAR}="
|
|
334
|
+
f"{shlex.quote(name)} && {refocus_cmd(trace, codes)}"]
|
|
335
|
+
if reason == CLIPPED:
|
|
336
|
+
return ["the capture is a prefix cut at the string cap, so the value "
|
|
337
|
+
"itself was never recorded",
|
|
338
|
+
f"see the caps this run used with: sensorium info "
|
|
339
|
+
f"{shlex.quote(trace.path.stem)}"]
|
|
340
|
+
if ever:
|
|
341
|
+
# How a name leaves scope is the LANGUAGE's fact, so the tail comes
|
|
342
|
+
# from the trace's own column: this sentence named `del` and
|
|
343
|
+
# `except E as e:` on a Rust and a TypeScript trace alike, which is
|
|
344
|
+
# two Python statements offered as advice to a reader of neither.
|
|
345
|
+
return ["recorded at other sites in these frames, so this is scope, "
|
|
346
|
+
"not capture depth:",
|
|
347
|
+
*terms(trace).scope_exit_note]
|
|
348
|
+
if not has_line:
|
|
349
|
+
if all_unframed:
|
|
350
|
+
return ["no site exists for these code objects: coroutine/"
|
|
351
|
+
"generator code opens no frame in this version"]
|
|
352
|
+
return ["no local of these frames was recorded at all -- line capture "
|
|
353
|
+
"is opt-in at record time",
|
|
354
|
+
"refocus and re-run: " + refocus_cmd(trace, codes)]
|
|
355
|
+
return [f"this run recorded locals for these frames but never a "
|
|
356
|
+
f"{name!r}; check the spelling, or widen --at"]
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
def print_never_recorded(ghosts: list[str],
|
|
360
|
+
all_unframed: bool = False) -> None:
|
|
361
|
+
"""Names the predicate needs that NO site in these frames ever bound.
|
|
362
|
+
|
|
363
|
+
The hole short-circuiting leaves, and it defeats the rule this command is
|
|
364
|
+
built on. `n > 1000 and ghost > 1` is decided entirely by `n` at every
|
|
365
|
+
site where `n` is small -- logically sound, and it means a typo'd or
|
|
366
|
+
never-focused conjunct is absorbed in SILENCE: the tally reports
|
|
367
|
+
`not-captured: 0` and the verdict comes back as strong as this command can
|
|
368
|
+
make it, with no mention of `ghost` anywhere. A predicate the reader
|
|
369
|
+
believes is checking two things, checking one, and reading as maximally
|
|
370
|
+
clean, is exactly the "could not evaluate" masquerading as "the invariant
|
|
371
|
+
held" that everything else here is built to prevent.
|
|
372
|
+
|
|
373
|
+
The `or` mirror is milder only by accident (a hit renders a state line
|
|
374
|
+
naming the name), so it is not relied on: both are warned, above the
|
|
375
|
+
verdict, and the verdict itself refuses to come back clean.
|
|
376
|
+
"""
|
|
377
|
+
if not ghosts:
|
|
378
|
+
return
|
|
379
|
+
names = ", ".join(repr(g) for g in ghosts)
|
|
380
|
+
print(f"NEVER RECORDED: {names} -- named by the predicate, captured at NO "
|
|
381
|
+
"site in these frames")
|
|
382
|
+
print(" every result below was decided WITHOUT it: nothing in this trace "
|
|
383
|
+
"witnesses that name")
|
|
384
|
+
if all_unframed:
|
|
385
|
+
print(" there are no frames here at all: --at matched only "
|
|
386
|
+
"coroutine/generator code, which opens no frame in this version "
|
|
387
|
+
"(see the line above the verdict)")
|
|
388
|
+
else:
|
|
389
|
+
print(" either it is misspelled, or it lives in frames this run did "
|
|
390
|
+
"not record")
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
def print_unavailable(trace, out: Outcome, sites, ever, codes,
|
|
394
|
+
n_sites: int, all_unframed: bool = False) -> None:
|
|
395
|
+
if not out.unavailable:
|
|
396
|
+
return
|
|
397
|
+
has_line = any(s.event.kind == "LINE" for s in sites)
|
|
398
|
+
print(f"not captured at {out.not_captured} of {n_sites} site(s) -- the "
|
|
399
|
+
"predicate could not be checked there:")
|
|
400
|
+
for (name, reason), n in sorted(out.unavailable.items(),
|
|
401
|
+
key=lambda kv: (-kv[1], kv[0])):
|
|
402
|
+
print(f" {name}: {reason.replace('NAME', name)} [{n} site(s)]")
|
|
403
|
+
for line in _guidance(reason, name, name in ever, has_line,
|
|
404
|
+
trace, codes, all_unframed):
|
|
405
|
+
print(f" {line}")
|
|
406
|
+
|
|
407
|
+
|
|
408
|
+
def print_errors(out: Outcome) -> None:
|
|
409
|
+
if not out.errors:
|
|
410
|
+
return
|
|
411
|
+
print(f"errors: {len(out.errors)} site(s) raised while applying the "
|
|
412
|
+
"predicate (neither a hit nor a miss):")
|
|
413
|
+
for site, err in out.errors[:_MAX_LISTED_ERRORS]:
|
|
414
|
+
print(f" e{site.event.id}: {err}")
|
|
415
|
+
extra = len(out.errors) - _MAX_LISTED_ERRORS
|
|
416
|
+
if extra > 0:
|
|
417
|
+
print(f" ... {extra} further site(s) raised the same way")
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
def unchecked_caveats(out: Outcome, n_sites: int) -> list[str]:
|
|
421
|
+
"""The buckets that make ANY verdict partial, hit or no hit.
|
|
422
|
+
|
|
423
|
+
Named separately rather than summed: "could not be evaluated" and "raised
|
|
424
|
+
while being applied" have different causes and different fixes, and a
|
|
425
|
+
reader discounting a verdict needs to know which one they are looking at.
|
|
426
|
+
|
|
427
|
+
Both paths use this. The hit path used to name only the errors, so a
|
|
428
|
+
confident SATISFIED could sit above 14 of 20 sites that went unchecked --
|
|
429
|
+
the same "reads cleaner than the evidence supports" failure as a phantom
|
|
430
|
+
name, arriving through the other branch.
|
|
431
|
+
"""
|
|
432
|
+
caveats = []
|
|
433
|
+
if out.not_captured:
|
|
434
|
+
caveats.append(f"{out.not_captured} of {n_sites} recorded site(s) "
|
|
435
|
+
"could NOT be evaluated")
|
|
436
|
+
if out.errors:
|
|
437
|
+
caveats.append(f"{len(out.errors)} of {n_sites} recorded site(s) "
|
|
438
|
+
"raised while the predicate was applied")
|
|
439
|
+
return caveats
|
|
440
|
+
|
|
441
|
+
|
|
442
|
+
class Says(Enum):
|
|
443
|
+
"""Which of three things a verdict says, as its own value.
|
|
444
|
+
|
|
445
|
+
The split that has to survive into the exit status is the module
|
|
446
|
+
docstring's last one: `hits: 0` because every evaluated site failed
|
|
447
|
+
(NOT_SATISFIED) versus `hits: 0` because nothing could be evaluated at
|
|
448
|
+
all (NOTHING_CHECKED). An agent branching on the status never reaches
|
|
449
|
+
the prose, so a NOTHING_CHECKED leaving as a 0 is "I could not check"
|
|
450
|
+
read as "the invariant held" -- this command's worst outcome, arriving
|
|
451
|
+
through the one channel the prose cannot qualify.
|
|
452
|
+
|
|
453
|
+
A partially-checked run is NOT a fourth class. Some sites evaluated and
|
|
454
|
+
some did not is still the trace answering "no" about the ones it could
|
|
455
|
+
check, so it reads NOT_SATISFIED, and the count it could not check is
|
|
456
|
+
carried in the caveat line rather than in the status (plan X7). Only a
|
|
457
|
+
run where NOTHING evaluated has no answer to give.
|
|
458
|
+
"""
|
|
459
|
+
SATISFIED = auto()
|
|
460
|
+
NOT_SATISFIED = auto()
|
|
461
|
+
NOTHING_CHECKED = auto()
|
|
462
|
+
|
|
463
|
+
|
|
464
|
+
# The convention, applied once. NOT_SATISFIED is the trace answering "no"
|
|
465
|
+
# about what it recorded; NOTHING_CHECKED is the trace unable to answer at
|
|
466
|
+
# all, which is fixed by recording again, not by asking differently.
|
|
467
|
+
STATUS = {Says.SATISFIED: ANSWERED,
|
|
468
|
+
Says.NOT_SATISFIED: NEGATIVE,
|
|
469
|
+
Says.NOTHING_CHECKED: UNSETTLED}
|
|
470
|
+
|
|
471
|
+
|
|
472
|
+
@dataclass(frozen=True)
|
|
473
|
+
class Verdict:
|
|
474
|
+
"""What the verdict says, and which of the three it is.
|
|
475
|
+
|
|
476
|
+
The class travels WITH the lines because only `verdict` knows which
|
|
477
|
+
branch it took. `run` could recover it by matching "NOTHING WAS CHECKED"
|
|
478
|
+
in the printed text -- and then the exit status would depend on the
|
|
479
|
+
wording of a sentence this command rewrites whenever it can be made
|
|
480
|
+
clearer, silently turning a 3 back into a 0 on the next rewording. The
|
|
481
|
+
same reasoning, and the same shape, as `frame._resolve`.
|
|
482
|
+
"""
|
|
483
|
+
says: Says
|
|
484
|
+
lines: list[str]
|
|
485
|
+
|
|
486
|
+
|
|
487
|
+
def verdict(out: Outcome, n_sites: int, ghosts: list[str]) -> Verdict:
|
|
488
|
+
decided_without = ("the predicate was decided WITHOUT "
|
|
489
|
+
+ ", ".join(repr(g) for g in ghosts))
|
|
490
|
+
caveats = unchecked_caveats(out, n_sites)
|
|
491
|
+
if out.hits:
|
|
492
|
+
lines = [f"verdict: SATISFIED at {len(out.hits)} of the "
|
|
493
|
+
f"{out.evaluated} site(s) the predicate could be evaluated "
|
|
494
|
+
"at"]
|
|
495
|
+
if caveats:
|
|
496
|
+
lines.append(" but " + ", and ".join(caveats) + ", so these are "
|
|
497
|
+
"not necessarily every time it held")
|
|
498
|
+
if ghosts:
|
|
499
|
+
lines.append((" and " if caveats else " but ") + decided_without
|
|
500
|
+
+ ", so these hits do not answer the whole predicate")
|
|
501
|
+
return Verdict(Says.SATISFIED, lines)
|
|
502
|
+
if out.evaluated == 0:
|
|
503
|
+
return Verdict(Says.NOTHING_CHECKED, [
|
|
504
|
+
"verdict: NOTHING WAS CHECKED -- the predicate could not be "
|
|
505
|
+
f"evaluated at any of the {n_sites} recorded site(s)",
|
|
506
|
+
" 'hits: 0' here means 'could not evaluate', NOT 'the "
|
|
507
|
+
"invariant held'"])
|
|
508
|
+
if ghosts:
|
|
509
|
+
caveats.append(decided_without)
|
|
510
|
+
if caveats:
|
|
511
|
+
return Verdict(Says.NOT_SATISFIED, [
|
|
512
|
+
f"verdict: not satisfied at any of the {out.evaluated} site(s)"
|
|
513
|
+
f" that could be evaluated -- but " + ", and ".join(caveats)
|
|
514
|
+
+ ",",
|
|
515
|
+
" so this is not a claim that the invariant held"])
|
|
516
|
+
return Verdict(Says.NOT_SATISFIED, [
|
|
517
|
+
f"verdict: not satisfied at any of the {n_sites} recorded "
|
|
518
|
+
"site(s), every one of which was evaluated",
|
|
519
|
+
" that is a fact about what was RECORDED, not a claim that the "
|
|
520
|
+
"invariant held: only recorded sites were checked"])
|
|
521
|
+
|
|
522
|
+
|
|
523
|
+
def continue_cmd(args, **over) -> str:
|
|
524
|
+
"""The exact command that shows more of *this* watch."""
|
|
525
|
+
opts = {"--at": args.at, "--expr": args.expr, "--limit": str(args.limit),
|
|
526
|
+
"--misses": str(args.misses), **over}
|
|
527
|
+
parts = ["sensorium", "watch", shlex.quote(args.run)]
|
|
528
|
+
for flag, val in opts.items():
|
|
529
|
+
parts += [flag, shlex.quote(str(val))]
|
|
530
|
+
return " ".join(parts)
|
|
531
|
+
|
|
532
|
+
|
|
533
|
+
def print_near(trace, expr, out: Outcome, args) -> None:
|
|
534
|
+
if out.hits:
|
|
535
|
+
return
|
|
536
|
+
if not out.near:
|
|
537
|
+
if not expr.has_boundary:
|
|
538
|
+
print("no near-misses: a near-miss distance is only defined for a "
|
|
539
|
+
"single numeric ordering comparison")
|
|
540
|
+
print(f" ({args.expr!r} has no boundary to approach; try one of "
|
|
541
|
+
"< <= > >= over numbers)")
|
|
542
|
+
return
|
|
543
|
+
shown = out.near[:args.misses]
|
|
544
|
+
print(f"near-misses -- the {len(shown)} closest approach(es); every one "
|
|
545
|
+
"of them FAILED the predicate:")
|
|
546
|
+
for m, s in shown:
|
|
547
|
+
print(f" margin {m:g}: {fmt_event(trace, s.event)} "
|
|
548
|
+
f"state: {state_of(expr, s)}")
|
|
549
|
+
withheld = len(out.near) - len(shown)
|
|
550
|
+
if withheld > 0:
|
|
551
|
+
print(f"... {withheld} further near-miss(es) not shown; see them "
|
|
552
|
+
f"with: {continue_cmd(args, **{'--misses': len(out.near)})}")
|
|
553
|
+
|
|
554
|
+
|
|
555
|
+
def print_hits(trace, expr, out: Outcome, args) -> None:
|
|
556
|
+
shown = out.hits[:args.limit]
|
|
557
|
+
for s in shown:
|
|
558
|
+
print(f" HIT {fmt_event(trace, s.event)} "
|
|
559
|
+
f"state: {state_of(expr, s)}")
|
|
560
|
+
if not shown:
|
|
561
|
+
return
|
|
562
|
+
last = f"e{shown[-1].event.id}"
|
|
563
|
+
note = more_note(len(out.hits), len(shown),
|
|
564
|
+
continue_cmd(args, **{"--after": last}))
|
|
565
|
+
if note:
|
|
566
|
+
print(note)
|
|
567
|
+
|
|
568
|
+
|
|
569
|
+
def _no_match(trace, args) -> int:
|
|
570
|
+
print(f"error: no recorded code matches --at {args.at!r}")
|
|
571
|
+
# Spelled the way this recorder's own sites are spelled everywhere
|
|
572
|
+
# else: a listing a reader is meant to pick their next `--at` out of is
|
|
573
|
+
# useless if the forms in it are not forms `--at` takes.
|
|
574
|
+
names = sorted({spell_site(trace, c) for c in trace.codes()})
|
|
575
|
+
print(f"this trace recorded {len(names)} code object(s):")
|
|
576
|
+
for n in names[:_MAX_LISTED_CODES]:
|
|
577
|
+
print(f" {n}")
|
|
578
|
+
extra = len(names) - _MAX_LISTED_CODES
|
|
579
|
+
if extra > 0:
|
|
580
|
+
print(f" ... and {extra} more (sensorium info "
|
|
581
|
+
f"{shlex.quote(args.run)} lists the hot ones)")
|
|
582
|
+
# The trace answering "no": it holds code, and none of it is what --at
|
|
583
|
+
# named. The listing above is what it does hold, so the next move is a
|
|
584
|
+
# different --at, not a different recording.
|
|
585
|
+
return NEGATIVE
|
|
586
|
+
|
|
587
|
+
|
|
588
|
+
def run(args) -> int:
|
|
589
|
+
for flag, val in (("--limit", args.limit), ("--misses", args.misses)):
|
|
590
|
+
if val < 1:
|
|
591
|
+
# `--misses 0` is refused for the same reason as `--limit 0`,
|
|
592
|
+
# and for one more: near-misses are the answer when nothing hit,
|
|
593
|
+
# so a flag that silently suppresses them is a way to make a run
|
|
594
|
+
# look clean without changing a thing about the run.
|
|
595
|
+
print(f"{flag} must be >= 1 (got {val}); "
|
|
596
|
+
"there is no useful zero-row page")
|
|
597
|
+
return BAD_CALL
|
|
598
|
+
try:
|
|
599
|
+
expr = compile_expr(args.expr)
|
|
600
|
+
except ExprError as e:
|
|
601
|
+
print(f"error: {e}")
|
|
602
|
+
return BAD_CALL
|
|
603
|
+
after = parse_eref(args.after) if args.after else 0
|
|
604
|
+
trace = Trace.open(paths.find_trace(args.run))
|
|
605
|
+
refusal = require(trace, "line", "watch")
|
|
606
|
+
if refusal:
|
|
607
|
+
print(f"REFUSED: {refusal}")
|
|
608
|
+
# UNSETTLED, not BAD_CALL: the command is spelled correctly and the
|
|
609
|
+
# trace is readable -- it simply holds no LINE event, because the
|
|
610
|
+
# recorder said it produces none. Nothing about the call can fix
|
|
611
|
+
# that; only a recording that captures lines can.
|
|
612
|
+
return UNSETTLED
|
|
613
|
+
codes = [c for c in trace.codes() if site_matches(c, args.at, trace)]
|
|
614
|
+
if not codes:
|
|
615
|
+
return _no_match(trace, args)
|
|
616
|
+
|
|
617
|
+
# Which formatter wrote this trace's rendered captures, read from the
|
|
618
|
+
# trace and never guessed from a text: `'rate'` is a string in one
|
|
619
|
+
# dialect and a five-character word in the other, and a predicate
|
|
620
|
+
# answered in the wrong one comes back a quiet, wrong False.
|
|
621
|
+
all_sites = sites_for(trace, [c.id for c in codes], expr.names,
|
|
622
|
+
for_trace(trace))
|
|
623
|
+
sites = [s for s in all_sites if s.event.id > after]
|
|
624
|
+
out = evaluate(sites, expr)
|
|
625
|
+
n = len(sites)
|
|
626
|
+
# Computed over the WHOLE run, never the --after page: a name recorded
|
|
627
|
+
# only before the cut is a scope fact, not a name the trace never held.
|
|
628
|
+
ever = {nm for s in all_sites for nm in s.caps}
|
|
629
|
+
ghosts = sorted(expr.names - ever)
|
|
630
|
+
|
|
631
|
+
print(f"watch {args.expr!r} at {args.at} in {trace.path.stem}")
|
|
632
|
+
for line in CLAIM:
|
|
633
|
+
print(" " + line)
|
|
634
|
+
print_incomplete(trace, "the sites below are not all the sites this "
|
|
635
|
+
"run had")
|
|
636
|
+
# Every bucket, so the arithmetic is checkable: sites = evaluated +
|
|
637
|
+
# not-captured + errors.
|
|
638
|
+
print(f"sites: {n} evaluated: {out.evaluated} hits: {len(out.hits)}"
|
|
639
|
+
f" not-captured: {out.not_captured} errors: {len(out.errors)}")
|
|
640
|
+
skipped = len(all_sites) - n
|
|
641
|
+
if skipped:
|
|
642
|
+
print(f"({skipped} earlier site(s) skipped by --after e{after})")
|
|
643
|
+
for line in unframed_note(trace, codes):
|
|
644
|
+
print(line)
|
|
645
|
+
all_unf = all_unframed_codes(trace, codes)
|
|
646
|
+
# Above the verdict on purpose: the verdict cannot be read without it.
|
|
647
|
+
print_never_recorded(ghosts, all_unf)
|
|
648
|
+
v = verdict(out, n, ghosts)
|
|
649
|
+
for line in v.lines:
|
|
650
|
+
print(line)
|
|
651
|
+
print_hits(trace, expr, out, args)
|
|
652
|
+
print_unavailable(trace, out, sites, ever, codes, n, all_unf)
|
|
653
|
+
print_errors(out)
|
|
654
|
+
print_near(trace, expr, out, args)
|
|
655
|
+
# The status IS the verdict, mapped once: the sentence above and the
|
|
656
|
+
# number the caller branches on must never be able to disagree.
|
|
657
|
+
return STATUS[v.says]
|
|
File without changes
|