Skip to main content

dive_api/
translate.rs

1//! Bounded native sequential/finite-process PlusCal artifacts, validated as enclosing modules.
2use crate::{AnalyzeOptions, ApiError, analyze_source};
3use dive_pluscal::{Code, TranslationOptions};
4use serde_json::{Value, json};
5use std::io::Read as _;
6use std::path::Path;
7
8/// Version of native translation report documents.
9pub const TRANSLATE_SCHEMA_VERSION: u32 = crate::REPORT_SCHEMA_VERSION;
10/// Translation mode and explicit resource/module resolution settings.
11#[derive(Clone, Debug, Default)]
12pub struct TranslationRequest {
13    /// Native bounded parser/generator limits.
14    pub limits: TranslationOptions,
15    /// Module resolution for validating the resulting module.
16    pub analyze: AnalyzeOptions,
17    /// Global compatibility selection. Current supported generation is shared;
18    /// specification backends and broader
19    /// checksum shapes remain pending.
20    pub compat_tlc: bool,
21}
22/// Stage-separated translation report. Acceptance never means a model proof.
23#[derive(Clone, Debug)]
24pub struct TranslationReport {
25    document: Value,
26    status: u8,
27}
28impl TranslationReport {
29    /// Whether a generated enclosing module passed native syntax and semantics.
30    #[must_use]
31    pub fn accepted(&self) -> bool {
32        self.status == 0
33    }
34    /// Native command exit: zero artifact, one rejected, three unsupported/bound,
35    /// four internal error. No TLC model-checking exit is implied.
36    #[must_use]
37    pub const fn exit_code(&self) -> u8 {
38        self.status
39    }
40    /// Complete stage/disposition/limits/evidence document.
41    #[must_use]
42    pub fn to_json(&self) -> Value {
43        self.document.clone()
44    }
45}
46pub(crate) fn translation_artifact_json(artifact: &dive_pluscal::Translation) -> Value {
47    let mut value = json!(artifact);
48    if let Some(object) = value.as_object_mut() {
49        object.remove("option_context");
50    }
51    value
52}
53fn report(
54    file: &str,
55    request: &TranslationRequest,
56    status: u8,
57    stage: &str,
58    details: Value,
59) -> TranslationReport {
60    let result = match status {
61        0 => "artifact",
62        1 => "rejected",
63        3 => "unsupported",
64        _ => "internal-error",
65    };
66    let mut document = json!({"schema_version":TRANSLATE_SCHEMA_VERSION,"command":"translate","file":file,
67        "profile":if request.compat_tlc {"tlc"} else {"dive"},"result":result,"stage":stage,"accepted":status==0,
68        "exit_code":status,"limits":request.limits});
69    if let (Some(object), Value::Object(extra)) = (document.as_object_mut(), details) {
70        object.extend(extra);
71    }
72    TranslationReport { document, status }
73}
74/// Translates a file in memory without rewriting it or invoking external tools.
75/// The file must contain one algorithm in a block comment. An existing translation
76/// is replaced in its original location; nothing is written to disk.
77/// Generated modules pass native syntax/name/level analysis before acceptance.
78///
79/// # Errors
80/// An I/O API error if the input cannot be read; stage failures are reports.
81pub fn translate_file(
82    path: &Path,
83    request: &TranslationRequest,
84) -> Result<TranslationReport, ApiError> {
85    let file = path.display().to_string();
86    let reader = std::fs::File::open(path).map_err(|error| ApiError::Io {
87        path: file.clone(),
88        error,
89    })?;
90    let mut bytes = Vec::new();
91    reader
92        .take(4_194_305)
93        .read_to_end(&mut bytes)
94        .map_err(|error| ApiError::Io {
95            path: file.clone(),
96            error,
97        })?;
98    if bytes.len() > 4_194_304 {
99        return Ok(report(
100            &file,
101            request,
102            3,
103            "selection",
104            json!({"diagnostic":{"code":"DIVE-P0040","span":{"start":0,"end":0},"message":"PlusCal module source exceeds 4 MiB"}}),
105        ));
106    }
107    let source = String::from_utf8(bytes).map_err(|error| ApiError::Io {
108        path: file.clone(),
109        error: std::io::Error::new(std::io::ErrorKind::InvalidData, error),
110    })?;
111    Ok(translate_source(&file, &source, request))
112}
113/// Translates module source in memory. Artifact spans refer to generated body;
114/// original spans refer to this exact UTF-8 source. No file mapping/checksum
115/// compatibility or complete PlusCal translation coverage is implied.
116#[must_use]
117pub fn translate_source(
118    file: &str,
119    source: &str,
120    request: &TranslationRequest,
121) -> TranslationReport {
122    translate_source_at_insertion(file, source, request, None)
123}
124
125/// Generates at the final placement before module analysis, including rewrite's
126/// masked view of a previous block located after intervening user definitions.
127#[allow(
128    clippy::too_many_lines,
129    reason = "ordered source selection, bounded generation and enclosing-module validation retain deciding-stage evidence"
130)]
131pub(crate) fn translate_source_at_insertion(
132    file: &str,
133    source: &str,
134    request: &TranslationRequest,
135    insertion_override: Option<usize>,
136) -> TranslationReport {
137    if source.len() > 4_194_304 {
138        return report(
139            file,
140            request,
141            3,
142            "selection",
143            json!({"diagnostic":{"code":"DIVE-P0040","span":{"start":0,"end":0},"message":"PlusCal module source exceeds 4 MiB"}}),
144        );
145    }
146    let selection = match dive_pluscal::rewrite::select_rewrite(
147        source,
148        &dive_pluscal::rewrite::RewriteOptions::default(),
149    ) {
150        Ok(selection) => selection,
151        Err(mut diagnostic) => {
152            // Plain translation has always refused incomplete marker layouts;
153            // retain that public selection boundary while sharing rewrite's selector.
154            if diagnostic.code == Code::Syntax
155                && diagnostic.message == "missing or reversed translation marker pair"
156            {
157                diagnostic.code = Code::Unsupported;
158                "unsupported incomplete translation marker pair"
159                    .clone_into(&mut diagnostic.message);
160            }
161            let status = match diagnostic.code {
162                Code::Unsupported | Code::Resource => 3,
163                Code::Internal => 4,
164                _ => 1,
165            };
166            return report(
167                file,
168                request,
169                status,
170                "selection",
171                json!({"code": diagnostic.code.as_str(), "diagnostic": diagnostic}),
172            );
173        }
174    };
175    if let Some(previous) = selection.previous
176        && let Some(declaration) = dive_pluscal::source_option_declaration_span(source)
177        && declaration.start < previous.end
178        && declaration.end > previous.start
179    {
180        return report(
181            file,
182            request,
183            3,
184            "source-options",
185            json!({"diagnostic": {
186                "code": "DIVE-P0090", "span": declaration,
187                "message": "unsupported PlusCal source option declaration inside previous translation; masking would change the deciding context",
188            }}),
189        );
190    }
191    let context = match dive_pluscal::resolve_translation_options(source, &request.limits) {
192        Ok(context) => context,
193        Err(error) => {
194            let status = match error.diagnostic.code {
195                Code::Unsupported | Code::Resource => 3,
196                Code::Internal => 4,
197                _ => 1,
198            };
199            return report(
200                file,
201                request,
202                status,
203                "translation",
204                json!({"translation_stage":error.stage,"diagnostic":error.diagnostic,"code":error.diagnostic.code.as_str()}),
205            );
206        }
207    };
208    let selection = match dive_pluscal::rewrite::select_rewrite_with_parser(
209        source,
210        &dive_pluscal::rewrite::RewriteOptions::default(),
211        &context.effective.parser,
212    ) {
213        Ok(selection) => selection,
214        Err(diagnostic) => {
215            let status = match diagnostic.code {
216                Code::Unsupported | Code::Resource => 3,
217                Code::Internal => 4,
218                _ => 1,
219            };
220            return report(
221                file,
222                request,
223                status,
224                "selection",
225                json!({"code":diagnostic.code.as_str(),"diagnostic":diagnostic}),
226            );
227        }
228    };
229    let masked = dive_pluscal::rewrite::mask_previous(source, selection.previous);
230    let region = selection.algorithm.start..selection.algorithm.end;
231    let insertion = insertion_override.unwrap_or_else(|| {
232        selection
233            .previous
234            .map_or(selection.insertion, |previous| previous.start)
235    });
236    let replacement_end = selection
237        .previous
238        .map_or(insertion, |previous| previous.end);
239    let artifact = match dive_pluscal::translate_at(&masked, region, &request.limits) {
240        Ok(artifact) => artifact,
241        Err(error) => {
242            let status = match error.diagnostic.code {
243                Code::Unsupported | Code::Resource => 3,
244                Code::Internal => 4,
245                _ => 1,
246            };
247            return report(
248                file,
249                request,
250                status,
251                "translation",
252                json!({"translation_stage":error.stage,"diagnostic":error.diagnostic,"code":error.diagnostic.code.as_str()}),
253            );
254        }
255    };
256    let body = if selection.previous.is_some() {
257        format!(
258            "\\* BEGIN TRANSLATION\n{}\n\\* END TRANSLATION\n",
259            artifact.tla
260        )
261    } else {
262        artifact.tla.clone()
263    };
264    let generated = format!(
265        "{}\n{body}\n{}",
266        &source[..insertion],
267        &source[replacement_end..]
268    );
269    let analysis = analyze_source(file, &generated, &request.analyze);
270    if !analysis.accepted() {
271        return report(
272            file,
273            request,
274            1,
275            "artifact-analysis",
276            json!({"analysis":analysis.to_json(),"artifact_returned":false}),
277        );
278    }
279    report(
280        file,
281        request,
282        0,
283        "artifact-analysis",
284        json!({"translation_options":artifact.option_context.effective,"requested_translation_options":request.limits,"source_options":artifact.option_context.source_declaration,"artifact":translation_artifact_json(&artifact),"module_source":generated,"analysis":analysis.to_json(),"filesystem_plan":{
285            "writes_performed":false,
286            "backup_requested":!artifact.option_context.effective.no_old,
287            "configuration_requested":!artifact.option_context.effective.no_configuration,
288            "configuration_requirements":artifact.configuration,
289            "unix_eol_requested":artifact.option_context.effective.unix_eol,
290            "body_newlines":"lf",
291            "source_newlines":"preserved"
292        }}),
293    )
294}