ra_ap_ide_db/
source_change.rs

1//! This modules defines type to represent changes to the source code, that flow
2//! from the server to the client.
3//!
4//! It can be viewed as a dual for `Change`.
5
6use std::{collections::hash_map::Entry, fmt, iter, mem};
7
8use crate::imports::insert_use::{ImportScope, ImportScopeKind};
9use crate::text_edit::{TextEdit, TextEditBuilder};
10use crate::{SnippetCap, assists::Command, syntax_helpers::tree_diff::diff};
11use base_db::AnchoredPathBuf;
12use itertools::Itertools;
13use macros::UpmapFromRaFixture;
14use nohash_hasher::IntMap;
15use rustc_hash::FxHashMap;
16use span::FileId;
17use stdx::never;
18use syntax::{
19    AstNode, SyntaxElement, SyntaxNode, SyntaxNodePtr, SyntaxToken, TextRange, TextSize,
20    syntax_editor::{SyntaxAnnotation, SyntaxEditor},
21};
22
23/// An annotation ID associated with an indel, to describe changes.
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, UpmapFromRaFixture)]
25pub struct ChangeAnnotationId(u32);
26
27impl fmt::Display for ChangeAnnotationId {
28    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
29        fmt::Display::fmt(&self.0, f)
30    }
31}
32
33#[derive(Debug, Clone)]
34pub struct ChangeAnnotation {
35    pub label: String,
36    pub needs_confirmation: bool,
37    pub description: Option<String>,
38}
39
40#[derive(Default, Debug, Clone)]
41pub struct SourceChange {
42    pub source_file_edits: IntMap<FileId, (TextEdit, Option<SnippetEdit>)>,
43    pub file_system_edits: Vec<FileSystemEdit>,
44    pub is_snippet: bool,
45    pub annotations: FxHashMap<ChangeAnnotationId, ChangeAnnotation>,
46    next_annotation_id: u32,
47}
48
49impl SourceChange {
50    pub fn from_text_edit(file_id: impl Into<FileId>, edit: TextEdit) -> Self {
51        SourceChange {
52            source_file_edits: iter::once((file_id.into(), (edit, None))).collect(),
53            ..Default::default()
54        }
55    }
56
57    pub fn insert_annotation(&mut self, annotation: ChangeAnnotation) -> ChangeAnnotationId {
58        let id = ChangeAnnotationId(self.next_annotation_id);
59        self.next_annotation_id += 1;
60        self.annotations.insert(id, annotation);
61        id
62    }
63
64    /// Inserts a [`TextEdit`] for the given [`FileId`]. This properly handles merging existing
65    /// edits for a file if some already exist.
66    pub fn insert_source_edit(&mut self, file_id: impl Into<FileId>, edit: TextEdit) {
67        self.insert_source_and_snippet_edit(file_id.into(), edit, None)
68    }
69
70    /// Inserts a [`TextEdit`] and potentially a [`SnippetEdit`] for the given [`FileId`].
71    /// This properly handles merging existing edits for a file if some already exist.
72    pub fn insert_source_and_snippet_edit(
73        &mut self,
74        file_id: impl Into<FileId>,
75        edit: TextEdit,
76        snippet_edit: Option<SnippetEdit>,
77    ) {
78        match self.source_file_edits.entry(file_id.into()) {
79            Entry::Occupied(mut entry) => {
80                let value = entry.get_mut();
81                never!(value.0.union(edit).is_err(), "overlapping edits for same file");
82                never!(
83                    value.1.is_some() && snippet_edit.is_some(),
84                    "overlapping snippet edits for same file"
85                );
86                if value.1.is_none() {
87                    value.1 = snippet_edit;
88                }
89            }
90            Entry::Vacant(entry) => {
91                entry.insert((edit, snippet_edit));
92            }
93        }
94    }
95
96    pub fn push_file_system_edit(&mut self, edit: FileSystemEdit) {
97        self.file_system_edits.push(edit);
98    }
99
100    pub fn get_source_and_snippet_edit(
101        &self,
102        file_id: FileId,
103    ) -> Option<&(TextEdit, Option<SnippetEdit>)> {
104        self.source_file_edits.get(&file_id)
105    }
106
107    pub fn merge(mut self, other: SourceChange) -> SourceChange {
108        self.extend(other.source_file_edits);
109        self.extend(other.file_system_edits);
110        self.is_snippet |= other.is_snippet;
111        self
112    }
113}
114
115impl Extend<(FileId, TextEdit)> for SourceChange {
116    fn extend<T: IntoIterator<Item = (FileId, TextEdit)>>(&mut self, iter: T) {
117        self.extend(iter.into_iter().map(|(file_id, edit)| (file_id, (edit, None))))
118    }
119}
120
121impl Extend<(FileId, (TextEdit, Option<SnippetEdit>))> for SourceChange {
122    fn extend<T: IntoIterator<Item = (FileId, (TextEdit, Option<SnippetEdit>))>>(
123        &mut self,
124        iter: T,
125    ) {
126        iter.into_iter().for_each(|(file_id, (edit, snippet_edit))| {
127            self.insert_source_and_snippet_edit(file_id, edit, snippet_edit)
128        });
129    }
130}
131
132impl Extend<FileSystemEdit> for SourceChange {
133    fn extend<T: IntoIterator<Item = FileSystemEdit>>(&mut self, iter: T) {
134        iter.into_iter().for_each(|edit| self.push_file_system_edit(edit));
135    }
136}
137
138impl From<IntMap<FileId, TextEdit>> for SourceChange {
139    fn from(source_file_edits: IntMap<FileId, TextEdit>) -> SourceChange {
140        let source_file_edits =
141            source_file_edits.into_iter().map(|(file_id, edit)| (file_id, (edit, None))).collect();
142        SourceChange {
143            source_file_edits,
144            file_system_edits: Vec::new(),
145            is_snippet: false,
146            ..SourceChange::default()
147        }
148    }
149}
150
151impl FromIterator<(FileId, TextEdit)> for SourceChange {
152    fn from_iter<T: IntoIterator<Item = (FileId, TextEdit)>>(iter: T) -> Self {
153        let mut this = SourceChange::default();
154        this.extend(iter);
155        this
156    }
157}
158
159#[derive(Debug, Clone, PartialEq, Eq)]
160pub struct SnippetEdit(Vec<(u32, TextRange)>);
161
162impl SnippetEdit {
163    pub fn new(snippets: Vec<Snippet>) -> Self {
164        let mut snippet_ranges = snippets
165            .into_iter()
166            .zip(1..)
167            .with_position()
168            .flat_map(|pos| {
169                let (snippet, index) = match pos {
170                    (itertools::Position::First, it) | (itertools::Position::Middle, it) => it,
171                    // last/only snippet gets index 0
172                    (itertools::Position::Last, (snippet, _))
173                    | (itertools::Position::Only, (snippet, _)) => (snippet, 0),
174                };
175
176                match snippet {
177                    Snippet::Tabstop(pos) => vec![(index, TextRange::empty(pos))],
178                    Snippet::Placeholder(range) => vec![(index, range)],
179                    Snippet::PlaceholderGroup(ranges) => {
180                        ranges.into_iter().map(|range| (index, range)).collect()
181                    }
182                }
183            })
184            .collect_vec();
185
186        snippet_ranges.sort_by_key(|(_, range)| range.start());
187
188        // Ensure that none of the ranges overlap
189        let disjoint_ranges = snippet_ranges
190            .iter()
191            .zip(snippet_ranges.iter().skip(1))
192            .all(|((_, left), (_, right))| left.end() <= right.start() || left == right);
193        stdx::always!(disjoint_ranges);
194
195        SnippetEdit(snippet_ranges)
196    }
197
198    /// Inserts all of the snippets into the given text.
199    pub fn apply(&self, text: &mut String) {
200        // Start from the back so that we don't have to adjust ranges
201        for (index, range) in self.0.iter().rev() {
202            if range.is_empty() {
203                // is a tabstop
204                text.insert_str(range.start().into(), &format!("${index}"));
205            } else {
206                // is a placeholder
207                text.insert(range.end().into(), '}');
208                text.insert_str(range.start().into(), &format!("${{{index}:"));
209            }
210        }
211    }
212
213    /// Gets the underlying snippet index + text range
214    /// Tabstops are represented by an empty range, and placeholders use the range that they were given
215    pub fn into_edit_ranges(self) -> Vec<(u32, TextRange)> {
216        self.0
217    }
218}
219
220pub struct SourceChangeBuilder {
221    pub edit: TextEditBuilder,
222    pub file_id: FileId,
223    pub source_change: SourceChange,
224    pub command: Option<Command>,
225
226    /// Keeps track of all edits performed on each file
227    pub file_editors: FxHashMap<FileId, SyntaxEditor>,
228    /// Keeps track of which annotations correspond to which snippets
229    pub snippet_annotations: Vec<(AnnotationSnippet, SyntaxAnnotation)>,
230
231    /// Maps the original, immutable `SyntaxNode` to a `clone_for_update` twin.
232    pub mutated_tree: Option<TreeMutator>,
233    /// Keeps track of where to place snippets
234    pub snippet_builder: Option<SnippetBuilder>,
235}
236
237pub struct TreeMutator {
238    immutable: SyntaxNode,
239    mutable_clone: SyntaxNode,
240}
241
242#[derive(Default)]
243pub struct SnippetBuilder {
244    /// Where to place snippets at
245    places: Vec<PlaceSnippet>,
246}
247
248impl TreeMutator {
249    pub fn new(immutable: &SyntaxNode) -> TreeMutator {
250        let immutable = immutable.ancestors().last().unwrap();
251        let mutable_clone = immutable.clone_for_update();
252        TreeMutator { immutable, mutable_clone }
253    }
254
255    pub fn make_mut<N: AstNode>(&self, node: &N) -> N {
256        N::cast(self.make_syntax_mut(node.syntax())).unwrap()
257    }
258
259    pub fn make_syntax_mut(&self, node: &SyntaxNode) -> SyntaxNode {
260        let ptr = SyntaxNodePtr::new(node);
261        ptr.to_node(&self.mutable_clone)
262    }
263}
264
265impl SourceChangeBuilder {
266    pub fn new(file_id: impl Into<FileId>) -> SourceChangeBuilder {
267        SourceChangeBuilder {
268            edit: TextEdit::builder(),
269            file_id: file_id.into(),
270            source_change: SourceChange::default(),
271            command: None,
272            file_editors: FxHashMap::default(),
273            snippet_annotations: vec![],
274            mutated_tree: None,
275            snippet_builder: None,
276        }
277    }
278
279    pub fn edit_file(&mut self, file_id: impl Into<FileId>) {
280        self.commit();
281        self.file_id = file_id.into();
282    }
283
284    pub fn make_editor(&self, node: &SyntaxNode) -> SyntaxEditor {
285        SyntaxEditor::new(node.ancestors().last().unwrap_or_else(|| node.clone()))
286    }
287
288    pub fn add_file_edits(&mut self, file_id: impl Into<FileId>, edit: SyntaxEditor) {
289        match self.file_editors.entry(file_id.into()) {
290            Entry::Occupied(mut entry) => entry.get_mut().merge(edit),
291            Entry::Vacant(entry) => {
292                entry.insert(edit);
293            }
294        }
295    }
296
297    pub fn make_placeholder_snippet(&mut self, _cap: SnippetCap) -> SyntaxAnnotation {
298        self.add_snippet_annotation(AnnotationSnippet::Over)
299    }
300
301    pub fn make_tabstop_before(&mut self, _cap: SnippetCap) -> SyntaxAnnotation {
302        self.add_snippet_annotation(AnnotationSnippet::Before)
303    }
304
305    pub fn make_tabstop_after(&mut self, _cap: SnippetCap) -> SyntaxAnnotation {
306        self.add_snippet_annotation(AnnotationSnippet::After)
307    }
308
309    fn commit(&mut self) {
310        // Apply syntax editor edits
311        for (file_id, editor) in mem::take(&mut self.file_editors) {
312            let edit_result = editor.finish();
313            let mut snippet_edit = vec![];
314
315            // Find snippet edits
316            for (kind, annotation) in &self.snippet_annotations {
317                let elements = edit_result.find_annotation(*annotation);
318
319                let snippet = match (kind, elements) {
320                    (AnnotationSnippet::Before, [element]) => {
321                        Snippet::Tabstop(element.text_range().start())
322                    }
323                    (AnnotationSnippet::After, [element]) => {
324                        Snippet::Tabstop(element.text_range().end())
325                    }
326                    (AnnotationSnippet::Over, [element]) => {
327                        Snippet::Placeholder(element.text_range())
328                    }
329                    (AnnotationSnippet::Over, elements) if !elements.is_empty() => {
330                        Snippet::PlaceholderGroup(
331                            elements.iter().map(|it| it.text_range()).collect(),
332                        )
333                    }
334                    _ => continue,
335                };
336
337                snippet_edit.push(snippet);
338            }
339
340            let mut edit = TextEdit::builder();
341            diff(edit_result.old_root(), edit_result.new_root()).into_text_edit(&mut edit);
342            let edit = edit.finish();
343
344            let snippet_edit =
345                if !snippet_edit.is_empty() { Some(SnippetEdit::new(snippet_edit)) } else { None };
346
347            if !edit.is_empty() || snippet_edit.is_some() {
348                self.source_change.insert_source_and_snippet_edit(file_id, edit, snippet_edit);
349            }
350        }
351
352        // Apply mutable edits
353        let snippet_edit = self.snippet_builder.take().map(|builder| {
354            SnippetEdit::new(
355                builder.places.into_iter().flat_map(PlaceSnippet::finalize_position).collect(),
356            )
357        });
358
359        if let Some(tm) = self.mutated_tree.take() {
360            diff(&tm.immutable, &tm.mutable_clone).into_text_edit(&mut self.edit);
361        }
362
363        let edit = mem::take(&mut self.edit).finish();
364        if !edit.is_empty() || snippet_edit.is_some() {
365            self.source_change.insert_source_and_snippet_edit(self.file_id, edit, snippet_edit);
366        }
367    }
368
369    pub fn make_mut<N: AstNode>(&mut self, node: N) -> N {
370        self.mutated_tree.get_or_insert_with(|| TreeMutator::new(node.syntax())).make_mut(&node)
371    }
372
373    pub fn make_import_scope_mut(&mut self, scope: ImportScope) -> ImportScope {
374        ImportScope {
375            kind: match scope.kind.clone() {
376                ImportScopeKind::File(it) => ImportScopeKind::File(self.make_mut(it)),
377                ImportScopeKind::Module(it) => ImportScopeKind::Module(self.make_mut(it)),
378                ImportScopeKind::Block(it) => ImportScopeKind::Block(self.make_mut(it)),
379            },
380            required_cfgs: scope.required_cfgs.iter().map(|it| self.make_mut(it.clone())).collect(),
381        }
382    }
383    /// Returns a copy of the `node`, suitable for mutation.
384    ///
385    /// Syntax trees in rust-analyzer are typically immutable, and mutating
386    /// operations panic at runtime. However, it is possible to make a copy of
387    /// the tree and mutate the copy freely. Mutation is based on interior
388    /// mutability, and different nodes in the same tree see the same mutations.
389    ///
390    /// The typical pattern for an assist is to find specific nodes in the read
391    /// phase, and then get their mutable counterparts using `make_mut` in the
392    /// mutable state.
393    pub fn make_syntax_mut(&mut self, node: SyntaxNode) -> SyntaxNode {
394        self.mutated_tree.get_or_insert_with(|| TreeMutator::new(&node)).make_syntax_mut(&node)
395    }
396
397    /// Remove specified `range` of text.
398    pub fn delete(&mut self, range: TextRange) {
399        self.edit.delete(range)
400    }
401    /// Append specified `text` at the given `offset`
402    pub fn insert(&mut self, offset: TextSize, text: impl Into<String>) {
403        self.edit.insert(offset, text.into())
404    }
405    /// Replaces specified `range` of text with a given string.
406    pub fn replace(&mut self, range: TextRange, replace_with: impl Into<String>) {
407        self.edit.replace(range, replace_with.into())
408    }
409    pub fn replace_ast<N: AstNode>(&mut self, old: N, new: N) {
410        diff(old.syntax(), new.syntax()).into_text_edit(&mut self.edit)
411    }
412    pub fn create_file(&mut self, dst: AnchoredPathBuf, content: impl Into<String>) {
413        let file_system_edit = FileSystemEdit::CreateFile { dst, initial_contents: content.into() };
414        self.source_change.push_file_system_edit(file_system_edit);
415    }
416    pub fn move_file(&mut self, src: impl Into<FileId>, dst: AnchoredPathBuf) {
417        let file_system_edit = FileSystemEdit::MoveFile { src: src.into(), dst };
418        self.source_change.push_file_system_edit(file_system_edit);
419    }
420
421    /// Triggers the parameter hint popup after the assist is applied
422    pub fn trigger_parameter_hints(&mut self) {
423        self.command = Some(Command::TriggerParameterHints);
424    }
425
426    /// Renames the item at the cursor position after the assist is applied
427    pub fn rename(&mut self) {
428        self.command = Some(Command::Rename);
429    }
430
431    /// Adds a tabstop snippet to place the cursor before `node`
432    pub fn add_tabstop_before(&mut self, _cap: SnippetCap, node: impl AstNode) {
433        assert!(node.syntax().parent().is_some());
434        self.add_snippet(PlaceSnippet::Before(node.syntax().clone().into()));
435    }
436
437    /// Adds a tabstop snippet to place the cursor after `node`
438    pub fn add_tabstop_after(&mut self, _cap: SnippetCap, node: impl AstNode) {
439        assert!(node.syntax().parent().is_some());
440        self.add_snippet(PlaceSnippet::After(node.syntax().clone().into()));
441    }
442
443    /// Adds a tabstop snippet to place the cursor before `token`
444    pub fn add_tabstop_before_token(&mut self, _cap: SnippetCap, token: SyntaxToken) {
445        assert!(token.parent().is_some());
446        self.add_snippet(PlaceSnippet::Before(token.into()));
447    }
448
449    /// Adds a tabstop snippet to place the cursor after `token`
450    pub fn add_tabstop_after_token(&mut self, _cap: SnippetCap, token: SyntaxToken) {
451        assert!(token.parent().is_some());
452        self.add_snippet(PlaceSnippet::After(token.into()));
453    }
454
455    /// Adds a snippet to move the cursor selected over `node`
456    pub fn add_placeholder_snippet(&mut self, _cap: SnippetCap, node: impl AstNode) {
457        assert!(node.syntax().parent().is_some());
458        self.add_snippet(PlaceSnippet::Over(node.syntax().clone().into()))
459    }
460
461    /// Adds a snippet to move the cursor selected over `token`
462    pub fn add_placeholder_snippet_token(&mut self, _cap: SnippetCap, token: SyntaxToken) {
463        assert!(token.parent().is_some());
464        self.add_snippet(PlaceSnippet::Over(token.into()))
465    }
466
467    /// Adds a snippet to move the cursor selected over `nodes`
468    ///
469    /// This allows for renaming newly generated items without having to go
470    /// through a separate rename step.
471    pub fn add_placeholder_snippet_group(&mut self, _cap: SnippetCap, nodes: Vec<SyntaxNode>) {
472        assert!(nodes.iter().all(|node| node.parent().is_some()));
473        self.add_snippet(PlaceSnippet::OverGroup(
474            nodes.into_iter().map(|node| node.into()).collect(),
475        ))
476    }
477
478    fn add_snippet(&mut self, snippet: PlaceSnippet) {
479        let snippet_builder = self.snippet_builder.get_or_insert(SnippetBuilder { places: vec![] });
480        snippet_builder.places.push(snippet);
481        self.source_change.is_snippet = true;
482    }
483
484    fn add_snippet_annotation(&mut self, kind: AnnotationSnippet) -> SyntaxAnnotation {
485        let annotation = SyntaxAnnotation::default();
486        self.snippet_annotations.push((kind, annotation));
487        self.source_change.is_snippet = true;
488        annotation
489    }
490
491    pub fn finish(mut self) -> SourceChange {
492        self.commit();
493
494        // Only one file can have snippet edits
495        stdx::never!(
496            self.source_change
497                .source_file_edits
498                .iter()
499                .filter(|(_, (_, snippet_edit))| snippet_edit.is_some())
500                .at_most_one()
501                .is_err()
502        );
503
504        mem::take(&mut self.source_change)
505    }
506}
507
508#[derive(Debug, Clone)]
509pub enum FileSystemEdit {
510    CreateFile { dst: AnchoredPathBuf, initial_contents: String },
511    MoveFile { src: FileId, dst: AnchoredPathBuf },
512    MoveDir { src: AnchoredPathBuf, src_id: FileId, dst: AnchoredPathBuf },
513}
514
515impl From<FileSystemEdit> for SourceChange {
516    fn from(edit: FileSystemEdit) -> SourceChange {
517        SourceChange {
518            source_file_edits: Default::default(),
519            file_system_edits: vec![edit],
520            is_snippet: false,
521            ..SourceChange::default()
522        }
523    }
524}
525
526pub enum Snippet {
527    /// A tabstop snippet (e.g. `$0`).
528    Tabstop(TextSize),
529    /// A placeholder snippet (e.g. `${0:placeholder}`).
530    Placeholder(TextRange),
531    /// A group of placeholder snippets, e.g.
532    ///
533    /// ```ignore
534    /// let ${0:new_var} = 4;
535    /// fun(1, 2, 3, ${0:new_var});
536    /// ```
537    PlaceholderGroup(Vec<TextRange>),
538}
539
540pub enum AnnotationSnippet {
541    /// Place a tabstop before an element
542    Before,
543    /// Place a tabstop before an element
544    After,
545    /// Place a placeholder snippet in place of the element(s)
546    Over,
547}
548
549enum PlaceSnippet {
550    /// Place a tabstop before an element
551    Before(SyntaxElement),
552    /// Place a tabstop before an element
553    After(SyntaxElement),
554    /// Place a placeholder snippet in place of the element
555    Over(SyntaxElement),
556    /// Place a group of placeholder snippets which are linked together
557    /// in place of the elements
558    OverGroup(Vec<SyntaxElement>),
559}
560
561impl PlaceSnippet {
562    fn finalize_position(self) -> Vec<Snippet> {
563        match self {
564            PlaceSnippet::Before(it) => vec![Snippet::Tabstop(it.text_range().start())],
565            PlaceSnippet::After(it) => vec![Snippet::Tabstop(it.text_range().end())],
566            PlaceSnippet::Over(it) => vec![Snippet::Placeholder(it.text_range())],
567            PlaceSnippet::OverGroup(it) => {
568                vec![Snippet::PlaceholderGroup(it.into_iter().map(|it| it.text_range()).collect())]
569            }
570        }
571    }
572}
ra_ap_ide_db/source_change.rs

ra_ap_ide_db/
source_change.rs
