sara_core/edit/
service.rs

1//! Edit service implementation.
2
3use std::fs;
4use std::path::PathBuf;
5
6use crate::error::EditError;
7use crate::graph::KnowledgeGraph;
8use crate::model::{FieldChange, Item, ItemType, TraceabilityLinks};
9use crate::parser::update_frontmatter;
10use crate::query::lookup_item_or_suggest;
11
12use super::{EditOptions, EditedValues};
13
14/// Result of a successful edit operation.
15#[derive(Debug)]
16pub struct EditResult {
17    /// The item ID that was edited.
18    pub item_id: String,
19    /// The file path that was modified.
20    pub file_path: PathBuf,
21    /// The changes that were applied.
22    pub changes: Vec<FieldChange>,
23}
24
25impl EditResult {
26    /// Returns true if any changes were made.
27    pub fn has_changes(&self) -> bool {
28        !self.changes.is_empty()
29    }
30
31    /// Returns the number of changes.
32    pub fn change_count(&self) -> usize {
33        self.changes.len()
34    }
35}
36
37/// Context for the item being edited.
38#[derive(Debug, Clone)]
39pub struct ItemContext {
40    /// The item ID.
41    pub id: String,
42    /// The item type.
43    pub item_type: ItemType,
44    /// The current name.
45    pub name: String,
46    /// The current description.
47    pub description: Option<String>,
48    /// The current specification.
49    pub specification: Option<String>,
50    /// The current platform.
51    pub platform: Option<String>,
52    /// The current traceability links.
53    pub traceability: TraceabilityLinks,
54    /// The file path.
55    pub file_path: PathBuf,
56}
57
58impl ItemContext {
59    /// Creates a context from an Item.
60    pub fn from_item(item: &Item) -> Self {
61        Self {
62            id: item.id.as_str().to_string(),
63            item_type: item.item_type,
64            name: item.name.clone(),
65            description: item.description.clone(),
66            specification: item.attributes.specification.clone(),
67            platform: item.attributes.platform.clone(),
68            traceability: TraceabilityLinks::from_upstream(&item.upstream),
69            file_path: item.source.full_path(),
70        }
71    }
72}
73
74/// Service for editing requirement items.
75#[derive(Debug, Default)]
76pub struct EditService;
77
78impl EditService {
79    /// Creates a new edit service.
80    pub fn new() -> Self {
81        Self
82    }
83
84    /// Looks up an item by ID with fuzzy suggestions on failure.
85    pub fn lookup_item<'a>(
86        &self,
87        graph: &'a KnowledgeGraph,
88        item_id: &str,
89    ) -> Result<&'a Item, EditError> {
90        lookup_item_or_suggest(graph, item_id)
91    }
92
93    /// Gets the context for an item.
94    pub fn get_item_context(&self, item: &Item) -> ItemContext {
95        ItemContext::from_item(item)
96    }
97
98    /// Validates edit options against the item type.
99    pub fn validate_options(
100        &self,
101        opts: &EditOptions,
102        item_type: ItemType,
103    ) -> Result<(), EditError> {
104        if opts.specification.is_some() && !item_type.requires_specification() {
105            return Err(EditError::IoError(format!(
106                "--specification is only valid for requirement types, not {}",
107                item_type.display_name()
108            )));
109        }
110
111        if opts.platform.is_some() && item_type != ItemType::SystemArchitecture {
112            return Err(EditError::IoError(
113                "--platform is only valid for System Architecture items".to_string(),
114            ));
115        }
116
117        Ok(())
118    }
119
120    /// Merges edit options with current item values.
121    pub fn merge_values(&self, opts: &EditOptions, current: &ItemContext) -> EditedValues {
122        EditedValues {
123            name: opts.name.clone().unwrap_or_else(|| current.name.clone()),
124            description: opts
125                .description
126                .clone()
127                .or_else(|| current.description.clone()),
128            specification: opts
129                .specification
130                .clone()
131                .or_else(|| current.specification.clone()),
132            platform: opts.platform.clone().or_else(|| current.platform.clone()),
133            traceability: TraceabilityLinks {
134                refines: opts
135                    .refines
136                    .clone()
137                    .unwrap_or_else(|| current.traceability.refines.clone()),
138                derives_from: opts
139                    .derives_from
140                    .clone()
141                    .unwrap_or_else(|| current.traceability.derives_from.clone()),
142                satisfies: opts
143                    .satisfies
144                    .clone()
145                    .unwrap_or_else(|| current.traceability.satisfies.clone()),
146            },
147        }
148    }
149
150    /// Builds a change summary comparing old and new values.
151    pub fn build_change_summary(&self, old: &ItemContext, new: &EditedValues) -> Vec<FieldChange> {
152        let mut changes = Vec::new();
153
154        changes.push(FieldChange::new("Name", &old.name, &new.name));
155        changes.push(FieldChange::new(
156            "Description",
157            old.description.as_deref().unwrap_or("(none)"),
158            new.description.as_deref().unwrap_or("(none)"),
159        ));
160
161        // Traceability changes
162        self.add_traceability_change(
163            &mut changes,
164            "Refines",
165            &old.traceability.refines,
166            &new.traceability.refines,
167        );
168        self.add_traceability_change(
169            &mut changes,
170            "Derives from",
171            &old.traceability.derives_from,
172            &new.traceability.derives_from,
173        );
174        self.add_traceability_change(
175            &mut changes,
176            "Satisfies",
177            &old.traceability.satisfies,
178            &new.traceability.satisfies,
179        );
180
181        // Type-specific
182        if old.specification.is_some() || new.specification.is_some() {
183            changes.push(FieldChange::new(
184                "Specification",
185                old.specification.as_deref().unwrap_or("(none)"),
186                new.specification.as_deref().unwrap_or("(none)"),
187            ));
188        }
189
190        if old.platform.is_some() || new.platform.is_some() {
191            changes.push(FieldChange::new(
192                "Platform",
193                old.platform.as_deref().unwrap_or("(none)"),
194                new.platform.as_deref().unwrap_or("(none)"),
195            ));
196        }
197
198        changes
199    }
200
201    /// Adds a traceability field change if values differ.
202    fn add_traceability_change(
203        &self,
204        changes: &mut Vec<FieldChange>,
205        field: &str,
206        old: &[String],
207        new: &[String],
208    ) {
209        if old.is_empty() && new.is_empty() {
210            return;
211        }
212
213        let old_str = if old.is_empty() {
214            "(none)".to_string()
215        } else {
216            old.join(", ")
217        };
218        let new_str = if new.is_empty() {
219            "(none)".to_string()
220        } else {
221            new.join(", ")
222        };
223
224        changes.push(FieldChange::new(field, &old_str, &new_str));
225    }
226
227    /// Applies changes to the file.
228    pub fn apply_changes(
229        &self,
230        item_id: &str,
231        item_type: ItemType,
232        new_values: &EditedValues,
233        file_path: &PathBuf,
234    ) -> Result<(), EditError> {
235        let content =
236            fs::read_to_string(file_path).map_err(|e| EditError::IoError(e.to_string()))?;
237        let new_yaml = self.build_frontmatter_yaml(item_id, item_type, new_values);
238        let updated_content = update_frontmatter(&content, &new_yaml);
239        fs::write(file_path, updated_content).map_err(|e| EditError::IoError(e.to_string()))?;
240        Ok(())
241    }
242
243    /// Builds YAML frontmatter string from edit values.
244    pub fn build_frontmatter_yaml(
245        &self,
246        item_id: &str,
247        item_type: ItemType,
248        values: &EditedValues,
249    ) -> String {
250        let mut yaml = format!(
251            "id: \"{}\"\ntype: {}\nname: \"{}\"\n",
252            item_id,
253            item_type.yaml_value(),
254            values.name.replace('"', "\\\"")
255        );
256
257        if let Some(ref desc) = values.description {
258            yaml += &format!("description: \"{}\"\n", desc.replace('"', "\\\""));
259        }
260
261        self.append_traceability_yaml(&mut yaml, "refines", &values.traceability.refines);
262        self.append_traceability_yaml(&mut yaml, "derives_from", &values.traceability.derives_from);
263        self.append_traceability_yaml(&mut yaml, "satisfies", &values.traceability.satisfies);
264
265        if let Some(ref spec) = values.specification {
266            yaml += &format!("specification: \"{}\"\n", spec.replace('"', "\\\""));
267        }
268
269        if let Some(ref plat) = values.platform {
270            yaml += &format!("platform: \"{}\"\n", plat.replace('"', "\\\""));
271        }
272
273        yaml
274    }
275
276    /// Appends a traceability list to YAML if non-empty.
277    fn append_traceability_yaml(&self, yaml: &mut String, field: &str, ids: &[String]) {
278        if ids.is_empty() {
279            return;
280        }
281
282        *yaml += &format!("{}:\n", field);
283        for id in ids {
284            *yaml += &format!("  - \"{}\"\n", id);
285        }
286    }
287
288    /// Performs a non-interactive edit operation.
289    pub fn edit(
290        &self,
291        graph: &KnowledgeGraph,
292        opts: &EditOptions,
293    ) -> Result<EditResult, EditError> {
294        // Look up the item
295        let item = self.lookup_item(graph, &opts.item_id)?;
296        let item_ctx = self.get_item_context(item);
297
298        // Validate options
299        self.validate_options(opts, item_ctx.item_type)?;
300
301        // Merge values
302        let new_values = self.merge_values(opts, &item_ctx);
303
304        // Build change summary
305        let changes: Vec<FieldChange> = self
306            .build_change_summary(&item_ctx, &new_values)
307            .into_iter()
308            .filter(|c| c.is_changed())
309            .collect();
310
311        // Apply changes
312        self.apply_changes(
313            &item_ctx.id,
314            item_ctx.item_type,
315            &new_values,
316            &item_ctx.file_path,
317        )?;
318
319        Ok(EditResult {
320            item_id: item_ctx.id,
321            file_path: item_ctx.file_path,
322            changes,
323        })
324    }
325}
326
327#[cfg(test)]
328mod tests {
329    use super::*;
330    use crate::model::{ItemBuilder, ItemId, SourceLocation};
331
332    fn create_test_item(id: &str, item_type: ItemType, name: &str) -> Item {
333        let source = SourceLocation::new(PathBuf::from("/repo"), format!("{}.md", id), 1);
334        let mut builder = ItemBuilder::new()
335            .id(ItemId::new_unchecked(id))
336            .item_type(item_type)
337            .name(name)
338            .source(source);
339
340        if item_type.requires_specification() {
341            builder = builder.specification("Test specification");
342        }
343
344        builder.build().unwrap()
345    }
346
347    #[test]
348    fn test_edit_options_has_updates() {
349        let opts = EditOptions::new("SOL-001");
350        assert!(!opts.has_updates());
351
352        let opts_with_name = EditOptions::new("SOL-001").with_name("New Name");
353        assert!(opts_with_name.has_updates());
354    }
355
356    #[test]
357    fn test_item_context_from_item() {
358        let item = create_test_item("SOL-001", ItemType::Solution, "Test Solution");
359        let ctx = ItemContext::from_item(&item);
360
361        assert_eq!(ctx.id, "SOL-001");
362        assert_eq!(ctx.name, "Test Solution");
363        assert_eq!(ctx.item_type, ItemType::Solution);
364    }
365
366    #[test]
367    fn test_validate_options_specification() {
368        let service = EditService::new();
369
370        // Valid: specification on requirement type
371        let opts = EditOptions::new("SYSREQ-001").with_specification("new spec");
372        assert!(
373            service
374                .validate_options(&opts, ItemType::SystemRequirement)
375                .is_ok()
376        );
377
378        // Invalid: specification on solution type
379        let opts = EditOptions::new("SOL-001").with_specification("new spec");
380        assert!(service.validate_options(&opts, ItemType::Solution).is_err());
381    }
382
383    #[test]
384    fn test_validate_options_platform() {
385        let service = EditService::new();
386
387        // Valid: platform on system architecture
388        let opts = EditOptions::new("SYSARCH-001").with_platform("AWS");
389        assert!(
390            service
391                .validate_options(&opts, ItemType::SystemArchitecture)
392                .is_ok()
393        );
394
395        // Invalid: platform on solution
396        let opts = EditOptions::new("SOL-001").with_platform("AWS");
397        assert!(service.validate_options(&opts, ItemType::Solution).is_err());
398    }
399
400    #[test]
401    fn test_merge_values() {
402        let service = EditService::new();
403
404        let current = ItemContext {
405            id: "SOL-001".to_string(),
406            item_type: ItemType::Solution,
407            name: "Old Name".to_string(),
408            description: Some("Old Description".to_string()),
409            specification: None,
410            platform: None,
411            traceability: TraceabilityLinks::default(),
412            file_path: PathBuf::from("/test.md"),
413        };
414
415        let opts = EditOptions::new("SOL-001").with_name("New Name");
416
417        let merged = service.merge_values(&opts, &current);
418
419        assert_eq!(merged.name, "New Name");
420        assert_eq!(merged.description, Some("Old Description".to_string()));
421    }
422
423    #[test]
424    fn test_build_change_summary() {
425        let service = EditService::new();
426
427        let old = ItemContext {
428            id: "SOL-001".to_string(),
429            item_type: ItemType::Solution,
430            name: "Old Name".to_string(),
431            description: None,
432            specification: None,
433            platform: None,
434            traceability: TraceabilityLinks::default(),
435            file_path: PathBuf::from("/test.md"),
436        };
437
438        let new = EditedValues::new("New Name");
439
440        let changes = service.build_change_summary(&old, &new);
441
442        let name_change = changes.iter().find(|c| c.field == "Name").unwrap();
443        assert!(name_change.is_changed());
444        assert_eq!(name_change.old_value, "Old Name");
445        assert_eq!(name_change.new_value, "New Name");
446    }
447
448    #[test]
449    fn test_build_frontmatter_yaml() {
450        let service = EditService::new();
451
452        let values = EditedValues::new("Test Solution")
453            .with_description(Some("A test solution".to_string()));
454
455        let yaml = service.build_frontmatter_yaml("SOL-001", ItemType::Solution, &values);
456
457        assert!(yaml.contains("id: \"SOL-001\""));
458        assert!(yaml.contains("type: solution"));
459        assert!(yaml.contains("name: \"Test Solution\""));
460        assert!(yaml.contains("description: \"A test solution\""));
461    }
462}
sara_core/edit/service.rs

sara_core/edit/
service.rs
