1mod 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#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
24pub enum FairnessOption {
25 #[default]
27 Declared,
28 None,
30 Weak,
32 Strong,
34 Next,
36}
37
38#[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 pub parser: Options,
64 pub insert_missing_labels: bool,
68 pub label_root: String,
70 #[serde(default)]
72 pub fairness: FairnessOption,
73 pub check_termination: bool,
76 pub no_done_disjunct: bool,
78 pub line_width: i32,
81 pub version: Option<String>,
84 pub report_labels: bool,
87 pub no_old: bool,
90 pub no_configuration: bool,
93 pub unix_eol: bool,
96 pub debug: bool,
99 pub write_ast: bool,
102 pub specification_backend: Option<(String, String)>,
105 pub max_actions: usize,
107 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#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
137pub enum TranslationStage {
138 Source,
140 Normalization,
142 Generation,
144}
145
146#[derive(Clone, Debug, Serialize, Deserialize)]
148pub struct TranslationError {
149 pub stage: TranslationStage,
151 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#[derive(Clone, Debug, Serialize, Deserialize)]
163pub struct TranslationMap {
164 pub generated: Span,
167 pub original: Span,
170}
171
172#[derive(Clone, Debug, Serialize, Deserialize)]
174pub struct TranslationWarning {
175 pub code: String,
177 pub span: Span,
179 pub message: String,
181}
182
183#[derive(Clone, Debug, Serialize, Deserialize)]
185pub struct InsertedLabel {
186 pub name: String,
188 pub source: Span,
190 pub position: crate::ast::Position,
192 #[serde(default, skip_serializing_if = "Option::is_none")]
194 pub macro_definition: Option<Span>,
195 #[serde(default, skip_serializing_if = "Option::is_none")]
197 pub macro_definition_position: Option<crate::ast::Position>,
198}
199
200#[derive(Clone, Debug, Serialize, Deserialize)]
202pub struct ProcessTranslation {
203 pub name: String,
205 pub binding_kind: crate::ast::BindingKind,
207 pub id_source: Span,
209 pub local_variables: Vec<String>,
211 pub source: Span,
213}
214
215#[derive(Clone, Debug, Serialize, Deserialize)]
217pub struct Translation {
218 pub tla: String,
220 pub mappings: Vec<TranslationMap>,
222 pub actions: Vec<String>,
224 pub program_counter: bool,
226 pub warnings: Vec<TranslationWarning>,
228 pub inserted_labels: Vec<InsertedLabel>,
230 pub configuration: String,
234 pub processes: Vec<ProcessTranslation>,
236 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#[must_use]
262pub fn source_option_declaration_span(source: &str) -> Option<Span> {
263 source_options_span(source)
264}
265
266pub fn translate(
275 source: &str,
276 options: &TranslationOptions,
277) -> Result<Translation, TranslationError> {
278 translate_at(source, 0..source.len(), options)
279}
280
281pub 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#[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 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
526fn 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
542fn 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 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}