@ngrok/mantle-server-syntax-highlighter 1.0.3 → 1.1.0

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.d.ts CHANGED
@@ -1,6 +1,5 @@
1
- import { Indentation, LineRange, SupportedLanguage } from "@ngrok/mantle/highlight-utils";
1
+ import { FoldLine, FoldableRange, Indentation, LineRange, SupportedLanguage } from "@ngrok/mantle/highlight-utils";
2
2
  import * as _$shiki from "shiki";
3
-
4
3
  //#region src/engine.d.ts
5
4
  /**
6
5
  * Shiki grammar IDs preloaded by Mantle's highlighting engine.
@@ -28,7 +27,7 @@ type MantleHighlightInput = {
28
27
  indentation?: Indentation;
29
28
  /**
30
29
  * Whether to render line numbers into the returned HTML.
31
- * @default false
30
+ * @default true
32
31
  */
33
32
  showLineNumbers?: boolean;
34
33
  /**
@@ -90,5 +89,225 @@ declare function highlightWithMantleShiki(input: MantleHighlightInput): Promise<
90
89
  */
91
90
  declare function createMantleServerSyntaxHighlighter(): MantleServerHighlighter;
92
91
  //#endregion
93
- export { type MantleHighlightInput, type MantleHighlightResult, type MantleServerHighlighter, createMantleServerSyntaxHighlighter, getMantleShikiHighlighter, highlightWithMantleShiki, mantleHighlightCacheMaxEntries, mantleShikiLanguageGrammarIds, mantleShikiThemeName };
92
+ //#region src/server-fold-ranges.d.ts
93
+ /**
94
+ * Server-side folding strategy applied to a language. This is a richer
95
+ * dispatch than `@ngrok/mantle/highlight-utils`'s `foldStrategyFor`:
96
+ *
97
+ * - `jsx-ast` parses JS / TS / JSX / TSX with `oxc-parser`.
98
+ * - `html-ast` parses HTML / XML with `parse5`.
99
+ * - `css-raw` runs a CSS-aware single-pass brace matcher.
100
+ * - `json-raw` reuses the existing `computeJsonFoldRanges` (raw, scope-free).
101
+ * - `token-bracket` / `token-indentation` are the existing token-based
102
+ * strategies for languages without a heavier parser (Go, Rust, Java, C#,
103
+ * Python, YAML).
104
+ * - `token-keyword` matches keyword openers / closers against tokenized line
105
+ * text (Bash / Shell).
106
+ * - `token-bracket-and-keyword` runs the bracket pass *and* the keyword pass
107
+ * and merges them — Ruby uses brace-style blocks (`{ |x| … }`) plus
108
+ * keyword blocks (`def … end`).
109
+ * - `none` opts out for plain text and unknown languages.
110
+ *
111
+ * Strategies suffixed `-ast` or `-raw` need only the raw source string;
112
+ * `token-*` strategies need Shiki-tokenized lines with scope explanations.
113
+ */
114
+ type ServerFoldStrategy = "jsx-ast" | "html-ast" | "css-raw" | "json-raw" | "token-bracket" | "token-indentation" | "token-keyword" | "token-bracket-and-keyword" | "none";
115
+ /** Returns the server fold strategy for the given supported language. */
116
+ declare function serverFoldStrategyFor(language: SupportedLanguage): ServerFoldStrategy;
117
+ /**
118
+ * Returns true when the strategy needs Shiki-tokenized lines (with scope
119
+ * explanations) to run. AST and raw-source strategies operate on the source
120
+ * string directly and let us skip the `includeExplanation: 'scopeName'`
121
+ * Shiki option, saving meaningful work on JS/TS/HTML/CSS hot paths.
122
+ */
123
+ declare function serverFoldNeedsTokens(strategy: ServerFoldStrategy): boolean;
124
+ /**
125
+ * Computes foldable ranges for a single highlighted code block, dispatching
126
+ * to the appropriate strategy. Every supported language flows through here,
127
+ * including the legacy token-based ones, so the engine has a single decision
128
+ * point.
129
+ *
130
+ * Caller contract:
131
+ * - For token-needing strategies, `tokens` must be the lines produced by
132
+ * Shiki with `includeExplanation: 'scopeName'`. Pass `undefined` and the
133
+ * strategy returns `[]`.
134
+ * - For raw / AST strategies, `tokens` is ignored; only `code` matters.
135
+ *
136
+ * Errors raised by underlying parsers are caught and converted into "no
137
+ * folds" — Shiki still gets to render the highlighted code, the gutter just
138
+ * skips the toggle. We log nothing here because the engine is the wrong
139
+ * layer to surface diagnostics.
140
+ */
141
+ declare function computeServerFoldRanges({
142
+ code,
143
+ language,
144
+ tokens
145
+ }: {
146
+ /** Normalized source code (post-`normalizeIndentation`). */code: string; /** Resolved Mantle supported language. */
147
+ language: SupportedLanguage; /** Shiki-tokenized lines, when the strategy needs them. */
148
+ tokens: FoldLine[] | undefined;
149
+ }): FoldableRange[];
150
+ //#endregion
151
+ //#region src/compute-jsx-fold-ranges.d.ts
152
+ /**
153
+ * AST-based fold computer for the JS/TS/JSX/TSX language family.
154
+ *
155
+ * Mirrors VS Code's TypeScript language service folder by walking the parsed
156
+ * AST instead of pairing brackets in the token stream. This lets us fold
157
+ * constructs that bracket-pairing can't see:
158
+ *
159
+ * - JSX elements (`<Foo>…</Foo>`, fragments, members like `<obj.Foo>`).
160
+ * - Template literals that span multiple lines (including tagged templates).
161
+ *
162
+ * It also keeps every fold the bracket strategy used to give us — block
163
+ * statements, object literals, array literals, class/interface bodies, switch
164
+ * statements — without the per-character scope-walk cost.
165
+ *
166
+ * @see https://github.com/microsoft/vscode/blob/main/extensions/typescript-language-features/src/languageFeatures/folding.ts
167
+ */
168
+ /** Subset of supported languages handled by this computer. */
169
+ type JsxFoldLanguage = "javascript" | "js" | "typescript" | "ts" | "jsx" | "tsx";
170
+ /**
171
+ * Computes foldable ranges for a JS/TS/JSX/TSX source string by parsing it
172
+ * with `oxc-parser` and walking the AST. Errors are tolerated — a partial AST
173
+ * still produces useful folds.
174
+ *
175
+ * @example
176
+ * computeJsxFoldRanges({ code: "<Foo>\n <Bar/>\n</Foo>", language: "tsx" });
177
+ * // => [{ id: "1", startLine: 1, endLine: 3 }]
178
+ */
179
+ declare function computeJsxFoldRanges({
180
+ code,
181
+ language
182
+ }: {
183
+ /** Raw source code to parse and fold. */code: string; /** Resolved Mantle language; controls grammar selection (TS vs JS, JSX vs plain). */
184
+ language: JsxFoldLanguage;
185
+ }): FoldableRange[];
186
+ //#endregion
187
+ //#region src/compute-html-fold-ranges.d.ts
188
+ /**
189
+ * AST-based fold computer for HTML and XML.
190
+ *
191
+ * Uses `parse5` with `sourceCodeLocationInfo: true` so each element node carries
192
+ * the line numbers of its open and close tags. Walking the tree gives us:
193
+ *
194
+ * - One fold per multi-line element (`<div>…</div>`).
195
+ * - One fold per multi-line opening tag (`<div\n class="x"\n>` — the
196
+ * attribute list collapses).
197
+ * - Correct void-element handling — parse5 already knows that `<br>`, `<img>`,
198
+ * etc. don't open folds.
199
+ * - Template content traversal — parse5 stores `<template>` descendants on a
200
+ * separate `content` fragment, not on `childNodes`.
201
+ * - String/comment scope filtering — angle brackets in `<!-- … -->` or
202
+ * inside `"…"` attribute values aren't mistaken for tag openings.
203
+ *
204
+ * @see https://parse5.js.org/
205
+ */
206
+ type HtmlFoldLanguage = "html" | "xml";
207
+ /**
208
+ * Computes foldable ranges for an HTML or XML source string.
209
+ *
210
+ * - HTML: uses `parse5.parse` so explicit `<html>`/`<head>`/`<body>` are
211
+ * honored as foldable openers. Implicit wrappers parse5 fabricates for
212
+ * fragment input have no `sourceCodeLocation` and are skipped.
213
+ * - XML: uses `parse5.parseFragment` rooted in an SVG fragment context so the
214
+ * tokenizer applies foreign-content (XML-like) rules — self-closing `<foo/>`
215
+ * is respected, void HTML elements aren't special-cased.
216
+ *
217
+ * @example
218
+ * computeHtmlFoldRanges({ code: "<div>\n <p>hi</p>\n</div>", language: "html" });
219
+ * // => [{ id: "1", startLine: 1, endLine: 3 }]
220
+ */
221
+ declare function computeHtmlFoldRanges({
222
+ code,
223
+ language
224
+ }: {
225
+ /** Raw source code to parse. */code: string; /** Resolved Mantle language; selects HTML vs. XML parsing rules. */
226
+ language: HtmlFoldLanguage;
227
+ }): FoldableRange[];
228
+ //#endregion
229
+ //#region src/compute-css-fold-ranges.d.ts
230
+ /**
231
+ * Raw-source fold computer for CSS — single-pass, parser-quality without a
232
+ * parser dependency.
233
+ *
234
+ * Mirrors `computeJsonFoldRanges` but adds CSS-specific lexical features:
235
+ *
236
+ * - `/* … *​/` block comments are skipped wholesale.
237
+ * - `"…"` and `'…'` string literals (including `\\` and `\` escapes) are
238
+ * skipped so braces inside `content: "{ }"` don't open folds.
239
+ * - Backslash escapes outside of strings (CSS identifiers can use them) are
240
+ * transparent — we just consume the next character.
241
+ *
242
+ * lightningcss is the project's preferred CSS parser, but its public visitor
243
+ * API only surfaces *start* locations (`Location { line, column }`), not end
244
+ * locations, which is what `FoldableRange.endLine` requires. Until upstream
245
+ * exposes end spans we get the same correctness from a single-pass brace
246
+ * matcher with a tiny CSS lexer — and skip the ~5MB native dep.
247
+ *
248
+ * @see https://github.com/parcel-bundler/lightningcss/issues/512
249
+ */
250
+ /**
251
+ * Computes foldable ranges for a CSS source string. Each multi-line `{ … }`
252
+ * (style rule, at-rule body, nested rule, keyframe selector) emits one range
253
+ * with the opener and closer lines staying visible.
254
+ *
255
+ * Tolerant of malformed CSS — unmatched braces are dropped silently rather
256
+ * than throwing, so a partial snippet still gets every fold it can. This
257
+ * matches the behavior of `computeJsonFoldRanges` for JSON.
258
+ *
259
+ * @example
260
+ * computeCssFoldRanges({ code: ".a {\n color: red;\n}" });
261
+ * // => [{ id: "1", startLine: 1, endLine: 3 }]
262
+ */
263
+ declare function computeCssFoldRanges({
264
+ code
265
+ }: {
266
+ /** Raw CSS source code to scan. */code: string;
267
+ }): FoldableRange[];
268
+ //#endregion
269
+ //#region src/compute-keyword-fold-ranges.d.ts
270
+ /**
271
+ * Keyword-pair fold computer for languages whose blocks are delimited by
272
+ * keywords rather than punctuation.
273
+ *
274
+ * VS Code models this with `foldingStartMarker` / `foldingStopMarker`
275
+ * declarations in each language's `language-configuration.json`. We mirror
276
+ * that behavior with linear marker predicates, evaluated against the
277
+ * *visible* (non-string, non-comment) portion of each line — the Shiki tokens
278
+ * carry scope information that lets us strip those out reliably.
279
+ *
280
+ * The stack is untyped — every closer pops the most recent opener, regardless
281
+ * of which keyword opened it. Real source code nests properly, so this stays
282
+ * correct without per-keyword tracking, and matches VS Code's marker-based
283
+ * behavior.
284
+ *
285
+ * @see https://github.com/microsoft/vscode/blob/main/extensions/ruby/language-configuration.json
286
+ * @see https://github.com/microsoft/vscode/blob/main/extensions/shellscript/language-configuration.json
287
+ */
288
+ /** Languages this computer knows how to fold. */
289
+ type KeywordFoldLanguage = "ruby" | "rb" | "bash" | "sh" | "shell";
290
+ /**
291
+ * Computes foldable ranges from tokenized source lines using the language's
292
+ * keyword opener/closer regex pair.
293
+ *
294
+ * The same line can both open and close a block (`if foo; end` in Ruby).
295
+ * Such lines push and pop on the stack but their start/end coincide, so the
296
+ * range gets discarded by the `endLine > startLine` filter — matching how
297
+ * the bracket strategy treats single-line `{}` constructs.
298
+ *
299
+ * @example
300
+ * // tokens: [["def f"], [" pass"], ["end"]]
301
+ * computeKeywordFoldRanges({ language: "ruby", tokens });
302
+ * // => [{ id: "1", startLine: 1, endLine: 3 }]
303
+ */
304
+ declare function computeKeywordFoldRanges({
305
+ language,
306
+ tokens
307
+ }: {
308
+ /** Resolved Mantle language; controls which keyword pattern to use. */language: KeywordFoldLanguage; /** Shiki-tokenized lines, with scope explanations populated. */
309
+ tokens: FoldLine[];
310
+ }): FoldableRange[];
311
+ //#endregion
312
+ export { type HtmlFoldLanguage, type JsxFoldLanguage, type KeywordFoldLanguage, type MantleHighlightInput, type MantleHighlightResult, type MantleServerHighlighter, type ServerFoldStrategy, computeCssFoldRanges, computeHtmlFoldRanges, computeJsxFoldRanges, computeKeywordFoldRanges, computeServerFoldRanges, createMantleServerSyntaxHighlighter, getMantleShikiHighlighter, highlightWithMantleShiki, mantleHighlightCacheMaxEntries, mantleShikiLanguageGrammarIds, mantleShikiThemeName, serverFoldNeedsTokens, serverFoldStrategyFor };
94
313
  //# sourceMappingURL=index.d.ts.map