sensorium-trace 0.18.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sensorium/__init__.py +0 -0
- sensorium/__main__.py +4 -0
- sensorium/_c/rt/sensorium_c_rt.c +1446 -0
- sensorium/_typescript/package-lock.json +68 -0
- sensorium/_typescript/package.json +39 -0
- sensorium/_typescript/src/bindings.mjs +792 -0
- sensorium/_typescript/src/cap.mjs +227 -0
- sensorium/_typescript/src/capabilities.mjs +40 -0
- sensorium/_typescript/src/dbg.mjs +348 -0
- sensorium/_typescript/src/escape.mjs +351 -0
- sensorium/_typescript/src/focus.mjs +135 -0
- sensorium/_typescript/src/hook.mjs +127 -0
- sensorium/_typescript/src/index.mjs +1 -0
- sensorium/_typescript/src/naming.mjs +63 -0
- sensorium/_typescript/src/positions.mjs +37 -0
- sensorium/_typescript/src/probe.mjs +246 -0
- sensorium/_typescript/src/qualname.mjs +236 -0
- sensorium/_typescript/src/redact.mjs +711 -0
- sensorium/_typescript/src/register.mjs +15 -0
- sensorium/_typescript/src/resolve.mjs +260 -0
- sensorium/_typescript/src/rt.mjs +798 -0
- sensorium/_typescript/src/setup.mjs +11 -0
- sensorium/_typescript/src/tally.mjs +164 -0
- sensorium/_typescript/src/tasks.mjs +175 -0
- sensorium/_typescript/src/transform.mjs +800 -0
- sensorium/_typescript/src/vite.mjs +99 -0
- sensorium/c/__init__.py +8 -0
- sensorium/c/cc.py +612 -0
- sensorium/c/cli.py +60 -0
- sensorium/c/convert.py +669 -0
- sensorium/c/decode.py +300 -0
- sensorium/c/driver.py +365 -0
- sensorium/c/dwarf.py +706 -0
- sensorium/c/format.py +271 -0
- sensorium/c/pkg.py +187 -0
- sensorium/c/plan.py +277 -0
- sensorium/cli.py +140 -0
- sensorium/driver.py +47 -0
- sensorium/exit.py +33 -0
- sensorium/invocations.py +83 -0
- sensorium/limits.py +253 -0
- sensorium/mcp/__init__.py +0 -0
- sensorium/mcp/audit.py +162 -0
- sensorium/mcp/child.py +240 -0
- sensorium/mcp/cmd.py +101 -0
- sensorium/mcp/jsonrpc.py +172 -0
- sensorium/mcp/result.py +187 -0
- sensorium/mcp/schema.py +390 -0
- sensorium/mcp/server.py +493 -0
- sensorium/mcp/tools.py +299 -0
- sensorium/paths.py +80 -0
- sensorium/query/__init__.py +0 -0
- sensorium/query/caps.py +150 -0
- sensorium/query/dbg_dialects.py +64 -0
- sensorium/query/diff_cmd.py +748 -0
- sensorium/query/diff_notes.py +117 -0
- sensorium/query/exceptions_c.py +263 -0
- sensorium/query/exceptions_cmd.py +788 -0
- sensorium/query/exceptions_group.py +571 -0
- sensorium/query/exceptions_invocation.py +487 -0
- sensorium/query/exceptions_rust.py +683 -0
- sensorium/query/exceptions_typescript.py +688 -0
- sensorium/query/expr.py +606 -0
- sensorium/query/failures_cmd.py +306 -0
- sensorium/query/flow_cmd.py +778 -0
- sensorium/query/flow_report.py +128 -0
- sensorium/query/flow_values.py +195 -0
- sensorium/query/fmt.py +280 -0
- sensorium/query/frame_cmd.py +237 -0
- sensorium/query/grep_cmd.py +156 -0
- sensorium/query/help.py +18 -0
- sensorium/query/info_cmd.py +527 -0
- sensorium/query/info_rust.py +214 -0
- sensorium/query/info_typescript.py +261 -0
- sensorium/query/js_inspect.py +394 -0
- sensorium/query/moves.py +254 -0
- sensorium/query/redact_cmd.py +304 -0
- sensorium/query/refocus_cmd.py +661 -0
- sensorium/query/refocus_env.py +493 -0
- sensorium/query/refocus_facts.py +269 -0
- sensorium/query/refocus_licence.py +187 -0
- sensorium/query/refocus_report.py +327 -0
- sensorium/query/refocus_rust.py +537 -0
- sensorium/query/refocus_threads.py +197 -0
- sensorium/query/refocus_typescript.py +756 -0
- sensorium/query/refocus_world.py +666 -0
- sensorium/query/runs_cmd.py +213 -0
- sensorium/query/rust_debug.py +176 -0
- sensorium/query/sites.py +171 -0
- sensorium/query/tree_cmd.py +511 -0
- sensorium/query/tree_threads.py +168 -0
- sensorium/query/vocab.py +723 -0
- sensorium/query/watch_cmd.py +657 -0
- sensorium/record/__init__.py +0 -0
- sensorium/record/boot.py +797 -0
- sensorium/record/boot_io.py +141 -0
- sensorium/record/budget.py +135 -0
- sensorium/record/capture.py +433 -0
- sensorium/record/children.py +755 -0
- sensorium/record/children_merge.py +179 -0
- sensorium/record/elide.py +55 -0
- sensorium/record/fingerprint.py +26 -0
- sensorium/record/thread_starts.py +261 -0
- sensorium/record/tracer.py +798 -0
- sensorium/record/tracer_exc.py +199 -0
- sensorium/record/tracer_frames.py +618 -0
- sensorium/redact.py +304 -0
- sensorium/redact_content.py +156 -0
- sensorium/redact_key.py +317 -0
- sensorium/redact_store.py +502 -0
- sensorium/redact_values.py +433 -0
- sensorium/store/__init__.py +0 -0
- sensorium/store/db.py +284 -0
- sensorium/store/gc.py +360 -0
- sensorium/store/payloads.py +69 -0
- sensorium/store/reader.py +438 -0
- sensorium/store/writer.py +283 -0
- sensorium/ts/__init__.py +10 -0
- sensorium/ts/build.py +783 -0
- sensorium/ts/cli.py +130 -0
- sensorium/ts/driver.py +472 -0
- sensorium/ts/focus.py +146 -0
- sensorium/ts/harness.py +314 -0
- sensorium/ts/ingest.py +380 -0
- sensorium/ts/invocation.py +252 -0
- sensorium/ts/pkg.py +167 -0
- sensorium/ts/redaction.py +64 -0
- sensorium/ts/spool.py +168 -0
- sensorium/ts/truncation.py +81 -0
- sensorium/ts/wrapper.py +255 -0
- sensorium_trace-0.18.2.dist-info/METADATA +245 -0
- sensorium_trace-0.18.2.dist-info/RECORD +135 -0
- sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
- sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
- sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
sensorium/query/expr.py
ADDED
|
@@ -0,0 +1,606 @@
|
|
|
1
|
+
"""A restricted predicate language over CAPTURED values.
|
|
2
|
+
|
|
3
|
+
WHAT THIS IS NOT
|
|
4
|
+
----------------
|
|
5
|
+
It is not `eval`. Nothing here executes program code, reads an attribute,
|
|
6
|
+
subscripts, imports, or touches a live object. The inputs are the primitives
|
|
7
|
+
`capture_value` wrote into a trace database; the operations are one
|
|
8
|
+
comparison, `and`/`or`/`not`, unary minus, five arithmetic operators and
|
|
9
|
+
`len(name)`. Everything else -- attributes, subscripts, calls other than
|
|
10
|
+
`len`, comprehensions, lambdas, f-strings, `is`/`in`, chained comparisons,
|
|
11
|
+
`**`, and every dunder path out of a literal -- is refused at COMPILE time,
|
|
12
|
+
before a single site is read. The refusal is compile-time on purpose: a
|
|
13
|
+
malformed or hostile expression then fails once, on the command line, rather
|
|
14
|
+
than once per site or (worse) not at all.
|
|
15
|
+
|
|
16
|
+
"Fails once" covers exhaustion as well as syntax, and it takes two guards
|
|
17
|
+
because there are two stages that can die. `compile_expr` catches the
|
|
18
|
+
parser's own stack overflow (`RecursionError`/`MemoryError`) as well as
|
|
19
|
+
`SyntaxError`; `_MAX_DEPTH` then guards `_validate`, which only ever runs on
|
|
20
|
+
a tree the parser survived. Either alone leaves a traceback reachable from an
|
|
21
|
+
ordinary command line.
|
|
22
|
+
|
|
23
|
+
The restriction is deliberately a real boundary and not a happy accident of
|
|
24
|
+
the input types. Reading captured primitives means there is nothing to escape
|
|
25
|
+
*to* today; a boundary that only holds because of what happens to be in the
|
|
26
|
+
dict is one refactor away from being `eval`, so it is enforced structurally
|
|
27
|
+
and tested as a boundary.
|
|
28
|
+
|
|
29
|
+
WHY A NAME CAN FAIL TO EVALUATE, AND WHY THE REASON MATTERS
|
|
30
|
+
-----------------------------------------------------------
|
|
31
|
+
A site where the predicate could not be applied is NOT a site where the
|
|
32
|
+
predicate was false, and the four ways it can fail send a reader to four
|
|
33
|
+
different fixes:
|
|
34
|
+
|
|
35
|
+
* OUT_OF_SCOPE -- the name is not bound here. Either it is not bound *yet*
|
|
36
|
+
(or has gone out of scope again, via `del` or the implicit unbind that
|
|
37
|
+
ends `except E as e:`), or this run never recorded that frame's locals at
|
|
38
|
+
all. Only the second is fixed by re-recording with `--focus`, and
|
|
39
|
+
`watch_cmd` tells the two apart before it suggests anything.
|
|
40
|
+
* NO_VALUE -- the name IS bound, to something `capture_value` could only
|
|
41
|
+
record as a type and a repr. Refocusing cannot help; an object has no
|
|
42
|
+
comparable value to record.
|
|
43
|
+
* CONTAINER -- bound to a list/tuple/set/dict, whose length was recorded
|
|
44
|
+
and whose contents were only sampled. `len(name)` works; comparing the
|
|
45
|
+
bare name does not.
|
|
46
|
+
* CLIPPED -- bound to a string longer than the capture cap, so what the
|
|
47
|
+
trace holds is a PREFIX. Comparing a prefix, or taking its length, is a
|
|
48
|
+
claim about characters that were never recorded.
|
|
49
|
+
* REDACTED_REASON -- the redaction rule took the value at the recorder,
|
|
50
|
+
before anything reached disk. Every taken capture holds the same marker
|
|
51
|
+
text, so comparing one would answer the same about two secrets that are
|
|
52
|
+
not equal to each other. Re-recording is what changes this, not asking
|
|
53
|
+
differently.
|
|
54
|
+
|
|
55
|
+
Collapsing any of these into a silent False would let "I could not check"
|
|
56
|
+
read as "the invariant held". That is the failure this whole module exists to
|
|
57
|
+
prevent, so the reason travels on the exception and `watch` prints it.
|
|
58
|
+
|
|
59
|
+
TRUNCATION, AND THE ONE PLACE IT DOES NOT BITE
|
|
60
|
+
----------------------------------------------
|
|
61
|
+
`trunc` on a container capture means the SAMPLE was capped, or the depth was
|
|
62
|
+
-- never the length: `_capture_sized` writes `len(obj)` before any cap is
|
|
63
|
+
applied. So `len(name)` over a truncated container is exact, and this module
|
|
64
|
+
never reads `sample` at all (a depth-capped capture omits that key entirely).
|
|
65
|
+
A clipped *string* is the real truncation case, and it is refused.
|
|
66
|
+
"""
|
|
67
|
+
import ast
|
|
68
|
+
import operator
|
|
69
|
+
|
|
70
|
+
from sensorium.query.rust_debug import read_debug
|
|
71
|
+
|
|
72
|
+
# Why a name the predicate needs has no usable value at some site. `NAME` is
|
|
73
|
+
# substituted with the actual name when the message is rendered.
|
|
74
|
+
OUT_OF_SCOPE = "not in scope at this site"
|
|
75
|
+
NO_VALUE = "recorded as an object, which has no comparable value"
|
|
76
|
+
CONTAINER = "recorded as a container; compare its length with len(NAME)"
|
|
77
|
+
CLIPPED = "recorded truncated, so the trace does not hold the whole value"
|
|
78
|
+
NO_LENGTH = "recorded as a value that has no length"
|
|
79
|
+
SAMPLED = ("recorded as a container whose sample does not decide whether "
|
|
80
|
+
"that value is in NAME (only a sample of its members was "
|
|
81
|
+
"recorded); its length is exact, so len(NAME) still is")
|
|
82
|
+
#: A value the redaction rule took at the RECORDER, before anything reached
|
|
83
|
+
#: disk. Every taken capture of every kind holds the same marker text, so a
|
|
84
|
+
#: predicate applied to one would compare `<redacted>` -- and would answer
|
|
85
|
+
#: the same about two secrets that are not equal to each other. There is
|
|
86
|
+
#: nothing here to compare, and saying so is the only honest answer.
|
|
87
|
+
REDACTED_REASON = "redacted by rule v1; no comparable value"
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
class ExprError(Exception):
|
|
91
|
+
"""Not in this language. Always raised at compile time."""
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
class NotCaptured(Exception):
|
|
95
|
+
"""A name the predicate needs has no usable captured value at this site.
|
|
96
|
+
|
|
97
|
+
Never a verdict. Callers count these and report them; the one thing they
|
|
98
|
+
must not do is treat them as the predicate having come back False.
|
|
99
|
+
"""
|
|
100
|
+
|
|
101
|
+
def __init__(self, name: str, reason: str = OUT_OF_SCOPE) -> None:
|
|
102
|
+
super().__init__(f"{name}: {reason.replace('NAME', name)}")
|
|
103
|
+
self.name = name
|
|
104
|
+
self.reason = reason
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
class EvalError(Exception):
|
|
108
|
+
"""The predicate is well-formed but could not be applied to these values.
|
|
109
|
+
|
|
110
|
+
`'five' > 3` and `x / 0` are not misses -- nothing was decided at all.
|
|
111
|
+
Kept apart from `NotCaptured` because the fix is different: the capture is
|
|
112
|
+
fine, the predicate does not fit the data.
|
|
113
|
+
"""
|
|
114
|
+
|
|
115
|
+
def __init__(self, cause: BaseException) -> None:
|
|
116
|
+
super().__init__(f"{type(cause).__name__}: {cause}")
|
|
117
|
+
self.cause = cause
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class _Marker:
|
|
121
|
+
"""A singleton with a readable repr, so a leak into output is obvious."""
|
|
122
|
+
__slots__ = ("_label",)
|
|
123
|
+
|
|
124
|
+
def __init__(self, label: str) -> None:
|
|
125
|
+
self._label = label
|
|
126
|
+
|
|
127
|
+
def __repr__(self) -> str:
|
|
128
|
+
return self._label
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
NOT_CAPTURED = _Marker("<NOT_CAPTURED>")
|
|
132
|
+
TRUNCATED = _Marker("<TRUNCATED>")
|
|
133
|
+
#: A value the redaction rule took. Its own marker and not NOT_CAPTURED,
|
|
134
|
+
#: because the two are different facts with different fixes: NOT_CAPTURED is
|
|
135
|
+
#: a recorder that could not read a value, and this is a rule that read it
|
|
136
|
+
#: and refused to store it. Equal only to itself, like every marker here --
|
|
137
|
+
#: which is what stops `token == '<redacted>'` from ever answering yes.
|
|
138
|
+
REDACTED = _Marker("<REDACTED>")
|
|
139
|
+
#: JavaScript's second absence. A name bound to `undefined` IS bound, and a
|
|
140
|
+
#: trace that recorded one holds a value -- so it may not read as `None`
|
|
141
|
+
#: (which would make `x == null` answer yes about a site that recorded
|
|
142
|
+
#: `undefined`) and may not read as NOT_CAPTURED (which would report a site
|
|
143
|
+
#: whose value the trace does hold as one the predicate could not be checked
|
|
144
|
+
#: at). Equal only to itself, like every other marker here.
|
|
145
|
+
UNDEFINED = _Marker("<undefined>")
|
|
146
|
+
|
|
147
|
+
#: The four words this language reads as VALUES rather than as names. They
|
|
148
|
+
#: are language-neutral: `x == null` on a Python trace compares with `None`
|
|
149
|
+
#: exactly as `x == None` does, and `x == undefined` is the one predicate
|
|
150
|
+
#: that can tell JavaScript's two absences apart. A program local spelled
|
|
151
|
+
#: `null`, `undefined`, `true` or `false` is SHADOWED by the constant --
|
|
152
|
+
#: declared here and pinned by `v35-predicate-constants`, because the
|
|
153
|
+
#: alternative is a predicate whose meaning depends on what the recorded
|
|
154
|
+
#: frame happened to bind.
|
|
155
|
+
_CONSTANTS = {"null": None, "undefined": UNDEFINED,
|
|
156
|
+
"true": True, "false": False}
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
class _Sized:
|
|
160
|
+
"""A container recorded by its length and, when the capture holds one, a
|
|
161
|
+
sample of its members. `len()` works; `literal in name` works when the
|
|
162
|
+
sample decides it (see `_member`); nothing else."""
|
|
163
|
+
__slots__ = ("n", "members", "complete")
|
|
164
|
+
|
|
165
|
+
def __init__(self, n: int, members=None, complete: bool = False) -> None:
|
|
166
|
+
self.n = n
|
|
167
|
+
self.members = members # frozenset of sampled primitives, or None
|
|
168
|
+
self.complete = complete # True when `members` IS the whole container
|
|
169
|
+
|
|
170
|
+
def __repr__(self) -> str:
|
|
171
|
+
return f"<len {self.n}>"
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
class _DbgText(str):
|
|
175
|
+
"""A string read out of a rendered TEXT capture (Rust's `{:?}`, or
|
|
176
|
+
JavaScript's `util.inspect`).
|
|
177
|
+
|
|
178
|
+
A `str`, because that is what the trace holds and what a predicate may
|
|
179
|
+
compare: `s == "A1"` and `"A" in s` are answered by the very characters
|
|
180
|
+
the recorder wrote, and design 2026-09-06 §4.2 says they are answered.
|
|
181
|
+
Its own class, because `len()` over it is not: `"A1"` is four characters
|
|
182
|
+
as Rust spells it and two as the program held it, and the recorder
|
|
183
|
+
measured NEITHER number -- it recorded a rendering. `_length` refuses it,
|
|
184
|
+
so such a site is reported as one the predicate could not be checked at.
|
|
185
|
+
"""
|
|
186
|
+
__slots__ = ()
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
_CMP = {ast.Lt: operator.lt, ast.LtE: operator.le, ast.Gt: operator.gt,
|
|
190
|
+
ast.GtE: operator.ge, ast.Eq: operator.eq, ast.NotEq: operator.ne}
|
|
191
|
+
_BIN = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul,
|
|
192
|
+
ast.Div: operator.truediv, ast.Mod: operator.mod}
|
|
193
|
+
# The comparisons that have a boundary to approach. `==`/`!=` do not: the
|
|
194
|
+
# distance from `a == b` to true is not a number a reader can act on.
|
|
195
|
+
_ORDERING = (ast.Lt, ast.LtE, ast.Gt, ast.GtE)
|
|
196
|
+
# Raised by applying a legal operator to captured values of the wrong shape.
|
|
197
|
+
# Caught and re-raised as EvalError so a site can be counted, never crashed on.
|
|
198
|
+
_ARITH = (TypeError, ZeroDivisionError, OverflowError, ValueError)
|
|
199
|
+
# How deep an expression tree may nest. `_validate` and `_eval` both recurse
|
|
200
|
+
# once per node, and `ast.parse` happily builds a tree far deeper than either
|
|
201
|
+
# survives: measured, `x + x + ...` a thousand times parses cleanly and then
|
|
202
|
+
# takes `_validate` out with a RecursionError -- a traceback and a non-2 exit
|
|
203
|
+
# from a command whose whole contract is that a bad expression fails once, on
|
|
204
|
+
# the command line. A fixed cap is used rather than catching RecursionError
|
|
205
|
+
# because it is deterministic (no dependence on the interpreter's remaining
|
|
206
|
+
# stack) and because refusing at 50 in `_validate` is what GUARANTEES `_eval`
|
|
207
|
+
# can never recurse deeply enough to fail at a site. Real predicates nest
|
|
208
|
+
# under 10.
|
|
209
|
+
_MAX_DEPTH = 50
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def resolve(v: dict, dialect=None):
|
|
213
|
+
"""One capture -> a usable value, or a marker saying why not.
|
|
214
|
+
|
|
215
|
+
Markers rather than exceptions because a caller folds these into an
|
|
216
|
+
environment long before any predicate looks at them: `env[name]` present
|
|
217
|
+
but NOT_CAPTURED means "in scope, no value", which is a different fact
|
|
218
|
+
from the name being absent, and both have to survive the fold.
|
|
219
|
+
|
|
220
|
+
`dialect` is which language's formatter wrote a `dbg` capture, from the
|
|
221
|
+
trace's own vocabulary (`query/dbg_dialects`). Absent, it is Rust's --
|
|
222
|
+
what every caller got before a second dialect existed, and what no
|
|
223
|
+
Python trace ever reaches, since Python's captures are typed (P10).
|
|
224
|
+
"""
|
|
225
|
+
# BEFORE the kind dispatch. A taken capture keeps its kind and holds
|
|
226
|
+
# the rule's marker text in the field the value was in, so `num` would
|
|
227
|
+
# hand back the STRING `<redacted>` as a number and `str` would hand it
|
|
228
|
+
# back as a string a predicate can match. A CONTENT hit is not this
|
|
229
|
+
# case and falls through on purpose: the rule replaced a span inside a
|
|
230
|
+
# text the recorder kept, and the text is what the trace holds.
|
|
231
|
+
if (v.get("redacted") or {}).get("by") == "name":
|
|
232
|
+
return REDACTED
|
|
233
|
+
k = v.get("k")
|
|
234
|
+
if k in ("num", "bool"):
|
|
235
|
+
return v["v"]
|
|
236
|
+
if k == "str":
|
|
237
|
+
# What the trace holds is a prefix of the real string. It is not the
|
|
238
|
+
# value and must not be compared as if it were.
|
|
239
|
+
return TRUNCATED if v.get("trunc") else v["v"]
|
|
240
|
+
if k == "none":
|
|
241
|
+
return None
|
|
242
|
+
if k in ("seq", "map"):
|
|
243
|
+
# `len` is exact even here: it is written before any cap is applied,
|
|
244
|
+
# and `trunc` on a container means the sample (or the depth) was cut.
|
|
245
|
+
# It is None only when the object's own `__len__` raised at capture
|
|
246
|
+
# time -- an unread size is not a size, and `len(buf) > 100` must
|
|
247
|
+
# report a site it could not evaluate rather than compare to nothing.
|
|
248
|
+
n = v.get("len")
|
|
249
|
+
if n is None:
|
|
250
|
+
return NOT_CAPTURED
|
|
251
|
+
members, complete = _members(v, n)
|
|
252
|
+
return _Sized(n, members, complete)
|
|
253
|
+
if k == "dbg":
|
|
254
|
+
# A value the recorder could only RENDER, with the language's own
|
|
255
|
+
# formatter, because it cannot decompose the type (Rust's `Debug`,
|
|
256
|
+
# JavaScript's `util.inspect`). The text is the capture, so the
|
|
257
|
+
# value is whatever the text spells IN THAT DIALECT -- and a
|
|
258
|
+
# truncated one is a prefix of the rendering, which spells nothing.
|
|
259
|
+
if v.get("trunc"):
|
|
260
|
+
return TRUNCATED
|
|
261
|
+
t = v.get("v")
|
|
262
|
+
if not isinstance(t, str):
|
|
263
|
+
return NOT_CAPTURED # a `dbg` with no text is malformed
|
|
264
|
+
read = dialect.read if dialect else read_debug
|
|
265
|
+
val = read(t)
|
|
266
|
+
# A dialect may find a prefix the wire flag cannot show (inspect
|
|
267
|
+
# cuts a long string itself), and that stays a prefix.
|
|
268
|
+
if val is TRUNCATED:
|
|
269
|
+
return TRUNCATED
|
|
270
|
+
return _DbgText(val) if isinstance(val, str) else val
|
|
271
|
+
return NOT_CAPTURED
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
_PRIMITIVE = ("num", "bool", "str", "none")
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
def _members(v: dict, n: int):
|
|
278
|
+
"""The sampled members of a captured container that a literal can be
|
|
279
|
+
compared with, and whether they are ALL of it. A map samples (key, value)
|
|
280
|
+
pairs -- membership is over keys, as in Python. A member that is itself a
|
|
281
|
+
container, an object, or a clipped string is not comparable, so a sample
|
|
282
|
+
holding one can prove presence but never absence.
|
|
283
|
+
|
|
284
|
+
A member the redaction rule TOOK is one of those: every taken capture
|
|
285
|
+
holds the same marker text, so adding it to the set would make
|
|
286
|
+
`'<redacted>' in cfg` a hit, and -- far worse -- would let
|
|
287
|
+
`'hunter2' in cfg` come back a DECIDED False about a container one of
|
|
288
|
+
whose members nobody recorded. It is counted as a member the sample
|
|
289
|
+
does not decide, which is exactly what `complete` already means."""
|
|
290
|
+
sample = v.get("sample")
|
|
291
|
+
if sample is None:
|
|
292
|
+
return None, False
|
|
293
|
+
members, comparable = set(), True
|
|
294
|
+
for entry in sample:
|
|
295
|
+
item = entry[0] if v.get("k") == "map" else entry
|
|
296
|
+
if (not isinstance(item, dict) or item.get("k") not in _PRIMITIVE
|
|
297
|
+
or item.get("trunc")
|
|
298
|
+
or (item.get("redacted") or {}).get("by") == "name"):
|
|
299
|
+
comparable = False
|
|
300
|
+
continue
|
|
301
|
+
members.add(None if item["k"] == "none" else item.get("v"))
|
|
302
|
+
complete = comparable and not v.get("trunc") and len(sample) == n
|
|
303
|
+
return frozenset(members), complete
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
# -- compiling -------------------------------------------------------------
|
|
307
|
+
def _validate_len(node: ast.Call) -> None:
|
|
308
|
+
if not (isinstance(node.func, ast.Name) and node.func.id == "len"):
|
|
309
|
+
raise ExprError("the only call allowed is len(name)")
|
|
310
|
+
if node.keywords or len(node.args) != 1:
|
|
311
|
+
raise ExprError("len takes exactly one positional argument")
|
|
312
|
+
if not isinstance(node.args[0], ast.Name):
|
|
313
|
+
raise ExprError("len's argument must be a plain name, as in len(buf)")
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
_EMPTY_LITERALS = (ast.Dict, ast.List, ast.Tuple, ast.Set)
|
|
317
|
+
|
|
318
|
+
|
|
319
|
+
def _is_empty_literal(node) -> bool:
|
|
320
|
+
if isinstance(node, ast.Dict):
|
|
321
|
+
return not node.keys
|
|
322
|
+
if isinstance(node, (ast.List, ast.Tuple, ast.Set)):
|
|
323
|
+
return not node.elts
|
|
324
|
+
return False
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
def _validate_compare(node: ast.Compare, depth: int) -> None:
|
|
328
|
+
if len(node.ops) != 1:
|
|
329
|
+
raise ExprError("chained comparisons are not allowed; write one "
|
|
330
|
+
"comparison, or join two with `and`")
|
|
331
|
+
op = type(node.ops[0])
|
|
332
|
+
left, right = node.left, node.comparators[0]
|
|
333
|
+
if op in (ast.In, ast.NotIn):
|
|
334
|
+
# Membership is decided from the SAMPLE a capture holds, so it is
|
|
335
|
+
# offered in the one shape a sample can answer: a literal looked up
|
|
336
|
+
# in a named container (or string).
|
|
337
|
+
if not (isinstance(left, ast.Constant) and isinstance(right, ast.Name)
|
|
338
|
+
and right.id != "len"):
|
|
339
|
+
raise ExprError("`in` is only allowed as a literal in a name, as "
|
|
340
|
+
"in 'key' in meta or 3 in xs")
|
|
341
|
+
_validate(left, depth)
|
|
342
|
+
return
|
|
343
|
+
if op not in _CMP:
|
|
344
|
+
raise ExprError("only < <= > >= == != and `in`/`not in` are allowed "
|
|
345
|
+
"as comparisons")
|
|
346
|
+
lits = [n for n in (left, right) if isinstance(n, _EMPTY_LITERALS)]
|
|
347
|
+
if lits:
|
|
348
|
+
# `name == {}` is a length-zero test the trace answers exactly; any
|
|
349
|
+
# non-empty literal would be compared against a SAMPLE, which is not
|
|
350
|
+
# the value.
|
|
351
|
+
other = right if lits[0] is left else left
|
|
352
|
+
if (len(lits) != 1 or op not in (ast.Eq, ast.NotEq)
|
|
353
|
+
or not _is_empty_literal(lits[0])
|
|
354
|
+
or not (isinstance(other, ast.Name) and other.id != "len")):
|
|
355
|
+
raise ExprError("a container literal can only be the empty {} / "
|
|
356
|
+
"[] / () compared with == or != to a name; for "
|
|
357
|
+
"anything else compare len(name), or test "
|
|
358
|
+
"'item' in name")
|
|
359
|
+
return
|
|
360
|
+
_validate(left, depth)
|
|
361
|
+
_validate(right, depth)
|
|
362
|
+
|
|
363
|
+
|
|
364
|
+
def _validate(node, depth: int = 0) -> None:
|
|
365
|
+
if depth > _MAX_DEPTH:
|
|
366
|
+
raise ExprError(f"expression nests deeper than {_MAX_DEPTH} levels; "
|
|
367
|
+
"a predicate over captured values does not need that")
|
|
368
|
+
depth += 1
|
|
369
|
+
if isinstance(node, ast.Expression):
|
|
370
|
+
_validate(node.body, depth)
|
|
371
|
+
elif isinstance(node, ast.Constant):
|
|
372
|
+
if not (isinstance(node.value, (int, float, str, bool))
|
|
373
|
+
or node.value is None):
|
|
374
|
+
raise ExprError(f"unsupported constant {node.value!r}")
|
|
375
|
+
elif isinstance(node, ast.Name):
|
|
376
|
+
# `len` reaches here only as a BARE name -- `_validate_len` checks the
|
|
377
|
+
# callee itself and never recurses into it. Left alone, `len > 1`
|
|
378
|
+
# would compile to a lookup for a variable no capture ever holds and
|
|
379
|
+
# be reported as "not in scope", sending a reader after a builtin.
|
|
380
|
+
if node.id == "len":
|
|
381
|
+
raise ExprError("`len` is only allowed as len(name), as in "
|
|
382
|
+
"len(buf) > 3")
|
|
383
|
+
elif isinstance(node, ast.Call):
|
|
384
|
+
_validate_len(node)
|
|
385
|
+
elif isinstance(node, ast.Compare):
|
|
386
|
+
_validate_compare(node, depth)
|
|
387
|
+
elif isinstance(node, ast.BoolOp):
|
|
388
|
+
for v in node.values:
|
|
389
|
+
_validate(v, depth)
|
|
390
|
+
elif isinstance(node, ast.UnaryOp) and isinstance(node.op,
|
|
391
|
+
(ast.Not, ast.USub)):
|
|
392
|
+
_validate(node.operand, depth)
|
|
393
|
+
elif isinstance(node, ast.BinOp) and type(node.op) in _BIN:
|
|
394
|
+
_validate(node.left, depth)
|
|
395
|
+
_validate(node.right, depth)
|
|
396
|
+
else:
|
|
397
|
+
raise ExprError(f"unsupported syntax: {type(node).__name__}")
|
|
398
|
+
|
|
399
|
+
|
|
400
|
+
def compile_expr(src: str) -> "Expr":
|
|
401
|
+
try:
|
|
402
|
+
tree = ast.parse(src, mode="eval")
|
|
403
|
+
except SyntaxError as e:
|
|
404
|
+
raise ExprError(f"not a valid expression: {e.msg}") from None
|
|
405
|
+
except (RecursionError, MemoryError):
|
|
406
|
+
# The parser has its own bounded stack, and it overflows BEFORE
|
|
407
|
+
# `_MAX_DEPTH` gets a look in -- the cap guards `_validate`, which
|
|
408
|
+
# never runs if there is no tree. Measured: 60000 unary minus, or
|
|
409
|
+
# `not ` 20000 times, raise `MemoryError: Parser stack overflowed`,
|
|
410
|
+
# and both fit inside one argv entry (MAX_ARG_STRLEN is 128 KB), so
|
|
411
|
+
# this is reachable from an ordinary command line. Without this the
|
|
412
|
+
# module's promise of a single clean refusal was false for exactly
|
|
413
|
+
# the inputs most likely to be hostile.
|
|
414
|
+
#
|
|
415
|
+
# Catching MemoryError is normally a bad idea -- the interpreter may
|
|
416
|
+
# be wedged -- but this one is raised deterministically by the parser
|
|
417
|
+
# against its own fixed limit, nothing has been allocated to leak,
|
|
418
|
+
# and it is re-raised immediately as a refusal.
|
|
419
|
+
raise ExprError("expression is too large or too deeply nested for "
|
|
420
|
+
"the parser; a predicate over captured values does "
|
|
421
|
+
"not need that") from None
|
|
422
|
+
_validate(tree)
|
|
423
|
+
names = {n.id for n in ast.walk(tree) if isinstance(n, ast.Name)}
|
|
424
|
+
names.discard("len") # the callee of a validated len(name) call
|
|
425
|
+
# A constant is not a name the trace could witness (plan P11). Left in,
|
|
426
|
+
# `null` would reach `watch`'s NEVER RECORDED banner -- "captured at NO
|
|
427
|
+
# site in these frames", about a word no recorder can capture -- and
|
|
428
|
+
# that banner discredits every verdict printed under it.
|
|
429
|
+
names -= _CONSTANTS.keys()
|
|
430
|
+
return Expr(tree, names, src)
|
|
431
|
+
|
|
432
|
+
|
|
433
|
+
def _is_real(x) -> bool:
|
|
434
|
+
"""A number a margin can be measured against. `True` is not one: bools
|
|
435
|
+
compare as 0/1 and would report a distance of 1 from a boundary they have
|
|
436
|
+
no relationship to."""
|
|
437
|
+
return isinstance(x, (int, float)) and not isinstance(x, bool)
|
|
438
|
+
|
|
439
|
+
|
|
440
|
+
class Expr:
|
|
441
|
+
"""A compiled predicate. `names` is every name it may need."""
|
|
442
|
+
|
|
443
|
+
def __init__(self, tree: ast.Expression, names: set[str],
|
|
444
|
+
src: str) -> None:
|
|
445
|
+
self._tree = tree
|
|
446
|
+
self.names = names
|
|
447
|
+
self.src = src
|
|
448
|
+
|
|
449
|
+
@property
|
|
450
|
+
def has_boundary(self) -> bool:
|
|
451
|
+
"""Whether `margin` can ever return a number for this predicate."""
|
|
452
|
+
node = self._tree.body
|
|
453
|
+
return (isinstance(node, ast.Compare)
|
|
454
|
+
and type(node.ops[0]) in _ORDERING)
|
|
455
|
+
|
|
456
|
+
def eval(self, env: dict) -> bool:
|
|
457
|
+
try:
|
|
458
|
+
return bool(self._eval(self._tree.body, env))
|
|
459
|
+
except _ARITH as e:
|
|
460
|
+
raise EvalError(e) from None
|
|
461
|
+
|
|
462
|
+
def margin(self, env: dict) -> float | None:
|
|
463
|
+
"""How far this site was from the boundary, or None if there is none.
|
|
464
|
+
|
|
465
|
+
Defined only for a single numeric ordering comparison at the top: that
|
|
466
|
+
is the only shape where "distance to the boundary" is a number a
|
|
467
|
+
reader can rank sites by.
|
|
468
|
+
"""
|
|
469
|
+
if not self.has_boundary:
|
|
470
|
+
return None
|
|
471
|
+
node = self._tree.body
|
|
472
|
+
try:
|
|
473
|
+
lhs = self._eval(node.left, env)
|
|
474
|
+
rhs = self._eval(node.comparators[0], env)
|
|
475
|
+
except (NotCaptured, *_ARITH):
|
|
476
|
+
return None
|
|
477
|
+
return abs(lhs - rhs) if _is_real(lhs) and _is_real(rhs) else None
|
|
478
|
+
|
|
479
|
+
# -- evaluation --------------------------------------------------------
|
|
480
|
+
def _eval(self, node, env):
|
|
481
|
+
if isinstance(node, ast.Constant):
|
|
482
|
+
return node.value
|
|
483
|
+
if isinstance(node, ast.Name):
|
|
484
|
+
if node.id in _CONSTANTS:
|
|
485
|
+
return _CONSTANTS[node.id]
|
|
486
|
+
return _name(node.id, env)
|
|
487
|
+
if isinstance(node, ast.Call): # validated: len(name)
|
|
488
|
+
return _length(node.args[0].id, env)
|
|
489
|
+
if isinstance(node, ast.Compare):
|
|
490
|
+
op = type(node.ops[0])
|
|
491
|
+
left, right = node.left, node.comparators[0]
|
|
492
|
+
if op in (ast.In, ast.NotIn):
|
|
493
|
+
hit = _member(left.value, right.id, env)
|
|
494
|
+
return hit if op is ast.In else not hit
|
|
495
|
+
if isinstance(left, _EMPTY_LITERALS) or isinstance(
|
|
496
|
+
right, _EMPTY_LITERALS):
|
|
497
|
+
name = right if isinstance(left, _EMPTY_LITERALS) else left
|
|
498
|
+
empty = _length(name.id, env) == 0
|
|
499
|
+
return empty if op is ast.Eq else not empty
|
|
500
|
+
return _CMP[op](self._eval(left, env), self._eval(right, env))
|
|
501
|
+
if isinstance(node, ast.BoolOp):
|
|
502
|
+
return self._boolop(node, env)
|
|
503
|
+
if isinstance(node, ast.UnaryOp):
|
|
504
|
+
v = self._eval(node.operand, env)
|
|
505
|
+
return (not v) if isinstance(node.op, ast.Not) else -v
|
|
506
|
+
return _BIN[type(node.op)](self._eval(node.left, env),
|
|
507
|
+
self._eval(node.right, env))
|
|
508
|
+
|
|
509
|
+
def _boolop(self, node: ast.BoolOp, env):
|
|
510
|
+
"""Short-circuiting, and that is a correctness property, not speed.
|
|
511
|
+
|
|
512
|
+
`False and <uncaptured>` is False; `True or <uncaptured>` is True. The
|
|
513
|
+
trace decides those sites, so refusing them would move a site out of
|
|
514
|
+
"evaluated" and into "could not check" -- inflating the one number a
|
|
515
|
+
reader uses to discount a run that reported no hits. Where the missing
|
|
516
|
+
half really does decide the answer, the refusal still happens.
|
|
517
|
+
"""
|
|
518
|
+
decisive = not isinstance(node.op, ast.And)
|
|
519
|
+
for v in node.values:
|
|
520
|
+
if bool(self._eval(v, env)) is decisive:
|
|
521
|
+
return decisive
|
|
522
|
+
return not decisive
|
|
523
|
+
|
|
524
|
+
|
|
525
|
+
def _bound(name: str, env: dict):
|
|
526
|
+
"""What a name stands for: a constant of the language first, then the
|
|
527
|
+
environment.
|
|
528
|
+
|
|
529
|
+
One rule, three readers. `_eval` answers a bare Name from `_CONSTANTS`
|
|
530
|
+
directly, and the other two paths into a name -- `len(name)` and
|
|
531
|
+
`literal in name` -- come through here, so `len(undefined)` reports the
|
|
532
|
+
value it names as having no recorded length rather than reporting the
|
|
533
|
+
word as out of scope, and the shadowing rule cannot differ by path.
|
|
534
|
+
"""
|
|
535
|
+
if name in _CONSTANTS:
|
|
536
|
+
return _CONSTANTS[name]
|
|
537
|
+
return env.get(name, NOT_CAPTURED)
|
|
538
|
+
|
|
539
|
+
|
|
540
|
+
def _name(name: str, env: dict):
|
|
541
|
+
val = _bound(name, env)
|
|
542
|
+
if val is REDACTED:
|
|
543
|
+
raise NotCaptured(name, REDACTED_REASON)
|
|
544
|
+
if val is NOT_CAPTURED:
|
|
545
|
+
raise NotCaptured(name, NO_VALUE if name in env else OUT_OF_SCOPE)
|
|
546
|
+
if val is TRUNCATED:
|
|
547
|
+
raise NotCaptured(name, CLIPPED)
|
|
548
|
+
if isinstance(val, _Sized):
|
|
549
|
+
raise NotCaptured(name, CONTAINER)
|
|
550
|
+
return val
|
|
551
|
+
|
|
552
|
+
|
|
553
|
+
def _member(value, name: str, env: dict) -> bool:
|
|
554
|
+
"""`value in name`, decided only where the capture decides it.
|
|
555
|
+
|
|
556
|
+
A container's capture is its length plus a SAMPLE of at most
|
|
557
|
+
CAPS["sample"] members. Found in the sample -> True, certainly. Not
|
|
558
|
+
found -> False only when the sample is the whole container and every
|
|
559
|
+
member was a comparable primitive; otherwise the trace does not hold the
|
|
560
|
+
answer and the site is reported, never guessed. A string is a substring
|
|
561
|
+
test; a clipped string cannot answer at all, because the prefix is not
|
|
562
|
+
in the environment.
|
|
563
|
+
"""
|
|
564
|
+
val = _bound(name, env)
|
|
565
|
+
if val is REDACTED:
|
|
566
|
+
raise NotCaptured(name, REDACTED_REASON)
|
|
567
|
+
if val is NOT_CAPTURED:
|
|
568
|
+
raise NotCaptured(name, NO_VALUE if name in env else OUT_OF_SCOPE)
|
|
569
|
+
if val is TRUNCATED:
|
|
570
|
+
raise NotCaptured(name, CLIPPED)
|
|
571
|
+
if isinstance(val, _Sized):
|
|
572
|
+
if val.members is not None and value in val.members:
|
|
573
|
+
return True
|
|
574
|
+
if val.complete:
|
|
575
|
+
return False
|
|
576
|
+
raise NotCaptured(name, SAMPLED)
|
|
577
|
+
if isinstance(val, str):
|
|
578
|
+
if not isinstance(value, str):
|
|
579
|
+
raise TypeError(f"'in <string>' needs a string literal, not "
|
|
580
|
+
f"{type(value).__name__}")
|
|
581
|
+
return value in val
|
|
582
|
+
raise NotCaptured(name, NO_LENGTH) # a number, bool or None: no members
|
|
583
|
+
|
|
584
|
+
|
|
585
|
+
def _length(name: str, env: dict) -> int:
|
|
586
|
+
val = _bound(name, env)
|
|
587
|
+
if val is REDACTED:
|
|
588
|
+
# A taken container's LENGTH is recorded and kept -- but it is kept
|
|
589
|
+
# on the capture, and what reached this environment is the marker.
|
|
590
|
+
# `len(token)` over a taken value is refused with every other path
|
|
591
|
+
# into it, so a reader is told one thing rather than three.
|
|
592
|
+
raise NotCaptured(name, REDACTED_REASON)
|
|
593
|
+
if isinstance(val, _Sized):
|
|
594
|
+
return val.n
|
|
595
|
+
if isinstance(val, _DbgText):
|
|
596
|
+
# BEFORE the `str` arm, which it would otherwise satisfy. What the
|
|
597
|
+
# trace holds is a rendering, and a rendering's length is not the
|
|
598
|
+
# value's -- no length was recorded here at all.
|
|
599
|
+
raise NotCaptured(name, NO_LENGTH)
|
|
600
|
+
if isinstance(val, str):
|
|
601
|
+
return len(val)
|
|
602
|
+
if val is NOT_CAPTURED:
|
|
603
|
+
raise NotCaptured(name, NO_VALUE if name in env else OUT_OF_SCOPE)
|
|
604
|
+
if val is TRUNCATED:
|
|
605
|
+
raise NotCaptured(name, CLIPPED)
|
|
606
|
+
raise NotCaptured(name, NO_LENGTH)
|