@yahyahammad/venastine 0.3.8 → 0.3.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
package/tui/commands.py CHANGED
@@ -1,26 +1,26 @@
1
- """
2
- tui/commands.py
3
-
4
- ROADMAP_v2 §16 slash-command registry -- the TUI's.
5
-
6
- The registry is §16's; the commands registered into it are not all §16's.
7
- D7 assigns `/skill <name>` to §19, and §18/§21 add their own -- each
8
- registers here rather than editing a match statement in the app, which is
9
- the same mechanism-vs-policy split tools/registry.py already uses for
10
- tools.
11
-
12
- Since ROADMAP_v3 §89 (#8) the MECHANISM lives in `core/commands.py`, beside
13
- the catalog both shells bind to, because the CLI binds to it too and must
14
- not import from `tui/` to do so. This module is the TUI's registry
15
- instance: it takes only what the catalog declares for the TUI, built with
16
- `bind()`.
17
-
18
- A handler takes (app, argument_string) and returns None. It runs on the UI
19
- thread, so anything slow belongs in a worker.
20
- """
21
-
22
- from core.commands import TUI, CommandRegistry, SlashCommand, bind
23
-
24
- __all__ = ["CommandRegistry", "SlashCommand", "bind", "registry"]
25
-
26
- registry = CommandRegistry(TUI)
1
+ """
2
+ tui/commands.py
3
+
4
+ ROADMAP_v2 §16 slash-command registry -- the TUI's.
5
+
6
+ The registry is §16's; the commands registered into it are not all §16's.
7
+ D7 assigns `/skill <name>` to §19, and §18/§21 add their own -- each
8
+ registers here rather than editing a match statement in the app, which is
9
+ the same mechanism-vs-policy split tools/registry.py already uses for
10
+ tools.
11
+
12
+ Since ROADMAP_v3 §89 (#8) the MECHANISM lives in `core/commands.py`, beside
13
+ the catalog both shells bind to, because the CLI binds to it too and must
14
+ not import from `tui/` to do so. This module is the TUI's registry
15
+ instance: it takes only what the catalog declares for the TUI, built with
16
+ `bind()`.
17
+
18
+ A handler takes (app, argument_string) and returns None. It runs on the UI
19
+ thread, so anything slow belongs in a worker.
20
+ """
21
+
22
+ from core.commands import TUI, CommandRegistry, SlashCommand, bind
23
+
24
+ __all__ = ["CommandRegistry", "SlashCommand", "bind", "registry"]
25
+
26
+ registry = CommandRegistry(TUI)
package/tui/diffs.py CHANGED
@@ -1,286 +1,286 @@
1
- """
2
- tui/diffs.py
3
-
4
- What a `write` or an `edit` actually changed, as a block the transcript can
5
- paint (ROADMAP_v2 §41, X4-X6).
6
-
7
- Both tools used to render as `▸ {name} {param_digest(input)}`, and
8
- `param_digest` caps every value at 60 characters -- so an edit showed the
9
- first 60 characters of `old_text`, the first 60 of `new_text`, and nothing
10
- at all about where in the file they landed. Three questions a reader
11
- actually has (what changed, where, and what is around it) and the line
12
- answered none of them.
13
-
14
- PURE. No I/O, no `core/` import, no harness state -- `tui/widgets.py`'s own
15
- rule, because the widget imports this. Reading the file is `tui/app.py`'s
16
- job, and the tool's own path resolution is what it uses to do it.
17
-
18
- THE BLOCK IS TEXT, and that is deliberate (X5). `Transcript._entries` holds
19
- `(role, text)` pairs and everything downstream -- `/copy`, `rerender()`
20
- after a `/theme` -- reads them as text. A structured payload would have
21
- meant widening that tuple for one caller. So `build_block()` renders a
22
- canonical form and `parse()` reads it back, both here so the format has one
23
- definition:
24
-
25
- tui/widgets.py
26
- 317 │ except Exception:
27
- - 319 │ MARKERS = {"completed": "x"}
28
- + 319 │ MARKERS = {"completed": "☑"}
29
- … +812 more lines
30
-
31
- Line 0 is the path. Every other line is a kind character, a gutter, ` │ `
32
- and the source text. The DISPLAY furniture -- the indent, the padding, the
33
- colours -- belongs to the renderer and is not stored, for the reason §38
34
- gives for the thinking span's bar: `/copy` should hand back the diff, and a
35
- replay under a new theme should re-derive the painting rather than replay a
36
- string that was decorated once.
37
-
38
- DEGRADATION IS PART OF THE CONTRACT (X6). A diff that cannot be computed
39
- narrows; it never raises. `pre=None` -- a new file, one too large to
40
- snapshot, one that could not be read -- renders every line as an addition.
41
- An `edit` whose file could not be read still renders its `old_text` and
42
- `new_text` as `-`/`+` rows with an empty gutter, because those came from
43
- the call's own arguments and need no file at all.
44
- """
45
-
46
- from __future__ import annotations
47
-
48
- import difflib
49
- from typing import Optional
50
-
51
- from rich.cells import cell_len
52
-
53
- #: Lines of unchanged context either side of a change.
54
- CONTEXT_LINES = 3
55
-
56
- #: Rows in one block before the rest is summarised. A `write` of an
57
- #: 800-line file is a legitimate call, and rendering it whole would put
58
- #: eight hundred solid-green rows into the transcript and push the
59
- #: conversation out of view.
60
- MAX_ROWS = 40
61
-
62
- CONTEXT, DELETED, ADDED, ELIDED = "context", "del", "add", "elided"
63
-
64
- _MARKS = {CONTEXT: " ", DELETED: "-", ADDED: "+"}
65
- _KINDS = {" ": CONTEXT, "-": DELETED, "+": ADDED}
66
-
67
- #: Between the gutter and the source text. A box-drawing bar rather than a
68
- #: colon or a pipe, so it cannot be mistaken for part of either side.
69
- GUTTER_SEP = " │ "
70
-
71
- _ELIDE_MARK = "…"
72
-
73
- #: (kind, gutter, text). `gutter` is a string, not an int: a `-` row
74
- #: carries the OLD line number and a `+` row the NEW one, and a row from a
75
- #: degraded block carries neither.
76
- Row = tuple[str, str, str]
77
-
78
-
79
- def build_block(path: str, pre: Optional[str], post: str, *,
80
- context: int = CONTEXT_LINES,
81
- max_rows: int = MAX_ROWS) -> str:
82
- """The canonical block for one file change.
83
-
84
- `pre` is the file's contents before the call, or None when there was
85
- no file to read. `post` is what it contains now -- reconstructed from
86
- the call's own arguments rather than read back, so the block cannot
87
- disagree with the call it describes.
88
- """
89
- post_lines = post.splitlines()
90
- if pre is None:
91
- rows = [(ADDED, str(n), line) for n, line in enumerate(post_lines, 1)]
92
- else:
93
- rows = _rows(pre.splitlines(), post_lines, context)
94
- return _render(path, _capped(rows, max_rows))
95
-
96
-
97
- def wrap_source(text: str, width: int) -> list:
98
- """One source line as the rows it will occupy, at `width` columns.
99
-
100
- The same rule `Transcript._split_committable` uses for a streamed
101
- answer -- break at the last space that fits, and hard-cut a run
102
- longer than a row -- rather than `textwrap`, which collapses runs
103
- of whitespace and would silently re-indent the code it is
104
- displaying.
105
-
106
- The wrap has to be OURS for the reason §38 gives: Rich would
107
- soft-wrap the row and the padding that carries the background
108
- would land on the first rendered row only, so a wrapped addition
109
- would be half green. Width <= 0 means nothing is measurable (a
110
- widget built bare in the suite) and the line is returned whole.
111
-
112
- IN CELLS, NOT CHARACTERS (#224, batch 214), because the terminal
113
- measures cells: twenty double-width characters are twenty `len` and
114
- forty cells, so a row this sized as fitting was one Rich wrapped
115
- itself, with the background landing on half of it -- the very thing
116
- the pre-wrap exists to prevent. A glyph wider than the row is kept
117
- whole for Rich to wrap, as `markdown.plain_split` does.
118
- """
119
- if width <= 0 or cell_len(text) <= width:
120
- return [text]
121
- rows, rest = [], text
122
- while cell_len(rest) > width:
123
- fit = _chars_within(rest, width)
124
- space = rest.rfind(" ", 1, fit + 1)
125
- cut = space if space > 0 else fit
126
- rows.append(rest[:cut])
127
- rest = rest[cut:].lstrip(" ") if space > 0 else rest[cut:]
128
- if not rest:
129
- break
130
- if rest:
131
- rows.append(rest)
132
- return rows
133
-
134
-
135
- def _chars_within(text: str, width: int) -> int:
136
- """How many leading characters of `text` fit in `width` cells -- at
137
- least one, so a glyph wider than the row still makes progress."""
138
- cells = 0
139
- for index, char in enumerate(text):
140
- cells += cell_len(char)
141
- if cells > width:
142
- return max(1, index)
143
- return len(text)
144
-
145
-
146
- def build_replacement_block(path: str, old: str, new: str, *,
147
- max_rows: int = MAX_ROWS) -> str:
148
- """The degraded form for an `edit` whose file could not be read (X6).
149
-
150
- No line numbers and no surrounding context, because both need the
151
- file. The replaced and replacing text do not: they are the call's own
152
- arguments, and showing them is strictly better than showing the first
153
- 60 characters of each.
154
- """
155
- rows = [(DELETED, "", line) for line in old.splitlines()]
156
- rows += [(ADDED, "", line) for line in new.splitlines()]
157
- return _render(path, _capped(rows, max_rows))
158
-
159
-
160
- def parse(block: str) -> tuple[str, list[Row]]:
161
- """A block back into (path, rows). The renderer's half of the format.
162
-
163
- Tolerant by construction: a line this cannot make sense of comes back
164
- as context with an empty gutter. The block is produced two lines above
165
- in the same module, so a malformed one is a bug -- but it arrives here
166
- from `Transcript._entries`, which is replayed after a `/theme` and
167
- copied out by `/copy`, and neither of those is worth an exception.
168
- """
169
- lines = block.split("\n")
170
- path = lines[0] if lines else ""
171
- rows: list[Row] = []
172
- for line in lines[1:]:
173
- if not line:
174
- continue
175
- if line.startswith(_ELIDE_MARK):
176
- rows.append((ELIDED, "", line[len(_ELIDE_MARK):].strip()))
177
- continue
178
- kind = _KINDS.get(line[:1])
179
- if kind is None:
180
- rows.append((CONTEXT, "", line))
181
- continue
182
- gutter, sep, text = line[1:].partition(GUTTER_SEP)
183
- if not sep:
184
- rows.append((CONTEXT, "", line))
185
- continue
186
- rows.append((kind, gutter.strip(), text))
187
- return path, rows
188
-
189
-
190
- # ---------------------------------------------------------------------------
191
- # ---- internals ------------------------------------------------------------
192
- # ---------------------------------------------------------------------------
193
-
194
- def _rows(pre_lines: list[str], post_lines: list[str], context: int) -> list[Row]:
195
- """Changed lines with `context` unchanged lines either side.
196
-
197
- `SequenceMatcher` rather than `unified_diff`, because what is wanted
198
- here is the opcodes: a unified diff would have to be re-parsed to
199
- recover the line numbers this puts in the gutter, and re-parsing a
200
- format one line after emitting it is the second definition this module
201
- exists to avoid.
202
- """
203
- rows: list[Row] = []
204
- opcodes = difflib.SequenceMatcher(None, pre_lines, post_lines).get_opcodes()
205
- if all(tag == "equal" for tag, *_rest in opcodes):
206
- return rows
207
-
208
- for index, (tag, i1, i2, j1, j2) in enumerate(opcodes):
209
- if tag != "equal":
210
- for offset in range(i2 - i1):
211
- rows.append(
212
- (DELETED, str(i1 + offset + 1), pre_lines[i1 + offset]))
213
- for offset in range(j2 - j1):
214
- rows.append(
215
- (ADDED, str(j1 + offset + 1), post_lines[j1 + offset]))
216
- continue
217
- # Opcodes alternate, so an equal run shows context at its head when
218
- # a change precedes it and at its tail when one follows.
219
- head = context if index and opcodes[index - 1][0] != "equal" else 0
220
- tail = (context if index + 1 < len(opcodes)
221
- and opcodes[index + 1][0] != "equal" else 0)
222
- rows.extend(_equal_rows(post_lines, i2 - i1, j1, j2, head, tail))
223
- return rows
224
-
225
-
226
- def _equal_rows(post_lines, length, j1, j2, head, tail) -> list[Row]:
227
- """One unchanged run, trimmed to `head` lines at its start and `tail`
228
- at its end.
229
-
230
- Numbered from the NEW side, which is what the reader is looking at
231
- after the call: an unchanged line's two numbers diverge once anything
232
- above it has been added or removed, and the file on disk has the new
233
- one.
234
-
235
- The count of what was skipped is emitted only BETWEEN two hunks --
236
- where it says something the gutter does not, namely how far apart two
237
- changes are. Before the first hunk and after the last there is no
238
- second change to measure against, and the line numbers already say
239
- where in the file the reader is, so a leading "316 unchanged lines"
240
- would be furniture reporting the obvious.
241
- """
242
- if head + tail >= length:
243
- return [(CONTEXT, str(j1 + n + 1), post_lines[j1 + n])
244
- for n in range(length)]
245
- rows = [(CONTEXT, str(j1 + n + 1), post_lines[j1 + n]) for n in range(head)]
246
- hidden = length - head - tail
247
- if hidden > 0 and head and tail:
248
- rows.append((ELIDED, "",
249
- f"{hidden} unchanged line{'s' if hidden > 1 else ''}"))
250
- rows += [(CONTEXT, str(j2 - tail + n + 1), post_lines[j2 - tail + n])
251
- for n in range(tail)]
252
- return rows
253
-
254
-
255
- def _capped(rows: list[Row], max_rows: int) -> list[Row]:
256
- """At most `max_rows`, with the remainder counted rather than dropped
257
- silently -- M14's no-silent-caps rule, applied to a rendering."""
258
- if max_rows <= 0 or len(rows) <= max_rows:
259
- return rows
260
- kept = rows[:max_rows]
261
- hidden = len(rows) - max_rows
262
- kept.append((ELIDED, "",
263
- f"+{hidden} more line{'s' if hidden > 1 else ''}"))
264
- return kept
265
-
266
-
267
- def _render(path: str, rows: list[Row]) -> str:
268
- # An EMPTY string when nothing changed, so a caller can treat the
269
- # block as falsy rather than inspecting it. `write` with identical
270
- # content is a real call and a real no-op, and a block carrying a
271
- # path and no rows would render as a header announcing nothing.
272
- if not rows:
273
- return ""
274
- width = max((len(gutter) for _kind, gutter, _text in rows), default=0)
275
- out = [path]
276
- for kind, gutter, text in rows:
277
- if kind == ELIDED:
278
- out.append(f"{_ELIDE_MARK} {text}")
279
- continue
280
- # A space between the sign and the number, matching what the
281
- # renderer draws, so the copied block and the drawn block
282
- # differ only in the indent the renderer owns. parse()
283
- # strips the gutter, so the space costs it nothing.
284
- out.append(
285
- f"{_MARKS[kind]} {gutter.rjust(width)}{GUTTER_SEP}{text}")
286
- return "\n".join(out)
1
+ """
2
+ tui/diffs.py
3
+
4
+ What a `write` or an `edit` actually changed, as a block the transcript can
5
+ paint (ROADMAP_v2 §41, X4-X6).
6
+
7
+ Both tools used to render as `▸ {name} {param_digest(input)}`, and
8
+ `param_digest` caps every value at 60 characters -- so an edit showed the
9
+ first 60 characters of `old_text`, the first 60 of `new_text`, and nothing
10
+ at all about where in the file they landed. Three questions a reader
11
+ actually has (what changed, where, and what is around it) and the line
12
+ answered none of them.
13
+
14
+ PURE. No I/O, no `core/` import, no harness state -- `tui/widgets.py`'s own
15
+ rule, because the widget imports this. Reading the file is `tui/app.py`'s
16
+ job, and the tool's own path resolution is what it uses to do it.
17
+
18
+ THE BLOCK IS TEXT, and that is deliberate (X5). `Transcript._entries` holds
19
+ `(role, text)` pairs and everything downstream -- `/copy`, `rerender()`
20
+ after a `/theme` -- reads them as text. A structured payload would have
21
+ meant widening that tuple for one caller. So `build_block()` renders a
22
+ canonical form and `parse()` reads it back, both here so the format has one
23
+ definition:
24
+
25
+ tui/widgets.py
26
+ 317 │ except Exception:
27
+ - 319 │ MARKERS = {"completed": "x"}
28
+ + 319 │ MARKERS = {"completed": "☑"}
29
+ … +812 more lines
30
+
31
+ Line 0 is the path. Every other line is a kind character, a gutter, ` │ `
32
+ and the source text. The DISPLAY furniture -- the indent, the padding, the
33
+ colours -- belongs to the renderer and is not stored, for the reason §38
34
+ gives for the thinking span's bar: `/copy` should hand back the diff, and a
35
+ replay under a new theme should re-derive the painting rather than replay a
36
+ string that was decorated once.
37
+
38
+ DEGRADATION IS PART OF THE CONTRACT (X6). A diff that cannot be computed
39
+ narrows; it never raises. `pre=None` -- a new file, one too large to
40
+ snapshot, one that could not be read -- renders every line as an addition.
41
+ An `edit` whose file could not be read still renders its `old_text` and
42
+ `new_text` as `-`/`+` rows with an empty gutter, because those came from
43
+ the call's own arguments and need no file at all.
44
+ """
45
+
46
+ from __future__ import annotations
47
+
48
+ import difflib
49
+ from typing import Optional
50
+
51
+ from rich.cells import cell_len
52
+
53
+ #: Lines of unchanged context either side of a change.
54
+ CONTEXT_LINES = 3
55
+
56
+ #: Rows in one block before the rest is summarised. A `write` of an
57
+ #: 800-line file is a legitimate call, and rendering it whole would put
58
+ #: eight hundred solid-green rows into the transcript and push the
59
+ #: conversation out of view.
60
+ MAX_ROWS = 40
61
+
62
+ CONTEXT, DELETED, ADDED, ELIDED = "context", "del", "add", "elided"
63
+
64
+ _MARKS = {CONTEXT: " ", DELETED: "-", ADDED: "+"}
65
+ _KINDS = {" ": CONTEXT, "-": DELETED, "+": ADDED}
66
+
67
+ #: Between the gutter and the source text. A box-drawing bar rather than a
68
+ #: colon or a pipe, so it cannot be mistaken for part of either side.
69
+ GUTTER_SEP = " │ "
70
+
71
+ _ELIDE_MARK = "…"
72
+
73
+ #: (kind, gutter, text). `gutter` is a string, not an int: a `-` row
74
+ #: carries the OLD line number and a `+` row the NEW one, and a row from a
75
+ #: degraded block carries neither.
76
+ Row = tuple[str, str, str]
77
+
78
+
79
+ def build_block(path: str, pre: Optional[str], post: str, *,
80
+ context: int = CONTEXT_LINES,
81
+ max_rows: int = MAX_ROWS) -> str:
82
+ """The canonical block for one file change.
83
+
84
+ `pre` is the file's contents before the call, or None when there was
85
+ no file to read. `post` is what it contains now -- reconstructed from
86
+ the call's own arguments rather than read back, so the block cannot
87
+ disagree with the call it describes.
88
+ """
89
+ post_lines = post.splitlines()
90
+ if pre is None:
91
+ rows = [(ADDED, str(n), line) for n, line in enumerate(post_lines, 1)]
92
+ else:
93
+ rows = _rows(pre.splitlines(), post_lines, context)
94
+ return _render(path, _capped(rows, max_rows))
95
+
96
+
97
+ def wrap_source(text: str, width: int) -> list:
98
+ """One source line as the rows it will occupy, at `width` columns.
99
+
100
+ The same rule `Transcript._split_committable` uses for a streamed
101
+ answer -- break at the last space that fits, and hard-cut a run
102
+ longer than a row -- rather than `textwrap`, which collapses runs
103
+ of whitespace and would silently re-indent the code it is
104
+ displaying.
105
+
106
+ The wrap has to be OURS for the reason §38 gives: Rich would
107
+ soft-wrap the row and the padding that carries the background
108
+ would land on the first rendered row only, so a wrapped addition
109
+ would be half green. Width <= 0 means nothing is measurable (a
110
+ widget built bare in the suite) and the line is returned whole.
111
+
112
+ IN CELLS, NOT CHARACTERS (#224, batch 214), because the terminal
113
+ measures cells: twenty double-width characters are twenty `len` and
114
+ forty cells, so a row this sized as fitting was one Rich wrapped
115
+ itself, with the background landing on half of it -- the very thing
116
+ the pre-wrap exists to prevent. A glyph wider than the row is kept
117
+ whole for Rich to wrap, as `markdown.plain_split` does.
118
+ """
119
+ if width <= 0 or cell_len(text) <= width:
120
+ return [text]
121
+ rows, rest = [], text
122
+ while cell_len(rest) > width:
123
+ fit = _chars_within(rest, width)
124
+ space = rest.rfind(" ", 1, fit + 1)
125
+ cut = space if space > 0 else fit
126
+ rows.append(rest[:cut])
127
+ rest = rest[cut:].lstrip(" ") if space > 0 else rest[cut:]
128
+ if not rest:
129
+ break
130
+ if rest:
131
+ rows.append(rest)
132
+ return rows
133
+
134
+
135
+ def _chars_within(text: str, width: int) -> int:
136
+ """How many leading characters of `text` fit in `width` cells -- at
137
+ least one, so a glyph wider than the row still makes progress."""
138
+ cells = 0
139
+ for index, char in enumerate(text):
140
+ cells += cell_len(char)
141
+ if cells > width:
142
+ return max(1, index)
143
+ return len(text)
144
+
145
+
146
+ def build_replacement_block(path: str, old: str, new: str, *,
147
+ max_rows: int = MAX_ROWS) -> str:
148
+ """The degraded form for an `edit` whose file could not be read (X6).
149
+
150
+ No line numbers and no surrounding context, because both need the
151
+ file. The replaced and replacing text do not: they are the call's own
152
+ arguments, and showing them is strictly better than showing the first
153
+ 60 characters of each.
154
+ """
155
+ rows = [(DELETED, "", line) for line in old.splitlines()]
156
+ rows += [(ADDED, "", line) for line in new.splitlines()]
157
+ return _render(path, _capped(rows, max_rows))
158
+
159
+
160
+ def parse(block: str) -> tuple[str, list[Row]]:
161
+ """A block back into (path, rows). The renderer's half of the format.
162
+
163
+ Tolerant by construction: a line this cannot make sense of comes back
164
+ as context with an empty gutter. The block is produced two lines above
165
+ in the same module, so a malformed one is a bug -- but it arrives here
166
+ from `Transcript._entries`, which is replayed after a `/theme` and
167
+ copied out by `/copy`, and neither of those is worth an exception.
168
+ """
169
+ lines = block.split("\n")
170
+ path = lines[0] if lines else ""
171
+ rows: list[Row] = []
172
+ for line in lines[1:]:
173
+ if not line:
174
+ continue
175
+ if line.startswith(_ELIDE_MARK):
176
+ rows.append((ELIDED, "", line[len(_ELIDE_MARK):].strip()))
177
+ continue
178
+ kind = _KINDS.get(line[:1])
179
+ if kind is None:
180
+ rows.append((CONTEXT, "", line))
181
+ continue
182
+ gutter, sep, text = line[1:].partition(GUTTER_SEP)
183
+ if not sep:
184
+ rows.append((CONTEXT, "", line))
185
+ continue
186
+ rows.append((kind, gutter.strip(), text))
187
+ return path, rows
188
+
189
+
190
+ # ---------------------------------------------------------------------------
191
+ # ---- internals ------------------------------------------------------------
192
+ # ---------------------------------------------------------------------------
193
+
194
+ def _rows(pre_lines: list[str], post_lines: list[str], context: int) -> list[Row]:
195
+ """Changed lines with `context` unchanged lines either side.
196
+
197
+ `SequenceMatcher` rather than `unified_diff`, because what is wanted
198
+ here is the opcodes: a unified diff would have to be re-parsed to
199
+ recover the line numbers this puts in the gutter, and re-parsing a
200
+ format one line after emitting it is the second definition this module
201
+ exists to avoid.
202
+ """
203
+ rows: list[Row] = []
204
+ opcodes = difflib.SequenceMatcher(None, pre_lines, post_lines).get_opcodes()
205
+ if all(tag == "equal" for tag, *_rest in opcodes):
206
+ return rows
207
+
208
+ for index, (tag, i1, i2, j1, j2) in enumerate(opcodes):
209
+ if tag != "equal":
210
+ for offset in range(i2 - i1):
211
+ rows.append(
212
+ (DELETED, str(i1 + offset + 1), pre_lines[i1 + offset]))
213
+ for offset in range(j2 - j1):
214
+ rows.append(
215
+ (ADDED, str(j1 + offset + 1), post_lines[j1 + offset]))
216
+ continue
217
+ # Opcodes alternate, so an equal run shows context at its head when
218
+ # a change precedes it and at its tail when one follows.
219
+ head = context if index and opcodes[index - 1][0] != "equal" else 0
220
+ tail = (context if index + 1 < len(opcodes)
221
+ and opcodes[index + 1][0] != "equal" else 0)
222
+ rows.extend(_equal_rows(post_lines, i2 - i1, j1, j2, head, tail))
223
+ return rows
224
+
225
+
226
+ def _equal_rows(post_lines, length, j1, j2, head, tail) -> list[Row]:
227
+ """One unchanged run, trimmed to `head` lines at its start and `tail`
228
+ at its end.
229
+
230
+ Numbered from the NEW side, which is what the reader is looking at
231
+ after the call: an unchanged line's two numbers diverge once anything
232
+ above it has been added or removed, and the file on disk has the new
233
+ one.
234
+
235
+ The count of what was skipped is emitted only BETWEEN two hunks --
236
+ where it says something the gutter does not, namely how far apart two
237
+ changes are. Before the first hunk and after the last there is no
238
+ second change to measure against, and the line numbers already say
239
+ where in the file the reader is, so a leading "316 unchanged lines"
240
+ would be furniture reporting the obvious.
241
+ """
242
+ if head + tail >= length:
243
+ return [(CONTEXT, str(j1 + n + 1), post_lines[j1 + n])
244
+ for n in range(length)]
245
+ rows = [(CONTEXT, str(j1 + n + 1), post_lines[j1 + n]) for n in range(head)]
246
+ hidden = length - head - tail
247
+ if hidden > 0 and head and tail:
248
+ rows.append((ELIDED, "",
249
+ f"{hidden} unchanged line{'s' if hidden > 1 else ''}"))
250
+ rows += [(CONTEXT, str(j2 - tail + n + 1), post_lines[j2 - tail + n])
251
+ for n in range(tail)]
252
+ return rows
253
+
254
+
255
+ def _capped(rows: list[Row], max_rows: int) -> list[Row]:
256
+ """At most `max_rows`, with the remainder counted rather than dropped
257
+ silently -- M14's no-silent-caps rule, applied to a rendering."""
258
+ if max_rows <= 0 or len(rows) <= max_rows:
259
+ return rows
260
+ kept = rows[:max_rows]
261
+ hidden = len(rows) - max_rows
262
+ kept.append((ELIDED, "",
263
+ f"+{hidden} more line{'s' if hidden > 1 else ''}"))
264
+ return kept
265
+
266
+
267
+ def _render(path: str, rows: list[Row]) -> str:
268
+ # An EMPTY string when nothing changed, so a caller can treat the
269
+ # block as falsy rather than inspecting it. `write` with identical
270
+ # content is a real call and a real no-op, and a block carrying a
271
+ # path and no rows would render as a header announcing nothing.
272
+ if not rows:
273
+ return ""
274
+ width = max((len(gutter) for _kind, gutter, _text in rows), default=0)
275
+ out = [path]
276
+ for kind, gutter, text in rows:
277
+ if kind == ELIDED:
278
+ out.append(f"{_ELIDE_MARK} {text}")
279
+ continue
280
+ # A space between the sign and the number, matching what the
281
+ # renderer draws, so the copied block and the drawn block
282
+ # differ only in the indent the renderer owns. parse()
283
+ # strips the gutter, so the space costs it nothing.
284
+ out.append(
285
+ f"{_MARKS[kind]} {gutter.rjust(width)}{GUTTER_SEP}{text}")
286
+ return "\n".join(out)