@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 03:37 UTC

main
ts 510 lines 16.2 KB
Raw
1 /**
2 * Source-mapped JSDoc prose, shared by the API reference generator and the
3 * website's dev-time copy editor.
4 *
5 * The generator renders a resource's JSDoc as a markdown page. With copy
6 * markers on:
7 *
8 * - each prose region (the summary, a section's description, an example's
9 * body) is wrapped in a `<div data-copy="jsdoc:<file>@<comment>#r<n>"
10 * data-copy-format="markdown">` the copy editor edits as markdown source;
11 * - each remaining one-line block (section and example titles) ends with a
12 * `<!--copy:jsdoc:<file>@<comment>#<n>-->` marker for inline text edits.
13 *
14 * Saving re-derives the same regions and blocks from the source file to find
15 * what to rewrite, so both sides MUST segment comments with
16 * {@link docRegions} and {@link docBlocks}.
17 */
18
19 export interface DocLine {
20 /** The line with its ` * ` prefix removed (what the generator parses). */
21 text: string;
22 /** Source offset where the raw line (including its ` * ` prefix) starts. */
23 lineStart: number;
24 /** Source offset where `text` starts. */
25 start: number;
26 /** Source offset where `text` ends. */
27 end: number;
28 }
29
30 /**
31 * Splits the `/** ... *\/` comment at `commentStart` into cleaned lines with
32 * source offsets. Cleaning matches the generator's historical behavior.
33 */
34 export function docCommentLines(fileText: string, commentStart: number): DocLine[] {
35 if (!fileText.startsWith("/*", commentStart)) {
36 throw new Error(`No doc comment at offset ${commentStart}`);
37 }
38 const close = fileText.indexOf("*/", commentStart + 2);
39 if (close === -1) throw new Error(`Unterminated doc comment at ${commentStart}`);
40 const raw = fileText.slice(commentStart, close + 2);
41 const open = /^\/\*\*?/.exec(raw)![0].length;
42 const body = raw.slice(open, raw.length - 2);
43 const lines: DocLine[] = [];
44 let offset = commentStart + open;
45 for (const line of body.split("\n")) {
46 const prefix = /^\s*\*\s?/.exec(line)?.[0].length ?? 0;
47 lines.push({
48 text: line.slice(prefix),
49 lineStart: offset,
50 start: offset + prefix,
51 end: offset + line.length,
52 });
53 offset += line.length + 1;
54 }
55 return lines;
56 }
57
58 export type DocBlockKind =
59 | "paragraph"
60 | "listItem"
61 | "heading"
62 | "proseHeading"
63 | "sectionTitle"
64 | "exampleTitle";
65
66 export interface DocBlock {
67 kind: DocBlockKind;
68 firstLine: number;
69 lastLine: number;
70 /** Source range of the block's editable inline markdown. */
71 start: number;
72 end: number;
73 }
74
75 const FENCE = /^\s*```/;
76 const PROSE_HEADING = /^(\s*###\s+)(.+?)\s+<!-- api-prose -->\s*$/;
77 const SECTION = /^(\s*###\s+)(.+?)\s*$/;
78 const EXAMPLE = /^(\s*\*\*Example:\*\*\s*)(.*?)\s*$/;
79 const TAG = /^\s*@(\w+)/;
80 const LIST_ITEM = /^(\s*(?:[-*+]|\d+[.)])\s+)/;
81 const HEADING = /^(\s*#{1,6}\s+)/;
82 /** Lines that aren't inline prose: tables, HTML, directives, quotes, rules. */
83 const NON_PROSE = /^\s*(?:\||<|:::|>|---+\s*$|\*\*\*+\s*$)/;
84
85 /**
86 * Finds the rendered prose blocks in a comment's lines, mirroring how the
87 * generator's `parseJSDoc` routes each line (summary, section description,
88 * example body, tag) so only lines that reach the page become blocks.
89 */
90 export function docBlocks(lines: DocLine[]): DocBlock[] {
91 const blocks: DocBlock[] = [];
92 let sawTag = false;
93 let inExample = false;
94 let inSectionDesc = false;
95 let insideFence = false;
96 let open: DocBlock | undefined;
97
98 const close = () => {
99 if (open) blocks.push(open);
100 open = undefined;
101 };
102 const single = (kind: DocBlockKind, i: number, from: number, to: number) => {
103 close();
104 const line = lines[i];
105 if (to > from) {
106 blocks.push({
107 kind,
108 firstLine: i,
109 lastLine: i,
110 start: line.start + from,
111 end: line.start + to,
112 });
113 }
114 };
115
116 lines.forEach((line, i) => {
117 const text = line.text;
118 if (FENCE.test(text)) {
119 insideFence = !insideFence;
120 close();
121 return;
122 }
123 if (insideFence) return;
124
125 const prose = PROSE_HEADING.exec(text);
126 if (prose) {
127 if (!sawTag) single("proseHeading", i, prose[1].length, prose[1].length + prose[2].length);
128 else close();
129 return;
130 }
131 const section = SECTION.exec(text);
132 if (section) {
133 sawTag = true;
134 inExample = false;
135 inSectionDesc = true;
136 single("sectionTitle", i, section[1].length, section[1].length + section[2].length);
137 return;
138 }
139 const example = EXAMPLE.exec(text);
140 if (example) {
141 sawTag = true;
142 inSectionDesc = false;
143 inExample = true;
144 single("exampleTitle", i, example[1].length, example[1].length + example[2].length);
145 return;
146 }
147 const tag = TAG.exec(text);
148 if (tag) {
149 sawTag = true;
150 if (tag[1] === "section") {
151 inExample = false;
152 inSectionDesc = true;
153 } else if (tag[1] === "example") {
154 inSectionDesc = false;
155 inExample = true;
156 }
157 close();
158 return;
159 }
160
161 const rendered = !sawTag || (!inExample && inSectionDesc);
162 if (!rendered || text.trim() === "" || NON_PROSE.test(text)) {
163 close();
164 return;
165 }
166
167 const trimmedEnd = text.trimEnd().length;
168 const heading = HEADING.exec(text);
169 if (heading) {
170 single("heading", i, heading[1].length, trimmedEnd);
171 return;
172 }
173 const item = LIST_ITEM.exec(text);
174 if (item) {
175 close();
176 open = {
177 kind: "listItem",
178 firstLine: i,
179 lastLine: i,
180 start: line.start + item[1].length,
181 end: line.start + trimmedEnd,
182 };
183 return;
184 }
185 if (open) {
186 open.lastLine = i;
187 open.end = line.start + trimmedEnd;
188 return;
189 }
190 const indent = text.length - text.trimStart().length;
191 open = {
192 kind: "paragraph",
193 firstLine: i,
194 lastLine: i,
195 start: line.start + indent,
196 end: line.start + trimmedEnd,
197 };
198 });
199 close();
200 return blocks;
201 }
202
203 // ── prose regions ─────────────────────────────────────────────────────────
204
205 export type DocRegionKind = "summary" | "sectionDescription" | "exampleBody";
206
207 export interface DocRegion {
208 kind: DocRegionKind;
209 /** First and last content line; `lastLine < firstLine` for an empty region. */
210 firstLine: number;
211 lastLine: number;
212 /** For an empty region, the line new content is inserted after. */
213 anchorLine: number;
214 /** False when the region shares a line with the comment's delimiters. */
215 editable: boolean;
216 }
217
218 type Route = "summary" | "sectionDescription" | "exampleBody" | "structural";
219
220 /**
221 * Finds the prose regions in a comment's lines: runs of lines the generator
222 * routes into one rendered chunk (summary, section description, example
223 * body), trimmed of blank edge lines. A section title with no description
224 * yields an empty region so a description can be added.
225 */
226 export function docRegions(lines: DocLine[]): DocRegion[] {
227 const routes: Route[] = [];
228 let sawTag = false;
229 let inExample = false;
230 let inSectionDesc = false;
231 let insideFence = false;
232 const sectionTitles = new Set<number>();
233
234 lines.forEach((line, i) => {
235 const text = line.text;
236 if (FENCE.test(text)) insideFence = !insideFence;
237 if (!insideFence && !FENCE.test(text)) {
238 if (PROSE_HEADING.test(text)) {
239 routes.push(sawTag ? "structural" : "summary");
240 return;
241 }
242 if (SECTION.test(text)) {
243 sawTag = true;
244 inExample = false;
245 inSectionDesc = true;
246 sectionTitles.add(i);
247 routes.push("structural");
248 return;
249 }
250 if (EXAMPLE.test(text)) {
251 sawTag = true;
252 inSectionDesc = false;
253 inExample = true;
254 routes.push("structural");
255 return;
256 }
257 const tag = TAG.exec(text);
258 if (tag) {
259 sawTag = true;
260 if (tag[1] === "section") {
261 inExample = false;
262 inSectionDesc = true;
263 } else if (tag[1] === "example") {
264 inSectionDesc = false;
265 inExample = true;
266 }
267 routes.push("structural");
268 return;
269 }
270 }
271 routes.push(
272 !sawTag
273 ? "summary"
274 : inExample
275 ? "exampleBody"
276 : inSectionDesc
277 ? "sectionDescription"
278 : "structural",
279 );
280 });
281
282 const regions: DocRegion[] = [];
283 const last = lines.length - 1;
284 let i = 0;
285 while (i < lines.length) {
286 const route = routes[i]!;
287 let j = i;
288 while (j + 1 < lines.length && routes[j + 1] === route) j++;
289 if (route !== "structural") {
290 let first = i;
291 let end = j;
292 while (first <= end && lines[first]!.text.trim() === "") first++;
293 while (end >= first && lines[end]!.text.trim() === "") end--;
294 if (first <= end) {
295 regions.push({
296 kind: route,
297 firstLine: first,
298 lastLine: end,
299 anchorLine: first - 1,
300 editable: first > 0 && end < last,
301 });
302 } else if (route === "sectionDescription" && sectionTitles.has(i - 1)) {
303 regions.push(emptyAfter(i - 1, last));
304 }
305 } else {
306 // A section title followed directly by an example, tag, or section.
307 for (let k = i; k <= j; k++) {
308 if (sectionTitles.has(k) && routes[k + 1] !== "sectionDescription") {
309 regions.push(emptyAfter(k, last));
310 }
311 }
312 }
313 i = j + 1;
314 }
315 return regions;
316 }
317
318 const emptyAfter = (anchorLine: number, last: number): DocRegion => ({
319 kind: "sectionDescription",
320 firstLine: anchorLine + 1,
321 lastLine: anchorLine,
322 anchorLine,
323 editable: anchorLine < last,
324 });
325
326 /**
327 * The copy-editable targets in a comment: prose regions (edited as markdown)
328 * and the inline blocks outside editable regions (titles, edited as text).
329 * Inline blocks are indexed among themselves so editing a region's markdown
330 * never shifts their ids.
331 */
332 export function docTargets(lines: DocLine[]) {
333 const regions = docRegions(lines);
334 const inRegion = (line: number) =>
335 regions.some((r) => r.editable && line >= r.firstLine && line <= r.lastLine);
336 const inline = docBlocks(lines).filter((b) => !inRegion(b.firstLine));
337 return { regions, inline };
338 }
339
340 /** The region's markdown, as shown for editing. */
341 export const regionSource = (lines: DocLine[], region: DocRegion) =>
342 lines
343 .slice(region.firstLine, region.lastLine + 1)
344 .map((l) => l.text)
345 .join("\n");
346
347 /**
348 * Returns `fileText` with `region` replaced by `markdown`, written as JSDoc
349 * lines in the comment's own indentation.
350 */
351 export function replaceRegion(
352 fileText: string,
353 lines: DocLine[],
354 region: DocRegion,
355 markdown: string,
356 ): string {
357 const reference =
358 lines[region.lastLine >= region.firstLine ? region.firstLine : region.anchorLine]!;
359 const prefix = fileText.slice(reference.lineStart, reference.start).replace(/\*\s*$/, "* ");
360 const bare = prefix.trimEnd();
361
362 let inCode = false;
363 let insideFence = false;
364 const body = markdown
365 .replace(/\r\n?/g, "\n")
366 .replace(/^\n+|\s+$/g, "")
367 .split("\n")
368 // Outside code, one blank line separates blocks as well as several.
369 .filter((line, i, all) => {
370 if (FENCE.test(line)) inCode = !inCode;
371 return inCode || line.trim() !== "" || all[i - 1]?.trim() !== "";
372 })
373 .map((line) => {
374 if (FENCE.test(line)) insideFence = !insideFence;
375 // Outside code, a leading `@` would start a JSDoc tag.
376 const safe = !insideFence && /^\s*@/.test(line) ? line.replace("@", "\\@") : line;
377 return safe.trim() === "" ? bare : `${prefix}${safe}`;
378 });
379 if (body.join("\n").includes("*/")) {
380 throw new Error("Markdown in a JSDoc comment can't contain */.");
381 }
382
383 const empty = body.length === 1 && body[0] === bare;
384 if (region.lastLine < region.firstLine) {
385 if (empty) return fileText;
386 const at = lines[region.anchorLine]!.end;
387 return `${fileText.slice(0, at)}\n${body.join("\n")}${fileText.slice(at)}`;
388 }
389 const from = lines[region.firstLine]!.lineStart;
390 if (empty) {
391 // Drop the region's lines entirely, including their line breaks.
392 const to = lines[region.lastLine + 1]!.lineStart;
393 return fileText.slice(0, from) + fileText.slice(to);
394 }
395 const to = lines[region.lastLine]!.end;
396 return fileText.slice(0, from) + body.join("\n") + fileText.slice(to);
397 }
398
399 // ── copy markers ──────────────────────────────────────────────────────────
400
401 export const JSDOC_COPY_SCHEME = "jsdoc";
402
403 /** Matches what follows `\n` on a JSDoc continuation line (` * `). */
404 export const JSDOC_LINE_PREFIX = "[ \\t]*\\*(?!/)[ \\t]?";
405
406 /** Style preset the website applies to previews of edited JSDoc markdown. */
407 export const JSDOC_COPY_STYLE = "docs";
408
409 export const jsdocCopyId = (
410 file: string,
411 commentStart: number,
412 target: `${number}` | `r${number}`,
413 ) => `${JSDOC_COPY_SCHEME}:${file}@${commentStart}#${target}`;
414
415 export const parseJsdocCopyId = (id: string) => {
416 const m = /^jsdoc:(.+)@(\d+)#(r?)(\d+)$/.exec(id);
417 if (!m) return undefined;
418 const base = { file: m[1]!, commentStart: Number(m[2]) };
419 return m[3] ? { ...base, region: Number(m[4]) } : { ...base, block: Number(m[4]) };
420 };
421
422 const REGION_CLOSE = "</div><!--/copy-->";
423 const COPY_MARKUP_RE = new RegExp(
424 `<!--copy:[^>]*?-->|^<div data-copy=[^\\n]*>$|^${REGION_CLOSE.replace(/[/]/g, "\\/")}$`,
425 "gm",
426 );
427
428 /** Removes copy markers and region wrappers from generated markdown. */
429 export const stripCopyMarkers = (text: string) => text.replace(COPY_MARKUP_RE, "");
430
431 /**
432 * Returns the comment's cleaned line texts with copy markup added: region
433 * wrappers around each editable prose region, and a trailing marker on each
434 * title block outside them.
435 */
436 export function markDocLines(
437 lines: DocLine[],
438 idFor: (target: `${number}` | `r${number}`) => string,
439 ): string[] {
440 const texts = lines.map((l) => l.text);
441 const { regions, inline } = docTargets(lines);
442
443 inline.forEach((block, index) => {
444 const marker = `<!--copy:${idFor(`${index}`)}-->`;
445 const text = texts[block.lastLine]!;
446 const prose = /\s+<!-- api-prose -->\s*$/.exec(text);
447 texts[block.lastLine] = prose
448 ? `${text.slice(0, prose.index).trimEnd()}${marker}${prose[0]}`
449 : `${text.trimEnd()}${marker}`;
450 });
451
452 const before = new Map<number, string[]>();
453 const after = new Map<number, string[]>();
454 const add = (map: Map<number, string[]>, line: number, add: string[]) =>
455 map.set(line, [...(map.get(line) ?? []), ...add]);
456 regions.forEach((region, index) => {
457 if (!region.editable) return;
458 const open = `<div data-copy="${idFor(`r${index}`)}" data-copy-format="markdown" data-copy-style="${JSDOC_COPY_STYLE}">`;
459 if (region.lastLine < region.firstLine) {
460 add(after, region.anchorLine, ["", open, REGION_CLOSE]);
461 } else {
462 add(before, region.firstLine, [open, ""]);
463 add(after, region.lastLine, ["", REGION_CLOSE]);
464 }
465 });
466 return texts.flatMap((text, i) => [...(before.get(i) ?? []), text, ...(after.get(i) ?? [])]);
467 }
468
469 // ── {@link} tags ──────────────────────────────────────────────────────────
470
471 export const LINK_TAG_RE = /\{@link\s+([^}]+)\}/g;
472
473 /** Split a `{@link ...}` tag's inner text into target + optional label. */
474 export function parseLinkTag(inner: string): {
475 target: string;
476 label?: string;
477 } {
478 const trimmed = inner.trim();
479 const pipe = trimmed.indexOf("|");
480 if (pipe !== -1) {
481 return {
482 target: trimmed.slice(0, pipe).trim(),
483 label: trimmed.slice(pipe + 1).trim() || undefined,
484 };
485 }
486 const space = trimmed.search(/\s/);
487 if (space !== -1) {
488 return {
489 target: trimmed.slice(0, space).trim(),
490 label: trimmed.slice(space + 1).trim() || undefined,
491 };
492 }
493 return { target: trimmed };
494 }
495
496 /**
497 * Reduce a typedoc-style `import("./Secrets.ts").Secrets` target to the bare
498 * symbol name — resolution (same-directory first) and display both want the
499 * name, not the module expression.
500 */
501 export function normalizeLinkTarget(target: string): string {
502 const match = target.match(/^import\((["'])[^"']+\1\)\.(.+)$/);
503 return match ? match[2] : target;
504 }
505
506 /** The text a `{@link}` tag renders as (its label, or the bare target). */
507 export function linkTagText(inner: string): string {
508 const { target, label } = parseLinkTag(inner.replace(/\s+/g, " "));
509 return label ?? normalizeLinkTarget(target);
510 }