Skip to main content

dive_api/
rewrite.rs

1//! Native bounded in-memory translation-block replacement; no file writes.
2use crate::{ApiError, TranslationRequest, analyze_source};
3pub use dive_pluscal::rewrite::{ChecksumPolicy, RewriteOptions};
4use dive_pluscal::{Code, Diagnostic};
5use serde_json::{Value, json};
6use std::{io::Read as _, path::Path};
7
8/// Generation settings and in-memory editing policy.
9#[derive(Clone, Debug, Default)]
10pub struct RewriteRequest {
11    /// Native PlusCal generation and enclosing-module resolution.
12    pub translation: TranslationRequest,
13    /// Source edit limits and modified-body protection; CRCs use best effort.
14    pub editing: RewriteOptions,
15}
16/// Stage-separated replacement report; it never certifies a checked model.
17#[derive(Clone, Debug)]
18pub struct RewriteReport {
19    pub(crate) document: Value,
20    status: u8,
21}
22impl RewriteReport {
23    /// Whether native generation and resulting module admission both succeeded.
24    #[must_use]
25    pub const fn accepted(&self) -> bool {
26        self.status == 0
27    }
28    /// Zero replacement, one rejection, three unsupported/resource, four bug.
29    #[must_use]
30    pub const fn exit_code(&self) -> u8 {
31        self.status
32    }
33    /// Complete replacement/provenance/limits/qualification document.
34    #[must_use]
35    pub fn to_json(&self) -> Value {
36        self.document.clone()
37    }
38}
39// Describe emitted replacement bytes, rather than predicting the editor policy.
40fn replacement_newlines(replacement: &str) -> &'static str {
41    match replacement
42        .find(['\r', '\n'])
43        .map(|at| &replacement.as_bytes()[at..])
44    {
45        Some([b'\r', b'\n', ..]) => "crlf",
46        Some([b'\r', ..]) => "cr",
47        _ => "lf",
48    }
49}
50
51fn effective_editing(request: &RewriteRequest) -> RewriteOptions {
52    let mut editing = request.editing.clone();
53    if request.translation.compat_tlc {
54        // Ordinary pinned pcal.trans uses its Noop overwrite callback.
55        editing.normalize_newlines = true;
56        editing.replace_modified = true;
57    }
58    editing
59}
60fn report(
61    file: &str,
62    request: &RewriteRequest,
63    status: u8,
64    stage: &str,
65    details: Value,
66) -> RewriteReport {
67    let mut document = json!({"schema_version":crate::REPORT_SCHEMA_VERSION,"command":"translate-rewrite","file":file,
68        "result":match status {0=>"replacement",1=>"rejected",3=>"unsupported",_=>"internal-error"},
69        "stage":stage,"accepted":status==0,"exit_code":status,
70        "profile":if request.translation.compat_tlc {"tlc"} else {"dive"},
71        "editing":effective_editing(request),"requested_editing":request.editing,"requested_translation_options":request.translation.limits});
72    if let (Some(object), Value::Object(extra)) = (document.as_object_mut(), details) {
73        object.extend(extra);
74    }
75    RewriteReport { document, status }
76}
77fn failure(
78    file: &str,
79    request: &RewriteRequest,
80    stage: &str,
81    diagnostic: &Diagnostic,
82) -> RewriteReport {
83    let status = match diagnostic.code {
84        Code::Unsupported | Code::Resource => 3,
85        Code::Internal => 4,
86        _ => 1,
87    };
88    report(
89        file,
90        request,
91        status,
92        stage,
93        json!({"code":diagnostic.code.as_str(),"diagnostic":diagnostic}),
94    )
95}
96/// Generate, replace and validate a module in memory. Nothing is written to disk.
97/// An unavailable algorithm CRC disables only that value; body CRCs remain real.
98/// Existing unverified/modified bodies require an explicit replacement grant.
99///
100/// ```
101/// use dive_api::{ChecksumPolicy, RewriteOptions, RewriteRequest, rewrite_source};
102/// let source = "---- MODULE R ----\nEXTENDS Integers\n(* --algorithm A variable x=0; begin L:x:=1; E:skip; end algorithm; *)\n====\n";
103/// let request = RewriteRequest {
104///     editing: RewriteOptions { checksums: ChecksumPolicy::BestEffort, ..RewriteOptions::default() },
105///     ..RewriteRequest::default()
106/// };
107/// let report = rewrite_source("R.tla", source, &request);
108/// assert!(report.accepted());
109/// assert!(report.to_json()["replacement"]["translation_checksum"].is_string());
110/// ```
111#[must_use]
112pub fn rewrite_source(file: &str, source: &str, request: &RewriteRequest) -> RewriteReport {
113    let selection = match dive_pluscal::rewrite::select_rewrite(source, &request.editing) {
114        Ok(selection) => selection,
115        Err(error) => return failure(file, request, "selection", &error),
116    };
117    let context =
118        match dive_pluscal::resolve_translation_options(source, &request.translation.limits) {
119            Ok(context) => context,
120            Err(error) => return failure(file, request, "source-options", &error.diagnostic),
121        };
122    if let (Some(previous), Some(declaration)) = (selection.previous, &context.source_declaration)
123        && declaration.span.start < previous.end
124        && declaration.span.end > previous.start
125    {
126        return failure(file, request, "source-options", &Diagnostic {
127                code: Code::Unsupported,
128                span: dive_pluscal::source_option_declaration_span(source)
129                    .unwrap_or(declaration.span),
130                message: "unsupported PlusCal source option declaration inside previous translation; masking would change the deciding context".into(),
131            });
132    }
133    let masked = dive_pluscal::rewrite::mask_previous(source, selection.previous);
134    let generated = crate::translate::translate_source_at_insertion(
135        file,
136        &masked,
137        &request.translation,
138        selection.previous.map(|previous| previous.start),
139    );
140    if !generated.accepted() {
141        return report(
142            file,
143            request,
144            generated.exit_code(),
145            "native-generation",
146            json!({"generation":generated.to_json()}),
147        );
148    }
149    let generated = generated.to_json();
150    let Some(body) = generated["artifact"]["tla"].as_str() else {
151        return report(
152            file,
153            request,
154            4,
155            "native-generation",
156            json!({"diagnostic":{"code":"DIVE-P0050","message":"accepted generator omitted body"}}),
157        );
158    };
159    let editing = effective_editing(request);
160    let plan = match dive_pluscal::rewrite::rewrite_document_with_translation_options(
161        source,
162        body,
163        &editing,
164        &request.translation.limits,
165    ) {
166        Ok(plan) => plan,
167        Err(error) => return failure(file, request, "replacement", &error),
168    };
169    let analysis = analyze_source(file, &plan.module_source, &request.translation.analyze);
170    if !analysis.accepted() {
171        return report(
172            file,
173            request,
174            1,
175            "replacement-analysis",
176            json!({"analysis":analysis.to_json(),"replacement_returned":false}),
177        );
178    }
179    let mut filesystem_plan = generated["filesystem_plan"].clone();
180    filesystem_plan["source_newlines"] = json!(if editing.normalize_newlines {
181        "normalized-lf"
182    } else {
183        "preserved"
184    });
185    filesystem_plan["body_newlines"] = json!(replacement_newlines(&plan.replacement));
186    report(
187        file,
188        request,
189        0,
190        "replacement-analysis",
191        json!({"translation_options":context.effective,"source_options":context.source_declaration,"replacement":plan,"artifact":generated["artifact"],"analysis":analysis.to_json(),"filesystem_plan":filesystem_plan}),
192    )
193}
194/// Read a bounded UTF-8 module and return its in-memory replacement plan.
195///
196/// # Errors
197/// An I/O API error on unreadable/non-UTF-8 source. Stage failures are reports.
198pub fn rewrite_file(path: &Path, request: &RewriteRequest) -> Result<RewriteReport, ApiError> {
199    let file = path.display().to_string();
200    let reader = std::fs::File::open(path).map_err(|error| ApiError::Io {
201        path: file.clone(),
202        error,
203    })?;
204    let limit = request.editing.max_bytes.min(4_194_304);
205    let mut bytes = Vec::new();
206    reader
207        .take(u64::try_from(limit).unwrap_or(u64::MAX).saturating_add(1))
208        .read_to_end(&mut bytes)
209        .map_err(|error| ApiError::Io {
210            path: file.clone(),
211            error,
212        })?;
213    if bytes.len() > limit {
214        return Ok(failure(
215            &file,
216            request,
217            "selection",
218            &Diagnostic {
219                code: Code::Resource,
220                span: dive_pluscal::ast::Span::default(),
221                message: "PlusCal rewrite source byte limit reached".to_owned(),
222            },
223        ));
224    }
225    let source = String::from_utf8(bytes).map_err(|error| ApiError::Io {
226        path: file.clone(),
227        error: std::io::Error::new(std::io::ErrorKind::InvalidData, error),
228    })?;
229    Ok(rewrite_source(&file, &source, request))
230}