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,128 @@
|
|
|
1
|
+
"""What `flow` PRINTS: the rows, the footer, and the notes under it.
|
|
2
|
+
|
|
3
|
+
Split out of `flow_cmd.py` at that file's 800-line ceiling, along the seam
|
|
4
|
+
the material has -- the same seam `refocus_report` sits on. Nothing here
|
|
5
|
+
decides anything: every fact these five functions put into words was settled
|
|
6
|
+
before they were called, by `scan`, `gaps` and `run`. `page_gaps` is the one
|
|
7
|
+
that looks like a decision and is not -- it slices a list that is already
|
|
8
|
+
computed, so that the gap crossing a page boundary is printed with the page
|
|
9
|
+
it leads into rather than lost with `--after`.
|
|
10
|
+
|
|
11
|
+
`continuity_line` travels with `_print_footer`, its only caller, and
|
|
12
|
+
`_MAX_NAMED_GAPS`, `ROLES_SEARCHED` and `EXACT_CONTINUITY` travel with the
|
|
13
|
+
two of them, which are the only things that read any of the three.
|
|
14
|
+
Everything here is re-exported by `flow_cmd`, so a caller (or a test) that
|
|
15
|
+
reaches for `flow_cmd.page_gaps` still finds it, and finds the same function
|
|
16
|
+
object.
|
|
17
|
+
|
|
18
|
+
The import runs one way, `flow_cmd` -> here. `_print_footer` calls one name
|
|
19
|
+
that stays behind (`continue_cmd`, which spells the command a reader would
|
|
20
|
+
type next), so it imports that inside its own body, the way
|
|
21
|
+
`refocus_licence` already does and for the same reason: a module-level
|
|
22
|
+
import back would be a cycle. `Gap` and `Index` appear only in annotations,
|
|
23
|
+
which `from __future__ import annotations` leaves unevaluated -- so they are
|
|
24
|
+
named under `TYPE_CHECKING` and are never imported at run time at all.
|
|
25
|
+
"""
|
|
26
|
+
from __future__ import annotations
|
|
27
|
+
|
|
28
|
+
from typing import TYPE_CHECKING
|
|
29
|
+
|
|
30
|
+
from sensorium.query.fmt import fmt_event, more_note
|
|
31
|
+
|
|
32
|
+
if TYPE_CHECKING:
|
|
33
|
+
from sensorium.query.flow_cmd import Gap, Index
|
|
34
|
+
|
|
35
|
+
_MAX_NAMED_GAPS = 6
|
|
36
|
+
ROLES_SEARCHED = "CALL args, RETURN values and LINE local deltas"
|
|
37
|
+
#: The footer line for an identity that needs no corroborating.
|
|
38
|
+
EXACT_CONTINUITY = "continuity: exact (serial identity)"
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _notes(idx: Index, seen: int, trunc: int) -> list[str]:
|
|
42
|
+
out = []
|
|
43
|
+
if trunc:
|
|
44
|
+
out.append(f"note: {trunc} of {seen} capture(s) searched were "
|
|
45
|
+
"truncated (over-cap or depth-capped containers, or "
|
|
46
|
+
"clipped strings); the parts not recorded could not be "
|
|
47
|
+
"compared, so a value present only there is not listed")
|
|
48
|
+
if not idx.has_line:
|
|
49
|
+
# Statement locals live on LINE rows. A return or an argument can
|
|
50
|
+
# still answer; this says what a miss is not evidence of.
|
|
51
|
+
out.append("note: this run recorded no LINE events, so statement "
|
|
52
|
+
"locals were not recorded; a value that only lived in a "
|
|
53
|
+
"local between call and return is not in this trace "
|
|
54
|
+
"(re-record with --focus MODULE[:QUALNAME])")
|
|
55
|
+
return out
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def page_gaps(all_gaps: list[Gap], start: int, shown: int) -> tuple:
|
|
59
|
+
"""(gaps this page must account for, gaps it can annotate, lead offset).
|
|
60
|
+
|
|
61
|
+
`start` is the index in the full sighting list of this page's first row.
|
|
62
|
+
A page after the first has a gap LEADING INTO its first row -- the one
|
|
63
|
+
crossing the page boundary -- which is as much part of its story as any
|
|
64
|
+
gap between its own rows: on page 2 of a lineage split by an ADDRESS
|
|
65
|
+
REUSED, that gap is the whole point. So it is annotated above the first
|
|
66
|
+
row and counted in this page's footer, instead of existing only in the
|
|
67
|
+
previous page's output.
|
|
68
|
+
"""
|
|
69
|
+
lead = 1 if start else 0
|
|
70
|
+
first = start - lead
|
|
71
|
+
end = start + max(shown - 1, 0)
|
|
72
|
+
return all_gaps[first:], all_gaps[first:max(end, first + lead)], lead
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _print_rows(trace, shown, notes: dict, lead: int) -> None:
|
|
76
|
+
if lead and 0 in notes:
|
|
77
|
+
print(" " + notes[0]) # the gap crossing into this page
|
|
78
|
+
for i, s in enumerate(shown):
|
|
79
|
+
print(f" {fmt_event(trace, s.event)} [{', '.join(s.labels)}]")
|
|
80
|
+
if lead + i in notes:
|
|
81
|
+
print(" " + notes[lead + i])
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def continuity_line(gs: list[Gap]) -> str:
|
|
85
|
+
unwit = [g for g in gs
|
|
86
|
+
if g.reuse is None and g.born is None and g.held is None]
|
|
87
|
+
named = ", ".join(f"e{g.a}->e{g.b}" for g in unwit[:_MAX_NAMED_GAPS])
|
|
88
|
+
extra = len(unwit) - _MAX_NAMED_GAPS
|
|
89
|
+
if named:
|
|
90
|
+
named = f" ({named}{f', +{extra} more' if extra > 0 else ''})"
|
|
91
|
+
parts = [f"{sum(1 for g in gs if g.held)} gap(s) spanned by a recorded "
|
|
92
|
+
"binding", f"{len(unwit)} unwitnessed{named}"]
|
|
93
|
+
reused = sum(1 for g in gs if g.reuse)
|
|
94
|
+
if reused:
|
|
95
|
+
parts.append(f"{reused} crossed a proven address reuse")
|
|
96
|
+
born = sum(1 for g in gs if g.born)
|
|
97
|
+
if born:
|
|
98
|
+
parts.append(f"{born} crossed a recorded construction")
|
|
99
|
+
return "continuity: " + ", ".join(parts)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def _print_footer(args, ref, idx, counts, scope, shown, gs, after,
|
|
103
|
+
exact: bool = False) -> None:
|
|
104
|
+
from sensorium.query.flow_cmd import continue_cmd
|
|
105
|
+
|
|
106
|
+
found, searched, seen, trunc = counts
|
|
107
|
+
# Counted over every sighting in scope, never over the printed page: a
|
|
108
|
+
# total that shrank with --limit would be a false fact about the run.
|
|
109
|
+
tail = ""
|
|
110
|
+
if len(shown) < len(scope):
|
|
111
|
+
tail += f" (showing {len(shown)})"
|
|
112
|
+
skipped = found - len(scope)
|
|
113
|
+
if skipped:
|
|
114
|
+
tail += f" ({skipped} earlier sighting(s) skipped by --after e{after})"
|
|
115
|
+
print(f"sightings: {len(scope)} event(s), "
|
|
116
|
+
f"{sum(len(s.labels) for s in scope)} capture(s){tail}")
|
|
117
|
+
if exact:
|
|
118
|
+
print(EXACT_CONTINUITY)
|
|
119
|
+
elif gs:
|
|
120
|
+
print(continuity_line(gs))
|
|
121
|
+
print(f"scope: {seen} capture(s) searched across {searched} event(s) in "
|
|
122
|
+
f"{ROLES_SEARCHED}")
|
|
123
|
+
for note in _notes(idx, seen, trunc):
|
|
124
|
+
print(note)
|
|
125
|
+
last = shown[-1].event.id if shown else after
|
|
126
|
+
note = more_note(len(scope), len(shown), continue_cmd(args, ref, last))
|
|
127
|
+
if note:
|
|
128
|
+
print(note)
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
"""The value layer `flow` searches: a literal, and what matches it.
|
|
2
|
+
|
|
3
|
+
Split out of `flow_cmd.py` at that file's 800-line ceiling, along the seam
|
|
4
|
+
the material has. Turning `--value`'s argument into a literal, and deciding
|
|
5
|
+
whether one capture is a sighting of a target, are decisions about CAPTURED
|
|
6
|
+
VALUES: they know nothing about events, frames, or the gap analysis that
|
|
7
|
+
reads them. Everything here is re-exported by `flow_cmd`, so a caller (or a
|
|
8
|
+
test) that reaches for `flow_cmd.matches` still finds it.
|
|
9
|
+
"""
|
|
10
|
+
import re
|
|
11
|
+
from dataclasses import dataclass
|
|
12
|
+
|
|
13
|
+
from sensorium.query.fmt import fmt_value
|
|
14
|
+
from sensorium.query.rust_debug import debug_text
|
|
15
|
+
|
|
16
|
+
CONTAINER_KINDS = ("obj", "seq", "map")
|
|
17
|
+
|
|
18
|
+
_NUMERIC = re.compile(r"[+-]?(\d[\d_]*\.?[\d_]*|\.\d[\d_]*)([eE][+-]?\d+)?")
|
|
19
|
+
_IDENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@dataclass(frozen=True)
|
|
23
|
+
class ObjTarget:
|
|
24
|
+
"""One object, as well as this trace can name one."""
|
|
25
|
+
oid: int
|
|
26
|
+
type: str
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
#: The words that name a value rather than a string, in both spellings the
|
|
30
|
+
#: reader may know (ruling R33). `--expr` already reads `null`, `true` and
|
|
31
|
+
#: `false` as values in every language (`expr._CONSTANTS`), and a reader
|
|
32
|
+
#: debugging a TypeScript trace writes them at `flow` too; a search that
|
|
33
|
+
#: quietly looked for the four-character STRING "null" instead would report
|
|
34
|
+
#: zero sightings of a value the trace holds. Language-neutral, like the
|
|
35
|
+
#: predicate's own constants: on a Rust trace `--value null` sights an
|
|
36
|
+
#: `Option::None` capture, which is the same value in the reader's terms.
|
|
37
|
+
#: `undefined` has no spelling here -- no writer can render it (a capture
|
|
38
|
+
#: that holds it is JavaScript's, and `inspect_text` returns None for the
|
|
39
|
+
#: marker) -- and neither has a BigInt; both are carried debts, not
|
|
40
|
+
#: silences: `--expr x == undefined` is what answers about one.
|
|
41
|
+
_WORDS = {"None": None, "null": None,
|
|
42
|
+
"True": True, "true": True,
|
|
43
|
+
"False": False, "false": False}
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def parse_literal(s: str):
|
|
47
|
+
"""The literal `--value` names.
|
|
48
|
+
|
|
49
|
+
Digits are a number, so quote to force a string (`--value "'1800'"`) --
|
|
50
|
+
otherwise a string of digits would be unsearchable. Words that `float()`
|
|
51
|
+
happens to accept ("nan", "inf", "infinity") stay strings: silently
|
|
52
|
+
turning a search for the word into a search for the float would report
|
|
53
|
+
zero sightings for a value the trace may well hold. The six words above
|
|
54
|
+
are the exception, and quoting still forces the string: `--value "'null'"`
|
|
55
|
+
searches for the four characters.
|
|
56
|
+
"""
|
|
57
|
+
if len(s) >= 2 and s[0] == s[-1] and s[0] in "'\"":
|
|
58
|
+
return s[1:-1]
|
|
59
|
+
if s in _WORDS:
|
|
60
|
+
return _WORDS[s]
|
|
61
|
+
if not _NUMERIC.fullmatch(s):
|
|
62
|
+
return s
|
|
63
|
+
try:
|
|
64
|
+
return int(s)
|
|
65
|
+
except ValueError:
|
|
66
|
+
pass
|
|
67
|
+
try:
|
|
68
|
+
return float(s)
|
|
69
|
+
except ValueError:
|
|
70
|
+
return s
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def matches(cap: dict, target, write=debug_text) -> bool:
|
|
74
|
+
"""Whether one capture is a sighting of `target`.
|
|
75
|
+
|
|
76
|
+
Bools and numbers are kept apart on the capture's own kind, because
|
|
77
|
+
`True == 1` in Python and a trace holding both must not report one as a
|
|
78
|
+
sighting of the other. A clipped string never matches: what was recorded
|
|
79
|
+
is a strict prefix of the real string, so the real string is longer than
|
|
80
|
+
-- and therefore unequal to -- anything it is compared with.
|
|
81
|
+
|
|
82
|
+
`write` is how the trace's own recorder would SPELL a literal
|
|
83
|
+
(`query/dbg_dialects`). Rust's by default, which is what every caller
|
|
84
|
+
written before a second dialect existed passes (plan P10) -- and what a
|
|
85
|
+
Python trace, whose captures are typed, never consults.
|
|
86
|
+
"""
|
|
87
|
+
if (cap.get("redacted") or {}).get("by") == "name":
|
|
88
|
+
# FIRST, and ahead of every kind below. A taken capture keeps its
|
|
89
|
+
# kind, its address and the rule's marker text, so it would answer
|
|
90
|
+
# yes to `--value '<redacted>'` and to an identity search over the
|
|
91
|
+
# address it kept -- and every taken value in the run redacts to
|
|
92
|
+
# the same text, so one literal would report values that are not
|
|
93
|
+
# equal to each other as sightings of one. A sighting the screen
|
|
94
|
+
# cannot be told apart from a correct one is this command's worst
|
|
95
|
+
# failure; a taken capture is a sighting of nothing.
|
|
96
|
+
return False
|
|
97
|
+
k = cap.get("k")
|
|
98
|
+
if isinstance(target, ObjTarget):
|
|
99
|
+
# A rendered capture carries an identity when the recorder minted
|
|
100
|
+
# one for it (`oid`/`type` on an object or a function, on nothing
|
|
101
|
+
# else). The identity is a KEY on the capture, never something read
|
|
102
|
+
# out of the text: matching on the text would splice every object
|
|
103
|
+
# that renders the same way into one lineage, which is the worst
|
|
104
|
+
# failure this command has -- the output looks exactly like a
|
|
105
|
+
# correct answer.
|
|
106
|
+
return ((k in CONTAINER_KINDS or (k == "dbg" and "oid" in cap))
|
|
107
|
+
and cap.get("oid") == target.oid
|
|
108
|
+
and cap.get("type") == target.type)
|
|
109
|
+
if k == "dbg":
|
|
110
|
+
# Rendered TEXT (design 2026-09-06 §4.2): a sighting is the
|
|
111
|
+
# literal's own RENDERING, spelled the way that recorder spells it
|
|
112
|
+
# -- so `"A1"` sights a Rust `String`, `'A1'` a JavaScript one, and
|
|
113
|
+
# the bare word `A1` sights an enum variant or a type name instead.
|
|
114
|
+
# A truncated text is a prefix of a rendering and equals none.
|
|
115
|
+
text = write(target)
|
|
116
|
+
return (not cap.get("trunc") and text is not None
|
|
117
|
+
and cap.get("v") == text)
|
|
118
|
+
if target is None:
|
|
119
|
+
return k == "none"
|
|
120
|
+
if isinstance(target, bool):
|
|
121
|
+
return k == "bool" and cap.get("v") == target
|
|
122
|
+
if isinstance(target, (int, float)):
|
|
123
|
+
return k == "num" and cap.get("v") == target
|
|
124
|
+
if k == "obj" and isinstance(target, str):
|
|
125
|
+
# A custom repr is the text the object captured. A truncated one is
|
|
126
|
+
# a prefix, same rule as a clipped string. The default
|
|
127
|
+
# `<Name object at 0x...>` form compares equal only to that exact
|
|
128
|
+
# string; `grep` is what searches a rendered field summary.
|
|
129
|
+
text = cap.get("repr")
|
|
130
|
+
return (not cap.get("trunc") and isinstance(text, str)
|
|
131
|
+
and text == target)
|
|
132
|
+
return k == "str" and not cap.get("trunc") and cap.get("v") == target
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def _key_step(kcap: dict) -> str:
|
|
136
|
+
"""How to render "the value under this key" in a path label."""
|
|
137
|
+
v = kcap.get("v")
|
|
138
|
+
if (kcap.get("k") == "str" and not kcap.get("trunc")
|
|
139
|
+
and isinstance(v, str) and _IDENT.fullmatch(v)):
|
|
140
|
+
return f".{v}"
|
|
141
|
+
return f"[{fmt_value(kcap)}]"
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _walk(v: dict, path: str = ""):
|
|
145
|
+
"""Every capture inside `v`, with the path that names it.
|
|
146
|
+
|
|
147
|
+
A depth-capped container omits `sample` entirely rather than supplying an
|
|
148
|
+
empty list, so it is always read with `.get` -- never `v["sample"]`.
|
|
149
|
+
"""
|
|
150
|
+
yield path, v
|
|
151
|
+
if (v.get("redacted") or {}).get("by") == "name":
|
|
152
|
+
# Yielded, never descended into. `matches` clears the container
|
|
153
|
+
# itself, but a walk that carried on would list `arg cfg.pw` --
|
|
154
|
+
# a path INSIDE a value the rule took, reported as a sighting.
|
|
155
|
+
# Today's Python writer strips the sample from a taken container
|
|
156
|
+
# (B4), so this shape reaches the reader only from another
|
|
157
|
+
# recorder's converter: the guard is on the capture, not on the
|
|
158
|
+
# absence of members, because the reader is shared by three
|
|
159
|
+
# languages.
|
|
160
|
+
return
|
|
161
|
+
k = v.get("k")
|
|
162
|
+
if k == "seq":
|
|
163
|
+
for i, x in enumerate(v.get("sample", [])):
|
|
164
|
+
yield from _walk(x, f"{path}[{i}]")
|
|
165
|
+
elif k == "map":
|
|
166
|
+
for i, pair in enumerate(v.get("sample", [])):
|
|
167
|
+
kcap, vcap = pair
|
|
168
|
+
yield from _walk(kcap, f"{path}[key {i}]")
|
|
169
|
+
yield from _walk(vcap, path + _key_step(kcap))
|
|
170
|
+
elif k == "obj":
|
|
171
|
+
fields = v.get("fields")
|
|
172
|
+
if isinstance(fields, dict):
|
|
173
|
+
for name, child in fields.items():
|
|
174
|
+
if isinstance(child, dict):
|
|
175
|
+
yield from _walk(child, path + _field_step(name))
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def _field_step(name) -> str:
|
|
179
|
+
"""How to render "the value of this field" in a path label."""
|
|
180
|
+
if isinstance(name, str) and _IDENT.fullmatch(name):
|
|
181
|
+
return f".{name}"
|
|
182
|
+
return f"[{name!r}]"
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def find_in_value(v: dict, target, path: str = "",
|
|
186
|
+
write=debug_text) -> list[str]:
|
|
187
|
+
"""The paths inside `v` at which `target` was captured.
|
|
188
|
+
|
|
189
|
+
`path` is third because it is `_walk`'s own parameter in that position
|
|
190
|
+
and a PREFIX the caller supplies, not a detail: it labels the root of
|
|
191
|
+
the result (`"arg cfg"` gives `arg cfg.grams`), and it is passed
|
|
192
|
+
positionally, so the order is part of the signature rather than a
|
|
193
|
+
leftover. `write` follows it as the debug sink, which no caller sets.
|
|
194
|
+
"""
|
|
195
|
+
return [p for p, cap in _walk(v, path) if matches(cap, target, write)]
|
sensorium/query/fmt.py
ADDED
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
"""Shared plain-text formatting: dense, stable, one fact per line."""
|
|
2
|
+
import re
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
def _size(v: dict) -> str:
|
|
6
|
+
"""A container's length, or `?` where the object's `__len__` raised.
|
|
7
|
+
|
|
8
|
+
`len` is None exactly when the capture could not read it (see
|
|
9
|
+
`capture.py`). Printing 0 there would be the recorder inventing a size.
|
|
10
|
+
"""
|
|
11
|
+
n = v.get("len")
|
|
12
|
+
return "?" if n is None else str(n)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def unread_marker(v: dict) -> str:
|
|
16
|
+
"""Which reads the observed object refused, named rather than implied."""
|
|
17
|
+
names = v.get("unread")
|
|
18
|
+
return f" <unread: {','.join(names)}>" if names else ""
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
#: How many hex of a digest a marker shows. Enough that two takings of one
|
|
22
|
+
#: value read alike on a screen, and far too few to guess a short value back
|
|
23
|
+
#: from -- the rule `info`'s `env:` field already keeps, applied where every
|
|
24
|
+
#: reader prints rather than to one field of one command.
|
|
25
|
+
_DIGEST_HEAD = 8
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _redacted_marker(v: dict) -> str | None:
|
|
29
|
+
"""How a capture the NAME rule took renders, or None for every capture
|
|
30
|
+
that renders the way it always did.
|
|
31
|
+
|
|
32
|
+
Read before `fmt_value`'s kind dispatch, and that ordering is the whole
|
|
33
|
+
of it. A taken capture KEEPS its kind and holds `redact.REDACTED` in the
|
|
34
|
+
field the value was in, so each arm below would render the rule's marker
|
|
35
|
+
text as if it were the value: a `num` through `repr` as the quoted
|
|
36
|
+
string `'<redacted>'` -- a number shown as a string the program never
|
|
37
|
+
held -- and a `str` indistinguishably from one that really did hold
|
|
38
|
+
those characters.
|
|
39
|
+
|
|
40
|
+
Three answers, one per shape the writer leaves behind (design B12):
|
|
41
|
+
|
|
42
|
+
* A text-shaped capture (`str`, `num`, `dbg`, and any kind the rule
|
|
43
|
+
did not recognise and so withheld whole) has nothing left but the
|
|
44
|
+
digest, so a prefix of the digest IS the rendering.
|
|
45
|
+
* A container keeps its type, its length and its address on purpose:
|
|
46
|
+
a size is a fact about the program, not about the value. It renders
|
|
47
|
+
as its own head with the marker where the members were.
|
|
48
|
+
* An object taken by name renders its identity only (`Type#oid`).
|
|
49
|
+
The rule takes `repr` and any `fields`; this rendering does not
|
|
50
|
+
print them. `flow --object` can still follow the identity. An
|
|
51
|
+
object the rule left alone prints its repr, or a field summary,
|
|
52
|
+
in `fmt_value` below.
|
|
53
|
+
|
|
54
|
+
`digest: null` is not a missing digest but a value that was never hashed
|
|
55
|
+
(a container has no one text to hash, and a withheld unknown kind has no
|
|
56
|
+
field this rule can name), so `<redacted #None>` there would be a reader
|
|
57
|
+
inventing a digest out of a null.
|
|
58
|
+
"""
|
|
59
|
+
r = v.get("redacted")
|
|
60
|
+
if not r or r.get("by") != "name":
|
|
61
|
+
return None
|
|
62
|
+
k = v.get("k")
|
|
63
|
+
if k == "obj":
|
|
64
|
+
return None
|
|
65
|
+
if k in ("seq", "map"):
|
|
66
|
+
return f"{v['type']}[{_size(v)}]=<redacted>"
|
|
67
|
+
digest = r.get("digest")
|
|
68
|
+
return f"<redacted #{digest[:_DIGEST_HEAD]}>" if digest else "<redacted>"
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
#: `object.__repr__`: `<Name object at 0xaddress>`. Addresses are recycled
|
|
72
|
+
#: and differ every run, so printing one would make a trace's text
|
|
73
|
+
#: nondeterministic and still say nothing about the value. A field summary
|
|
74
|
+
#: is what a reader gets instead; an instance with no fields stays `Type#oid`.
|
|
75
|
+
_DEFAULT_OBJ_REPR = re.compile(r"^<.+ object at 0x[0-9a-fA-F]+>$")
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def fmt_value(v: dict | None) -> str:
|
|
79
|
+
if v is None:
|
|
80
|
+
return "?"
|
|
81
|
+
# BEFORE the dispatch: a taken capture keeps its kind, so every arm
|
|
82
|
+
# below would render the rule's marker text as if it were the value.
|
|
83
|
+
taken = _redacted_marker(v)
|
|
84
|
+
if taken is not None:
|
|
85
|
+
return taken
|
|
86
|
+
k = v.get("k")
|
|
87
|
+
if k == "none":
|
|
88
|
+
return "None"
|
|
89
|
+
if k in ("num", "bool"):
|
|
90
|
+
return repr(v["v"])
|
|
91
|
+
if k == "str":
|
|
92
|
+
return repr(v["v"]) + ("~" if v.get("trunc") else "")
|
|
93
|
+
if k == "seq":
|
|
94
|
+
# A depth-capped capture omits "sample" entirely rather than
|
|
95
|
+
# supplying an empty list -- always read it with .get, never [].
|
|
96
|
+
inner = ", ".join(fmt_value(x) for x in v.get("sample", []))
|
|
97
|
+
more = ", ..." if v.get("trunc") else ""
|
|
98
|
+
return f"{v['type']}[{_size(v)}]=[{inner}{more}]{unread_marker(v)}"
|
|
99
|
+
if k == "map":
|
|
100
|
+
pairs = ", ".join(f"{fmt_value(a)}: {fmt_value(b)}"
|
|
101
|
+
for a, b in v.get("sample", []))
|
|
102
|
+
more = ", ..." if v.get("trunc") else ""
|
|
103
|
+
return f"{v['type']}[{_size(v)}]={{{pairs}{more}}}{unread_marker(v)}"
|
|
104
|
+
if k == "obj":
|
|
105
|
+
ident = f"{v['type']}#{v['oid']}{unread_marker(v)}"
|
|
106
|
+
# A name-taken object keeps `repr == <redacted>` (and used to keep
|
|
107
|
+
# fields). Printing either would show the marker as the program's
|
|
108
|
+
# own text, or a summary the rule was asked to withhold.
|
|
109
|
+
if (v.get("redacted") or {}).get("by") == "name":
|
|
110
|
+
return ident
|
|
111
|
+
fields = v.get("fields")
|
|
112
|
+
if isinstance(fields, dict) and fields:
|
|
113
|
+
parts = [f"{n}: {fmt_value(c) if isinstance(c, dict) else '?'}"
|
|
114
|
+
for n, c in fields.items()]
|
|
115
|
+
more = ", ..." if v.get("fields_trunc") else ""
|
|
116
|
+
return f"{ident} {{{', '.join(parts)}{more}}}"
|
|
117
|
+
text = v.get("repr")
|
|
118
|
+
if (isinstance(text, str) and "repr" not in (v.get("unread") or ())
|
|
119
|
+
and not _DEFAULT_OBJ_REPR.fullmatch(text)):
|
|
120
|
+
# A repr the program already wrapped in `<>` is printed as it
|
|
121
|
+
# is. Anything else is wrapped so the repr stays one token
|
|
122
|
+
# after the identity (`Cfg#7 <Cfg(a=1)>`).
|
|
123
|
+
shown = (text if text.startswith("<") and text.endswith(">")
|
|
124
|
+
else f"<{text}>")
|
|
125
|
+
return f"{ident} {shown}" + ("~" if v.get("trunc") else "")
|
|
126
|
+
return ident
|
|
127
|
+
if k == "dbg":
|
|
128
|
+
# A value the recorder rendered with the language's own formatter
|
|
129
|
+
# (Rust's `Debug`) rather than decomposing it. The text IS the
|
|
130
|
+
# capture; there is no type, length or sample behind it to print,
|
|
131
|
+
# and the ellipsis says the recorder's cap stopped the formatter
|
|
132
|
+
# mid-value -- not that the reader trimmed it here.
|
|
133
|
+
return f"{v.get('v', '?')}" + ("…" if v.get("trunc") else "")
|
|
134
|
+
if k == "unread":
|
|
135
|
+
# Nothing about this value could be read at all -- not even which
|
|
136
|
+
# kind it is. Say so; do not render it as an object with no repr.
|
|
137
|
+
if "type" not in v and "oid" not in v:
|
|
138
|
+
# ...and a recorder with no object identity to offer says only
|
|
139
|
+
# that: `<unreadable ?#?>` invents two fields it never had.
|
|
140
|
+
return "<unread>"
|
|
141
|
+
return f"<unreadable {v.get('type', '?')}#{v.get('oid', '?')}>"
|
|
142
|
+
return "?"
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def fmt_args(args: dict, limit: int = 4) -> str:
|
|
146
|
+
parts = [f"{n}={fmt_value(v)}" for n, v in list(args.items())[:limit]]
|
|
147
|
+
if len(args) > limit:
|
|
148
|
+
parts.append("...")
|
|
149
|
+
return ", ".join(parts)
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def _no_message(e: dict) -> str:
|
|
153
|
+
"""WHY a recorded exception carries no message, in the words of the
|
|
154
|
+
recorder that wrote it.
|
|
155
|
+
|
|
156
|
+
`''` here would read as an exception raised with no message at all, so
|
|
157
|
+
something must be said -- and until rung 3 the something was Python's
|
|
158
|
+
reason printed about every trace. On a Rust trace `__str__` does not
|
|
159
|
+
exist; `msg` is unread there because an `Err(_) =>` arm binds no name,
|
|
160
|
+
so the probe was handed nothing to read (design R4's
|
|
161
|
+
`err_site_unbound`). Naming a method that raised, about a language with
|
|
162
|
+
no such method, is a false statement about why the field is missing.
|
|
163
|
+
|
|
164
|
+
`exc.kind` is the discriminator TRACE-FORMAT section 5 gives for exactly
|
|
165
|
+
this: every `exc` a Rust recorder writes carries one, and an `exc` with
|
|
166
|
+
no `kind` at all is the Python recorder's. The unbound arm is the ONLY
|
|
167
|
+
site that leaves a Rust `msg` unread -- a panic always carries text,
|
|
168
|
+
even where that text says the panic was not recorded -- so one Rust
|
|
169
|
+
sentence covers the Rust column today; a new `kind` would need its own.
|
|
170
|
+
"""
|
|
171
|
+
if e.get("kind") is None:
|
|
172
|
+
return "<message unreadable: __str__ raised>"
|
|
173
|
+
return "<value not read: the arm binds no name>"
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def fmt_exc(e: dict) -> str:
|
|
177
|
+
if "msg" in (e.get("unread") or ()):
|
|
178
|
+
return f"{e['type']}({_no_message(e)})"
|
|
179
|
+
return f"{e['type']}({e['msg']!r})"
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def _site(e) -> str:
|
|
183
|
+
"""` L<n>` for a row whose recorder wrote a line, and NOTHING for one
|
|
184
|
+
that did not (R28a).
|
|
185
|
+
|
|
186
|
+
Every renderer below used to interpolate `L{e.line}` unconditionally,
|
|
187
|
+
which was true by accident: every recorder that existed when they were
|
|
188
|
+
written puts a line on every row that carries one. `sensorium-ts` does
|
|
189
|
+
not -- its YIELD and RESUME rows carry `line: null`, which the contract
|
|
190
|
+
reads as "the wire carries none" -- and the unconditional form spelled
|
|
191
|
+
that NULL out as the literal `LNone`, a reader naming a site the
|
|
192
|
+
recording does not hold.
|
|
193
|
+
|
|
194
|
+
Prepending the space rather than appending it is what keeps the
|
|
195
|
+
line-PRESENT rendering byte for byte what it was: ` L6 awaiting X` is
|
|
196
|
+
the same string as the old `f"{q} L{e.line} awaiting ..."` built the
|
|
197
|
+
other way round, so no Python or Rust output moves. A RETURN row prints
|
|
198
|
+
no site here at all and never did; that is unchanged.
|
|
199
|
+
"""
|
|
200
|
+
return f" L{e.line}" if e.line is not None else ""
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
def fmt_event(trace, e) -> str:
|
|
204
|
+
code = trace.code(e.code_id) if e.code_id is not None else None
|
|
205
|
+
q = code.qualname if code else "?"
|
|
206
|
+
p = e.payload or {}
|
|
207
|
+
if e.kind == "CALL":
|
|
208
|
+
body = f"{q}({fmt_args(p.get('args', {}))}){unread_marker(p)}"
|
|
209
|
+
elif e.kind == "RETURN":
|
|
210
|
+
body = f"{q} -> {fmt_value(p.get('value'))}"
|
|
211
|
+
elif e.kind in ("RAISE", "HANDLED"):
|
|
212
|
+
body = f"{q} {e.kind.lower()} {fmt_exc(p['exc'])}{_site(e)}"
|
|
213
|
+
elif e.kind == "LINE":
|
|
214
|
+
body = f"{q}{_site(e)}{_fmt_line_tail(p)}"
|
|
215
|
+
elif e.kind == "YIELD":
|
|
216
|
+
body = f"{q}{_site(e)} awaiting {p.get('awaiting', '?')}"
|
|
217
|
+
elif e.kind == "RESUME":
|
|
218
|
+
thrown = p.get("thrown")
|
|
219
|
+
body = (f"{q}{_site(e)} thrown {fmt_exc(thrown)}" if thrown
|
|
220
|
+
else f"{q}{_site(e)}")
|
|
221
|
+
else:
|
|
222
|
+
body = q
|
|
223
|
+
return f"e{e.id} {e.kind:<7} {body}"
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def _fmt_line_tail(p: dict) -> str:
|
|
227
|
+
"""LINE payloads carry "deltas" and may carry a sibling "unbound" list
|
|
228
|
+
(names that went out of scope this step: `del x`, or the implicit
|
|
229
|
+
unbind at the end of `except E as e:`). A step can legitimately have
|
|
230
|
+
empty deltas and a non-empty unbound -- render both, drop neither.
|
|
231
|
+
|
|
232
|
+
They may also carry `unread: ["locals"]`, when the frame's locals could
|
|
233
|
+
not be read at all -- a mapping the program supplied, whose `items()`
|
|
234
|
+
raised. That MUST render: empty deltas alone read as "nothing changed
|
|
235
|
+
here", which is the opposite of what this event says."""
|
|
236
|
+
deltas = ", ".join(f"{n}={fmt_value(v)}"
|
|
237
|
+
for n, v in p.get("deltas", {}).items())
|
|
238
|
+
unbound = p.get("unbound", [])
|
|
239
|
+
parts = [s for s in (deltas, f"unbound:{','.join(unbound)}"
|
|
240
|
+
if unbound else "", unread_marker(p).strip()) if s]
|
|
241
|
+
return " " + " ".join(parts) if parts else ""
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
def more_note(total: int, shown: int, hint: str) -> str | None:
|
|
245
|
+
if shown >= total:
|
|
246
|
+
return None
|
|
247
|
+
return f"... {total - shown} more; continue with: {hint}"
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
class RefError(ValueError):
|
|
251
|
+
"""A malformed event or frame reference given on the command line.
|
|
252
|
+
|
|
253
|
+
Raised rather than let `int()` escape: every command that takes a ref
|
|
254
|
+
(`grep --after`, `exceptions --after`, `flow --after`, `tree --root` /
|
|
255
|
+
`--around`, `frame f<id>`) used to die with an uncaught ValueError
|
|
256
|
+
traceback on a typo. `cli.main` turns this into a one-line refusal and
|
|
257
|
+
exit 2 -- a traceback is a poor answer for a human and an actively
|
|
258
|
+
confusing one for an agent parsing the output.
|
|
259
|
+
"""
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
def _parse_ref(s: str, sigil: str, kind: str) -> int:
|
|
263
|
+
"""`e12` / `12` -> 12. Anything else is a user error, not a crash.
|
|
264
|
+
|
|
265
|
+
Only ONE leading sigil is accepted: `int(s.lstrip("ef"))` took "eef12"
|
|
266
|
+
and "fe12" as 12, which quietly answers a question nobody asked.
|
|
267
|
+
"""
|
|
268
|
+
body = s[1:] if s[:1] == sigil else s
|
|
269
|
+
if not body.isdigit():
|
|
270
|
+
raise RefError(f"{s!r} is not {kind} reference; expected "
|
|
271
|
+
f"{sigil}<id> such as {sigil}42")
|
|
272
|
+
return int(body)
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
def parse_eref(s: str) -> int:
|
|
276
|
+
return _parse_ref(s, "e", "an event")
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
def parse_fref(s: str) -> int:
|
|
280
|
+
return _parse_ref(s, "f", "a frame")
|