@ngrok/mantle-server-syntax-highlighter 1.0.4 → 1.1.1

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.
package/dist/index.js CHANGED
@@ -1,5 +1,7 @@
1
+ import { createRequire } from "node:module";
1
2
  import { createHash } from "node:crypto";
2
- import { decorateHighlightedHtml, inferIndentation, isSupportedLanguage, normalizeIndentation, parseLanguage } from "@ngrok/mantle/highlight-utils";
3
+ import { computeFoldRanges, computeJsonFoldRanges, decorateHighlightedHtml, finalizeFoldRanges, inferIndentation, isSupportedLanguage, normalizeIndentation, parseLanguage } from "@ngrok/mantle/highlight-utils";
4
+ import { html, parse, parseFragment } from "parse5";
3
5
 
4
6
  //#region src/lru-cache.ts
5
7
  /** Creates an LRU cache that evicts the least-recently-used entry when `maxEntries` is exceeded. */
@@ -30,6 +32,852 @@ function createLruCache(maxEntries) {
30
32
  };
31
33
  }
32
34
 
35
+ //#endregion
36
+ //#region src/compute-css-fold-ranges.ts
37
+ /**
38
+ * Raw-source fold computer for CSS — single-pass, parser-quality without a
39
+ * parser dependency.
40
+ *
41
+ * Mirrors `computeJsonFoldRanges` but adds CSS-specific lexical features:
42
+ *
43
+ * - `/* … *​/` block comments are skipped wholesale.
44
+ * - `"…"` and `'…'` string literals (including `\\` and `\` escapes) are
45
+ * skipped so braces inside `content: "{ }"` don't open folds.
46
+ * - Backslash escapes outside of strings (CSS identifiers can use them) are
47
+ * transparent — we just consume the next character.
48
+ *
49
+ * lightningcss is the project's preferred CSS parser, but its public visitor
50
+ * API only surfaces *start* locations (`Location { line, column }`), not end
51
+ * locations, which is what `FoldableRange.endLine` requires. Until upstream
52
+ * exposes end spans we get the same correctness from a single-pass brace
53
+ * matcher with a tiny CSS lexer — and skip the ~5MB native dep.
54
+ *
55
+ * @see https://github.com/parcel-bundler/lightningcss/issues/512
56
+ */
57
+ /**
58
+ * Computes foldable ranges for a CSS source string. Each multi-line `{ … }`
59
+ * (style rule, at-rule body, nested rule, keyframe selector) emits one range
60
+ * with the opener and closer lines staying visible.
61
+ *
62
+ * Tolerant of malformed CSS — unmatched braces are dropped silently rather
63
+ * than throwing, so a partial snippet still gets every fold it can. This
64
+ * matches the behavior of `computeJsonFoldRanges` for JSON.
65
+ *
66
+ * @example
67
+ * computeCssFoldRanges({ code: ".a {\n color: red;\n}" });
68
+ * // => [{ id: "1", startLine: 1, endLine: 3 }]
69
+ */
70
+ function computeCssFoldRanges({ code }) {
71
+ const length = code.length;
72
+ if (length === 0) return [];
73
+ const stack = [];
74
+ const ranges = [];
75
+ let line = 1;
76
+ let index = 0;
77
+ while (index < length) {
78
+ const character = code.charCodeAt(index);
79
+ if (character === 10) {
80
+ line += 1;
81
+ index += 1;
82
+ continue;
83
+ }
84
+ if (character === 13) {
85
+ line += 1;
86
+ index += 1;
87
+ if (index < length && code.charCodeAt(index) === 10) index += 1;
88
+ continue;
89
+ }
90
+ if (character === 47 && index + 1 < length && code.charCodeAt(index + 1) === 42) {
91
+ index += 2;
92
+ while (index < length) {
93
+ const commentChar = code.charCodeAt(index);
94
+ if (commentChar === 10) {
95
+ line += 1;
96
+ index += 1;
97
+ continue;
98
+ }
99
+ if (commentChar === 13) {
100
+ line += 1;
101
+ index += 1;
102
+ if (index < length && code.charCodeAt(index) === 10) index += 1;
103
+ continue;
104
+ }
105
+ if (commentChar === 42 && index + 1 < length && code.charCodeAt(index + 1) === 47) {
106
+ index += 2;
107
+ break;
108
+ }
109
+ index += 1;
110
+ }
111
+ continue;
112
+ }
113
+ if (character === 34 || character === 39) {
114
+ const quote = character;
115
+ index += 1;
116
+ while (index < length) {
117
+ const stringChar = code.charCodeAt(index);
118
+ if (stringChar === 92) {
119
+ index += 1;
120
+ if (index >= length) break;
121
+ const escaped = code.charCodeAt(index);
122
+ if (escaped === 10) line += 1;
123
+ else if (escaped === 13) {
124
+ line += 1;
125
+ if (index + 1 < length && code.charCodeAt(index + 1) === 10) index += 1;
126
+ }
127
+ index += 1;
128
+ continue;
129
+ }
130
+ if (stringChar === quote) {
131
+ index += 1;
132
+ break;
133
+ }
134
+ if (stringChar === 10) break;
135
+ index += 1;
136
+ }
137
+ continue;
138
+ }
139
+ if (character === 123) {
140
+ stack.push(line);
141
+ index += 1;
142
+ continue;
143
+ }
144
+ if (character === 125) {
145
+ const startLine = stack.pop();
146
+ if (startLine != null && startLine !== line) ranges.push({
147
+ id: String(startLine),
148
+ startLine,
149
+ endLine: line
150
+ });
151
+ index += 1;
152
+ continue;
153
+ }
154
+ index += 1;
155
+ }
156
+ return finalizeFoldRanges(ranges);
157
+ }
158
+
159
+ //#endregion
160
+ //#region src/compute-html-fold-ranges.ts
161
+ /**
162
+ * Synthetic SVG fragment context shared across XML parses. Only the namespace
163
+ * matters for the foreign-content tokenizer mode; the rest of the fields
164
+ * satisfy parse5's tree-adapter shape.
165
+ */
166
+ const xmlFragmentContext = {
167
+ nodeName: "svg",
168
+ tagName: "svg",
169
+ namespaceURI: html.NS.SVG,
170
+ attrs: [],
171
+ childNodes: [],
172
+ parentNode: null
173
+ };
174
+ /**
175
+ * Returns true when a parse5 tree node has element-style `tagName` and child
176
+ * nodes — i.e. it's an `Element` we should consider folding. Comments,
177
+ * doctypes, text nodes, and the document root all fail this check.
178
+ */
179
+ function isElement(node) {
180
+ return "tagName" in node && typeof node.tagName === "string" && "childNodes" in node;
181
+ }
182
+ /**
183
+ * Traverses `root` depth-first and pushes a {@link FoldableRange} for every
184
+ * element whose source span covers more than one line.
185
+ *
186
+ * Multi-line *elements* fold from the opening tag's start line to the closing
187
+ * tag's end line (or to the element end when `endTag` info is unavailable —
188
+ * parse5 sometimes synthesizes elements without a real closer when handling
189
+ * malformed input).
190
+ *
191
+ * Multi-line *opening tags* (e.g. `<div\n class="x">`) fold from the start
192
+ * of the tag to its `>` so the attribute list collapses into the tag name.
193
+ * VS Code emits this as a separate "tag" fold marker; we mirror that.
194
+ */
195
+ function collectRanges(root, ranges) {
196
+ const stack = [root];
197
+ while (stack.length > 0) {
198
+ const node = stack.pop();
199
+ if (node == null) continue;
200
+ if (isElement(node)) pushRangesForElement(node, ranges);
201
+ pushChildNodes(node, stack);
202
+ if ("content" in node && typeof node.content === "object" && node.content != null) pushChildNodes(node.content, stack);
203
+ }
204
+ }
205
+ /** Pushes parse5 child nodes onto the DFS stack in source order. */
206
+ function pushChildNodes(parent, stack) {
207
+ if (typeof parent !== "object" || parent == null || !("childNodes" in parent)) return;
208
+ const childNodes = parent.childNodes;
209
+ if (!Array.isArray(childNodes)) return;
210
+ for (let index = childNodes.length - 1; index >= 0; index -= 1) {
211
+ const child = childNodes[index];
212
+ if (child != null) stack.push(child);
213
+ }
214
+ }
215
+ /**
216
+ * Emits up to two fold ranges for a single element: one for the element's
217
+ * full body and one for its multi-line opening tag.
218
+ */
219
+ function pushRangesForElement(element, ranges) {
220
+ const location = element.sourceCodeLocation;
221
+ if (location == null) return;
222
+ const startTag = location.startTag;
223
+ if (location.endTag == null) {
224
+ pushTagFoldIfMultiline(startTag, ranges);
225
+ return;
226
+ }
227
+ const startLine = location.startLine;
228
+ const endLine = location.endLine;
229
+ if (endLine > startLine) ranges.push({
230
+ id: String(startLine),
231
+ startLine,
232
+ endLine
233
+ });
234
+ pushTagFoldIfMultiline(startTag, ranges);
235
+ }
236
+ /**
237
+ * Pushes a fold range for an opening tag (`startTag`) when its `<` and `>`
238
+ * sit on different lines. Conservative: contributes nothing for single-line
239
+ * tags so we don't fight `pushRangesForElement` for the same opener.
240
+ */
241
+ function pushTagFoldIfMultiline(startTag, ranges) {
242
+ if (startTag == null) return;
243
+ if (startTag.endLine > startTag.startLine) ranges.push({
244
+ id: String(startTag.startLine),
245
+ startLine: startTag.startLine,
246
+ endLine: startTag.endLine
247
+ });
248
+ }
249
+ /**
250
+ * Computes foldable ranges for an HTML or XML source string.
251
+ *
252
+ * - HTML: uses `parse5.parse` so explicit `<html>`/`<head>`/`<body>` are
253
+ * honored as foldable openers. Implicit wrappers parse5 fabricates for
254
+ * fragment input have no `sourceCodeLocation` and are skipped.
255
+ * - XML: uses `parse5.parseFragment` rooted in an SVG fragment context so the
256
+ * tokenizer applies foreign-content (XML-like) rules — self-closing `<foo/>`
257
+ * is respected, void HTML elements aren't special-cased.
258
+ *
259
+ * @example
260
+ * computeHtmlFoldRanges({ code: "<div>\n <p>hi</p>\n</div>", language: "html" });
261
+ * // => [{ id: "1", startLine: 1, endLine: 3 }]
262
+ */
263
+ function computeHtmlFoldRanges({ code, language }) {
264
+ if (code.length === 0) return [];
265
+ const document = language === "xml" ? parseFragment(xmlFragmentContext, code, { sourceCodeLocationInfo: true }) : parse(code, { sourceCodeLocationInfo: true });
266
+ const ranges = [];
267
+ collectRanges(document, ranges);
268
+ return finalizeFoldRanges(ranges);
269
+ }
270
+
271
+ //#endregion
272
+ //#region src/line-offsets.ts
273
+ /**
274
+ * Helpers for converting parser byte offsets into 1-indexed line numbers.
275
+ *
276
+ * Every AST-based fold strategy in this package speaks line numbers (because
277
+ * `FoldableRange.startLine` / `endLine` are line-anchored), but parsers like
278
+ * `oxc-parser` and `postcss` report offsets / line+col tuples derived from
279
+ * byte positions. Building a single sorted `lineOffsets` array up front keeps
280
+ * the per-node lookup `O(log n)` instead of rescanning the source each call.
281
+ */
282
+ /**
283
+ * Returns an array where index `i` holds the byte offset of the start of
284
+ * the `i + 1`-th line of `source`. The first entry is always `0`.
285
+ *
286
+ * Treats `\n`, `\r\n`, and bare `\r` as line breaks so it agrees with how
287
+ * Shiki, oxc, parse5, and postcss split lines (they all match the JS
288
+ * runtime's `String.prototype.split(/\r\n|\r|\n/)` behavior in practice).
289
+ */
290
+ function buildLineOffsets(source) {
291
+ const offsets = [0];
292
+ const length = source.length;
293
+ for (let index = 0; index < length; index += 1) {
294
+ const character = source.charCodeAt(index);
295
+ if (character === 10) {
296
+ offsets.push(index + 1);
297
+ continue;
298
+ }
299
+ if (character === 13) {
300
+ const isCrLf = index + 1 < length && source.charCodeAt(index + 1) === 10;
301
+ offsets.push(isCrLf ? index + 2 : index + 1);
302
+ if (isCrLf) index += 1;
303
+ }
304
+ }
305
+ return offsets;
306
+ }
307
+ /**
308
+ * Returns the 1-indexed line number that contains `offset` in the source
309
+ * scanned by {@link buildLineOffsets}. Out-of-range offsets clamp to the
310
+ * first or last line.
311
+ */
312
+ function offsetToLine(lineOffsets, offset) {
313
+ if (lineOffsets.length === 0) return 1;
314
+ if (offset <= 0) return 1;
315
+ let low = 0;
316
+ let high = lineOffsets.length - 1;
317
+ while (low < high) {
318
+ const mid = low + high + 1 >>> 1;
319
+ if ((lineOffsets[mid] ?? 0) <= offset) low = mid;
320
+ else high = mid - 1;
321
+ }
322
+ return low + 1;
323
+ }
324
+
325
+ //#endregion
326
+ //#region src/compute-jsx-fold-ranges.ts
327
+ const requireOxc = createRequire(import.meta.url);
328
+ /** Creates a memoized parser loader that caches both success and load failure. */
329
+ function createOxcParserLoader(load) {
330
+ let cachedOxcParser;
331
+ let didFailToLoadOxcParser = false;
332
+ return () => {
333
+ if (cachedOxcParser != null) return cachedOxcParser;
334
+ if (didFailToLoadOxcParser) return;
335
+ let oxcParser;
336
+ try {
337
+ oxcParser = load();
338
+ } catch {
339
+ didFailToLoadOxcParser = true;
340
+ return;
341
+ }
342
+ cachedOxcParser = oxcParser;
343
+ return oxcParser;
344
+ };
345
+ }
346
+ /** Returns the lazily-resolved `oxc-parser` module, or undefined after a cached load failure. */
347
+ const loadOxcParser = createOxcParserLoader(() => requireOxc("oxc-parser"));
348
+ /**
349
+ * Maps a Mantle language to the oxc-parser `lang` option. JavaScript keeps
350
+ * JSX enabled so JSX-in-JS examples still fold, but TypeScript must stay in
351
+ * plain `ts` mode: TSX parses generic arrow functions (`<T>(x: T) => ...`) as
352
+ * JSX and drops the AST folds for otherwise-valid TypeScript snippets.
353
+ */
354
+ function oxcLangFor(language) {
355
+ switch (language) {
356
+ case "tsx": return "tsx";
357
+ case "typescript":
358
+ case "ts": return "ts";
359
+ case "jsx":
360
+ case "javascript":
361
+ case "js": return "jsx";
362
+ }
363
+ }
364
+ /** Type guard for an arbitrary value being an AST node. */
365
+ function isAstNode(value) {
366
+ return typeof value === "object" && value != null && "type" in value && typeof value.type === "string" && "start" in value && typeof value.start === "number" && "end" in value && typeof value.end === "number";
367
+ }
368
+ /**
369
+ * AST node types whose `start`/`end` positions delimit a foldable region
370
+ * when they span multiple lines.
371
+ *
372
+ * Curated to match VS Code's TypeScript folder:
373
+ * - Block-like statement bodies — covers function/method bodies, class bodies,
374
+ * `if`/`for`/`while` blocks, modules, namespaces.
375
+ * - Object & array literals — covers JSON-shaped data and JSX style props.
376
+ * - JSX elements & fragments — open/close tags fold like HTML.
377
+ * - Template literals — fold multi-line backtick strings (including tagged).
378
+ * - Switch statements — VS Code folds the whole `switch (…) { … }`, not each case.
379
+ */
380
+ const FOLDABLE_NODE_TYPES = new Set([
381
+ "BlockStatement",
382
+ "ClassBody",
383
+ "ObjectExpression",
384
+ "ObjectPattern",
385
+ "ArrayExpression",
386
+ "ArrayPattern",
387
+ "JSXElement",
388
+ "JSXFragment",
389
+ "TemplateLiteral",
390
+ "SwitchStatement",
391
+ "TSInterfaceBody",
392
+ "TSTypeLiteral",
393
+ "TSEnumBody",
394
+ "TSEnumDeclaration",
395
+ "TSModuleBlock",
396
+ "TSMappedType"
397
+ ]);
398
+ /** Returns the `openingElement` of a `JSXElement` if present (the `<Foo …>` span). */
399
+ function jsxOpeningElement(node) {
400
+ if (node.type !== "JSXElement") return;
401
+ const opening = node.openingElement;
402
+ return isAstNode(opening) ? opening : void 0;
403
+ }
404
+ /** Returns true when a `JSXOpeningElement` is self-closing (`<Foo/>`). */
405
+ function isSelfClosingOpening(opening) {
406
+ return opening.selfClosing === true;
407
+ }
408
+ /**
409
+ * Recursively walks every AST node reachable from `root`, calling `visit`
410
+ * with each one. Mirrors the helper used in the Vite plugin but stays local
411
+ * so this module has no extra cross-package dependency.
412
+ */
413
+ function walk(root, visit) {
414
+ if (Array.isArray(root)) {
415
+ for (const item of root) walk(item, visit);
416
+ return;
417
+ }
418
+ if (!isAstNode(root)) return;
419
+ visit(root);
420
+ for (const value of Object.values(root)) {
421
+ if (Array.isArray(value)) {
422
+ for (const item of value) walk(item, visit);
423
+ continue;
424
+ }
425
+ if (isAstNode(value)) walk(value, visit);
426
+ }
427
+ }
428
+ /**
429
+ * Filename passed to `oxc-parser` purely for diagnostic strings; the actual
430
+ * grammar comes from the `lang` option on the parser options object.
431
+ */
432
+ const SYNTHETIC_FILENAME = "__mantle_fold__";
433
+ /**
434
+ * Pushes a {@link FoldableRange} for the source span `[startOffset, endOffset]`
435
+ * (inclusive) when it crosses a line boundary. Single-line spans contribute
436
+ * nothing — there's nothing to fold.
437
+ */
438
+ function pushRange(ranges, lineOffsets, startOffset, endOffset) {
439
+ const startLine = offsetToLine(lineOffsets, startOffset);
440
+ const endLine = offsetToLine(lineOffsets, endOffset);
441
+ if (endLine > startLine) ranges.push({
442
+ id: String(startLine),
443
+ startLine,
444
+ endLine
445
+ });
446
+ }
447
+ /**
448
+ * Computes foldable ranges for a JS/TS/JSX/TSX source string by parsing it
449
+ * with `oxc-parser` and walking the AST. Errors are tolerated — a partial AST
450
+ * still produces useful folds.
451
+ *
452
+ * @example
453
+ * computeJsxFoldRanges({ code: "<Foo>\n <Bar/>\n</Foo>", language: "tsx" });
454
+ * // => [{ id: "1", startLine: 1, endLine: 3 }]
455
+ */
456
+ function computeJsxFoldRanges({ code, language }) {
457
+ if (code.length === 0) return [];
458
+ const options = {
459
+ sourceType: "unambiguous",
460
+ lang: oxcLangFor(language)
461
+ };
462
+ const oxcParser = loadOxcParser();
463
+ if (oxcParser == null) return [];
464
+ const { parseSync } = oxcParser;
465
+ const parsed = parseSync(SYNTHETIC_FILENAME, code, options);
466
+ const lineOffsets = buildLineOffsets(code);
467
+ const ranges = [];
468
+ walk(parsed.program, (node) => {
469
+ if (node.type === "JSXElement") {
470
+ const opening = jsxOpeningElement(node);
471
+ if (opening != null && isSelfClosingOpening(opening)) {
472
+ if (opening != null) pushRange(ranges, lineOffsets, opening.start, opening.end - 1);
473
+ return;
474
+ }
475
+ pushRange(ranges, lineOffsets, node.start, node.end - 1);
476
+ if (opening != null) pushRange(ranges, lineOffsets, opening.start, opening.end - 1);
477
+ return;
478
+ }
479
+ if (!FOLDABLE_NODE_TYPES.has(node.type)) return;
480
+ pushRange(ranges, lineOffsets, node.start, node.end - 1);
481
+ });
482
+ return finalizeFoldRanges(ranges);
483
+ }
484
+
485
+ //#endregion
486
+ //#region src/compute-keyword-fold-ranges.ts
487
+ const RUBY_START_KEYWORDS = [
488
+ "def",
489
+ "class",
490
+ "module",
491
+ "begin",
492
+ "if",
493
+ "unless",
494
+ "while",
495
+ "until",
496
+ "for",
497
+ "case"
498
+ ];
499
+ const BASH_START_KEYWORDS = [
500
+ "if",
501
+ "while",
502
+ "for",
503
+ "case",
504
+ "until",
505
+ "select"
506
+ ];
507
+ const BASH_END_KEYWORDS = [
508
+ "fi",
509
+ "esac",
510
+ "done"
511
+ ];
512
+ /**
513
+ * Ruby keyword folds modeled after VS Code's grammar. Covers:
514
+ *
515
+ * - Definition keywords at the start of a line: `def`, `class`, `module`, `begin`.
516
+ * - Control-flow openers at the start of a line: `if`, `unless`, `while`,
517
+ * `until`, `for`, `case` — Ruby's flagship multi-line constructs.
518
+ * - Trailing `do` / `do |args|` for blocks attached to a method call.
519
+ *
520
+ * `end` always closes; mid-block keywords (`else`, `elsif`, `when`, `rescue`,
521
+ * `ensure`) deliberately don't, so a single `if … else … end` becomes one
522
+ * fold, not three.
523
+ */
524
+ const RUBY_PATTERN = {
525
+ startsFold: rubyStartsFold,
526
+ endsFold: (visible) => startsWithAnyWordAfterWhitespace(visible, ["end"])
527
+ };
528
+ /**
529
+ * Bash / Shell keyword folds modeled after VS Code's grammar.
530
+ *
531
+ * - Opener keywords at the start of a line — `if`, `while`, `for`, `case`,
532
+ * `until`, `select` — that aren't closed by a same-line command marker.
533
+ * - Lines ending with an unmatched `{` (function bodies, brace groups).
534
+ * - Lines ending with `do` (the `for x in y; do` / `while cond; do` form).
535
+ *
536
+ * The end predicate matches `}` only when it leads its line — that lets us
537
+ * close brace groups while ignoring `${VAR}` parameter expansions, which
538
+ * are never line-leading.
539
+ */
540
+ const BASH_PATTERN = {
541
+ startsFold: bashStartsFold,
542
+ endsFold: bashEndsFold
543
+ };
544
+ /** Returns true for ASCII identifier characters used by shell/Ruby keywords. */
545
+ function isWordChar(character) {
546
+ return character >= 48 && character <= 57 || character >= 65 && character <= 90 || character >= 97 && character <= 122 || character === 95;
547
+ }
548
+ /** Returns true for whitespace characters accepted around language markers. */
549
+ function isWhitespaceChar(character) {
550
+ return character === 9 || character === 10 || character === 11 || character === 12 || character === 13 || character === 32;
551
+ }
552
+ /** Returns the index of the first non-whitespace character in `text`. */
553
+ function firstNonWhitespaceIndex(text) {
554
+ let index = 0;
555
+ while (index < text.length && isWhitespaceChar(text.charCodeAt(index))) index += 1;
556
+ return index;
557
+ }
558
+ /** Returns the exclusive index after the last non-whitespace character. */
559
+ function endTrimmedIndex(text) {
560
+ let index = text.length;
561
+ while (index > 0 && isWhitespaceChar(text.charCodeAt(index - 1))) index -= 1;
562
+ return index;
563
+ }
564
+ /** Returns true if `word` appears at `index` with word boundaries. */
565
+ function isWordAt(text, index, word, end = text.length) {
566
+ if (index < 0 || index + word.length > end) return false;
567
+ if (text.slice(index, index + word.length) !== word) return false;
568
+ const beforeIsBoundary = index === 0 || !isWordChar(text.charCodeAt(index - 1));
569
+ const afterIndex = index + word.length;
570
+ const afterIsBoundary = afterIndex >= end || !isWordChar(text.charCodeAt(afterIndex));
571
+ return beforeIsBoundary && afterIsBoundary;
572
+ }
573
+ /** Returns true when a line begins with one of the given keywords. */
574
+ function startsWithAnyWordAfterWhitespace(text, words) {
575
+ const index = firstNonWhitespaceIndex(text);
576
+ for (const word of words) if (isWordAt(text, index, word)) return true;
577
+ return false;
578
+ }
579
+ /**
580
+ * Returns true when `index` is positioned where the shell can begin another
581
+ * command word on the same physical line. This intentionally ignores ordinary
582
+ * arguments and variables like `$done`, so `case $done in` still opens a fold.
583
+ */
584
+ function isShellCommandBoundary(text, index) {
585
+ let cursor = index - 1;
586
+ while (cursor >= 0 && isWhitespaceChar(text.charCodeAt(cursor))) cursor -= 1;
587
+ if (cursor < 0) return true;
588
+ const previous = text.charCodeAt(cursor);
589
+ return previous === 38 || previous === 40 || previous === 59 || previous === 124;
590
+ }
591
+ /**
592
+ * Returns true when a Bash closer appears as a same-line command marker, e.g.
593
+ * `if ok; then echo hi; fi`. A single linear scan is cheaper than running one
594
+ * regex per marker and keeps shell variables / arguments named `done`, `fi`,
595
+ * or `esac` from suppressing valid opener folds.
596
+ */
597
+ function hasShellSameLineEndKeyword(text) {
598
+ for (let index = 0; index < text.length; index += 1) {
599
+ if (!isWordChar(text.charCodeAt(index))) continue;
600
+ for (const word of BASH_END_KEYWORDS) if (isWordAt(text, index, word) && isShellCommandBoundary(text, index)) return true;
601
+ while (index + 1 < text.length && isWordChar(text.charCodeAt(index + 1))) index += 1;
602
+ }
603
+ return false;
604
+ }
605
+ /**
606
+ * Returns true when a line starts with a shell closer command. `done)` and
607
+ * similar case labels are deliberately excluded; `)` is not a command
608
+ * separator, so those labels should not pop the fold stack.
609
+ */
610
+ function startsWithShellEndKeyword(text) {
611
+ const index = firstNonWhitespaceIndex(text);
612
+ for (const word of BASH_END_KEYWORDS) {
613
+ if (!isWordAt(text, index, word)) continue;
614
+ const next = text.charCodeAt(index + word.length);
615
+ return Number.isNaN(next) || isWhitespaceChar(next) || next === 38 || next === 59 || next === 124;
616
+ }
617
+ return false;
618
+ }
619
+ /** Returns true when a line ends with `word`, ignoring trailing whitespace. */
620
+ function endsWithWord(text, word) {
621
+ const end = endTrimmedIndex(text);
622
+ return isWordAt(text, end - word.length, word, end);
623
+ }
624
+ /** Returns true for trailing Ruby `do` / `do |args|` block openers. */
625
+ function endsWithRubyDoBlock(text) {
626
+ let end = endTrimmedIndex(text);
627
+ if (end <= 0) return false;
628
+ if (text.charCodeAt(end - 1) === 124) {
629
+ const paramsStart = text.lastIndexOf("|", end - 2);
630
+ if (paramsStart === -1) return false;
631
+ end = paramsStart;
632
+ while (end > 0 && isWhitespaceChar(text.charCodeAt(end - 1))) end -= 1;
633
+ }
634
+ return isWordAt(text, end - 2, "do", end);
635
+ }
636
+ /** Returns true when a Ruby line opens a keyword-paired block. */
637
+ function rubyStartsFold(visible) {
638
+ return startsWithAnyWordAfterWhitespace(visible, RUBY_START_KEYWORDS) || endsWithRubyDoBlock(visible);
639
+ }
640
+ /** Returns true when a shell line has a `{` with no later `}` on the same line. */
641
+ function endsWithOpenBrace(visible) {
642
+ return visible.lastIndexOf("{") > visible.lastIndexOf("}");
643
+ }
644
+ /** Returns true when a Bash/Shell line opens a keyword-paired block. */
645
+ function bashStartsFold(visible) {
646
+ if (startsWithAnyWordAfterWhitespace(visible, BASH_START_KEYWORDS) && !hasShellSameLineEndKeyword(visible)) return true;
647
+ return endsWithOpenBrace(visible) || endsWithWord(visible, "do");
648
+ }
649
+ /** Returns true when a Bash/Shell line closes a keyword-paired block. */
650
+ function bashEndsFold(visible) {
651
+ const firstContent = firstNonWhitespaceIndex(visible);
652
+ return visible.charCodeAt(firstContent) === 125 || startsWithShellEndKeyword(visible);
653
+ }
654
+ /** Resolves the keyword pattern for a given language. */
655
+ function patternFor(language) {
656
+ switch (language) {
657
+ case "ruby":
658
+ case "rb": return RUBY_PATTERN;
659
+ case "bash":
660
+ case "sh":
661
+ case "shell": return BASH_PATTERN;
662
+ }
663
+ }
664
+ /**
665
+ * TextMate scope prefixes that mark a token as inert content (string body,
666
+ * comment body, character escape). Mirrors the filter used by
667
+ * `computeFoldRanges` for the bracket strategy so behaviors stay consistent.
668
+ */
669
+ const INERT_SCOPE_PREFIXES = [
670
+ "string.",
671
+ "comment.",
672
+ "constant.character.escape"
673
+ ];
674
+ /** Returns true when the innermost scope of a token marks it inert. */
675
+ function isInertScope(scopes) {
676
+ if (scopes.length === 0) return false;
677
+ const innermost = scopes[scopes.length - 1]?.scopeName ?? "";
678
+ if (innermost === "string" || innermost === "comment") return true;
679
+ for (const prefix of INERT_SCOPE_PREFIXES) if (innermost.startsWith(prefix)) return true;
680
+ return false;
681
+ }
682
+ /**
683
+ * Reconstructs the visible (non-string, non-comment) text of a single
684
+ * tokenized line.
685
+ *
686
+ * Subtlety: Shiki keeps leading whitespace inside `token.content` but strips
687
+ * it from every `explanation.content` piece — so `" HttpListener"` (token)
688
+ * decomposes into `[{ content: "HttpListener", scopes: […] }]`. Iterating
689
+ * explanations alone collapses adjacent identifiers (`class HttpListener`
690
+ * becomes `classHttpListener`), which breaks every word-boundary keyword
691
+ * regex. We use `token.content` whenever no explanation piece is inert and
692
+ * only fall back to per-explanation iteration for mixed-scope tokens.
693
+ */
694
+ function visibleTextForLine(line) {
695
+ let visible = "";
696
+ for (const token of line) {
697
+ const explanations = token.explanation;
698
+ if (explanations == null || explanations.length === 0) {
699
+ visible += token.content;
700
+ continue;
701
+ }
702
+ let hasInert = false;
703
+ for (const explanation of explanations) if (isInertScope(explanation.scopes)) {
704
+ hasInert = true;
705
+ break;
706
+ }
707
+ if (!hasInert) {
708
+ visible += token.content;
709
+ continue;
710
+ }
711
+ for (const explanation of explanations) {
712
+ if (isInertScope(explanation.scopes)) continue;
713
+ visible += explanation.content;
714
+ }
715
+ }
716
+ return visible;
717
+ }
718
+ /**
719
+ * Computes foldable ranges from tokenized source lines using the language's
720
+ * keyword opener/closer regex pair.
721
+ *
722
+ * The same line can both open and close a block (`if foo; end` in Ruby).
723
+ * Such lines push and pop on the stack but their start/end coincide, so the
724
+ * range gets discarded by the `endLine > startLine` filter — matching how
725
+ * the bracket strategy treats single-line `{}` constructs.
726
+ *
727
+ * @example
728
+ * // tokens: [["def f"], [" pass"], ["end"]]
729
+ * computeKeywordFoldRanges({ language: "ruby", tokens });
730
+ * // => [{ id: "1", startLine: 1, endLine: 3 }]
731
+ */
732
+ function computeKeywordFoldRanges({ language, tokens }) {
733
+ const pattern = patternFor(language);
734
+ const stack = [];
735
+ const ranges = [];
736
+ for (let lineIndex = 0; lineIndex < tokens.length; lineIndex += 1) {
737
+ const line = tokens[lineIndex];
738
+ if (line == null) continue;
739
+ const visible = visibleTextForLine(line);
740
+ if (visible.length === 0) continue;
741
+ const lineNumber = lineIndex + 1;
742
+ if (pattern.endsFold(visible)) {
743
+ const startLine = stack.pop();
744
+ if (startLine != null && startLine < lineNumber) ranges.push({
745
+ id: String(startLine),
746
+ startLine,
747
+ endLine: lineNumber
748
+ });
749
+ }
750
+ if (pattern.startsFold(visible)) stack.push(lineNumber);
751
+ }
752
+ return finalizeFoldRanges(ranges);
753
+ }
754
+
755
+ //#endregion
756
+ //#region src/server-fold-ranges.ts
757
+ /** Returns the server fold strategy for the given supported language. */
758
+ function serverFoldStrategyFor(language) {
759
+ switch (language) {
760
+ case "javascript":
761
+ case "js":
762
+ case "typescript":
763
+ case "ts":
764
+ case "jsx":
765
+ case "tsx": return "jsx-ast";
766
+ case "html":
767
+ case "xml": return "html-ast";
768
+ case "css": return "css-raw";
769
+ case "json": return "json-raw";
770
+ case "python":
771
+ case "py":
772
+ case "yaml":
773
+ case "yml": return "token-indentation";
774
+ case "ruby":
775
+ case "rb": return "token-bracket-and-keyword";
776
+ case "bash":
777
+ case "sh":
778
+ case "shell": return "token-keyword";
779
+ case "plain":
780
+ case "plaintext":
781
+ case "text":
782
+ case "txt": return "none";
783
+ default: return "token-bracket";
784
+ }
785
+ }
786
+ /**
787
+ * Returns true when the strategy needs Shiki-tokenized lines (with scope
788
+ * explanations) to run. AST and raw-source strategies operate on the source
789
+ * string directly and let us skip the `includeExplanation: 'scopeName'`
790
+ * Shiki option, saving meaningful work on JS/TS/HTML/CSS hot paths.
791
+ */
792
+ function serverFoldNeedsTokens(strategy) {
793
+ switch (strategy) {
794
+ case "token-bracket":
795
+ case "token-indentation":
796
+ case "token-keyword":
797
+ case "token-bracket-and-keyword": return true;
798
+ case "jsx-ast":
799
+ case "html-ast":
800
+ case "css-raw":
801
+ case "json-raw":
802
+ case "none": return false;
803
+ }
804
+ }
805
+ /** Type guard: narrows `SupportedLanguage` to languages handled by the JSX strategy. */
806
+ function isJsxFoldLanguage(language) {
807
+ return language === "javascript" || language === "js" || language === "typescript" || language === "ts" || language === "jsx" || language === "tsx";
808
+ }
809
+ /** Type guard: narrows `SupportedLanguage` to languages handled by the HTML strategy. */
810
+ function isHtmlFoldLanguage(language) {
811
+ return language === "html" || language === "xml";
812
+ }
813
+ /** Type guard: narrows `SupportedLanguage` to languages handled by the keyword strategy. */
814
+ function isKeywordFoldLanguage(language) {
815
+ return language === "ruby" || language === "rb" || language === "bash" || language === "sh" || language === "shell";
816
+ }
817
+ /**
818
+ * Computes foldable ranges for a single highlighted code block, dispatching
819
+ * to the appropriate strategy. Every supported language flows through here,
820
+ * including the legacy token-based ones, so the engine has a single decision
821
+ * point.
822
+ *
823
+ * Caller contract:
824
+ * - For token-needing strategies, `tokens` must be the lines produced by
825
+ * Shiki with `includeExplanation: 'scopeName'`. Pass `undefined` and the
826
+ * strategy returns `[]`.
827
+ * - For raw / AST strategies, `tokens` is ignored; only `code` matters.
828
+ *
829
+ * Errors raised by underlying parsers are caught and converted into "no
830
+ * folds" — Shiki still gets to render the highlighted code, the gutter just
831
+ * skips the toggle. We log nothing here because the engine is the wrong
832
+ * layer to surface diagnostics.
833
+ */
834
+ function computeServerFoldRanges({ code, language, tokens }) {
835
+ const strategy = serverFoldStrategyFor(language);
836
+ try {
837
+ switch (strategy) {
838
+ case "jsx-ast":
839
+ if (!isJsxFoldLanguage(language)) return [];
840
+ return computeJsxFoldRanges({
841
+ code,
842
+ language
843
+ });
844
+ case "html-ast":
845
+ if (!isHtmlFoldLanguage(language)) return [];
846
+ return computeHtmlFoldRanges({
847
+ code,
848
+ language
849
+ });
850
+ case "css-raw": return computeCssFoldRanges({ code });
851
+ case "json-raw": return computeJsonFoldRanges(code);
852
+ case "token-bracket":
853
+ case "token-indentation":
854
+ if (tokens == null) return [];
855
+ return computeFoldRanges({
856
+ language,
857
+ tokens
858
+ });
859
+ case "token-keyword":
860
+ if (tokens == null || !isKeywordFoldLanguage(language)) return [];
861
+ return computeKeywordFoldRanges({
862
+ language,
863
+ tokens
864
+ });
865
+ case "token-bracket-and-keyword":
866
+ if (tokens == null || !isKeywordFoldLanguage(language)) return [];
867
+ return finalizeFoldRanges([...computeFoldRanges({
868
+ language,
869
+ tokens
870
+ }), ...computeKeywordFoldRanges({
871
+ language,
872
+ tokens
873
+ })]);
874
+ case "none": return [];
875
+ }
876
+ } catch {
877
+ return [];
878
+ }
879
+ }
880
+
33
881
  //#endregion
