The best way to control Claude Code, Codex and more from any computer or phone

main
ts 381 lines 13.8 KB
Raw
1 import type { Root } from "mdast";
2 import type { Transformer } from "unified";
3
4 import { GITHUB_ALERT_MARKER } from "./markdownGithubAlerts.ts";
5
6 interface MarkdownPoint {
7 readonly line: number;
8 readonly column: number;
9 readonly offset?: number | undefined;
10 }
11
12 interface MarkdownNode {
13 readonly type: string;
14 value?: string;
15 position?: { readonly start: MarkdownPoint; readonly end: MarkdownPoint } | undefined;
16 children?: MarkdownNode[];
17 data?: Record<string, unknown> | undefined;
18 }
19
20 type Container =
21 | { readonly kind: "quote" }
22 | { readonly kind: "item"; readonly node: MarkdownNode; indent?: number | null }
23 // Recovered list content starts past the item's indentation, so its lines measure from there.
24 | { readonly kind: "indent"; readonly indent: number };
25
26 interface Cursor {
27 offset: number;
28 column: number;
29 /** The character at `offset` is a tab whose first columns are already taken. */
30 insideTab: boolean;
31 }
32
33 interface Source {
34 readonly text: string;
35 readonly lineStarts: readonly number[];
36 }
37
38 const LINE_ENDING = /\r\n|\r|\n/g;
39 // Whitespace at a line start, or past a quote marker and its one optional space.
40 const MAY_KEEP_WHITESPACE = /(?:^|[\r\n])[ \t]|>(?:\t|[ \t]{2})/;
41 const LIST_MARKER = /[-*+]|\d{1,9}[.)]/y;
42 const INLINE_CONTAINERS = new Set(["emphasis", "strong", "delete", "link", "linkReference"]);
43 const nextTabStop = (column: number) => (Math.floor(column / 4) + 1) * 4;
44 const isBlank = (character: string | undefined) => character === " " || character === "\t";
45
46 function columnAt(source: Source, line: number, offset: number): number {
47 let column = 0;
48 for (let index = source.lineStarts[line - 1]!; index < offset; index++) {
49 column = source.text[index] === "\t" ? nextTabStop(column) : column + 1;
50 }
51 return column;
52 }
53
54 /** Moves `width` columns through spaces and tabs, splitting a tab where it must. */
55 function skipColumns(source: Source, cursor: Cursor, width: number): boolean {
56 let left = width;
57 while (left > 0) {
58 const character = source.text[cursor.offset];
59 if (!isBlank(character)) return false;
60 const step = character === " " ? 1 : nextTabStop(cursor.column) - cursor.column;
61 if (step > left) {
62 cursor.column += left;
63 cursor.insideTab = true;
64 return true;
65 }
66 cursor.offset += 1;
67 cursor.column += step;
68 cursor.insideTab = false;
69 left -= step;
70 }
71 return true;
72 }
73
74 /**
75 * Where the item's content starts on its own first line, and its column, measured from the marker
76 * as CommonMark does. A task's checkbox is content, whatever GFM makes the paragraph's position.
77 */
78 function itemContent(source: Source, item: MarkdownNode): Cursor | undefined {
79 const start = item.position?.start;
80 if (start?.offset === undefined) return undefined;
81 LIST_MARKER.lastIndex = start.offset;
82 const marker = LIST_MARKER.exec(source.text)?.[0];
83 if (!marker) return undefined;
84 const end = start.offset + marker.length;
85 const cursor: Cursor = {
86 offset: end,
87 column: columnAt(source, start.line, end),
88 insideTab: false,
89 };
90 let offset = end;
91 let column = cursor.column;
92 while (isBlank(source.text[offset])) {
93 column = source.text[offset] === "\t" ? nextTabStop(column) : column + 1;
94 offset += 1;
95 }
96 const blankLine = offset >= source.text.length || /[\r\n]/.test(source.text[offset]!);
97 if (!blankLine && column - cursor.column <= 4) return { offset, column, insideTab: false };
98 // A blank first line, or code after five or more columns, starts one column past the marker.
99 if (blankLine) return { ...cursor, column: cursor.column + 1 };
100 skipColumns(source, cursor, 1);
101 return cursor;
102 }
103
104 /** The end of the container markers and indentation on `line`, or nothing for a lazy line. */
105 function containerEnd(
106 source: Source,
107 line: number,
108 chain: readonly Container[],
109 depth = chain.length,
110 ): Cursor | undefined {
111 const cursor: Cursor = { offset: source.lineStarts[line - 1]!, column: 0, insideTab: false };
112 for (let index = 0; index < depth; index++) {
113 const container = chain[index]!;
114 if (container.kind === "quote") {
115 // Up to three columns of indentation, the marker, then one optional space.
116 const indentation = { ...cursor };
117 while (isBlank(source.text[cursor.offset]) && skipColumns(source, cursor, 1)) {
118 if (cursor.column - indentation.column > 3) return undefined;
119 }
120 if (cursor.insideTab || source.text[cursor.offset] !== ">") return undefined;
121 cursor.offset += 1;
122 cursor.column += 1;
123 if (isBlank(source.text[cursor.offset])) skipColumns(source, cursor, 1);
124 continue;
125 }
126 if (container.kind === "item" && container.node.position?.start.line === line) {
127 const content = itemContent(source, container.node);
128 if (!content) return undefined;
129 Object.assign(cursor, content);
130 continue;
131 }
132 const indent =
133 container.kind === "indent" ? container.indent : itemIndent(source, chain, index);
134 if (indent === undefined || !skipColumns(source, cursor, indent)) return undefined;
135 }
136 return cursor;
137 }
138
139 /** The columns an item's continuation lines need past its parent's own markers. */
140 function itemIndent(
141 source: Source,
142 chain: readonly Container[],
143 index: number,
144 ): number | undefined {
145 const item = chain[index];
146 if (item?.kind !== "item") return undefined;
147 if (item.indent === undefined) {
148 const line = item.node.position?.start.line;
149 const parent = line === undefined ? undefined : containerEnd(source, line, chain, index);
150 const content = itemContent(source, item.node);
151 item.indent = parent && content ? content.column - parent.column : null;
152 }
153 return item.indent ?? undefined;
154 }
155
156 /** The spaces and tabs typed on `line` that CommonMark drops, past what is structure. */
157 function typedWhitespace(
158 source: Source,
159 line: number,
160 paragraph: MarkdownNode,
161 chain: readonly Container[],
162 ): string {
163 const cursor = containerEnd(source, line, chain);
164 if (!cursor) return "";
165 const start = paragraph.position!.start;
166 let end = cursor.offset;
167 if (line === start.line) end = start.offset!;
168 else while (isBlank(source.text[end])) end++;
169 const typed = source.text.slice(cursor.offset, end);
170 if (end <= cursor.offset || !/^[ \t]+$/.test(typed)) return "";
171 // A tab split by the container keeps the columns left of it, as spaces.
172 return cursor.insideTab
173 ? " ".repeat(nextTabStop(cursor.column) - cursor.column) + typed.slice(1)
174 : typed;
175 }
176
177 function whitespaceNode(value: string): MarkdownNode {
178 return {
179 type: "text",
180 value,
181 // Converting to HTML trims a whitespace-only text, and the first text after a line break;
182 // the empty text takes that trim.
183 data: {
184 hName: "span",
185 hProperties: { dataLeadingWhitespace: "" },
186 hChildren: [
187 { type: "text", value: "" },
188 { type: "text", value },
189 ],
190 },
191 };
192 }
193
194 /** Whether `node` starts with a space, tab or line ending, which a line start drops or hides. */
195 function startsBlank(node: MarkdownNode): boolean {
196 if (typeof node.value === "string") return /^[ \t\r\n]/.test(node.value);
197 const first = node.children?.[0];
198 return first !== undefined && startsBlank(first);
199 }
200
201 // Split or trimmed texts drop their position: nothing later reads a text node's.
202 function withValue({ position: _position, ...text }: MarkdownNode, value: string): MarkdownNode {
203 return { ...text, value };
204 }
205
206 /** `node` with the start trim that converting to HTML gives whatever follows a line break. */
207 function trimmedAfterBreak(node: MarkdownNode): MarkdownNode {
208 const value = node.value ?? "";
209 if (node.type === "text" && /^[ \t]/.test(value)) {
210 return withValue(node, value.replace(/^[ \t]+/, ""));
211 }
212 // Code turns its line endings into spaces first.
213 if (node.type === "inlineCode" && /^[ \t\r\n]/.test(value)) {
214 return { ...node, value: value.replace(/^(?:[ \t]|\r?\n|\r)+/, "") };
215 }
216 const head = node.children?.[0];
217 if (INLINE_CONTAINERS.has(node.type) && node.type !== "linkReference" && head?.type === "text") {
218 return { ...node, children: [trimmedAfterBreak(head), ...node.children!.slice(1)] };
219 }
220 return node;
221 }
222
223 /**
224 * Converting to HTML trims the start of the node after a line break, and the span now takes that
225 * place, so the node after the span gets the same trim. A line whose content still starts with
226 * whitespace, which the browser hides at a line start, keeps no span, so it shows as without one.
227 */
228 function settle(children: MarkdownNode[], at: number, afterBreak: boolean): void {
229 if (afterBreak && children[at + 1]) children[at + 1] = trimmedAfterBreak(children[at + 1]!);
230 let index = at + 1;
231 while (children[index]?.type === "text" && children[index]!.value === "") index++;
232 const content = children[index];
233 if (!content || content.type === "break" || startsBlank(content)) children.splice(at, 1);
234 }
235
236 function restoreParagraph(
237 source: Source,
238 paragraph: MarkdownNode,
239 chain: readonly Container[],
240 skipFirstLine: boolean,
241 ): void {
242 const start = paragraph.position?.start;
243 if (start?.offset === undefined || !paragraph.children) return;
244 const typed = (at: number) => typedWhitespace(source, at, paragraph, chain);
245 const inserted = new Set<MarkdownNode>();
246 const indentation = (value: string) => {
247 const node = whitespaceNode(value);
248 inserted.add(node);
249 return node;
250 };
251 // Nodes a plugin made without a position follow on from their siblings.
252 let line = start.line;
253
254 const split = (text: MarkdownNode): MarkdownNode[] => {
255 const value = text.value ?? "";
256 const endings = [...value.matchAll(LINE_ENDING)];
257 // A character reference such as `&#10;` adds a line ending the source does not have.
258 if (
259 endings.length === 0 ||
260 (text.position && text.position.end.line - text.position.start.line !== endings.length)
261 ) {
262 return [text];
263 }
264 const parts: MarkdownNode[] = [];
265 let cut = 0;
266 for (const ending of endings) {
267 line += 1;
268 const whitespace = typed(line);
269 if (!whitespace) continue;
270 const at = ending.index + ending[0].length;
271 parts.push(withValue(text, value.slice(cut, at)), indentation(whitespace));
272 cut = at;
273 }
274 if (parts.length === 0) return [text];
275 if (cut < value.length) parts.push(withValue(text, value.slice(cut)));
276 return parts;
277 };
278
279 const walk = (parent: MarkdownNode) => {
280 const children: MarkdownNode[] = [];
281 for (const child of parent.children ?? []) {
282 line = child.position?.start.line ?? line;
283 if (child.type === "text") {
284 children.push(...split(child));
285 } else {
286 children.push(child);
287 if (child.type === "break") {
288 line = child.position?.end.line ?? line + 1;
289 const whitespace = typed(line);
290 if (whitespace) children.push(indentation(whitespace));
291 } else if (INLINE_CONTAINERS.has(child.type)) {
292 walk(child);
293 }
294 }
295 line = child.position?.end.line ?? line;
296 }
297 // From the end, so settling one span leaves the earlier ones' places as they are.
298 for (let index = children.length - 1; index >= 0; index--) {
299 if (inserted.has(children[index]!)) settle(children, index, true);
300 }
301 parent.children = children;
302 };
303
304 const first = skipFirstLine ? "" : typed(start.line);
305 walk(paragraph);
306 if (first) {
307 paragraph.children.unshift(indentation(first));
308 settle(paragraph.children, 0, false);
309 }
310 }
311
312 // The alert plugin reads the marker from the first text, and drops the marker's line.
313 function startsWithAlertMarker(paragraph: MarkdownNode): boolean {
314 const first = paragraph.children?.[0];
315 return first?.type === "text" && GITHUB_ALERT_MARKER.test(first.value ?? "");
316 }
317
318 function visit(
319 source: Source,
320 node: MarkdownNode,
321 chain: readonly Container[],
322 firstInQuote: boolean,
323 ): void {
324 if (node.type === "paragraph") {
325 restoreParagraph(source, node, chain, firstInQuote && startsWithAlertMarker(node));
326 return;
327 }
328 // Other containers, such as footnote definitions, keep CommonMark's reading.
329 const inner =
330 node.type === "root" || node.type === "list"
331 ? chain
332 : node.type === "blockquote"
333 ? [...chain, { kind: "quote" } as const]
334 : node.type === "listItem"
335 ? [...chain, { kind: "item", node } as const]
336 : undefined;
337 if (!inner) return;
338 node.children?.forEach((child, index) =>
339 visit(source, child, inner, node.type === "blockquote" && index === 0),
340 );
341 }
342
343 /**
344 * CommonMark drops the spaces and tabs at the start of each line of a paragraph. This puts back
345 * what was typed past the structure CommonMark reads, such as a list item's indentation or a
346 * quote's marker, in spans the stylesheet keeps whitespace in. `source` is the text the node's
347 * offsets point into; `indent` is how far its lines are already indented.
348 */
349 export function keepLeadingWhitespace(
350 node: { readonly type: string; readonly children?: readonly object[] | undefined },
351 source: string,
352 indent = 0,
353 ): void {
354 if (!MAY_KEEP_WHITESPACE.test(source)) return;
355 const lineStarts = [0];
356 for (const ending of source.matchAll(LINE_ENDING))
357 lineStarts.push(ending.index + ending[0].length);
358 const chain: Container[] = indent > 0 ? [{ kind: "indent", indent }] : [];
359 visit({ text: source, lineStarts }, node as MarkdownNode, chain, false);
360 }
361
362 const enabledProcessors = new WeakSet<object>();
363
364 /**
365 * Opts a processor in. User messages use it so the sent bubble shows each line as it was typed
366 * and the agent received it; agent replies and files keep CommonMark's reading.
367 */
368 export function remarkEnableLeadingWhitespace(this: object): undefined {
369 enabledProcessors.add(this);
370 }
371
372 export function keepsLeadingWhitespace(processor: object): boolean {
373 return enabledProcessors.has(processor);
374 }
375
376 /** Sits before plugins that split text without positions, and before list recovery. */
377 export function remarkKeepLeadingWhitespace(this: object): Transformer<Root> {
378 return (tree, file) => {
379 if (enabledProcessors.has(this)) keepLeadingWhitespace(tree, String(file));
380 };
381 }