@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.d.ts +222 -3
- package/dist/index.js +868 -4
- package/dist/index.js.map +1 -1
- package/package.json +7 -5
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.
|
|
@@ -90,5 +89,225 @@ declare function highlightWithMantleShiki(input: MantleHighlightInput): Promise<
|
|
|
90
89
|
*/
|
|
91
90
|
declare function createMantleServerSyntaxHighlighter(): MantleServerHighlighter;
|
|
92
91
|
//#endregion
|
|
93
|
-
|
|
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
|