34
882
  //#region src/engine.ts
35
883
  /**
@@ -152,14 +1000,30 @@ async function highlightWithMantleShiki(input) {
152
1000
  const cached = mantleHighlightCache.get(cacheKey);
153
1001
  if (cached != null) return cached;
154
1002
  const promise = (async () => {
155
- const baseHtml = extractHighlightedCodeInnerHtml((await getMantleShikiHighlighter()).codeToHtml(normalizedCode, {
1003
+ const highlighter = await getMantleShikiHighlighter();
1004
+ const foldStrategy = serverFoldStrategyFor(resolvedLanguage);
1005
+ const wantsTokens = serverFoldNeedsTokens(foldStrategy);
1006
+ let capturedTokens;
1007
+ const baseHtml = extractHighlightedCodeInnerHtml(highlighter.codeToHtml(normalizedCode, {
156
1008
  lang: resolvedLanguage,
157
- theme: mantleShikiThemeName
1009
+ theme: mantleShikiThemeName,
1010
+ includeExplanation: wantsTokens ? "scopeName" : false,
1011
+ transformers: wantsTokens ? [{
1012
+ name: "mantle:capture-tokens",
1013
+ tokens(tokens) {
1014
+ capturedTokens = tokens;
1015
+ }
1016
+ }] : void 0
158
1017
  }));
159
1018
  if (baseHtml == null) throw new Error("Failed to extract highlighted HTML from Shiki output");
160
1019
  return {
161
1020
  code: normalizedCode,
162
1021
  html: decorateHighlightedHtml({
1022
+ foldableRanges: foldStrategy === "none" ? void 0 : computeServerFoldRanges({
1023
+ code: normalizedCode,
1024
+ language: resolvedLanguage,
1025
+ tokens: capturedTokens
1026
+ }),
163
1027
  highlightLines,
164
1028
  html: baseHtml,
165
1029
  lineNumberStart,
@@ -185,5 +1049,5 @@ function createMantleServerSyntaxHighlighter() {
185
1049
  }
186
1050
 
187
1051
  //#endregion
188
- export { createMantleServerSyntaxHighlighter, getMantleShikiHighlighter, highlightWithMantleShiki, mantleHighlightCacheMaxEntries, mantleShikiLanguageGrammarIds, mantleShikiThemeName };
1052
+ export { computeCssFoldRanges, computeHtmlFoldRanges, computeJsxFoldRanges, computeKeywordFoldRanges, computeServerFoldRanges, createMantleServerSyntaxHighlighter, getMantleShikiHighlighter, highlightWithMantleShiki, mantleHighlightCacheMaxEntries, mantleShikiLanguageGrammarIds, mantleShikiThemeName, serverFoldNeedsTokens, serverFoldStrategyFor };
189
1053
  //# sourceMappingURL=index.js.map