@hydranium/core 1.0.0-next.36 → 1.0.0-next.360

package/lib/langium/trivia/comment-preserver.d.ts

@@ -0,0 +1,543 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type Tracer } from '@hydranium/protocol';
+import { type AstNode, type CompositeCstNode, type CstNode, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type HydraniumLanguageServices } from '../language-module.js';
+import { type TriviaContribution, type TriviaRegistry } from './trivia-contribution.js';
+import { type TriviaPreserver } from './trivia-preserver.js';
+/**
+ * Where a comment sat relative to the node it belongs to.
+ *
+ * The CST records source order but not ownership, so getting this wrong
+ * relocates a comment rather than losing it.
+ *
+ * - `atContainerStart` — before everything the container holds.
+ * - `leading` — on its own line(s) above the node that follows it.
+ * - `trailing` — on the same line the previous node ended on.
+ * - `trailingOnContainer` — on the container's own header line, or amongst its
+ *   syntax with more of the container still to come.
+ * - `afterNode` — on its own line after the last node, still inside the
+ *   container.
+ * - `atContainerEnd` — after everything the container holds.
+ */
+export type CommentPlacement = 'atContainerStart' | 'leading' | 'trailing' | 'trailingOnContainer' | 'afterNode' | 'atContainerEnd';
+/** One comment, bound to the AST node it hangs off rather than to an offset. */
+export interface DocumentComment {
+    /** The comment's source text, delimiters included. */
+    readonly text: string;
+    /**
+     * The node the comment hangs off, held as the AST OBJECT rather than a path
+     * or an offset, so a write that mutates the tree IN PLACE — an integrity
+     * repair, a diagram gesture — is reflected without re-extracting.
+     *
+     * A transfer-model write supplies a separate object graph. A unique rename
+     * can still be matched when its type, parent slot and other properties agree;
+     * ambiguous matches are dropped.
+     */
+    readonly anchor: AstNode;
+    readonly placement: CommentPlacement;
+    /**
+     * Blank lines between the comment and what it leads, for the placements that
+     * emit it BEFORE its anchor.
+     *
+     * Captured for the placements that emit it after as well, where nothing reads
+     * it: there the spacing an author means is the gap above the comment, which
+     * {@link blankLinesBefore} carries.
+     */
+    readonly blankLinesAfter: number;
+    /**
+     * Blank lines between the comment and what PRECEDES it, for the placements
+     * that emit it after their anchor. A comment separated from the closing brace
+     * above it by a blank line reads as a new thought; re-emitting it flush
+     * against that brace silently rewrites the author's spacing.
+     */
+    readonly blankLinesBefore: number;
+    /**
+     * The indentation the comment sat at in the source, when it owned its line —
+     * `undefined` for one sharing a line with code, which is never reindented.
+     *
+     * A MULTI-LINE comment needs it to shift its continuation lines, which carry
+     * their original indentation inside {@link text}: emitting the block at a new
+     * indentation without shifting them leaves it hanging off its old column.
+     *
+     * A single-line one needs it whenever its anchor turns out to share a line,
+     * because the indentation read off a mid-line offset is the code's and not
+     * the comment's.
+     */
+    readonly sourceIndent?: string;
+}
+/** What {@link CommentPreserver} takes off a document. */
+export interface CommentTrivia {
+    readonly comments: readonly DocumentComment[];
+    /** Original tree, retained to detect ambiguous or removed anchors at apply time. */
+    readonly sourceRoot: AstNode;
+}
+/** Construction options for {@link CommentPreserver}. */
+export interface CommentPreserverOptions extends LogNameOptions {
+    /**
+     * Registry id, defaulting to `comments`. Set it only to run a second comment
+     * preserver beside the framework's; a subclass that REPLACES it keeps the
+     * default so the contribution sub-key and the id stay in step.
+     */
+    readonly id?: string;
+    /**
+     * How many comments spliced into shared lines are worth blaming one at a
+     * time when the result will not parse. Default {@link DEFAULT_ISOLATED_EDITS}.
+     *
+     * Isolating means re-splicing and re-parsing the whole document once per
+     * candidate, so the search costs the document's length times their number.
+     * Past this many the write drops them together instead — the same text it
+     * would reach anyway if every one of them were at fault, without spending
+     * that search on a build's write lock.
+     */
+    readonly maxIsolatedEdits?: number;
+}
+/**
+ * Where a node begins and ends in the text it was located in, and which node
+ * that is.
+ *
+ * Exported because {@link CommentPreserver.editFor} takes one, and an override
+ * that cannot name its own parameter type has to restate the shape — which then
+ * stops compiling the moment a field is added here.
+ */
+export interface AnchorSpan {
+    readonly offset: number;
+    readonly end: number;
+    readonly owner: AstNode;
+}
+export interface IndentationTokenNames {
+    readonly indent: string;
+    readonly dedent: string;
+}
+/**
+ * A container a run of comment lines can be placed in: the run's own, or one
+ * it is lifted into when a block's DEDENT follows the run. `last` is the index
+ * in its content the run is placed after, `closed` the block the run is lifted
+ * out of, and `liftBelow` the column a comment line has to start left of to be
+ * lifted this far.
+ */
+export interface CommentLiftTarget {
+    readonly container: CompositeCstNode;
+    readonly last: number;
+    readonly closed?: CompositeCstNode;
+    readonly liftBelow?: number;
+}
+/**
+ * A run of hidden nodes in `content`, from `start` to `end`, with the syntax
+ * before it and the containers its comments can be placed in, innermost first.
+ */
+export interface CommentRun {
+    readonly content: readonly CstNode[];
+    readonly start: number;
+    readonly end: number;
+    readonly previous?: {
+        readonly end: number;
+    };
+    readonly targets: readonly CommentLiftTarget[];
+    /** The nodes {@link CommentPreserver.neighbours} finds before the run, in order. */
+    readonly before: readonly CstNode[];
+    /** Per target, the nodes {@link CommentPreserver.neighbours} finds after its `last`. */
+    readonly after: readonly (readonly CstNode[])[];
+}
+/**
+ * One splice, with what it takes to check the risky kind afterwards.
+ *
+ * `inline` is set only for an edit that opens a line inside syntax the
+ * serializer emitted whole; it carries what the comment must look like when the
+ * result is read back, since that edit is the one that can hand a comment to
+ * the wrong declaration.
+ *
+ * Exported for the same reason {@link AnchorSpan} is: the members that take one
+ * are protected, so an override has to be able to name it.
+ */
+export interface InlineAwareEdit {
+    readonly at: number;
+    readonly text: string;
+    /** Capture order, so several comments on one anchor keep the order written. */
+    readonly order: number;
+    readonly inline?: {
+        readonly text: string;
+        readonly key: string;
+    };
+}
+/**
+ * Carries a document's comments across a write that re-serializes it from the
+ * AST: extract against the node each comment hangs off, then splice into the
+ * serializer's output, located by re-parsing it.
+ *
+ * **Emitting comments from inside a serializer instead drops them silently for
+ * most nodes.** A hand-written concrete-syntax serializer reaches its children
+ * through its own per-`$type` emitters, not through
+ * `AbstractSerializer.serializeNode`, so a hook on that seam is reached by some
+ * nodes and bypassed by the rest — and the ones it misses fail as absence,
+ * which no test notices unless it asserts on exact text.
+ */
+export declare class CommentPreserver implements TriviaPreserver<CommentTrivia> {
+    protected readonly services: HydraniumLanguageServices;
+    /**
+     * **Registering a second preserver under this id throws.** A subclass added
+     * ALONGSIDE the framework's — rather than replacing it by rebinding the
+     * `comments` contribution sub-key — collides here, and the throw surfaces
+     * from the first write rather than from server start, because the service is
+     * constructed lazily. Pass an `id` to run both.
+     */
+    readonly id: string;
+    readonly label = "Comments";
+    /** Default {@link CommentPreserverOptions.maxIsolatedEdits}. */
+    static readonly DEFAULT_ISOLATED_EDITS = 24;
+    protected readonly tracer: Tracer;
+    protected readonly maxIsolatedEdits: number;
+    protected commentTokenNames?: readonly string[];
+    protected indentationTokenNames?: IndentationTokenNames | null;
+    /**
+     * Set for the duration of one {@link extract}: the run
+     * {@link resolveCommentRun} resolved last, so the run's next comment reuses
+     * it.
+     */
+    protected commentRun?: CommentRun;
+    /**
+     * Set for the duration of one {@link extract}: {@link syntaxSpan} per node,
+     * as a block a run is lifted out of would otherwise be measured once per
+     * comment.
+     */
+    protected spanMemo?: Map<CstNode, {
+        readonly offset: number;
+        readonly end: number;
+    } | undefined>;
+    /** Set for the duration of one {@link apply}; see {@link cachedAnchorKey}. */
+    protected keyMemo?: Map<AstNode, string | undefined>;
+    /** Set for the duration of one {@link apply}; see {@link ambiguousRetainedKey}. */
+    protected listVerdicts?: Map<AstNode, Map<string, boolean>>;
+    /** Set for the duration of one {@link apply}; see {@link parse}. */
+    protected lastParse?: {
+        text?: string;
+        uri?: string;
+        document?: LangiumDocument;
+    };
+    constructor(services: HydraniumLanguageServices, options?: CommentPreserverOptions);
+    /**
+     * Every comment terminal the grammar declares, by token name.
+     *
+     * Deliberately NOT `GrammarConfig.multilineCommentRules`, which Langium
+     * populates only with terminals whose regex spans lines — so a grammar that
+     * comments with `//` answers an empty list there and every one of its
+     * comments would be invisible to a capture keyed on it.
+     */
+    protected getCommentTokenNames(): readonly string[];
+    /**
+     * The names of the INDENT and DEDENT tokens the language's
+     * `IndentationAwareTokenBuilder` emits, `undefined` for a lexer that emits
+     * none. Override it for a lexer of your own that emits such tokens.
+     *
+     * They are syntax to the parser only. A DEDENT is zero-width at the start of
+     * the line after its block, and an INDENT covers the whitespace in front of
+     * the block's first line, so a comment line beside either reads as sharing a
+     * line with the block, and moves onto the block's last line or its header.
+     */
+    protected getIndentationTokenNames(): IndentationTokenNames | undefined;
+    protected isIndentation(node: CstNode): boolean;
+    /**
+     * Where the syntax of `node` begins and ends without the indentation tokens
+     * at its edges.
+     */
+    protected syntaxSpan(node: CstNode): {
+        readonly offset: number;
+        readonly end: number;
+    } | undefined;
+    /** The first token of `node` for a `step` of 1, the last for -1, that is neither hidden nor indentation. */
+    protected edgeToken(node: CstNode, step: 1 | -1): CstNode | undefined;
+    /**
+     * Stable identity for one AST node, used to find it again in the
+     * re-serialized text — or `undefined` when no stable identity exists.
+     *
+     * **Read through the `NameProvider`, so the anchor is what the grammar treats
+     * as IDENTITY rather than whatever sits on `name`.** A grammar whose `name`
+     * is a display label, carrying its identifier on another property, would
+     * otherwise anchor comments to a value users retitle freely. A simple
+     * retitle can be matched, but the real identifier remains the safer key.
+     * `NameProviderOptions.nameProperties` names that property.
+     *
+     * **Whatever an override returns must survive a sibling being inserted into
+     * the same list.** A positional key does not: every comment after the
+     * insertion point is then written against the following declaration — a move,
+     * which reads as text the author wrote there and which nothing downstream can
+     * detect. That is why an unidentified node answers `undefined` here rather
+     * than falling back to a container index, and why this cannot delegate to
+     * `ElementKeyProvider`, whose name-based strategy makes exactly that fallback:
+     * its keys are derived and consumed within one snapshot, where no position can
+     * have shifted underneath them.
+     *
+     * Overriding is the supported route for a grammar that identifies some nodes
+     * outside the naming surface altogether — by a cross-reference that is unique
+     * among its siblings, say. Capture and lookup both read this one definition,
+     * so an override cannot make those two disagree.
+     *
+     * **Matching a rename does not read it.** That comparison asks the
+     * `NameProvider` what changed, so a node identified only by an override is
+     * carried across a write that leaves its identity alone and dropped by one
+     * that rewrites it — never misplaced, but never followed either.
+     */
+    protected anchorKey(node: AstNode): string | undefined;
+    /**
+     * Escape the characters {@link anchorKey} builds its keys out of, so a name
+     * containing one cannot spell a key another node also answers to — which
+     * would make two distinct nodes indistinguishable to the lookup.
+     */
+    protected escapeKeySegment(name: string): string;
+    /**
+     * Collect every comment in `document`, each bound to the node it hangs off.
+     *
+     * Call this BEFORE the mutation that prompts the write. The anchors are AST
+     * objects, so a rule that renames one in place is reflected automatically;
+     * capturing afterwards would work too, but capturing first is what keeps the
+     * CST and the comments describing the same state.
+     */
+    extract(document: LangiumDocument): CommentTrivia;
+    /** Recursive half of {@link extract}: one composite node's content, then its children. */
+    protected captureFrom(node: CstNode, source: string, commentTokens: readonly string[], into: DocumentComment[]): void;
+    /**
+     * Decide which node a comment belongs to, and how it sat against it.
+     *
+     * A comment on the same line the previous node ENDED on is that node's
+     * trailing comment — checked first, because by source order it also precedes
+     * whatever comes next, and reading it as the NEXT node's leading comment is
+     * what relocates an end-of-line note onto the following declaration.
+     */
+    protected classify(comment: CstNode, index: number, container: CompositeCstNode, source: string): DocumentComment;
+    /**
+     * Resolves the container {@link classify} anchors `comment` in, and the
+     * comment's adjacent siblings there and the nearest syntax on each side,
+     * without INDENT and DEDENT tokens. The content is that window, not all of
+     * the container's siblings.
+     *
+     * An indentation-aware lexer can emit a block's DEDENT after the comment
+     * lines that follow the block, so the parser nests them in it. An own-line
+     * comment left of the column a block's INDENT opened is lifted out of each
+     * block that ends right after it, with its adjacent hidden nodes, and placed
+     * after that block in the enclosing container.
+     */
+    protected placeAmongSyntax(comment: CstNode, index: number, container: CompositeCstNode, source: string): {
+        readonly container: CompositeCstNode;
+        readonly content: readonly CstNode[];
+        readonly index: number;
+    };
+    /**
+     * The run of hidden nodes around `container.content[index]`, and the blocks
+     * it can be lifted out of: each that ends right after the run and whose
+     * INDENT opened a column, up to the first that does not.
+     */
+    protected resolveCommentRun(index: number, container: CompositeCstNode, source: string): CommentRun;
+    /** The nodes of `content` from `from` in `step` direction up to the first that is syntax, without indentation tokens. */
+    protected neighbours(content: readonly CstNode[], from: number, step: 1 | -1): CstNode[];
+    /** Whether only hidden and indentation tokens follow `index` in `content`. */
+    protected closesAfter(content: readonly CstNode[], index: number): boolean;
+    /** The column the last INDENT before `content[index]` opens, `undefined` without one. */
+    protected openedColumn(content: readonly CstNode[], index: number, source: string): number | undefined;
+    /**
+     * The index of `node` in `content`, found by offset: `indexOf` per lifted
+     * block makes extraction quadratic in a block's siblings.
+     */
+    protected indexIn(content: readonly CstNode[], node: CstNode): number;
+    /** Whether `text` has a line break from `from` up to `to`, without copying the span. */
+    protected breaksLine(text: string, from: number, to: number): boolean;
+    /** The column of `offset` in `text`. */
+    protected columnAt(text: string, offset: number): number;
+    /**
+     * Comment text with CRLF reduced to LF.
+     *
+     * Serializers emit LF, so splicing a comment captured from a CRLF document
+     * verbatim puts lone CR bytes in the middle of LF-terminated lines.
+     */
+    protected normalizeLineEndings(text: string): string;
+    /** Blank lines in a run of whitespace — one fewer than its newlines. */
+    protected countBlankLines(gap: string): number;
+    /**
+     * Splice the captured comments back into `serialized`.
+     *
+     * A comment whose anchor the write deleted, or whose anchor has no stable
+     * key, is dropped — counted at `debug`, because a silent drop is the failure
+     * this preserver exists to remove and an unexplained one just moves it.
+     */
+    apply(serialized: string, trivia: CommentTrivia, uri: URI): string;
+    /** {@link apply}'s body, inside the per-write memos it sets up. */
+    protected applyComments(serialized: string, trivia: CommentTrivia, uri: URI): string;
+    /**
+     * {@link anchorKey}, answered once per node per write.
+     *
+     * The key walks `$container` to the root building a segment each step, and
+     * every stage of a write asks about the same nodes — locating spans, matching
+     * a rename, judging a key the output kept. Recomputing makes each of those
+     * stages cost nodes × depth, and the stages that scan a sibling list do it
+     * once per comment.
+     */
+    protected cachedAnchorKey(node: AstNode): string | undefined;
+    /**
+     * Parse `text` as an unregistered document, or `undefined` when it is not
+     * readable — by reported error, or by a throw from a URI that routes to no
+     * services. Does NOT register the result, so `LangiumDocuments` is untouched.
+     *
+     * Within one {@link apply}, the text and URI parsed last are answered with
+     * the same document rather than parsed again, so a caller must not change
+     * it. One entry, so no document outlives the next parse.
+     */
+    protected parse(text: string, uri: URI): LangiumDocument | undefined;
+    /** The splice itself, run before {@link apply}'s parse check. */
+    protected spliceComments(serialized: string, trivia: CommentTrivia, uri: URI): string;
+    /**
+     * Whether this comment's edit has to be read back before it can be trusted.
+     *
+     * Both cases are the serializer having put the anchor on a line it shares.
+     * A comment that wants the line above has to open one mid-construct; a
+     * comment that wants the end of the anchor's line gets the end of a line that
+     * may belong to a later sibling, and a second such comment lands inside the
+     * first one's text and stops being a comment at all. Neither can be judged
+     * from the offsets alone — only from what the text says once re-read.
+     */
+    protected needsReadBack(comment: DocumentComment, span: AnchorSpan, serialized: string): boolean;
+    /**
+     * Splice `edits` into `serialized`, in the order given.
+     *
+     * Two inline edits landing on one offset collapse into a single opened line,
+     * so a stack of comments above one inline member comes back as a stack rather
+     * than with a blank line between each pair.
+     */
+    protected assembleComments(serialized: string, edits: readonly InlineAwareEdit[]): string;
+    /**
+     * Whether the output node now answering to `source`'s key is too likely to be
+     * a DIFFERENT node for the comment to follow it.
+     *
+     * A key surviving the write normally means the node did. It can also mean a
+     * sibling took the name over, which reads as the author having written the
+     * comment about a declaration they never saw.
+     *
+     * **What is detectable is a list whose members changed places; what is not is
+     * a payload that renames a node and gives its old name to another.** Those
+     * two writes produce the same text and the same keys, and the node carrying
+     * the old name afterwards is byte-identical under both readings, so no rule
+     * over this evidence separates them. A caller that knows which node it
+     * renamed is the only thing that could, and the transfer model carries no
+     * such record.
+     *
+     * **The evidence is the ORDER of the keys the two lists share.** Adding or
+     * removing siblings shifts the rest but leaves them in the same relative
+     * order; only names changing places can put two shared keys out of order. A
+     * list whose shared keys invert is therefore read as exchanged identities and
+     * those siblings lose their comments — which costs a deliberate reorder its
+     * comments, the conservative half of a trade whose other half is that a bare
+     * swap cannot move one.
+     *
+     * **Comparing counts or key SETS instead misses cases each way.** A swap
+     * alongside an insertion leaves the counts differing and the key set whole,
+     * so neither test sees it; a deletion alongside an insertion leaves the counts
+     * equal while every surviving sibling is still itself, so a count test drops
+     * comments that were never in doubt.
+     */
+    protected ambiguousRetainedKey(source: AstNode, output: AstNode): boolean;
+    /**
+     * Whether the two lists differ in a way a plain insertion or deletion cannot
+     * explain — the expensive half of {@link ambiguousRetainedKey}, split out so
+     * it can be answered once per list.
+     *
+     * What says the members may have swapped names rather than moved:
+     *
+     * - **The lists are the same length.** Every rename chain over a fixed set of
+     *   slots looks exactly like the shift a deletion plus an insertion produces,
+     *   and for members carrying nothing but a name the properties match under
+     *   both readings. Neither this nor anything downstream can separate them.
+     * - **Keys present on both sides have changed places.** Adding or removing
+     *   siblings shifts the rest but never reorders them, so an inversion is
+     *   evidence no insertion or deletion can account for — and it is evidence
+     *   the lengths alone miss, since a swap alongside an insertion leaves the
+     *   counts differing and the key set whole.
+     */
+    protected reidentifiedList(sourceParent: AstNode, outputParent: AstNode, property: string): boolean;
+    /**
+     * The inline edits `candidate` did not round-trip: each one whose comment came
+     * back on a different anchor, and — when `candidate` does not parse at all —
+     * each one that cannot be put back beside the others without breaking it
+     * again. `serialized` is the unspliced text those trials are rebuilt from,
+     * since finding the single edit at fault means assembling the rest without it.
+     *
+     * Costs a parse and an extract, so it answers empty without either when
+     * nothing was spliced inline — which is every write into a document the
+     * serializer lays out one declaration per line.
+     */
+    protected unverifiedInlineEdits(candidate: string, edits: readonly InlineAwareEdit[], uri: URI, serialized: string): Set<InlineAwareEdit>;
+    protected renamedKey(anchor: AstNode, oldKey: string, renamed: Map<AstNode, string>): string | undefined;
+    protected matchRenamedAnchors(sourceRoot: AstNode, serialized: string, uri: URI, located: Map<string, AnchorSpan>, sourceOwners: Map<string, AstNode>, sourceCollisions: Set<string>): Map<AstNode, string>;
+    protected sameAsideFromName(source: AstNode, target: AstNode): boolean;
+    /**
+     * The properties `type` declares in the grammar — everything a rename match
+     * may compare, and nothing else.
+     *
+     * **Comparing own keys instead compares derived state, and matches nothing.**
+     * A built document carries whatever `ast.extensions` computed onto its nodes;
+     * the re-parsed serializer output is never built and carries none of it. Every
+     * candidate then differs on a property the grammar never mentioned, so no
+     * rename is ever matched — on the real write path only, because a document a
+     * test parses from a string has no computed state to disagree about.
+     */
+    protected comparableProperties(type: string): readonly string[];
+    protected sameValue(left: unknown, right: unknown): boolean;
+    /** The insertion this comment's placement implies, against its anchor's span. */
+    protected editFor(comment: DocumentComment, span: AnchorSpan, serialized: string): {
+        at: number;
+        text: string;
+    };
+    /**
+     * A multi-line comment's continuation lines, shifted by the same delta its
+     * first line moves — so a block emitted at a new indentation stays square
+     * instead of trailing its original column.
+     *
+     * **Only the leading whitespace run is touched, and an outdent removes at
+     * most what is there** — shifting further would eat the comment's own text.
+     *
+     * Single-line comments and ones sharing a line with code are returned
+     * unchanged.
+     */
+    protected reindent(comment: DocumentComment, targetIndent: string): string;
+    /** Whether everything from `offset` to the end of its line is whitespace. */
+    protected restOfLineIsBlank(text: string, offset: number): boolean;
+    /** Whether `offset` is preceded on its own line by whitespace alone. */
+    protected startOfLineIsBlank(text: string, offset: number): boolean;
+    /**
+     * End of the line `offset` sits on, as an insertion point for a trailing
+     * comment. Stops before a CR so an insertion into CRLF text lands inside the
+     * line rather than between its two terminator bytes.
+     */
+    protected endOfLineAt(text: string, offset: number): number;
+    /** Leading whitespace of the line `offset` sits on, so an insertion lines up with it. */
+    protected indentAt(text: string, offset: number): string;
+    /**
+     * Where every node landed in the serializer's output, keyed by
+     * {@link anchorKey}.
+     *
+     * Re-parses `serialized` through the document factory, which does NOT
+     * register the result, so this leaves `LangiumDocuments` alone. Output the
+     * grammar cannot read, by reported error or by a throw from a URI that
+     * routes to no services, yields `undefined`: the caller then writes the
+     * serializer's text unchanged rather than splicing into text already wrong.
+     *
+     * **A key claimed by two DIFFERENT nodes is removed, not merged.** A repeated
+     * identity is exactly what the integrity tier exists to repair, so collisions
+     * reach this method routinely; merging their spans puts every one of their
+     * comments on whichever came first. Removing the key drops those instead,
+     * which is the only outcome here that keeps a comment off a declaration its
+     * author did not write it on.
+     */
+    protected locate(serialized: string, uri: URI): Map<string, AnchorSpan> | undefined;
+}
+/** Registers {@link CommentPreserver}; bound at `trivia.preservers.comments`. */
+export declare class CommentPreserverContribution implements TriviaContribution {
+    protected readonly services: HydraniumLanguageServices;
+    constructor(services: HydraniumLanguageServices);
+    registerTriviaPreservers(registry: TriviaRegistry): void;
+}
+//# sourceMappingURL=comment-preserver.d.ts.map

package/lib/langium/trivia/comment-preserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-preserver.d.ts","sourceRoot":"","sources":["../../../src/langium/trivia/comment-preserver.ts"],"names":[],"mappings":"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"}