@hydranium/core 1.0.0-next.38 → 1.0.0-next.380

package/lib/langium/trivia/comment-preserver.js

@@ -0,0 +1,1165 @@
+/********************************************************************************
+ * 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 { AstUtils, GrammarAST, GrammarUtils, IndentationAwareTokenBuilder, isAstNode } from '@hydranium/langium';
+import { hasSyntaxErrors } from '../workspace/syntax-errors.js';
+function isComposite(node) {
+    return 'content' in node;
+}
+function tokenNameOf(node) {
+    return 'tokenType' in node ? node.tokenType.name : undefined;
+}
+/**
+ * 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 class CommentPreserver {
+    services;
+    /**
+     * **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.
+     */
+    id;
+    label = 'Comments';
+    /** Default {@link CommentPreserverOptions.maxIsolatedEdits}. */
+    static DEFAULT_ISOLATED_EDITS = 24;
+    tracer;
+    maxIsolatedEdits;
+    commentTokenNames;
+    indentationTokenNames;
+    /**
+     * Set for the duration of one {@link extract}: the run
+     * {@link resolveCommentRun} resolved last, so the run's next comment reuses
+     * it.
+     */
+    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.
+     */
+    spanMemo;
+    /** Set for the duration of one {@link apply}; see {@link cachedAnchorKey}. */
+    keyMemo;
+    /** Set for the duration of one {@link apply}; see {@link ambiguousRetainedKey}. */
+    listVerdicts;
+    /** Set for the duration of one {@link apply}; see {@link parse}. */
+    lastParse;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.id = options.id ?? 'comments';
+        this.maxIsolatedEdits = options.maxIsolatedEdits ?? CommentPreserver.DEFAULT_ISOLATED_EDITS;
+        this.tracer = services.shared.Tracer.for(options.logName ?? 'CommentPreserver');
+    }
+    /**
+     * 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.
+     */
+    getCommentTokenNames() {
+        if (!this.commentTokenNames) {
+            this.commentTokenNames = this.services.Grammar.rules
+                .filter(GrammarAST.isTerminalRule)
+                .filter(rule => GrammarUtils.isCommentTerminal(rule))
+                .map(rule => rule.name);
+        }
+        return this.commentTokenNames;
+    }
+    /**
+     * 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.
+     */
+    getIndentationTokenNames() {
+        if (this.indentationTokenNames === undefined) {
+            const builder = this.services.parser.TokenBuilder;
+            this.indentationTokenNames =
+                builder instanceof IndentationAwareTokenBuilder
+                    ? { indent: builder.indentTokenType.name, dedent: builder.dedentTokenType.name }
+                    : null;
+        }
+        return this.indentationTokenNames ?? undefined;
+    }
+    isIndentation(node) {
+        const names = this.getIndentationTokenNames();
+        const name = tokenNameOf(node);
+        return names !== undefined && (name === names.indent || name === names.dedent);
+    }
+    /**
+     * Where the syntax of `node` begins and ends without the indentation tokens
+     * at its edges.
+     */
+    syntaxSpan(node) {
+        if (this.getIndentationTokenNames() === undefined) {
+            return node;
+        }
+        if (this.spanMemo?.has(node)) {
+            return this.spanMemo.get(node);
+        }
+        const first = this.edgeToken(node, 1);
+        const last = this.edgeToken(node, -1);
+        const span = first && last && { offset: first.offset, end: last.end };
+        this.spanMemo?.set(node, span);
+        return span;
+    }
+    /** The first token of `node` for a `step` of 1, the last for -1, that is neither hidden nor indentation. */
+    edgeToken(node, step) {
+        if (!isComposite(node)) {
+            return node.hidden || this.isIndentation(node) ? undefined : node;
+        }
+        const content = node.content;
+        for (let index = step > 0 ? 0 : content.length - 1; index >= 0 && index < content.length; index += step) {
+            const found = this.edgeToken(content[index], step);
+            if (found !== undefined) {
+                return found;
+            }
+        }
+        return 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.
+     */
+    anchorKey(node) {
+        const nameProvider = this.services.references.NameProvider;
+        const segments = [];
+        let current = node;
+        while (current?.$container) {
+            const name = nameProvider.getOwnName(current);
+            if (name === undefined || name.length === 0) {
+                return undefined;
+            }
+            segments.unshift(`${current.$type}#${this.escapeKeySegment(name)}`);
+            current = current.$container;
+        }
+        return segments.length === 0 ? `@root:${node.$type}` : segments.join('/');
+    }
+    /**
+     * 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.
+     */
+    escapeKeySegment(name) {
+        return name.replace(/[\\#/]/g, character => `\\${character}`);
+    }
+    /**
+     * 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) {
+        // The capture reads the CST, which a residency policy may have shed.
+        // Restored rather than skipped: skipping would lose the whole file's
+        // comments for a document that had gone idle, silently and only under a
+        // shedding strategy.
+        this.services.shared.workspace.CstResidencyService.rehydrate(document);
+        const root = document.parseResult.value.$cstNode;
+        const commentTokens = this.getCommentTokenNames();
+        if (!root || commentTokens.length === 0) {
+            return { comments: [], sourceRoot: document.parseResult.value };
+        }
+        const source = document.textDocument.getText();
+        const comments = [];
+        this.commentRun = undefined;
+        this.spanMemo = new Map();
+        try {
+            this.captureFrom(root, source, commentTokens, comments);
+        }
+        finally {
+            this.commentRun = undefined;
+            this.spanMemo = undefined;
+        }
+        return { comments, sourceRoot: document.parseResult.value };
+    }
+    /** Recursive half of {@link extract}: one composite node's content, then its children. */
+    captureFrom(node, source, commentTokens, into) {
+        if (!isComposite(node)) {
+            return;
+        }
+        const content = node.content;
+        content.forEach((child, index) => {
+            const tokenName = tokenNameOf(child);
+            if (child.hidden && tokenName !== undefined && commentTokens.includes(tokenName)) {
+                into.push(this.classify(child, index, node, source));
+            }
+            this.captureFrom(child, source, commentTokens, into);
+        });
+    }
+    /**
+     * 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.
+     */
+    classify(comment, index, container, source) {
+        const placed = this.placeAmongSyntax(comment, index, container, source);
+        const owner = placed.container;
+        const content = placed.content;
+        const at = placed.index;
+        const ownsOwnNode = (candidate) => candidate?.astNode !== undefined && candidate.astNode !== owner.astNode;
+        const realSibling = (from, step) => {
+            for (let scan = from; scan >= 0 && scan < content.length; scan += step) {
+                if (!content[scan].hidden) {
+                    return content[scan];
+                }
+            }
+            return undefined;
+        };
+        const offsetOf = (node) => this.syntaxSpan(node)?.offset ?? node.offset;
+        const endOf = (node) => this.syntaxSpan(node)?.end ?? node.end;
+        const previous = realSibling(at - 1, -1);
+        const next = realSibling(at + 1, 1);
+        // Measured to whatever comes NEXT IN SOURCE, comment or not — never to the
+        // next real node, which would skip the rest of a comment block and make
+        // every line of it re-emit the whole gap that follows the block.
+        const following = content[at + 1];
+        const blankLinesAfter = following === undefined ? 0 : this.countBlankLines(source.slice(comment.end, offsetOf(following)));
+        const preceding = at > 0 ? content[at - 1] : undefined;
+        // From the last text before the comment: a block it is lifted out of can
+        // end with comment lines of its own, after the block's syntax.
+        const precedingEnd = preceding === undefined ? comment.offset : endOf(preceding);
+        let gapStart = comment.offset;
+        while (gapStart > precedingEnd && /\s/.test(source[gapStart - 1])) {
+            gapStart--;
+        }
+        const blankLinesBefore = preceding === undefined ? 0 : this.countBlankLines(source.slice(gapStart, comment.offset));
+        // Only a comment that OWNS its line can be reindented — one sharing a line
+        // with code keeps whatever spacing that line gives it.
+        const lineStart = source.lastIndexOf('\n', comment.offset - 1) + 1;
+        const beforeOnLine = source.slice(lineStart, comment.offset);
+        const sourceIndent = beforeOnLine.trim().length === 0 ? beforeOnLine : undefined;
+        const text = this.normalizeLineEndings(comment.text);
+        const sharesLineWithPrevious = previous !== undefined && !this.breaksLine(source, endOf(previous), comment.offset);
+        if (sharesLineWithPrevious) {
+            // On the same line as whatever precedes it, so it annotates that line.
+            // When the preceding sibling is the CONTAINER's own syntax — an opening
+            // brace, a name token, a keyword — the line is the container's header
+            // and the comment belongs to the container, NOT to the first member
+            // that happens to follow. Reading it as that member's leading comment
+            // moves a note about the declaration onto its first child.
+            return ownsOwnNode(previous)
+                ? { text, anchor: previous.astNode, placement: 'trailing', blankLinesAfter: 0, blankLinesBefore: 0 }
+                : { text, anchor: owner.astNode, placement: 'trailingOnContainer', blankLinesAfter: 0, blankLinesBefore: 0 };
+        }
+        if (ownsOwnNode(next)) {
+            return { text, anchor: next.astNode, placement: 'leading', blankLinesAfter, blankLinesBefore: 0, sourceIndent };
+        }
+        if (ownsOwnNode(previous)) {
+            return { text, anchor: previous.astNode, placement: 'afterNode', blankLinesAfter: 0, blankLinesBefore, sourceIndent };
+        }
+        if (previous === undefined) {
+            return { text, anchor: owner.astNode, placement: 'atContainerStart', blankLinesAfter, blankLinesBefore: 0, sourceIndent };
+        }
+        // Surrounded by the container's own syntax on both sides. A further
+        // sibling after it means the comment sits INSIDE the construct — between
+        // the braces of an empty body, or partway through a header — so it stays
+        // with the container rather than being pushed past its closing syntax,
+        // which would move it out to the enclosing scope. Only a comment with
+        // nothing after it at all actually trails the container.
+        const placement = next === undefined ? 'atContainerEnd' : 'trailingOnContainer';
+        return { text, anchor: owner.astNode, placement, blankLinesAfter, blankLinesBefore, sourceIndent };
+    }
+    /**
+     * 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.
+     */
+    placeAmongSyntax(comment, index, container, source) {
+        const content = container.content;
+        const run = this.resolveCommentRun(index, container, source);
+        let placed = 0;
+        if (run.targets.length > 1 && (run.previous === undefined || this.breaksLine(source, run.previous.end, comment.offset))) {
+            const column = this.columnAt(source, comment.offset);
+            while (placed + 1 < run.targets.length && column < (run.targets[placed + 1].liftBelow ?? 0)) {
+                placed++;
+            }
+        }
+        const { container: parent, closed } = run.targets[placed];
+        const before = closed ? [closed] : run.before;
+        const around = content.slice(Math.max(index - 1, run.start), Math.min(index + 1, run.end) + 1);
+        const view = [...before, ...around, ...run.after[placed]];
+        return { container: parent, content: view, index: before.length + (index > run.start ? 1 : 0) };
+    }
+    /**
+     * 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.
+     */
+    resolveCommentRun(index, container, source) {
+        const content = container.content;
+        const cached = this.commentRun;
+        // Resolved once per run, not per comment: a run of k comment lines would
+        // otherwise cost k scans of the run.
+        if (cached?.content === content && index >= cached.start && index <= cached.end) {
+            return cached;
+        }
+        let start = index;
+        while (start > 0 && content[start - 1].hidden) {
+            start--;
+        }
+        let end = index;
+        while (end + 1 < content.length && content[end + 1].hidden) {
+            end++;
+        }
+        let previous;
+        const targets = [{ container, last: end }];
+        if (this.getIndentationTokenNames() !== undefined) {
+            for (let scan = start - 1; scan >= 0 && previous === undefined; scan--) {
+                previous = content[scan].hidden ? undefined : this.syntaxSpan(content[scan]);
+            }
+            let target = targets[0];
+            while (target.container.container && this.closesAfter(target.container.content, target.last)) {
+                const opened = this.openedColumn(target.container.content, target.closed ? target.last : start, source) ?? 0;
+                if (opened === 0) {
+                    break;
+                }
+                const parent = target.container.container;
+                target = {
+                    container: parent,
+                    last: this.indexIn(parent.content, target.container),
+                    closed: target.container,
+                    liftBelow: opened
+                };
+                targets.push(target);
+            }
+        }
+        const before = this.neighbours(content, start - 1, -1).reverse();
+        const after = targets.map(target => this.neighbours(target.container.content, target.last + 1, 1));
+        return (this.commentRun = { content, start, end, previous, targets, before, after });
+    }
+    /** The nodes of `content` from `from` in `step` direction up to the first that is syntax, without indentation tokens. */
+    neighbours(content, from, step) {
+        const found = [];
+        for (let scan = from; scan >= 0 && scan < content.length; scan += step) {
+            const node = content[scan];
+            if (!this.isIndentation(node)) {
+                found.push(node);
+                if (!node.hidden) {
+                    break;
+                }
+            }
+        }
+        return found;
+    }
+    /** Whether only hidden and indentation tokens follow `index` in `content`. */
+    closesAfter(content, index) {
+        for (let scan = index + 1; scan < content.length; scan++) {
+            if (!content[scan].hidden && !this.isIndentation(content[scan])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** The column the last INDENT before `content[index]` opens, `undefined` without one. */
+    openedColumn(content, index, source) {
+        const indent = this.getIndentationTokenNames()?.indent;
+        for (let scan = index - 1; scan >= 0; scan--) {
+            if (tokenNameOf(content[scan]) === indent) {
+                return this.columnAt(source, content[scan].end);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * The index of `node` in `content`, found by offset: `indexOf` per lifted
+     * block makes extraction quadratic in a block's siblings.
+     */
+    indexIn(content, node) {
+        let low = 0;
+        let high = content.length;
+        while (low < high) {
+            const middle = (low + high) >> 1;
+            if (content[middle].offset < node.offset) {
+                low = middle + 1;
+            }
+            else {
+                high = middle;
+            }
+        }
+        // Zero-width tokens can share the node's offset.
+        for (let index = low; index < content.length && content[index].offset === node.offset; index++) {
+            if (content[index] === node) {
+                return index;
+            }
+        }
+        return content.indexOf(node);
+    }
+    /** Whether `text` has a line break from `from` up to `to`, without copying the span. */
+    breaksLine(text, from, to) {
+        // Not indexOf, which scans on to the next line break past `to`.
+        for (let offset = from; offset < to; offset++) {
+            if (text.charCodeAt(offset) === 10) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** The column of `offset` in `text`. */
+    columnAt(text, offset) {
+        return offset - (text.lastIndexOf('\n', offset - 1) + 1);
+    }
+    /**
+     * 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.
+     */
+    normalizeLineEndings(text) {
+        return text.includes('\r') ? text.replace(/\r\n/g, '\n') : text;
+    }
+    /** Blank lines in a run of whitespace — one fewer than its newlines. */
+    countBlankLines(gap) {
+        return Math.max(0, (gap.match(/\n/g)?.length ?? 0) - 1);
+    }
+    /**
+     * 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, trivia, uri) {
+        if (trivia.comments.length === 0) {
+            return serialized;
+        }
+        // The memos are scoped to this call and not to the instance, because an
+        // in-place write changes what a node's key IS: a repair that renames a
+        // node between two writes would otherwise be answered from the first.
+        this.keyMemo = new Map();
+        this.listVerdicts = new Map();
+        this.lastParse = {};
+        try {
+            return this.applyComments(serialized, trivia, uri);
+        }
+        finally {
+            this.keyMemo = undefined;
+            this.listVerdicts = undefined;
+            this.lastParse = undefined;
+        }
+    }
+    /** {@link apply}'s body, inside the per-write memos it sets up. */
+    applyComments(serialized, trivia, uri) {
+        const spliced = this.spliceComments(serialized, trivia, uri);
+        // **Never hand back text the grammar cannot read.** A splice edits syntax
+        // it did not produce, and a line comment in particular ends whatever
+        // shares its line — so a placement that is merely wrong becomes a file
+        // that no longer parses, written to disk by an integrity repair with no
+        // user gesture. Dropping the comments is recoverable; corrupting the
+        // document is not.
+        if (spliced !== serialized && this.parse(spliced, uri) === undefined) {
+            this.tracer.withUri(uri.toString()).warn('Reattaching comments produced text that does not parse; writing without them');
+            return serialized;
+        }
+        return spliced;
+    }
+    /**
+     * {@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.
+     */
+    cachedAnchorKey(node) {
+        const memo = this.keyMemo;
+        if (memo === undefined) {
+            return this.anchorKey(node);
+        }
+        if (!memo.has(node)) {
+            memo.set(node, this.anchorKey(node));
+        }
+        return memo.get(node);
+    }
+    /**
+     * 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.
+     */
+    parse(text, uri) {
+        const memo = this.lastParse;
+        if (memo !== undefined && memo.text === text && memo.uri === uri.toString()) {
+            return memo.document;
+        }
+        let document;
+        try {
+            document = this.services.shared.workspace.LangiumDocumentFactory.fromString(text, uri);
+        }
+        catch {
+            document = undefined;
+        }
+        if (document !== undefined && hasSyntaxErrors(document.parseResult)) {
+            document = undefined;
+        }
+        if (memo !== undefined) {
+            memo.text = text;
+            memo.uri = uri.toString();
+            memo.document = document;
+        }
+        return document;
+    }
+    /** The splice itself, run before {@link apply}'s parse check. */
+    spliceComments(serialized, trivia, uri) {
+        const located = this.locate(serialized, uri);
+        if (located === undefined) {
+            return serialized;
+        }
+        const sourceOwners = new Map();
+        const sourceCollisions = new Set();
+        const liveAnchors = new Set();
+        for (const node of [trivia.sourceRoot, ...AstUtils.streamAllContents(trivia.sourceRoot)]) {
+            liveAnchors.add(node);
+            const key = this.cachedAnchorKey(node);
+            if (key === undefined) {
+                continue;
+            }
+            const owner = sourceOwners.get(key);
+            if (owner !== undefined && owner !== node) {
+                sourceCollisions.add(key);
+            }
+            else {
+                sourceOwners.set(key, node);
+            }
+        }
+        const needsRename = trivia.comments.some(comment => {
+            const key = this.cachedAnchorKey(comment.anchor);
+            return key !== undefined && !located.has(key);
+        });
+        const renamed = needsRename
+            ? this.matchRenamedAnchors(trivia.sourceRoot, serialized, uri, located, sourceOwners, sourceCollisions)
+            : new Map();
+        const edits = [];
+        let dropped = 0;
+        trivia.comments.forEach((comment, order) => {
+            const key = this.cachedAnchorKey(comment.anchor);
+            const destination = key === undefined ? undefined : located.has(key) ? key : this.renamedKey(comment.anchor, key, renamed);
+            const retained = destination === key ? located.get(key) : undefined;
+            const span = key === undefined ||
+                !liveAnchors.has(comment.anchor) ||
+                sourceCollisions.has(key) ||
+                destination === undefined ||
+                (retained !== undefined && this.ambiguousRetainedKey(comment.anchor, retained.owner))
+                ? undefined
+                : located.get(destination);
+            if (span === undefined) {
+                dropped++;
+                return;
+            }
+            const edit = this.editFor(comment, span, serialized);
+            edits.push({
+                ...edit,
+                order,
+                inline: this.needsReadBack(comment, span, serialized) ? { text: comment.text, key: destination } : undefined
+            });
+        });
+        if (dropped > 0) {
+            this.tracer.withUri(uri.toString()).debug(`Dropped ${dropped} comment(s): anchor deleted by the write, or carrying no stable key`);
+        }
+        // Stable by offset, then by capture order, so several comments landing on
+        // one anchor keep the order the author wrote them in.
+        edits.sort((left, right) => left.at - right.at || left.order - right.order);
+        // **This is what licenses the mid-line split** `editFor` makes for a
+        // `leading` comment whose anchor does not start its line. Parsing alone
+        // cannot license it: text can parse perfectly well having handed the
+        // comment to the following declaration instead. Re-extracting and
+        // requiring the same anchor back is the only evidence the comment still
+        // belongs where its author put it.
+        //
+        // A failed edit is dropped and the rest reassembled, since removing one
+        // changes what the others land in; two rounds, then the inline edits go
+        // as a set rather than iterating towards a text nothing has verified.
+        let remaining = edits;
+        let result = this.assembleComments(serialized, remaining);
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const failed = this.unverifiedInlineEdits(result, remaining, uri, serialized);
+            if (failed.size === 0) {
+                return result;
+            }
+            remaining = remaining.filter(edit => !failed.has(edit));
+            result = this.assembleComments(serialized, remaining);
+        }
+        return this.assembleComments(serialized, remaining.filter(edit => edit.inline === undefined));
+    }
+    /**
+     * 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.
+     */
+    needsReadBack(comment, span, serialized) {
+        if (comment.placement === 'leading' || comment.placement === 'atContainerStart') {
+            return !this.startOfLineIsBlank(serialized, span.offset);
+        }
+        return comment.placement === 'trailing' && this.endOfLineAt(serialized, span.end) !== span.end;
+    }
+    /**
+     * 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.
+     */
+    assembleComments(serialized, edits) {
+        let result = '';
+        let cursor = 0;
+        let previousInlineAt;
+        for (const edit of edits) {
+            const text = edit.inline !== undefined && edit.at === previousInlineAt ? edit.text.replace(/^\n[ \t]*/, '') : edit.text;
+            result += serialized.slice(cursor, edit.at) + text;
+            cursor = edit.at;
+            previousInlineAt = edit.inline !== undefined ? edit.at : undefined;
+        }
+        return result + serialized.slice(cursor);
+    }
+    /**
+     * 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.
+     */
+    ambiguousRetainedKey(source, output) {
+        const sourceParent = source.$container;
+        const outputParent = output.$container;
+        if (!sourceParent || !outputParent) {
+            return false;
+        }
+        const parentKey = this.cachedAnchorKey(sourceParent);
+        if (parentKey !== this.cachedAnchorKey(outputParent) || source.$containerProperty !== output.$containerProperty) {
+            return true;
+        }
+        if (source.$containerIndex === output.$containerIndex) {
+            return false;
+        }
+        const property = source.$containerProperty;
+        if (property === undefined) {
+            return true;
+        }
+        // Answered once per list rather than once per comment. One insertion moves
+        // every later sibling, so each of their comments asks the same question of
+        // the same two lists — and scanning both per comment costs the list's
+        // length squared.
+        //
+        // Memoised against the parent NODE rather than its key, because two
+        // same-named parents answer to one key and would otherwise share a verdict
+        // about lists that have nothing to do with each other.
+        const cached = this.listVerdicts?.get(sourceParent)?.get(property);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const verdict = this.reidentifiedList(sourceParent, outputParent, property);
+        if (this.listVerdicts !== undefined) {
+            const byProperty = this.listVerdicts.get(sourceParent) ?? new Map();
+            byProperty.set(property, verdict);
+            this.listVerdicts.set(sourceParent, byProperty);
+        }
+        return verdict;
+    }
+    /**
+     * 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.
+     */
+    reidentifiedList(sourceParent, outputParent, property) {
+        const before = sourceParent[property];
+        const after = outputParent[property];
+        if (!Array.isArray(before) || !Array.isArray(after)) {
+            return true;
+        }
+        if (before.length === after.length) {
+            return true;
+        }
+        const positions = new Map();
+        after.filter(isAstNode).forEach((node, index) => {
+            const key = this.cachedAnchorKey(node);
+            if (key !== undefined && !positions.has(key)) {
+                positions.set(key, index);
+            }
+        });
+        let furthest = -1;
+        for (const node of before.filter(isAstNode)) {
+            const key = this.cachedAnchorKey(node);
+            const position = key === undefined ? undefined : positions.get(key);
+            if (position === undefined) {
+                continue;
+            }
+            if (position < furthest) {
+                return true;
+            }
+            furthest = position;
+        }
+        return false;
+    }
+    /**
+     * 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.
+     */
+    unverifiedInlineEdits(candidate, edits, uri, serialized) {
+        const inlineEdits = edits.filter(edit => edit.inline !== undefined);
+        if (inlineEdits.length === 0) {
+            return new Set();
+        }
+        const reparsed = this.parse(candidate, uri);
+        if (reparsed === undefined) {
+            if (inlineEdits.length > this.maxIsolatedEdits) {
+                this.tracer
+                    .withUri(uri.toString())
+                    .debug(`Spliced text did not parse; dropping ${inlineEdits.length} shared-line comments without isolating`);
+                return new Set(inlineEdits);
+            }
+            const retained = edits.filter(edit => edit.inline === undefined);
+            const failed = new Set();
+            for (const edit of inlineEdits) {
+                const trial = [...retained, edit].sort((left, right) => left.at - right.at || left.order - right.order);
+                const text = this.assembleComments(serialized, trial);
+                if (this.parse(text, uri) !== undefined && this.unverifiedInlineEdits(text, trial, uri, serialized).size === 0) {
+                    retained.push(edit);
+                }
+                else {
+                    failed.add(edit);
+                }
+            }
+            return failed;
+        }
+        // Counted rather than scanned per edit: several comments can share an
+        // anchor and a text, and each edit must consume one of them.
+        const captured = new Map();
+        for (const comment of this.extract(reparsed).comments) {
+            const seen = `${this.cachedAnchorKey(comment.anchor) ?? ''}\u0000${comment.text}`;
+            captured.set(seen, (captured.get(seen) ?? 0) + 1);
+        }
+        const failed = new Set();
+        for (const edit of inlineEdits) {
+            const expected = edit.inline;
+            const wanted = `${expected.key}\u0000${expected.text}`;
+            const remaining = captured.get(wanted) ?? 0;
+            if (remaining === 0) {
+                failed.add(edit);
+            }
+            else {
+                captured.set(wanted, remaining - 1);
+            }
+        }
+        return failed;
+    }
+    renamedKey(anchor, oldKey, renamed) {
+        let current = anchor;
+        while (current !== undefined) {
+            const newPrefix = renamed.get(current);
+            const oldPrefix = this.cachedAnchorKey(current);
+            if (newPrefix !== undefined && oldPrefix !== undefined && (oldKey === oldPrefix || oldKey.startsWith(`${oldPrefix}/`))) {
+                return newPrefix + oldKey.slice(oldPrefix.length);
+            }
+            current = current.$container;
+        }
+        return undefined;
+    }
+    matchRenamedAnchors(sourceRoot, serialized, uri, located, sourceOwners, sourceCollisions) {
+        const matches = new Map();
+        const output = this.parse(serialized, uri);
+        if (output === undefined) {
+            return matches;
+        }
+        const outputNodes = [output.parseResult.value, ...AstUtils.streamAllContents(output.parseResult.value)];
+        const unmatchedBySlot = new Map();
+        for (const node of outputNodes) {
+            const key = this.cachedAnchorKey(node);
+            const parent = node.$container && this.cachedAnchorKey(node.$container);
+            if (key === undefined || !located.has(key) || sourceOwners.has(key) || parent === undefined) {
+                continue;
+            }
+            const slot = JSON.stringify([parent, node.$containerProperty, node.$containerIndex, node.$type]);
+            const candidates = unmatchedBySlot.get(slot) ?? [];
+            candidates.push(node);
+            unmatchedBySlot.set(slot, candidates);
+        }
+        const claimed = new Map();
+        const ambiguous = new Set();
+        for (const source of [sourceRoot, ...AstUtils.streamAllContents(sourceRoot)]) {
+            const key = this.cachedAnchorKey(source);
+            if (key === undefined || sourceCollisions.has(key) || located.has(key) || !source.$container) {
+                continue;
+            }
+            const parentKey = this.cachedAnchorKey(source.$container);
+            if (parentKey === undefined) {
+                continue;
+            }
+            const slot = JSON.stringify([parentKey, source.$containerProperty, source.$containerIndex, source.$type]);
+            const candidates = (unmatchedBySlot.get(slot) ?? []).filter(candidate => this.sameAsideFromName(source, candidate));
+            if (candidates.length === 1) {
+                const candidate = candidates[0];
+                if (ambiguous.has(candidate)) {
+                    continue;
+                }
+                if (claimed.has(candidate)) {
+                    matches.delete(claimed.get(candidate));
+                    ambiguous.add(candidate);
+                }
+                else {
+                    matches.set(source, this.cachedAnchorKey(candidate));
+                }
+                claimed.set(candidate, source);
+            }
+        }
+        return matches;
+    }
+    sameAsideFromName(source, target) {
+        const nameProvider = this.services.references.NameProvider;
+        const before = nameProvider.getOwnName(source);
+        const after = nameProvider.getOwnName(target);
+        if (before === undefined || after === undefined || before === after) {
+            return false;
+        }
+        let renamed = false;
+        for (const key of this.comparableProperties(source.$type)) {
+            const oldValue = source[key];
+            const newValue = target[key];
+            if (oldValue === before && newValue === after) {
+                renamed = true;
+            }
+            else if (!this.sameValue(oldValue, newValue)) {
+                return false;
+            }
+        }
+        return renamed;
+    }
+    /**
+     * 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.
+     */
+    comparableProperties(type) {
+        return Object.keys(this.services.shared.AstReflection.getTypeMetaData(type).properties);
+    }
+    sameValue(left, right) {
+        if (left === right) {
+            return true;
+        }
+        if (Array.isArray(left) && Array.isArray(right)) {
+            return left.length === right.length && left.every((value, index) => this.sameValue(value, right[index]));
+        }
+        if (isAstNode(left) && isAstNode(right)) {
+            if (left.$type !== right.$type) {
+                return false;
+            }
+            return this.comparableProperties(left.$type).every(key => this.sameValue(left[key], right[key]));
+        }
+        if (left !== null && right !== null && typeof left === 'object' && typeof right === 'object') {
+            if ('$refText' in left && '$refText' in right) {
+                return left.$refText === right.$refText;
+            }
+        }
+        return false;
+    }
+    /** The insertion this comment's placement implies, against its anchor's span. */
+    editFor(comment, span, serialized) {
+        const blanks = '\n'.repeat(comment.blankLinesAfter);
+        const blanksBefore = '\n'.repeat(comment.blankLinesBefore);
+        switch (comment.placement) {
+            case 'trailing':
+                return { at: this.endOfLineAt(serialized, span.end), text: ` ${comment.text}` };
+            // Appended to the container's FIRST line, which is its header. The
+            // comment may have sat further along that line in the source — mid
+            // header, or between braces the serializer has since collapsed to `{}`
+            // — and the exact column is not recoverable from a re-emitted
+            // document. The line is, and that is what keeps it on its own
+            // declaration instead of on a neighbour.
+            case 'trailingOnContainer':
+                return { at: this.endOfLineAt(serialized, span.offset), text: ` ${comment.text}` };
+            // Both of these open a NEW line after the anchor, which is only safe
+            // while nothing else shares the anchor's line. When the serializer put
+            // the anchor and its container's closing syntax together — an inline
+            // enum body, say — splitting there pushes that syntax onto the comment's
+            // line, and a line comment then ends the construct. Appending to the
+            // line instead keeps the comment on the same declaration and the
+            // document readable.
+            case 'afterNode': {
+                if (!this.restOfLineIsBlank(serialized, span.end)) {
+                    return { at: this.endOfLineAt(serialized, span.end), text: ` ${comment.text}` };
+                }
+                const indent = this.indentAt(serialized, span.offset);
+                return { at: span.end, text: `\n${blanksBefore}${indent}${this.reindent(comment, indent)}` };
+            }
+            case 'atContainerEnd':
+                return this.restOfLineIsBlank(serialized, span.end)
+                    ? { at: span.end, text: `\n${blanksBefore}${comment.text}` }
+                    : { at: this.endOfLineAt(serialized, span.end), text: ` ${comment.text}` };
+            case 'atContainerStart':
+            case 'leading':
+            default: {
+                // `leading` means "on the line above", and the anchor may sit
+                // mid-line — a member of a body the serializer emitted inline.
+                // **Opening a line there is sound only because the caller reads the
+                // result back and requires this comment on this same anchor**,
+                // dropping the edit when it is not. Unguarded, the split strands the
+                // rest of the construct at column zero and lands somewhere different
+                // again on the next write.
+                if (!this.startOfLineIsBlank(serialized, span.offset)) {
+                    const indent = comment.sourceIndent ?? this.indentAt(serialized, span.offset);
+                    return { at: span.offset, text: `\n${indent}${this.reindent(comment, indent)}\n${blanks}${indent}` };
+                }
+                const indent = this.indentAt(serialized, span.offset);
+                return { at: span.offset, text: `${this.reindent(comment, indent)}\n${blanks}${indent}` };
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    reindent(comment, targetIndent) {
+        if (comment.sourceIndent === undefined || !comment.text.includes('\n')) {
+            return comment.text;
+        }
+        // Indentation is compared as characters, which only means anything while
+        // both sides use the SAME whitespace character. A tab-indented source
+        // re-emitted with spaces has no meaningful delta, and shifting by one
+        // anyway prepends spaces in front of tabs.
+        const sourceUnit = /^\t*$/.test(comment.sourceIndent) ? '\t' : ' ';
+        const targetUnit = /^\t*$/.test(targetIndent) ? '\t' : ' ';
+        const delta = targetIndent.length - comment.sourceIndent.length;
+        if (delta === 0 || sourceUnit !== targetUnit) {
+            return comment.text;
+        }
+        const [first, ...rest] = comment.text.split('\n');
+        const shifted = rest.map(line => {
+            if (delta > 0) {
+                return targetUnit.repeat(delta) + line;
+            }
+            const removable = /^[ \t]*/.exec(line)?.[0].length ?? 0;
+            return line.slice(Math.min(-delta, removable));
+        });
+        return [first, ...shifted].join('\n');
+    }
+    /** Whether everything from `offset` to the end of its line is whitespace. */
+    restOfLineIsBlank(text, offset) {
+        return text.slice(offset, this.endOfLineAt(text, offset)).trim().length === 0;
+    }
+    /** Whether `offset` is preceded on its own line by whitespace alone. */
+    startOfLineIsBlank(text, offset) {
+        return text.slice(text.lastIndexOf('\n', offset - 1) + 1, offset).trim().length === 0;
+    }
+    /**
+     * 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.
+     */
+    endOfLineAt(text, offset) {
+        const newline = text.indexOf('\n', offset);
+        const lineEnd = newline < 0 ? text.length : newline;
+        return lineEnd > 0 && text[lineEnd - 1] === '\r' ? lineEnd - 1 : lineEnd;
+    }
+    /** Leading whitespace of the line `offset` sits on, so an insertion lines up with it. */
+    indentAt(text, offset) {
+        const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
+        return /^\s*/.exec(text.slice(lineStart, offset))?.[0] ?? '';
+    }
+    /**
+     * 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.
+     */
+    locate(serialized, uri) {
+        const document = this.parse(serialized, uri);
+        if (document === undefined) {
+            this.tracer.withUri(uri.toString()).warn('Serialized output did not re-parse; writing it without comments');
+            return undefined;
+        }
+        const root = document.parseResult.value.$cstNode;
+        if (!root) {
+            return undefined;
+        }
+        const found = new Map();
+        // One AST node owns many CST nodes — its composite plus every token under
+        // it — so a repeated key is only a collision when a DIFFERENT node claims
+        // it. Tracking the owner is what separates the two.
+        const owners = new Map();
+        const collided = new Set();
+        // One AST node owns every CST node beneath it, so this asks for the same
+        // key once per token; `cachedAnchorKey` is what keeps the pass from
+        // costing nodes x depth.
+        const visit = (node) => {
+            const key = node.astNode !== undefined && !node.hidden ? this.cachedAnchorKey(node.astNode) : undefined;
+            // Without the indentation tokens, whose DEDENT would end a block at
+            // the start of the line after it.
+            const span = key === undefined ? undefined : this.syntaxSpan(node);
+            if (key !== undefined && span !== undefined) {
+                const owner = owners.get(key);
+                if (owner === undefined) {
+                    owners.set(key, node.astNode);
+                    found.set(key, { offset: span.offset, end: span.end, owner: node.astNode });
+                }
+                else if (owner === node.astNode) {
+                    // Widest span per node: its first CST node gives the start, a
+                    // later token contributing to the same node extends the end.
+                    const existing = found.get(key);
+                    found.set(key, {
+                        offset: Math.min(existing.offset, span.offset),
+                        end: Math.max(existing.end, span.end),
+                        owner: existing.owner
+                    });
+                }
+                else {
+                    collided.add(key);
+                }
+            }
+            if (isComposite(node)) {
+                node.content.forEach(visit);
+            }
+        };
+        visit(root);
+        for (const key of collided) {
+            found.delete(key);
+        }
+        return found;
+    }
+}
+/** Registers {@link CommentPreserver}; bound at `trivia.preservers.comments`. */
+export class CommentPreserverContribution {
+    services;
+    constructor(services) {
+        this.services = services;
+    }
+    registerTriviaPreservers(registry) {
+        registry.register(new CommentPreserver(this.services));
+    }
+}
+//# sourceMappingURL=comment-preserver.js.map