@yahyahammad/venastine 0.2.0 → 0.3.8

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 (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +277 -43
  12. package/agents/tui_commands.py +7 -12
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +158 -20
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +1516 -440
  38. package/core/memory.py +120 -8
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +158 -26
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1671 -199
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +7 -12
  70. package/package.json +234 -4
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +368 -35
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
package/tui/diffs.py CHANGED
@@ -1,265 +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 List, Optional, Tuple
50
-
51
- #: Lines of unchanged context either side of a change.
52
- CONTEXT_LINES = 3
53
-
54
- #: Rows in one block before the rest is summarised. A `write` of an
55
- #: 800-line file is a legitimate call, and rendering it whole would put
56
- #: eight hundred solid-green rows into the transcript and push the
57
- #: conversation out of view.
58
- MAX_ROWS = 40
59
-
60
- CONTEXT, DELETED, ADDED, ELIDED = "context", "del", "add", "elided"
61
-
62
- _MARKS = {CONTEXT: " ", DELETED: "-", ADDED: "+"}
63
- _KINDS = {" ": CONTEXT, "-": DELETED, "+": ADDED}
64
-
65
- #: Between the gutter and the source text. A box-drawing bar rather than a
66
- #: colon or a pipe, so it cannot be mistaken for part of either side.
67
- GUTTER_SEP = " │ "
68
-
69
- _ELIDE_MARK = "…"
70
-
71
- #: (kind, gutter, text). `gutter` is a string, not an int: a `-` row
72
- #: carries the OLD line number and a `+` row the NEW one, and a row from a
73
- #: degraded block carries neither.
74
- Row = Tuple[str, str, str]
75
-
76
-
77
- def build_block(path: str, pre: Optional[str], post: str, *,
78
- context: int = CONTEXT_LINES,
79
- max_rows: int = MAX_ROWS) -> str:
80
- """The canonical block for one file change.
81
-
82
- `pre` is the file's contents before the call, or None when there was
83
- no file to read. `post` is what it contains now -- reconstructed from
84
- the call's own arguments rather than read back, so the block cannot
85
- disagree with the call it describes.
86
- """
87
- post_lines = post.splitlines()
88
- if pre is None:
89
- rows = [(ADDED, str(n), line) for n, line in enumerate(post_lines, 1)]
90
- else:
91
- rows = _rows(pre.splitlines(), post_lines, context)
92
- return _render(path, _capped(rows, max_rows))
93
-
94
-
95
- def wrap_source(text: str, width: int) -> list:
96
- """One source line as the rows it will occupy, at `width` columns.
97
-
98
- The same rule `Transcript._split_committable` uses for a streamed
99
- answer -- break at the last space that fits, and hard-cut a run
100
- longer than a row -- rather than `textwrap`, which collapses runs
101
- of whitespace and would silently re-indent the code it is
102
- displaying.
103
-
104
- The wrap has to be OURS for the reason §38 gives: Rich would
105
- soft-wrap the row and the padding that carries the background
106
- would land on the first rendered row only, so a wrapped addition
107
- would be half green. Width <= 0 means nothing is measurable (a
108
- widget built bare in the suite) and the line is returned whole.
109
- """
110
- if width <= 0 or len(text) <= width:
111
- return [text]
112
- rows, rest = [], text
113
- while len(rest) > width:
114
- space = rest.rfind(" ", 1, width + 1)
115
- cut = space if space > 0 else width
116
- rows.append(rest[:cut])
117
- rest = rest[cut:].lstrip(" ") if space > 0 else rest[cut:]
118
- if not rest:
119
- break
120
- if rest:
121
- rows.append(rest)
122
- return rows
123
-
124
-
125
- def build_replacement_block(path: str, old: str, new: str, *,
126
- max_rows: int = MAX_ROWS) -> str:
127
- """The degraded form for an `edit` whose file could not be read (X6).
128
-
129
- No line numbers and no surrounding context, because both need the
130
- file. The replaced and replacing text do not: they are the call's own
131
- arguments, and showing them is strictly better than showing the first
132
- 60 characters of each.
133
- """
134
- rows = [(DELETED, "", line) for line in old.splitlines()]
135
- rows += [(ADDED, "", line) for line in new.splitlines()]
136
- return _render(path, _capped(rows, max_rows))
137
-
138
-
139
- def parse(block: str) -> Tuple[str, List[Row]]:
140
- """A block back into (path, rows). The renderer's half of the format.
141
-
142
- Tolerant by construction: a line this cannot make sense of comes back
143
- as context with an empty gutter. The block is produced two lines above
144
- in the same module, so a malformed one is a bug -- but it arrives here
145
- from `Transcript._entries`, which is replayed after a `/theme` and
146
- copied out by `/copy`, and neither of those is worth an exception.
147
- """
148
- lines = block.split("\n")
149
- path = lines[0] if lines else ""
150
- rows: List[Row] = []
151
- for line in lines[1:]:
152
- if not line:
153
- continue
154
- if line.startswith(_ELIDE_MARK):
155
- rows.append((ELIDED, "", line[len(_ELIDE_MARK):].strip()))
156
- continue
157
- kind = _KINDS.get(line[:1])
158
- if kind is None:
159
- rows.append((CONTEXT, "", line))
160
- continue
161
- gutter, sep, text = line[1:].partition(GUTTER_SEP)
162
- if not sep:
163
- rows.append((CONTEXT, "", line))
164
- continue
165
- rows.append((kind, gutter.strip(), text))
166
- return path, rows
167
-
168
-
169
- # ---------------------------------------------------------------------------
170
- # ---- internals ------------------------------------------------------------
171
- # ---------------------------------------------------------------------------
172
-
173
- def _rows(pre_lines: List[str], post_lines: List[str], context: int) -> List[Row]:
174
- """Changed lines with `context` unchanged lines either side.
175
-
176
- `SequenceMatcher` rather than `unified_diff`, because what is wanted
177
- here is the opcodes: a unified diff would have to be re-parsed to
178
- recover the line numbers this puts in the gutter, and re-parsing a
179
- format one line after emitting it is the second definition this module
180
- exists to avoid.
181
- """
182
- rows: List[Row] = []
183
- opcodes = difflib.SequenceMatcher(None, pre_lines, post_lines).get_opcodes()
184
- if all(tag == "equal" for tag, *_rest in opcodes):
185
- return rows
186
-
187
- for index, (tag, i1, i2, j1, j2) in enumerate(opcodes):
188
- if tag != "equal":
189
- for offset in range(i2 - i1):
190
- rows.append(
191
- (DELETED, str(i1 + offset + 1), pre_lines[i1 + offset]))
192
- for offset in range(j2 - j1):
193
- rows.append(
194
- (ADDED, str(j1 + offset + 1), post_lines[j1 + offset]))
195
- continue
196
- # Opcodes alternate, so an equal run shows context at its head when
197
- # a change precedes it and at its tail when one follows.
198
- head = context if index and opcodes[index - 1][0] != "equal" else 0
199
- tail = (context if index + 1 < len(opcodes)
200
- and opcodes[index + 1][0] != "equal" else 0)
201
- rows.extend(_equal_rows(post_lines, i2 - i1, j1, j2, head, tail))
202
- return rows
203
-
204
-
205
- def _equal_rows(post_lines, length, j1, j2, head, tail) -> List[Row]:
206
- """One unchanged run, trimmed to `head` lines at its start and `tail`
207
- at its end.
208
-
209
- Numbered from the NEW side, which is what the reader is looking at
210
- after the call: an unchanged line's two numbers diverge once anything
211
- above it has been added or removed, and the file on disk has the new
212
- one.
213
-
214
- The count of what was skipped is emitted only BETWEEN two hunks --
215
- where it says something the gutter does not, namely how far apart two
216
- changes are. Before the first hunk and after the last there is no
217
- second change to measure against, and the line numbers already say
218
- where in the file the reader is, so a leading "316 unchanged lines"
219
- would be furniture reporting the obvious.
220
- """
221
- if head + tail >= length:
222
- return [(CONTEXT, str(j1 + n + 1), post_lines[j1 + n])
223
- for n in range(length)]
224
- rows = [(CONTEXT, str(j1 + n + 1), post_lines[j1 + n]) for n in range(head)]
225
- hidden = length - head - tail
226
- if hidden > 0 and head and tail:
227
- rows.append((ELIDED, "",
228
- f"{hidden} unchanged line{'s' if hidden > 1 else ''}"))
229
- rows += [(CONTEXT, str(j2 - tail + n + 1), post_lines[j2 - tail + n])
230
- for n in range(tail)]
231
- return rows
232
-
233
-
234
- def _capped(rows: List[Row], max_rows: int) -> List[Row]:
235
- """At most `max_rows`, with the remainder counted rather than dropped
236
- silently -- M14's no-silent-caps rule, applied to a rendering."""
237
- if max_rows <= 0 or len(rows) <= max_rows:
238
- return rows
239
- kept = rows[:max_rows]
240
- hidden = len(rows) - max_rows
241
- kept.append((ELIDED, "",
242
- f"+{hidden} more line{'s' if hidden > 1 else ''}"))
243
- return kept
244
-
245
-
246
- def _render(path: str, rows: List[Row]) -> str:
247
- # An EMPTY string when nothing changed, so a caller can treat the
248
- # block as falsy rather than inspecting it. `write` with identical
249
- # content is a real call and a real no-op, and a block carrying a
250
- # path and no rows would render as a header announcing nothing.
251
- if not rows:
252
- return ""
253
- width = max((len(gutter) for _kind, gutter, _text in rows), default=0)
254
- out = [path]
255
- for kind, gutter, text in rows:
256
- if kind == ELIDED:
257
- out.append(f"{_ELIDE_MARK} {text}")
258
- continue
259
- # A space between the sign and the number, matching what the
260
- # renderer draws, so the copied block and the drawn block
261
- # differ only in the indent the renderer owns. parse()
262
- # strips the gutter, so the space costs it nothing.
263
- out.append(
264
- f"{_MARKS[kind]} {gutter.rjust(width)}{GUTTER_SEP}{text}")
265
- 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)