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,213 @@
|
|
|
1
|
+
"""List recorded traces, newest-last."""
|
|
2
|
+
from sensorium import paths
|
|
3
|
+
from sensorium.exit import ANSWERED, NEGATIVE
|
|
4
|
+
from sensorium.query.vocab import exit_brief
|
|
5
|
+
from sensorium.store.reader import Trace
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def _licence_flag(m: dict) -> str:
|
|
9
|
+
"""`(granted)` is not what was granted.
|
|
10
|
+
|
|
11
|
+
A bare "granted" here reads as unbounded, which is the same failure this
|
|
12
|
+
listing already refuses for a bare "refocus-of" and a bare "MATCH", one
|
|
13
|
+
step further along: what `refocus` actually grants is a licence over a
|
|
14
|
+
counted, itemised set of points, and `sensorium info` prints them. Say
|
|
15
|
+
how many, and where to read them. A withheld licence keeps its own count
|
|
16
|
+
for the same reason.
|
|
17
|
+
"""
|
|
18
|
+
licence = m.get("refocus_licence")
|
|
19
|
+
if not licence:
|
|
20
|
+
return ""
|
|
21
|
+
key = ("refocus_licence_verified" if licence == "granted"
|
|
22
|
+
else "refocus_licence_reasons")
|
|
23
|
+
n = len(m.get(key) or [])
|
|
24
|
+
if not n:
|
|
25
|
+
return f"({licence},points-not-recorded)"
|
|
26
|
+
return f"({licence}:{n},see-info)"
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def add_parser(sub) -> None:
|
|
30
|
+
p = sub.add_parser(
|
|
31
|
+
"runs", help="list recorded traces",
|
|
32
|
+
description="One line per trace, oldest first: run id, exit, event "
|
|
33
|
+
"count, the command; a refocus rerun names its original "
|
|
34
|
+
"and its verdict.",
|
|
35
|
+
epilog="exit: 0 yes, 1 no, 2 fix the call, 3 change the recording")
|
|
36
|
+
p.set_defaults(func=run)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _cmd(m: dict) -> str:
|
|
40
|
+
"""What was run, as short as it can be said without losing it.
|
|
41
|
+
|
|
42
|
+
A Rust trace's `argv[0]` is the absolute path of a test binary under
|
|
43
|
+
`target/`, which is 90 characters of build directory and one useful
|
|
44
|
+
word. The basename of `exe` is that word; `info` prints the full path,
|
|
45
|
+
so nothing is lost -- it moves to the view that has room for it. A trace
|
|
46
|
+
with no `exe` (every Python one) is unchanged: its whole argv.
|
|
47
|
+
"""
|
|
48
|
+
argv = m.get("argv") or []
|
|
49
|
+
exe = m.get("exe")
|
|
50
|
+
if not exe:
|
|
51
|
+
return " ".join(argv)
|
|
52
|
+
return " ".join([str(exe).rsplit("/", 1)[-1], *argv[1:]])
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _row(stem: str, trace: Trace) -> str:
|
|
56
|
+
m = trace.meta
|
|
57
|
+
flags = []
|
|
58
|
+
if m.get("incomplete"):
|
|
59
|
+
flags.append("INCOMPLETE")
|
|
60
|
+
if m.get("trace_truncated"):
|
|
61
|
+
flags.append("TRUNCATED")
|
|
62
|
+
if m.get("refocus_of"):
|
|
63
|
+
# The verdict rides with the label, and the licence rides with
|
|
64
|
+
# the verdict. A bare "refocus-of" reads as a pedigree; a bare
|
|
65
|
+
# "verdict:MATCH" reads as a clean bill of health for a rerun
|
|
66
|
+
# whose licence was withheld on every count. Same failure, one
|
|
67
|
+
# level down.
|
|
68
|
+
flags.append(f"refocus-of:{m['refocus_of']}")
|
|
69
|
+
flags.append(f"verdict:{m.get('refocus_verdict', 'UNVERIFIED')}"
|
|
70
|
+
+ _licence_flag(m))
|
|
71
|
+
suffix = f" [{','.join(flags)}]" if flags else ""
|
|
72
|
+
return (f"{stem} exit:{exit_brief(m)} "
|
|
73
|
+
f"events:{sum(trace.counts().values())} "
|
|
74
|
+
f"{_what(m, trace.lang)}{suffix}")
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _what(m: dict, lang: str) -> str:
|
|
78
|
+
"""Which process this row is, in the fewest words that still tell it
|
|
79
|
+
apart from the others in its invocation.
|
|
80
|
+
|
|
81
|
+
A Rust invocation's members are distinct BINARIES, so the command is
|
|
82
|
+
what tells them apart. A vitest invocation's members are workers of one
|
|
83
|
+
harness: every one of them has the same
|
|
84
|
+
`node .../vitest/dist/workers/forks.js` command line, and a listing of
|
|
85
|
+
them by argv is a column of identical strings. What differs is the test
|
|
86
|
+
FILE the container ran, which the converter records as `test_file`
|
|
87
|
+
(`typescript/HONESTY.md` section 6) -- so that is what the row shows,
|
|
88
|
+
and `info` keeps the whole command line.
|
|
89
|
+
|
|
90
|
+
A reused worker ran several files and carries `test_files`: the count,
|
|
91
|
+
not the list, because a row is one line. A container that ran none -- a
|
|
92
|
+
`globalSetup` in the main process, any `node --test` process -- carries
|
|
93
|
+
neither key and keeps its argv, and that ABSENCE is the recorder's
|
|
94
|
+
statement rather than a gap.
|
|
95
|
+
|
|
96
|
+
GATED ON `lang`, NOT ON THE KEY BEING THERE (R27a). `info` has always
|
|
97
|
+
decided its language-specific blocks by `trace.lang` and never by
|
|
98
|
+
sniffing a key, for the reason `vocab` exists: a key name is not a
|
|
99
|
+
recorder's signature, and one recorder reading another's key off a
|
|
100
|
+
trace is the same class of error as reading another's WORD off it. Two
|
|
101
|
+
commands over one trace must not disagree about which recorder wrote
|
|
102
|
+
it, so `runs` reads the language the same way.
|
|
103
|
+
"""
|
|
104
|
+
if lang != "typescript":
|
|
105
|
+
return f"cmd: {_cmd(m)}"
|
|
106
|
+
one = m.get("test_file")
|
|
107
|
+
if one:
|
|
108
|
+
return f"file: {one}"
|
|
109
|
+
several = m.get("test_files")
|
|
110
|
+
if several:
|
|
111
|
+
return f"files: {len(several)}"
|
|
112
|
+
return f"cmd: {_cmd(m)}"
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _header(m: dict, lang: str) -> str:
|
|
116
|
+
"""The command one invocation's traces all came out of, in the words of
|
|
117
|
+
whatever ran it.
|
|
118
|
+
|
|
119
|
+
Without it a `cargo test` run is 30 unrelated-looking rows with 30
|
|
120
|
+
build-directory paths, and a `vitest run` is a dozen rows of the same
|
|
121
|
+
worker script; with it they are one command's processes, and the reader
|
|
122
|
+
can see at a glance that they belong together.
|
|
123
|
+
|
|
124
|
+
THE EXIT STATUS IS THE DIFFERENCE BETWEEN THE TWO HEADERS, and it is a
|
|
125
|
+
difference in what was RECORDED, not in taste. The cargo runner shim
|
|
126
|
+
waits for each test binary and nothing waits for cargo, so a Rust
|
|
127
|
+
invocation has no status to print and this line does not claim one. The
|
|
128
|
+
TypeScript driver spawns the harness and waits for the harness, so
|
|
129
|
+
`harness_exit` is a status somebody really did observe -- carried with
|
|
130
|
+
its own basis, and printed with it (`(waited)`), because that is the
|
|
131
|
+
whole of what makes it different from the `unwitnessed` on every member
|
|
132
|
+
row below it.
|
|
133
|
+
|
|
134
|
+
Which of the two is decided by `lang` and never by the presence of a
|
|
135
|
+
`harness` key, for the reason `_what` gives at length (R27a).
|
|
136
|
+
"""
|
|
137
|
+
if lang == "typescript":
|
|
138
|
+
return (f"invocation {m['invocation']}: {_harness_cmd(m)}"
|
|
139
|
+
+ _harness_exit(m))
|
|
140
|
+
if lang == "c":
|
|
141
|
+
# The command the driver was given. Never `cargo`: that word is
|
|
142
|
+
# the Rust header's, and a C invocation does not run it. The
|
|
143
|
+
# harness exit is the same witness the TypeScript header prints.
|
|
144
|
+
command = " ".join(str(a) for a in (m.get("driver_command") or []))
|
|
145
|
+
return (f"invocation {m['invocation']}: {command}".rstrip()
|
|
146
|
+
+ _harness_exit(m))
|
|
147
|
+
args = " ".join(m.get("cargo_args") or [])
|
|
148
|
+
return (f"invocation {m['invocation']}: cargo"
|
|
149
|
+
+ (f" {args}" if args else ""))
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def _harness_cmd(m: dict) -> str:
|
|
153
|
+
"""The command the user typed, verbatim (R26).
|
|
154
|
+
|
|
155
|
+
`harness_command` is those tokens before the driver consumed or
|
|
156
|
+
re-issued anything, and it is the only list here that is a command.
|
|
157
|
+
The fallback is for a trace whose converter predates the key, and it
|
|
158
|
+
is what this line printed before: `harness` + `harness_args`, which
|
|
159
|
+
reconstructs a plausible-looking command rather than the real one --
|
|
160
|
+
`node-test --test test/` names no program, and a `--root` the user
|
|
161
|
+
passed is missing from it. Kept because the alternative for such a
|
|
162
|
+
trace is printing nothing at all; corrected by re-recording.
|
|
163
|
+
"""
|
|
164
|
+
typed = m.get("harness_command")
|
|
165
|
+
if typed:
|
|
166
|
+
return " ".join(typed)
|
|
167
|
+
return " ".join([m["harness"], *(m.get("harness_args") or [])]).rstrip()
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def _harness_exit(m: dict) -> str:
|
|
171
|
+
"""How the harness ended, when somebody waited for it -- and nothing at
|
|
172
|
+
all when the record is absent, which is a driver killed before the
|
|
173
|
+
harness returned rather than a harness that ended at 0.
|
|
174
|
+
|
|
175
|
+
`status` and `signal` are exclusive: a process killed by a signal chose
|
|
176
|
+
no status, and printing `exit:None` for one is the failure the whole
|
|
177
|
+
exit rule exists to stop (TRACE-FORMAT section 4).
|
|
178
|
+
"""
|
|
179
|
+
ending = m.get("harness_exit")
|
|
180
|
+
if not ending:
|
|
181
|
+
return ""
|
|
182
|
+
basis = ending.get("basis", "waited")
|
|
183
|
+
if ending.get("status") is not None:
|
|
184
|
+
return f" exit:{ending['status']} ({basis})"
|
|
185
|
+
if ending.get("signal") is not None:
|
|
186
|
+
return f" exit:signal {ending['signal']} ({basis})"
|
|
187
|
+
return ""
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def run(args) -> int:
|
|
191
|
+
files = sorted(paths.traces_dir().glob("*.db"), key=lambda p: p.name)
|
|
192
|
+
if not files:
|
|
193
|
+
print("no traces recorded")
|
|
194
|
+
return NEGATIVE
|
|
195
|
+
# Opened in name order, exactly as before, and rendered in one pass
|
|
196
|
+
# afterwards: a group's members are its whole invocation, which can be
|
|
197
|
+
# anywhere in the listing, so the rows have to exist before the first
|
|
198
|
+
# header can be printed.
|
|
199
|
+
rows = [(f.stem, Trace.open(f)) for f in files]
|
|
200
|
+
seen: set = set()
|
|
201
|
+
for stem, trace in rows:
|
|
202
|
+
inv = trace.meta.get("invocation")
|
|
203
|
+
if inv is None:
|
|
204
|
+
print(_row(stem, trace))
|
|
205
|
+
continue
|
|
206
|
+
if inv in seen:
|
|
207
|
+
continue # printed under its own header
|
|
208
|
+
seen.add(inv)
|
|
209
|
+
print(_header(trace.meta, trace.lang))
|
|
210
|
+
for stem2, t2 in rows:
|
|
211
|
+
if t2.meta.get("invocation") == inv:
|
|
212
|
+
print(" " + _row(stem2, t2))
|
|
213
|
+
return ANSWERED
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
"""Rust `Debug` text: read one way, written one way, one escape table.
|
|
2
|
+
|
|
3
|
+
A `dbg` capture is what a probe got out of a value's own `Debug` impl --
|
|
4
|
+
TEXT, and the only thing a recorder can get for a type it cannot decompose.
|
|
5
|
+
Two commands have to make sense of that text and they must not disagree:
|
|
6
|
+
`watch --expr` READS it (`read_debug`, the value the text spells) and
|
|
7
|
+
`flow --value` WRITES it (`debug_text`, the rendering a literal would have).
|
|
8
|
+
An escape undone in one and re-applied differently in the other would report
|
|
9
|
+
a sighting that the predicate at the same site then denies, so both live
|
|
10
|
+
here, over one table.
|
|
11
|
+
|
|
12
|
+
WHAT IS PINNED, AND HOW IT WAS ESTABLISHED
|
|
13
|
+
------------------------------------------
|
|
14
|
+
Rust's spellings were MEASURED with `rustc` (2026-09-06), not assumed, and
|
|
15
|
+
two of them differ from Python's `repr` in ways no reader would guess:
|
|
16
|
+
|
|
17
|
+
2.0 -> "2.0" (same as repr)
|
|
18
|
+
1e20 -> "1e20" (repr says `1e+20`)
|
|
19
|
+
1e-5 -> "1e-5" (repr says `1e-05`)
|
|
20
|
+
"café" -> "café" (Debug escapes neither: non-ASCII is printable)
|
|
21
|
+
inf/-inf -> "inf"/"-inf" and NaN -> "NaN" (measured, all three)
|
|
22
|
+
"a\"b" -> "a\\"b" (`"` and `\\` are escaped, `'` is NOT)
|
|
23
|
+
'\\x07' -> "\\u{7}" (unprintables, minimal lowercase hex)
|
|
24
|
+
None -> "None" (an `Option`, printed as the word)
|
|
25
|
+
|
|
26
|
+
THE TWO DIRECTIONS ARE INVERSES ON THE LITERAL DOMAIN
|
|
27
|
+
-----------------------------------------------------
|
|
28
|
+
Design amendment A11: `read_debug` parses exactly what `debug_text` can
|
|
29
|
+
spell, so `resolve(dbg(debug_text(L))) == L` for every literal `L` a
|
|
30
|
+
command accepts. This is not tidiness -- it is the fix for a measured
|
|
31
|
+
disagreement. With `read_debug` stopping at the decimal forms, `flow
|
|
32
|
+
--value 1e20` reported a sighting of a capture that `watch --expr x ==
|
|
33
|
+
1e20` at that same site then denied (a plain False out of comparing text
|
|
34
|
+
with a float), and the same went for `1e400`/`inf` and for `None`. One
|
|
35
|
+
instrument answering yes and no about one capture is worse than either
|
|
36
|
+
answer, so the domains are pinned together: integers, floats in every
|
|
37
|
+
Debug spelling Rust uses (`2.5`, `1e20`, `1e-5`, `inf`, `-inf`, `NaN`),
|
|
38
|
+
`true`/`false`, the bare `None`, and quoted strings.
|
|
39
|
+
|
|
40
|
+
THE ONE THING NEITHER DIRECTION DOES
|
|
41
|
+
------------------------------------
|
|
42
|
+
Guess. `read_debug` returns the text itself whenever the text spells no
|
|
43
|
+
literal (a struct, an enum, a `Vec`), because the text is what the trace
|
|
44
|
+
holds; `debug_text` returns None for a target that has no Rust spelling,
|
|
45
|
+
and a capture then matches nothing rather than matching approximately.
|
|
46
|
+
"""
|
|
47
|
+
import re
|
|
48
|
+
|
|
49
|
+
# A Debug integer, and a Debug float -- a decimal POINT, an EXPONENT, or
|
|
50
|
+
# both, which is every shape Rust prints (`2.5`, `1e20`, `1e-5`, `1.5e-7`).
|
|
51
|
+
# The integer is tried first, so `5` is an int and never a float.
|
|
52
|
+
_INT = re.compile(r"-?\d+")
|
|
53
|
+
_FLOAT = re.compile(r"-?\d+\.\d+([eE][-+]?\d+)?|-?\d+([eE][-+]?\d+)")
|
|
54
|
+
# The three floats Rust spells as words rather than digits (measured).
|
|
55
|
+
_WORD_FLOATS = {"inf": float("inf"), "-inf": float("-inf"),
|
|
56
|
+
"NaN": float("nan")}
|
|
57
|
+
# Python's repr writes an exponent's sign and pads it to two digits; Rust
|
|
58
|
+
# writes neither. `1e+20` -> `1e20`, `1e-05` -> `1e-5`.
|
|
59
|
+
_EXP = re.compile(r"e\+?(-?)0*(\d)")
|
|
60
|
+
|
|
61
|
+
# `\'` never appears in a string's Debug (Rust escapes a single quote only
|
|
62
|
+
# inside a char's), and it is read anyway: undoing an escape the writer did
|
|
63
|
+
# not have to make is harmless, refusing one is not.
|
|
64
|
+
_UNESCAPE = {"n": "\n", "t": "\t", "r": "\r", "0": "\0",
|
|
65
|
+
"\\": "\\", '"': '"', "'": "'"}
|
|
66
|
+
_ESCAPE = {"\\": "\\\\", '"': '\\"', "\n": "\\n", "\t": "\\t",
|
|
67
|
+
"\r": "\\r", "\0": "\\0"}
|
|
68
|
+
_HEX = "0123456789abcdefABCDEF"
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def read_debug(text: str):
|
|
72
|
+
"""The value a Debug text spells: int, float, bool, None, str, or text.
|
|
73
|
+
|
|
74
|
+
The caller has already dealt with truncation -- a clipped rendering is
|
|
75
|
+
not a rendering, and nothing here may be applied to a prefix.
|
|
76
|
+
"""
|
|
77
|
+
if _INT.fullmatch(text):
|
|
78
|
+
return int(text)
|
|
79
|
+
if _FLOAT.fullmatch(text):
|
|
80
|
+
return float(text)
|
|
81
|
+
if text in _WORD_FLOATS:
|
|
82
|
+
return _WORD_FLOATS[text]
|
|
83
|
+
if text in ("true", "false"):
|
|
84
|
+
return text == "true"
|
|
85
|
+
if text == "None":
|
|
86
|
+
# `Option::None`, and the one way a reader can name it: `flow
|
|
87
|
+
# --value None` already searches for this text, so a predicate at
|
|
88
|
+
# the same site has to see the same thing (A11).
|
|
89
|
+
return None
|
|
90
|
+
if len(text) >= 2 and text[0] == '"' == text[-1]:
|
|
91
|
+
return unescape_debug(text[1:-1])
|
|
92
|
+
return text
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def unescape_debug(inner: str) -> str:
|
|
96
|
+
r"""The characters a Debug string's body stands for.
|
|
97
|
+
|
|
98
|
+
Hand-written rather than `codecs.decode(.., "unicode_escape")`, which
|
|
99
|
+
decodes latin-1 and so turns every non-ASCII character Rust printed
|
|
100
|
+
literally into mojibake -- `"café"` would come back as `café` and
|
|
101
|
+
compare unequal to the string the program held.
|
|
102
|
+
|
|
103
|
+
An escape this table does not know is left EXACTLY as it was read: a
|
|
104
|
+
reader comparing against text sees the same characters the trace holds,
|
|
105
|
+
rather than a silent reinterpretation of them.
|
|
106
|
+
"""
|
|
107
|
+
out: list[str] = []
|
|
108
|
+
i, n = 0, len(inner)
|
|
109
|
+
while i < n:
|
|
110
|
+
ch = inner[i]
|
|
111
|
+
if ch != "\\" or i + 1 >= n:
|
|
112
|
+
out.append(ch)
|
|
113
|
+
i += 1
|
|
114
|
+
continue
|
|
115
|
+
nxt = inner[i + 1]
|
|
116
|
+
if nxt in _UNESCAPE:
|
|
117
|
+
out.append(_UNESCAPE[nxt])
|
|
118
|
+
i += 2
|
|
119
|
+
continue
|
|
120
|
+
if nxt == "u" and inner[i + 2:i + 3] == "{":
|
|
121
|
+
end = inner.find("}", i + 3)
|
|
122
|
+
digits = inner[i + 3:end] if end != -1 else ""
|
|
123
|
+
if digits and all(c in _HEX for c in digits):
|
|
124
|
+
try:
|
|
125
|
+
out.append(chr(int(digits, 16)))
|
|
126
|
+
except ValueError:
|
|
127
|
+
pass # beyond U+10FFFF: leave it read
|
|
128
|
+
else:
|
|
129
|
+
i = end + 1
|
|
130
|
+
continue
|
|
131
|
+
out.append(ch)
|
|
132
|
+
i += 1
|
|
133
|
+
return "".join(out)
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def escape_debug(s: str) -> str:
|
|
137
|
+
"""A string's characters as Rust's `Debug` prints them, without quotes.
|
|
138
|
+
|
|
139
|
+
`str::escape_debug` escapes `\\` `"` and the unprintables and leaves
|
|
140
|
+
everything else alone; `'` is escaped only in a char's Debug, never in a
|
|
141
|
+
string's. `str.isprintable()` is Python's name for the same category
|
|
142
|
+
test (Cc, Cf, Cs, Co, Cn, Zl, Zp and the non-space Zs are not printable
|
|
143
|
+
in either language), so the two agree on which characters need `\\u{..}`.
|
|
144
|
+
"""
|
|
145
|
+
out = []
|
|
146
|
+
for ch in s:
|
|
147
|
+
esc = _ESCAPE.get(ch)
|
|
148
|
+
if esc is not None:
|
|
149
|
+
out.append(esc)
|
|
150
|
+
elif ch.isprintable():
|
|
151
|
+
out.append(ch)
|
|
152
|
+
else:
|
|
153
|
+
out.append(f"\\u{{{ord(ch):x}}}")
|
|
154
|
+
return "".join(out)
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def debug_text(target) -> str | None:
|
|
158
|
+
"""How Rust's `Debug` would spell this literal, or None if it would not.
|
|
159
|
+
|
|
160
|
+
None is the honest answer for anything with no Rust spelling (an
|
|
161
|
+
`ObjTarget`, say): a capture then matches it nowhere, rather than
|
|
162
|
+
matching something adjacent.
|
|
163
|
+
"""
|
|
164
|
+
if target is None:
|
|
165
|
+
return "None" # `Option::None`, as Rust prints
|
|
166
|
+
if isinstance(target, bool): # before int: a bool IS an int
|
|
167
|
+
return "true" if target else "false"
|
|
168
|
+
if isinstance(target, int):
|
|
169
|
+
return str(target)
|
|
170
|
+
if isinstance(target, float):
|
|
171
|
+
if target != target:
|
|
172
|
+
return "NaN" # `repr` says `nan`; Rust `NaN`
|
|
173
|
+
return _EXP.sub(r"e\1\2", repr(target))
|
|
174
|
+
if isinstance(target, str):
|
|
175
|
+
return '"' + escape_debug(target) + '"'
|
|
176
|
+
return None
|
sensorium/query/sites.py
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
"""One recorded site: how a reader names it, and how a reader is shown it.
|
|
2
|
+
|
|
3
|
+
A SITE is a code object -- a file and a qualname -- and three commands have
|
|
4
|
+
to agree about how it is written down: `watch --at` reads a spelling from
|
|
5
|
+
the command line, `watch`'s no-match listing and its re-record guidance
|
|
6
|
+
write one back, and `sensorium ts run --focus` (a different program, in a
|
|
7
|
+
different language) reads one before a run. A reader who focused a function
|
|
8
|
+
and then asks about it types the SAME characters both times, or the second
|
|
9
|
+
command answers "no recorded code matches" about the function they just
|
|
10
|
+
recorded.
|
|
11
|
+
|
|
12
|
+
So the spelling lives here, once, keyed on the trace's own vocabulary:
|
|
13
|
+
|
|
14
|
+
* `"module"` -- Python's dotted module name, derived from the run's root,
|
|
15
|
+
which is what `watch` has always printed and what Rust's listings quote
|
|
16
|
+
(plan P8: the design's `"stem"` for Rust would move a closed record's
|
|
17
|
+
bytes for no gain).
|
|
18
|
+
* `"rel"` -- the path relative to the invocation's root, which is what a
|
|
19
|
+
TypeScript `--focus` is typed with and what `meta.focus_matched`
|
|
20
|
+
records.
|
|
21
|
+
|
|
22
|
+
WHAT `--at` ACCEPTS, AND WHY IT IS WIDER THAN WHAT IT PRINTS
|
|
23
|
+
------------------------------------------------------------
|
|
24
|
+
Matching is deliberately wider than spelling: the file half of a spec may
|
|
25
|
+
be the dotted module, the stem, the basename or the root-relative path, in
|
|
26
|
+
every language. That is additive -- nothing that matched before stops
|
|
27
|
+
matching -- and it is what makes every `--focus` spelling an `--at`
|
|
28
|
+
spelling. It stays a real boundary all the same: `lib` is a directory,
|
|
29
|
+
`src/cache.ts` is a path this trace does not hold, and neither selects
|
|
30
|
+
`src/lib/cache.ts`. Answering about a file the reader did not name is worse
|
|
31
|
+
than refusing, because the answer looks right.
|
|
32
|
+
|
|
33
|
+
TWO IMPLEMENTATIONS OF ONE RULE, ON PURPOSE
|
|
34
|
+
-------------------------------------------
|
|
35
|
+
`typescript/src/focus.mjs` applies the same rule to source before a run;
|
|
36
|
+
this applies it to a recorded trace after one. They cannot be one function
|
|
37
|
+
-- they are in different languages and see different inputs -- so they are
|
|
38
|
+
held to one example table instead,
|
|
39
|
+
`typescript/test/fixtures/site-spellings.json`. `focus.test.mjs` reads it
|
|
40
|
+
on that side and `tests/test_watch_typescript.py` on this one, and
|
|
41
|
+
`v39-site-spellings` asks the CLI those same ten rows as questions
|
|
42
|
+
(design 2026-09-11 section 4.3, ruling R7).
|
|
43
|
+
"""
|
|
44
|
+
import shlex
|
|
45
|
+
from pathlib import Path
|
|
46
|
+
|
|
47
|
+
from sensorium.query.vocab import terms
|
|
48
|
+
from sensorium.record.tracer import module_name_for
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _anchor(trace) -> Path | None:
|
|
52
|
+
"""The directory every relative path in this trace is relative to.
|
|
53
|
+
|
|
54
|
+
`root` is the invocation's, written by the TypeScript driver because
|
|
55
|
+
every `rel` in that trace -- the fingerprint's paths, the test file, a
|
|
56
|
+
`focus_matched` entry -- was made relative to it (plan P9); `cwd` is
|
|
57
|
+
what the Python recorder has always had. A trace with neither can still
|
|
58
|
+
be matched by stem and basename, which need no anchor at all.
|
|
59
|
+
"""
|
|
60
|
+
root = trace.meta.get("root") or trace.meta.get("cwd")
|
|
61
|
+
return Path(root).resolve() if root else None
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _relative(file: str, anchor: Path | None) -> str | None:
|
|
65
|
+
"""This file as the invocation named it, or None if it lies outside."""
|
|
66
|
+
if anchor is None:
|
|
67
|
+
return None
|
|
68
|
+
try:
|
|
69
|
+
return Path(file).resolve().relative_to(anchor).as_posix()
|
|
70
|
+
except ValueError:
|
|
71
|
+
return None
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _rel_site(trace, code) -> str:
|
|
75
|
+
rel = _relative(code.file, _anchor(trace))
|
|
76
|
+
# The basename is the honest fallback for a file outside the root (or a
|
|
77
|
+
# trace that records none): it is still a spelling `--at` accepts, and
|
|
78
|
+
# it never claims a path this recording cannot support.
|
|
79
|
+
return f"{rel or Path(code.file).name}:{code.qualname}"
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _module_site(trace, code) -> str:
|
|
83
|
+
anchor = _anchor(trace)
|
|
84
|
+
mod = module_name_for(code.file, anchor) if anchor else None
|
|
85
|
+
return f"{mod or Path(code.file).stem}:{code.qualname}"
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
_SPELLERS = {"rel": _rel_site, "module": _module_site}
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def spell_site(trace, code) -> str:
|
|
92
|
+
"""`<file>:<qualname>`, in this recorder's own spelling.
|
|
93
|
+
|
|
94
|
+
Strict, like `vocab.terms` itself: a `site_spelling` no speller answers
|
|
95
|
+
for is a programming error, not a trace a user can produce -- the
|
|
96
|
+
vocabulary table is closed and `tests/test_vocab.py` pins every
|
|
97
|
+
column's word.
|
|
98
|
+
"""
|
|
99
|
+
return _SPELLERS[terms(trace).site_spelling](trace, code)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def file_names(trace, code) -> set[str]:
|
|
103
|
+
"""Every spelling of this code object's FILE that `--at` accepts."""
|
|
104
|
+
path = Path(code.file)
|
|
105
|
+
anchor = _anchor(trace)
|
|
106
|
+
names = {path.stem, path.name}
|
|
107
|
+
if anchor is not None:
|
|
108
|
+
names.add(module_name_for(code.file, anchor))
|
|
109
|
+
names.add(_relative(code.file, anchor))
|
|
110
|
+
names.discard(None)
|
|
111
|
+
return names
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def _qual_matches(qualname: str, spec: str) -> bool:
|
|
115
|
+
"""`Pot` selects `Pot.add`, and `Counter` selects `Counter::new`.
|
|
116
|
+
|
|
117
|
+
A prefix counts only where it ends at a BOUNDARY -- Python's `.` or
|
|
118
|
+
Rust's `::` -- or `--at Counter` would quietly answer about
|
|
119
|
+
`Counters::new`, a different function the reader never named. One rule
|
|
120
|
+
holding both separators, and no `lang` branch anywhere near it: `watch`
|
|
121
|
+
takes the qualname its own recorder printed (design 2026-09-06 §4.1).
|
|
122
|
+
JavaScript's boundary is `.` as well, so the third recorder needed no
|
|
123
|
+
third separator -- `Fog` selects `Fog.compute` and `Fogs` selects
|
|
124
|
+
neither.
|
|
125
|
+
|
|
126
|
+
This is the only prefix rule in `query/`. `flow --object
|
|
127
|
+
<qualname>:<name>` names ONE function and resolves it by equality, so
|
|
128
|
+
there is no second copy of the rule to keep in step with this one; the
|
|
129
|
+
recorder's own focus matchers (`record/tracer`,
|
|
130
|
+
`typescript/src/focus.mjs`) are a different question, asked of source
|
|
131
|
+
before a run rather than of a recorded trace.
|
|
132
|
+
"""
|
|
133
|
+
return (qualname == spec or qualname.startswith(spec + ".")
|
|
134
|
+
or qualname.startswith(spec + "::"))
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def site_matches(code, at: str, trace) -> bool:
|
|
138
|
+
"""Whether `--at <at>` selects this code object."""
|
|
139
|
+
mod, sep, qual = at.partition(":")
|
|
140
|
+
if sep:
|
|
141
|
+
if qual and not _qual_matches(code.qualname, qual):
|
|
142
|
+
return False
|
|
143
|
+
return not mod or mod in file_names(trace, code)
|
|
144
|
+
return (_qual_matches(code.qualname, at)
|
|
145
|
+
or at in file_names(trace, code))
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def rerun_command(trace, codes) -> str:
|
|
149
|
+
"""The exact command that records this run again with these frames'
|
|
150
|
+
locals.
|
|
151
|
+
|
|
152
|
+
Fully instantiated, including the run's own command line and any focus
|
|
153
|
+
it already had: a hint carrying a literal MODULE:QUALNAME placeholder is
|
|
154
|
+
a template, not an answer, and an agent reading it has to guess. The
|
|
155
|
+
focus already in the meta travels AS TYPED -- that is what its author
|
|
156
|
+
will recognise -- and the sites asked about are added in this
|
|
157
|
+
recorder's own spelling, which is what its `--focus` resolves.
|
|
158
|
+
"""
|
|
159
|
+
words = terms(trace)
|
|
160
|
+
meta = trace.meta
|
|
161
|
+
specs = [*(meta.get("focus") or []),
|
|
162
|
+
*(spell_site(trace, c) for c in codes)]
|
|
163
|
+
focus = "".join(f" --focus {shlex.quote(s)}" for s in specs)
|
|
164
|
+
command = " ".join(shlex.quote(str(a))
|
|
165
|
+
for a in (meta.get(words.command_key) or []))
|
|
166
|
+
# `rstrip`, because a template whose `{command}` came back empty would
|
|
167
|
+
# otherwise end in a space -- and the Python column's bytes, which the
|
|
168
|
+
# legacy suite fences, have never had one (ruling R3).
|
|
169
|
+
body = words.rerun_command.format(focus=focus, command=command).rstrip()
|
|
170
|
+
cwd = meta.get("cwd")
|
|
171
|
+
return f"cd {shlex.quote(cwd)} && {body}" if cwd else body
|