1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
//! Values that cross the engine boundary.
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use std::{collections::BTreeMap, path::PathBuf};
use crate::syntax::{FileSyntax, PlanSyntax};
use crate::pattern_locator::PatternLocator;
pub use crate::problem::{Problem, ProblemKind, Window};
/// A half-open byte range `[start, end)` in a file's text.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ByteRange {
/// First byte of the range.
pub start: usize,
/// One past the last byte of the range.
pub end: usize,
}
/// Which matches of an anchor an operation targets.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum Occurrence {
/// Exactly one match; two or more is an error listing every candidate.
#[default]
Unique,
/// Every match.
All,
/// The Nth match, counting from 1.
Nth(usize),
}
/// Text that locates an edit inside a file. A plain string is accepted as
/// shorthand for `{ text }`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(from = "crate::anchor_input::AnchorInput")]
pub struct Anchor {
/// Text to find.
pub text: String,
/// Only consider matches after the first occurrence of this text.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub after: Option<String>,
/// Match whole lines only. Patch hunks set this.
#[serde(default)]
pub whole_lines: bool,
}
/// One requested change.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "op", rename_all = "snake_case")]
pub enum Op {
/// Replace anchored text, an exact byte range, or a structural pattern
/// match. Give exactly one of `find`, `range`, or `pattern`.
Replace {
/// File to change.
path: PathBuf,
/// Text to locate. Required unless `range` or `pattern` is given.
#[serde(default, skip_serializing_if = "Option::is_none")]
find: Option<Anchor>,
/// Exact byte range in the file as it was when found.
#[serde(default, skip_serializing_if = "Option::is_none")]
range: Option<ByteRange>,
/// Structural pattern match, as an alternative to `find`/`range`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pattern: Option<PatternLocator>,
/// Replacement text.
replace: String,
/// Which matches to replace.
#[serde(default)]
occurrence: Occurrence,
/// With `pattern`, edit only this metavariable's range, e.g. `$NAME`.
#[serde(default, skip_serializing_if = "Option::is_none")]
target: Option<String>,
/// Fingerprint the file must still have.
#[serde(default, skip_serializing_if = "Option::is_none")]
expect_hash: Option<String>,
},
/// Insert text before or after a unique anchor.
Insert {
/// File to change.
path: PathBuf,
/// Text to locate.
anchor: Anchor,
/// Insert after the anchor instead of before it.
#[serde(default)]
after: bool,
/// Text to insert.
text: String,
/// Fingerprint the file must still have.
#[serde(default, skip_serializing_if = "Option::is_none")]
expect_hash: Option<String>,
},
/// Create a file that must not exist yet.
Create {
/// File to create.
path: PathBuf,
/// Full contents.
text: String,
},
/// Delete a file that must exist.
Delete {
/// File to delete.
path: PathBuf,
/// Fingerprint the file must still have.
#[serde(default, skip_serializing_if = "Option::is_none")]
expect_hash: Option<String>,
},
/// Move a file to a path that must not exist yet.
Move {
/// File to move.
path: PathBuf,
/// Destination.
to: PathBuf,
/// Fingerprint the file must still have.
#[serde(default, skip_serializing_if = "Option::is_none")]
expect_hash: Option<String>,
},
}
impl Op {
/// The file this operation starts from.
#[must_use]
pub fn path(&self) -> &PathBuf {
match self {
Self::Replace { path, .. }
| Self::Insert { path, .. }
| Self::Create { path, .. }
| Self::Delete { path, .. }
| Self::Move { path, .. } => path,
}
}
}
/// How sure the engine is that an edit landed where the caller meant.
///
/// Ordered: `Maybe` is below `Machine`.
#[derive(
Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
)]
#[serde(rename_all = "snake_case")]
pub enum Confidence {
/// Located by tolerant matching; a person or program should look first.
Maybe,
/// Located exactly; safe to apply without review.
Machine,
}
/// The matching rung that located an edit.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum Rung {
/// Byte range supplied by the caller.
Range,
/// Exact text.
Exact,
/// Lines equal after trimming trailing whitespace.
TrailingWhitespace,
/// Lines equal after trimming both ends.
Trimmed,
/// Lines equal after removing their shared indentation.
Indentation,
/// Whole-file operation such as create, delete, or move.
File,
/// A structural pattern match: exact identity on the parse tree, never tolerant.
Pattern,
}
impl Rung {
/// Only exact rungs are safe to apply unattended.
#[must_use]
pub fn confidence(self) -> Confidence {
match self {
Self::Range | Self::Exact | Self::File | Self::Pattern => Confidence::Machine,
Self::TrailingWhitespace | Self::Trimmed | Self::Indentation => Confidence::Maybe,
}
}
}
/// One change the plan makes.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Edit {
/// Stable identifier: `e<op>` or `e<op>.<n>` for repeated matches.
pub id: String,
/// Index of the operation that produced this edit.
pub op: usize,
/// File the edit lands in.
pub path: PathBuf,
/// 1-based line where the edit starts, 0 for whole-file edits.
pub line: usize,
/// Rung that located it.
pub rung: Rung,
/// Confidence derived from the rung.
pub confidence: Confidence,
}
/// What a file change does.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ChangeKind {
/// Existing file rewritten.
Modify,
/// New file.
Create,
/// File removed.
Delete,
}
/// The planned before and after state of one file.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct FileChange {
/// File path.
pub path: PathBuf,
/// What happens to it.
pub kind: ChangeKind,
/// Text the plan was computed against; absent for a new file.
pub before: Option<String>,
/// Fingerprint of `before`.
pub before_hash: Option<String>,
/// Text after the plan; absent for a deleted file.
pub after: Option<String>,
/// Fingerprint of `after`.
pub after_hash: Option<String>,
}
/// The complete, unwritten result of a set of operations.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Plan {
/// Every changed file, sorted by path.
pub files: Vec<FileChange>,
/// Every edit, in operation order.
pub edits: Vec<Edit>,
/// Every operation that could not be planned. A plan with problems must
/// never be applied.
pub problems: Vec<Problem>,
/// Overall syntax verdict, over every changed file's [`FileSyntax`].
/// Fact only: never `problems`, never refuses.
#[serde(default)]
pub syntax: PlanSyntax,
/// Parse facts for each changed file in an enabled language.
#[serde(default)]
pub file_syntax: BTreeMap<PathBuf, FileSyntax>,
}
impl Plan {
/// Lowest confidence of any edit, or `Machine` for an empty plan.
#[must_use]
pub fn confidence(&self) -> Confidence {
self.edits
.iter()
.map(|edit| edit.confidence)
.min()
.unwrap_or(Confidence::Machine)
}
}