Skip to main content

dive_pluscal/translate/
mod.rs

1//! Native reference-semantic PlusCal translation with explicit resource bounds.
2mod checksum;
3mod definitions;
4pub use checksum::{
5    AlgorithmChecksum, OriginalAstArtifact, algorithm_checksum_at, original_ast_at,
6};
7mod labels;
8mod lower;
9mod macros;
10mod options;
11mod pcal;
12mod procedures;
13mod process;
14pub use options::{
15    SourceOptionArgument, SourceOptionDeclaration, TranslationContext, resolve_translation_options,
16    source_options_span,
17};
18
19use crate::{Code, Diagnostic, Options, ast::Span};
20use serde::{Deserialize, Serialize};
21
22/// Pinned translator fairness selection, applied before process normalization.
23#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
24pub enum FairnessOption {
25    /// Preserve explicit source declarations (the pinned default).
26    #[default]
27    Declared,
28    /// Suppress generated fairness (`-nof`), except a sequential `--fair` source.
29    None,
30    /// Supply weak fairness for otherwise unfair processes (`-wf`).
31    Weak,
32    /// Supply strong fairness for otherwise unfair processes (`-sf`).
33    Strong,
34    /// Add weak fairness of the complete next action (`-wfNext`).
35    Next,
36}
37
38/// Native translator settings and explicit resource bounds.
39///
40/// ```
41/// use dive_pluscal::{TranslationOptions, translate};
42/// let options = TranslationOptions {
43///     check_termination: true,
44///     no_done_disjunct: true,
45///     line_width: 60,
46///     ..TranslationOptions::default()
47/// };
48/// let artifact = translate(
49///     "--algorithm A variable x=0; begin L:x:=1; E:skip; end algorithm", &options,
50/// )?;
51/// assert_eq!(artifact.configuration, "PROPERTY Termination\n");
52/// assert!(!artifact.tla.contains("Terminating =="));
53/// # Ok::<(), dive_pluscal::TranslationError>(())
54/// ```
55#[derive(Clone, Debug, Serialize, Deserialize)]
56#[serde(default)]
57#[allow(
58    clippy::struct_excessive_bools,
59    reason = "independent pinned translator switches retain their option identities"
60)]
61pub struct TranslationOptions {
62    /// Source parser limits.
63    pub parser: Options,
64    /// Insert missing labels even when the source already has labels (`-label`).
65    /// Sequential sources without labels enable insertion by default; process
66    /// bodies always require this option when a label is missing.
67    pub insert_missing_labels: bool,
68    /// Prefix of generated labels (`-labelRoot`); this does not enable insertion.
69    pub label_root: String,
70    /// Process/default fairness (`-nof`, `-wf`, `-sf`, `-wfNext`).
71    #[serde(default)]
72    pub fairness: FairnessOption,
73    /// Request `PROPERTY Termination`; defaults unspecified fairness to weak
74    /// fairness, as `-termination` does. This never proves termination.
75    pub check_termination: bool,
76    /// Omit the terminating stutter action/disjunct (`-noDoneDisjunct`).
77    pub no_done_disjunct: bool,
78    /// Reference wrapping column (`-lineWidth`), an i32 value at least 60.
79    /// Default 78 is TLC-equivalent; this is not a hard maximum line length.
80    pub line_width: i32,
81    /// Input language version (`-version`), using pinned decimal thousandths.
82    /// None selects the actual current weight 1903, not the displayed `1.12`.
83    pub version: Option<String>,
84    /// Report added labels (`-reportLabels`); also enables label insertion.
85    /// CLI-only in the pinned translator; source declarations still refuse it.
86    pub report_labels: bool,
87    /// Suppress the backup in a filesystem artifact plan (`-noold`).
88    /// The translator itself performs no filesystem writes.
89    pub no_old: bool,
90    /// Suppress configuration emission in an artifact plan (`-nocfg`).
91    /// Semantic configuration requirements remain in the returned translation.
92    pub no_configuration: bool,
93    /// Record the CLI-only `-unixEOL` request. On the pinned JRE this does not
94    /// override the writer's established separator; no forced LF is implied.
95    pub unix_eol: bool,
96    /// CLI-only debug AST location serialization. Supported bounded simple
97    /// statement shapes change the algorithm CRC while preserving TLA output.
98    pub debug: bool,
99    /// CLI-only `-writeAST` filesystem operation, currently unsupported.
100    /// Use [`original_ast_at`] for explicit in-memory original bytes.
101    pub write_ast: bool,
102    /// The pcal.trans specification-backend option and specification name.
103    /// `spec`, `myspec`, `spec2`, `myspec2` are explicitly unsupported backends.
104    pub specification_backend: Option<(String, String)>,
105    /// Maximum labelled actions (hard ceiling: 10,000).
106    pub max_actions: usize,
107    /// Maximum generated bytes (hard ceiling: 4 MiB).
108    /// Also bounds macro expression expansion before token allocation.
109    pub max_output_bytes: usize,
110}
111impl Default for TranslationOptions {
112    fn default() -> Self {
113        Self {
114            parser: Options::default(),
115            insert_missing_labels: false,
116            label_root: "Lbl_".into(),
117            fairness: FairnessOption::Declared,
118            check_termination: false,
119            no_done_disjunct: false,
120            line_width: 78,
121            version: None,
122            report_labels: false,
123            no_old: false,
124            no_configuration: false,
125            unix_eol: false,
126            debug: false,
127            write_ast: false,
128            specification_backend: None,
129            max_actions: 10_000,
130            max_output_bytes: 4_194_304,
131        }
132    }
133}
134
135/// The stage deciding a translation failure.
136#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
137pub enum TranslationStage {
138    /// Lexing/source grammar failed.
139    Source,
140    /// Labels, names or control flow failed admission.
141    Normalization,
142    /// Generated expression/action construction failed.
143    Generation,
144}
145
146/// A translation failure never carries a partially accepted artifact.
147#[derive(Clone, Debug, Serialize, Deserialize)]
148pub struct TranslationError {
149    /// Deciding stage, separate from source grammar acceptance.
150    pub stage: TranslationStage,
151    /// Stable diagnostic over original source.
152    pub diagnostic: Diagnostic,
153}
154impl std::fmt::Display for TranslationError {
155    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
156        self.diagnostic.fmt(formatter)
157    }
158}
159impl std::error::Error for TranslationError {}
160
161/// An artifact region and its original PlusCal source region.
162#[derive(Clone, Debug, Serialize, Deserialize)]
163pub struct TranslationMap {
164    /// UTF-8 byte interval of an emitted action definition in the generated
165    /// TLA body, including its header and complete body. The end is exclusive.
166    pub generated: Span,
167    /// UTF-8 byte interval of the original labelled statement owner. The end
168    /// is exclusive; scoped renaming and program-counter omission retain it.
169    pub original: Span,
170}
171
172/// A nonfatal normalization observation, never a successful check verdict.
173#[derive(Clone, Debug, Serialize, Deserialize)]
174pub struct TranslationWarning {
175    /// Stable observation code.
176    pub code: String,
177    /// Original PlusCal source bytes.
178    pub span: Span,
179    /// Human-readable detail.
180    pub message: String,
181}
182
183/// A generated label associated with its original statement, not a source token.
184#[derive(Clone, Debug, Serialize, Deserialize)]
185pub struct InsertedLabel {
186    /// Generated action name.
187    pub name: String,
188    /// Original statement extent.
189    pub source: Span,
190    /// Original one-based reference statement position (C `with` uses its `(`).
191    pub position: crate::ast::Position,
192    /// Macro definition statement extent, when the label arose from expansion.
193    #[serde(default, skip_serializing_if = "Option::is_none")]
194    pub macro_definition: Option<Span>,
195    /// Definition position paired with the existing call-site `position`.
196    #[serde(default, skip_serializing_if = "Option::is_none")]
197    pub macro_definition_position: Option<crate::ast::Position>,
198}
199
200/// Admitted process storage context, never an evaluated process-domain claim.
201#[derive(Clone, Debug, Serialize, Deserialize)]
202pub struct ProcessTranslation {
203    /// Original process operator spelling.
204    pub name: String,
205    /// Constant ID versus membership domain.
206    pub binding_kind: crate::ast::BindingKind,
207    /// Original ID/domain expression bytes.
208    pub id_source: Span,
209    /// Local storage variables, scalar for constant IDs and indexed for sets.
210    pub local_variables: Vec<String>,
211    /// Original complete process bytes.
212    pub source: Span,
213}
214
215/// A native generated TLA body, without file checksums or translator map format.
216#[derive(Clone, Debug, Serialize, Deserialize)]
217pub struct Translation {
218    /// Generated operator/declaration body, not a complete enclosing module.
219    pub tla: String,
220    /// Native source associations. This is not TLC's translator map file.
221    pub mappings: Vec<TranslationMap>,
222    /// Labelled actions in the original translator's expansion order.
223    pub actions: Vec<String>,
224    /// Original translator's program-counter optimization decision.
225    pub program_counter: bool,
226    /// Nonfatal normalization observations with original spans.
227    pub warnings: Vec<TranslationWarning>,
228    /// Inserted labels in the reference normalization traversal order.
229    pub inserted_labels: Vec<InsertedLabel>,
230    /// Required TLC configuration text for default model-value initialization
231    /// and requested `PROPERTY Termination`, even when `-nocfg` suppresses emission.
232    /// This contains requirements, not a rewritten complete configuration file.
233    pub configuration: String,
234    /// Admitted process declarations; empty for sequential translation.
235    pub processes: Vec<ProcessTranslation>,
236    /// Requested and effective source/CLI settings used for this artifact.
237    pub option_context: TranslationContext,
238}
239
240fn error(
241    stage: TranslationStage,
242    code: Code,
243    span: Span,
244    message: impl Into<String>,
245) -> TranslationError {
246    TranslationError {
247        stage,
248        diagnostic: Diagnostic {
249            code,
250            span,
251            message: message.into(),
252        },
253    }
254}
255
256/// Find the reference-style source option header before hiding old output.
257///
258/// This callback-free alias preserves the original header diagnostic extent.
259/// It does not parse arguments or certify admission. Resolved declarations carry
260/// the full extent used for overlap checks; callers enforce their byte limit.
261#[must_use]
262pub fn source_option_declaration_span(source: &str) -> Option<Span> {
263    source_options_span(source)
264}
265
266/// Translates a bounded current C/P algorithm using the pinned translator's
267/// labels, scoped renaming, macro expansion, process and procedure semantics.
268/// Symbolic process domains are translated without evaluating them. Historical
269/// modes and generated-operator collisions remain explicit refusals. Complete
270/// module name and level analysis belongs to the whole-module API.
271///
272/// # Errors
273/// Named source, normalization, generation or resource diagnostics.
274pub fn translate(
275    source: &str,
276    options: &TranslationOptions,
277) -> Result<Translation, TranslationError> {
278    translate_at(source, 0..source.len(), options)
279}
280
281/// Translates a selected algorithm in original module source.
282/// Original byte spans are preserved. Each call joins a 16 MiB scoped worker;
283/// the translator never invokes Java or writes files.
284///
285/// # Errors
286/// Named source, normalization, generation or resource diagnostics.
287pub fn translate_at(
288    source: &str,
289    region: std::ops::Range<usize>,
290    options: &TranslationOptions,
291) -> Result<Translation, TranslationError> {
292    std::thread::scope(|scope| {
293        let worker = std::thread::Builder::new()
294            .name("dive-pluscal-translator".into())
295            .stack_size(16 * 1024 * 1024)
296            .spawn_scoped(scope, || {
297                let context = resolve_translation_options(source, options)?;
298                let mut parser = context.effective.parser.clone();
299                parser.input_version =
300                    options::version_weight(context.effective.version.as_deref())?;
301                let parsed = crate::parse_at(source, region, &parser).map_err(|diagnostic| {
302                    TranslationError {
303                        stage: TranslationStage::Source,
304                        diagnostic,
305                    }
306                })?;
307                generate(source, &parsed, &context).map_err(|mut failure: TranslationError| {
308                    if failure.diagnostic.span == Span::default() {
309                        failure.diagnostic.span = parsed.algorithm.span;
310                    }
311                    failure
312                })
313            })
314            .map_err(|failure| {
315                error(
316                    TranslationStage::Normalization,
317                    Code::Resource,
318                    Span::default(),
319                    format!("cannot start PlusCal translator: {failure}"),
320                )
321            })?;
322        worker.join().map_err(|_| {
323            error(
324                TranslationStage::Generation,
325                Code::Internal,
326                Span::default(),
327                "PlusCal translation worker failed; report this input as a bug",
328            )
329        })?
330    })
331}
332
333fn fairness_name(fairness: FairnessOption) -> &'static str {
334    match fairness {
335        FairnessOption::Declared => "",
336        FairnessOption::None => "nof",
337        FairnessOption::Weak => "wf",
338        FairnessOption::Strong => "sf",
339        FairnessOption::Next => "wfNext",
340    }
341}
342
343/// Runs the translator and packages its output.
344#[allow(
345    clippy::too_many_lines,
346    reason = "package translation output and source associations together"
347)]
348fn generate(
349    source: &str,
350    parsed: &crate::Parsed,
351    context: &TranslationContext,
352) -> Result<Translation, TranslationError> {
353    let options = &context.effective;
354    let root = &options.label_root;
355    if root.len() > 256 {
356        return Err(error(
357            TranslationStage::Normalization,
358            Code::Resource,
359            parsed.algorithm.span,
360            "PlusCal label-root byte limit (256) reached",
361        ));
362    }
363    let mut chars = root.chars();
364    if !chars.next().is_some_and(|c| c.is_ascii_alphabetic())
365        || !chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
366    {
367        return Err(error(
368            TranslationStage::Normalization,
369            Code::Label,
370            parsed.algorithm.span,
371            "Label root must be a valid PlusCal identifier (must start with a letter and contain only letters, numbers, and underscores)",
372        ));
373    }
374    let settings = pcal::Settings {
375        label: options.insert_missing_labels,
376        label_root: root.clone(),
377        fairness: fairness_name(if parsed.algorithm.legacy_fair {
378            FairnessOption::Weak
379        } else {
380            options.fairness
381        })
382        .to_owned(),
383        no_done_disjunct: options.no_done_disjunct,
384        wrap_column: usize::try_from(options.line_width).map_err(|_| {
385            error(
386                TranslationStage::Normalization,
387                Code::Unsupported,
388                parsed.algorithm.span,
389                "unsupported PlusCal lineWidth",
390            )
391        })?,
392        version_weight: options::version_weight(options.version.as_deref())?,
393        max_depth: options.parser.max_depth.min(256),
394        max_actions: options.max_actions.min(10_000),
395        max_output_bytes: options.max_output_bytes.min(4_194_304),
396        max_macro_nodes: options.parser.max_nodes.min(20_000),
397        max_macro_tokens: options.parser.max_tokens.saturating_mul(4).min(400_000),
398        max_macro_bytes: options
399            .parser
400            .max_bytes
401            .saturating_mul(4)
402            .min(options.max_output_bytes)
403            .min(4_194_304),
404    };
405    options::admit_version_shape(parsed, settings.version_weight)?;
406    let output = pcal::translate(parsed, &settings).map_err(|failure| {
407        let span = failure.at.map_or(Span::default(), |at| {
408            parsed
409                .tokens
410                .iter()
411                .find(|t| t.span.start >= at)
412                .map_or(Span { start: at, end: at }, |t| t.span)
413        });
414        let stage = if failure.in_generation || failure.code == Code::Internal {
415            TranslationStage::Generation
416        } else {
417            TranslationStage::Normalization
418        };
419        error(stage, failure.code, span, failure.message)
420    })?;
421    let tla = output.lines.join("\n");
422    if tla.len() > options.max_output_bytes.min(4_194_304) {
423        return Err(error(
424            TranslationStage::Generation,
425            Code::Resource,
426            parsed.algorithm.span,
427            "PlusCal generated-output byte limit reached",
428        ));
429    }
430    // Source expressions are scanned, not parsed, so a generated body can be
431    // malformed (pcal.trans then writes it anyway). Never return one.
432    let module = format!("---- MODULE NativePlusCal ----\nEXTENDS TLC\n{tla}\n====\n");
433    if !dive_syntax::parse_module(&module).is_ok() {
434        return Err(error(
435            TranslationStage::Generation,
436            Code::Expression,
437            parsed.algorithm.span,
438            "generated TLA syntax rejected; source expression validation failed",
439        ));
440    }
441    let processes = match &parsed.algorithm.body {
442        crate::ast::Body::Processes(list) => list
443            .iter()
444            .zip(&output.processes)
445            .map(|(process, info)| ProcessTranslation {
446                name: info.name.clone(),
447                binding_kind: process.id.kind,
448                id_source: process.id.expression.span,
449                local_variables: info.local_variables.clone(),
450                source: process.span,
451            })
452            .collect(),
453        crate::ast::Body::Sequential(_) => Vec::new(),
454    };
455    let warnings = if output.renamed.is_empty() {
456        Vec::new()
457    } else {
458        vec![TranslationWarning {
459            code: "symbols-renamed".into(),
460            span: parsed.algorithm.span,
461            message: "symbols were renamed.".into(),
462        }]
463    };
464    let mappings = output
465        .mappings
466        .iter()
467        .map(|mapping| {
468            let at = mapping.original;
469            TranslationMap {
470                generated: mapping.generated,
471                original: statement_span(
472                    parsed,
473                    position_offset(
474                        source,
475                        at.macro_call.map_or(at.line, |(line, _)| line),
476                        at.macro_call.map_or(at.col, |(_, column)| column),
477                    ),
478                ),
479            }
480        })
481        .collect();
482    Ok(Translation {
483        tla,
484        mappings,
485        actions: output.actions,
486        program_counter: output.program_counter,
487        warnings,
488        inserted_labels: output
489            .added_labels
490            .iter()
491            .map(|label| InsertedLabel {
492                name: label.name.clone(),
493                source: label.macro_call.map_or_else(
494                    || statement_span(parsed, label.at),
495                    |(line, column)| statement_span(parsed, position_offset(source, line, column)),
496                ),
497                position: label.macro_call.map_or(
498                    crate::ast::Position {
499                        line: label.line,
500                        column: label.column,
501                    },
502                    |(line, column)| crate::ast::Position { line, column },
503                ),
504                macro_definition: label.macro_call.map(|_| statement_span(parsed, label.at)),
505                macro_definition_position: label.macro_call.map(|_| crate::ast::Position {
506                    line: label.line,
507                    column: label.column,
508                }),
509            })
510            .collect(),
511        configuration: {
512            let mut requirements = String::new();
513            if output.default_init {
514                requirements.push_str("CONSTANT defaultInitValue = defaultInitValue\n");
515            }
516            if options.check_termination {
517                requirements.push_str("PROPERTY Termination\n");
518            }
519            requirements
520        },
521        processes,
522        option_context: context.clone(),
523    })
524}
525
526/// The innermost original statement owning a translator offset.
527fn statement_span(parsed: &crate::Parsed, offset: usize) -> Span {
528    parsed
529        .statements
530        .iter()
531        .filter(|stmt| stmt.span.start <= offset && offset < stmt.span.end)
532        .min_by_key(|stmt| stmt.span.end.saturating_sub(stmt.span.start))
533        .map_or(
534            Span {
535                start: offset,
536                end: offset,
537            },
538            |stmt| stmt.span,
539        )
540}
541
542/// Byte offset of a reference location, expanding tabs as the source builder does.
543fn position_offset(source: &str, target_line: usize, target_column: usize) -> usize {
544    let mut line = 1;
545    let mut column = 1;
546    let mut characters = source.char_indices().peekable();
547    while let Some((offset, ch)) = characters.next() {
548        if line == target_line && column == target_column {
549            return offset;
550        }
551        match ch {
552            '\r' => {
553                // CRLF is one physical break, with no intermediate line start.
554                if characters.peek().is_some_and(|(_, next)| *next == '\n') {
555                    let _ = characters.next();
556                }
557                line += 1;
558                column = 1;
559            }
560            '\n' => {
561                line += 1;
562                column = 1;
563            }
564            '\t' => column += 8 - (column - 1) % 8,
565            _ => column += 1,
566        }
567    }
568    source.len()
569}