kcl_lib/execution/
state.rs

1use std::sync::Arc;
2
3use anyhow::Result;
4use indexmap::IndexMap;
5use schemars::JsonSchema;
6use serde::{Deserialize, Serialize};
7use uuid::Uuid;
8
9#[cfg(feature = "artifact-graph")]
10use crate::execution::{Artifact, ArtifactCommand, ArtifactGraph, ArtifactId};
11use crate::{
12    CompilationError, EngineManager, ExecutorContext, KclErrorWithOutputs,
13    errors::{KclError, KclErrorDetails, Severity},
14    exec::DefaultPlanes,
15    execution::{
16        EnvironmentRef, ExecOutcome, ExecutorSettings, KclValue, UnitAngle, UnitLen, annotations,
17        cad_op::Operation,
18        id_generator::IdGenerator,
19        memory::{ProgramMemory, Stack},
20        types::{self, NumericType},
21    },
22    modules::{ModuleId, ModuleInfo, ModuleLoader, ModulePath, ModuleRepr, ModuleSource},
23    parsing::ast::types::{Annotation, NodeRef},
24    source_range::SourceRange,
25};
26
27/// State for executing a program.
28#[derive(Debug, Clone)]
29pub struct ExecState {
30    pub(super) global: GlobalState,
31    pub(super) mod_local: ModuleState,
32}
33
34pub type ModuleInfoMap = IndexMap<ModuleId, ModuleInfo>;
35
36#[derive(Debug, Clone)]
37pub(super) struct GlobalState {
38    /// Map from source file absolute path to module ID.
39    pub path_to_source_id: IndexMap<ModulePath, ModuleId>,
40    /// Map from module ID to source file.
41    pub id_to_source: IndexMap<ModuleId, ModuleSource>,
42    /// Map from module ID to module info.
43    pub module_infos: ModuleInfoMap,
44    /// Module loader.
45    pub mod_loader: ModuleLoader,
46    /// Errors and warnings.
47    pub errors: Vec<CompilationError>,
48    /// Global artifacts that represent the entire program.
49    pub artifacts: ArtifactState,
50    /// Artifacts for only the root module.
51    pub root_module_artifacts: ModuleArtifactState,
52}
53
54#[cfg(feature = "artifact-graph")]
55#[derive(Debug, Clone, Default)]
56pub(super) struct ArtifactState {
57    /// Internal map of UUIDs to exec artifacts.  This needs to persist across
58    /// executions to allow the graph building to refer to cached artifacts.
59    pub artifacts: IndexMap<ArtifactId, Artifact>,
60    /// Output artifact graph.
61    pub graph: ArtifactGraph,
62}
63
64#[cfg(not(feature = "artifact-graph"))]
65#[derive(Debug, Clone, Default)]
66pub(super) struct ArtifactState {}
67
68/// Artifact state for a single module.
69#[cfg(feature = "artifact-graph")]
70#[derive(Debug, Clone, Default, PartialEq, Serialize)]
71pub struct ModuleArtifactState {
72    /// Internal map of UUIDs to exec artifacts.
73    pub artifacts: IndexMap<ArtifactId, Artifact>,
74    /// Outgoing engine commands that have not yet been processed and integrated
75    /// into the artifact graph.
76    #[serde(skip)]
77    pub unprocessed_commands: Vec<ArtifactCommand>,
78    /// Outgoing engine commands.
79    pub commands: Vec<ArtifactCommand>,
80    /// Operations that have been performed in execution order, for display in
81    /// the Feature Tree.
82    pub operations: Vec<Operation>,
83}
84
85#[cfg(not(feature = "artifact-graph"))]
86#[derive(Debug, Clone, Default, PartialEq, Serialize)]
87pub struct ModuleArtifactState {}
88
89#[derive(Debug, Clone)]
90pub(super) struct ModuleState {
91    /// The id generator for this module.
92    pub id_generator: IdGenerator,
93    pub stack: Stack,
94    /// The current value of the pipe operator returned from the previous
95    /// expression.  If we're not currently in a pipeline, this will be None.
96    pub pipe_value: Option<KclValue>,
97    /// The closest variable declaration being executed in any parent node in the AST.
98    /// This is used to provide better error messages, e.g. noticing when the user is trying
99    /// to use the variable `length` inside the RHS of its own definition, like `length = tan(length)`.
100    /// TODO: Make this a reference.
101    pub being_declared: Option<String>,
102    /// Identifiers that have been exported from the current module.
103    pub module_exports: Vec<String>,
104    /// Settings specified from annotations.
105    pub settings: MetaSettings,
106    pub(super) explicit_length_units: bool,
107    pub(super) path: ModulePath,
108    /// Artifacts for only this module.
109    pub artifacts: ModuleArtifactState,
110
111    pub(super) allowed_warnings: Vec<&'static str>,
112    pub(super) denied_warnings: Vec<&'static str>,
113}
114
115impl ExecState {
116    pub fn new(exec_context: &super::ExecutorContext) -> Self {
117        ExecState {
118            global: GlobalState::new(&exec_context.settings),
119            mod_local: ModuleState::new(ModulePath::Main, ProgramMemory::new(), Default::default()),
120        }
121    }
122
123    pub(super) fn reset(&mut self, exec_context: &super::ExecutorContext) {
124        let global = GlobalState::new(&exec_context.settings);
125
126        *self = ExecState {
127            global,
128            mod_local: ModuleState::new(self.mod_local.path.clone(), ProgramMemory::new(), Default::default()),
129        };
130    }
131
132    /// Log a non-fatal error.
133    pub fn err(&mut self, e: CompilationError) {
134        self.global.errors.push(e);
135    }
136
137    /// Log a warning.
138    pub fn warn(&mut self, mut e: CompilationError, name: &'static str) {
139        debug_assert!(annotations::WARN_VALUES.contains(&name));
140
141        if self.mod_local.allowed_warnings.contains(&name) {
142            return;
143        }
144
145        if self.mod_local.denied_warnings.contains(&name) {
146            e.severity = Severity::Error;
147        } else {
148            e.severity = Severity::Warning;
149        }
150
151        self.global.errors.push(e);
152    }
153
154    pub fn clear_units_warnings(&mut self, source_range: &SourceRange) {
155        self.global.errors = std::mem::take(&mut self.global.errors)
156            .into_iter()
157            .filter(|e| {
158                e.severity != Severity::Warning
159                    || !source_range.contains_range(&e.source_range)
160                    || e.tag != crate::errors::Tag::UnknownNumericUnits
161            })
162            .collect();
163    }
164
165    pub fn errors(&self) -> &[CompilationError] {
166        &self.global.errors
167    }
168
169    /// Convert to execution outcome when running in WebAssembly.  We want to
170    /// reduce the amount of data that crosses the WASM boundary as much as
171    /// possible.
172    pub async fn into_exec_outcome(self, main_ref: EnvironmentRef, ctx: &ExecutorContext) -> ExecOutcome {
173        // Fields are opt-in so that we don't accidentally leak private internal
174        // state when we add more to ExecState.
175        ExecOutcome {
176            variables: self.mod_local.variables(main_ref),
177            filenames: self.global.filenames(),
178            #[cfg(feature = "artifact-graph")]
179            operations: self.global.root_module_artifacts.operations,
180            #[cfg(feature = "artifact-graph")]
181            artifact_graph: self.global.artifacts.graph,
182            errors: self.global.errors,
183            default_planes: ctx.engine.get_default_planes().read().await.clone(),
184        }
185    }
186
187    pub(crate) fn stack(&self) -> &Stack {
188        &self.mod_local.stack
189    }
190
191    pub(crate) fn mut_stack(&mut self) -> &mut Stack {
192        &mut self.mod_local.stack
193    }
194
195    pub fn next_uuid(&mut self) -> Uuid {
196        self.mod_local.id_generator.next_uuid()
197    }
198
199    pub fn id_generator(&mut self) -> &mut IdGenerator {
200        &mut self.mod_local.id_generator
201    }
202
203    #[cfg(feature = "artifact-graph")]
204    pub(crate) fn add_artifact(&mut self, artifact: Artifact) {
205        let id = artifact.id();
206        self.mod_local.artifacts.artifacts.insert(id, artifact);
207    }
208
209    pub(crate) fn push_op(&mut self, op: Operation) {
210        #[cfg(feature = "artifact-graph")]
211        self.mod_local.artifacts.operations.push(op.clone());
212        #[cfg(not(feature = "artifact-graph"))]
213        drop(op);
214    }
215
216    #[cfg(feature = "artifact-graph")]
217    pub(crate) fn push_command(&mut self, command: ArtifactCommand) {
218        self.mod_local.artifacts.unprocessed_commands.push(command);
219        #[cfg(not(feature = "artifact-graph"))]
220        drop(command);
221    }
222
223    pub(super) fn next_module_id(&self) -> ModuleId {
224        ModuleId::from_usize(self.global.path_to_source_id.len())
225    }
226
227    pub(super) fn id_for_module(&self, path: &ModulePath) -> Option<ModuleId> {
228        self.global.path_to_source_id.get(path).cloned()
229    }
230
231    pub(super) fn add_path_to_source_id(&mut self, path: ModulePath, id: ModuleId) {
232        debug_assert!(!self.global.path_to_source_id.contains_key(&path));
233        self.global.path_to_source_id.insert(path.clone(), id);
234    }
235
236    pub(crate) fn add_root_module_contents(&mut self, program: &crate::Program) {
237        let root_id = ModuleId::default();
238        // Get the path for the root module.
239        let path = self
240            .global
241            .path_to_source_id
242            .iter()
243            .find(|(_, v)| **v == root_id)
244            .unwrap()
245            .0
246            .clone();
247        self.add_id_to_source(
248            root_id,
249            ModuleSource {
250                path,
251                source: program.original_file_contents.to_string(),
252            },
253        );
254    }
255
256    pub(super) fn add_id_to_source(&mut self, id: ModuleId, source: ModuleSource) {
257        self.global.id_to_source.insert(id, source.clone());
258    }
259
260    pub(super) fn add_module(&mut self, id: ModuleId, path: ModulePath, repr: ModuleRepr) {
261        debug_assert!(self.global.path_to_source_id.contains_key(&path));
262        let module_info = ModuleInfo { id, repr, path };
263        self.global.module_infos.insert(id, module_info);
264    }
265
266    pub fn get_module(&mut self, id: ModuleId) -> Option<&ModuleInfo> {
267        self.global.module_infos.get(&id)
268    }
269
270    #[cfg(all(test, feature = "artifact-graph"))]
271    pub(crate) fn modules(&self) -> &ModuleInfoMap {
272        &self.global.module_infos
273    }
274
275    #[cfg(all(test, feature = "artifact-graph"))]
276    pub(crate) fn root_module_artifact_state(&self) -> &ModuleArtifactState {
277        &self.global.root_module_artifacts
278    }
279
280    pub fn current_default_units(&self) -> NumericType {
281        NumericType::Default {
282            len: self.length_unit(),
283            angle: self.angle_unit(),
284        }
285    }
286
287    pub fn length_unit(&self) -> UnitLen {
288        self.mod_local.settings.default_length_units
289    }
290
291    pub fn angle_unit(&self) -> UnitAngle {
292        self.mod_local.settings.default_angle_units
293    }
294
295    pub(super) fn circular_import_error(&self, path: &ModulePath, source_range: SourceRange) -> KclError {
296        KclError::new_import_cycle(KclErrorDetails::new(
297            format!(
298                "circular import of modules is not allowed: {} -> {}",
299                self.global
300                    .mod_loader
301                    .import_stack
302                    .iter()
303                    .map(|p| p.to_string_lossy())
304                    .collect::<Vec<_>>()
305                    .join(" -> "),
306                path,
307            ),
308            vec![source_range],
309        ))
310    }
311
312    pub(crate) fn pipe_value(&self) -> Option<&KclValue> {
313        self.mod_local.pipe_value.as_ref()
314    }
315
316    pub(crate) fn error_with_outputs(
317        &self,
318        error: KclError,
319        main_ref: Option<EnvironmentRef>,
320        default_planes: Option<DefaultPlanes>,
321    ) -> KclErrorWithOutputs {
322        let module_id_to_module_path: IndexMap<ModuleId, ModulePath> = self
323            .global
324            .path_to_source_id
325            .iter()
326            .map(|(k, v)| ((*v), k.clone()))
327            .collect();
328
329        KclErrorWithOutputs::new(
330            error,
331            self.errors().to_vec(),
332            main_ref
333                .map(|main_ref| self.mod_local.variables(main_ref))
334                .unwrap_or_default(),
335            #[cfg(feature = "artifact-graph")]
336            self.global.root_module_artifacts.operations.clone(),
337            #[cfg(feature = "artifact-graph")]
338            Default::default(),
339            #[cfg(feature = "artifact-graph")]
340            self.global.artifacts.graph.clone(),
341            module_id_to_module_path,
342            self.global.id_to_source.clone(),
343            default_planes,
344        )
345    }
346
347    #[cfg(feature = "artifact-graph")]
348    pub(crate) async fn build_artifact_graph(
349        &mut self,
350        engine: &Arc<Box<dyn EngineManager>>,
351        program: NodeRef<'_, crate::parsing::ast::types::Program>,
352    ) -> Result<(), KclError> {
353        let mut new_commands = Vec::new();
354        let mut new_exec_artifacts = IndexMap::new();
355        for module in self.global.module_infos.values_mut() {
356            match &mut module.repr {
357                ModuleRepr::Kcl(_, Some((_, _, _, module_artifacts)))
358                | ModuleRepr::Foreign(_, Some((_, module_artifacts))) => {
359                    new_commands.extend(module_artifacts.process_commands());
360                    new_exec_artifacts.extend(module_artifacts.artifacts.clone());
361                }
362                ModuleRepr::Root | ModuleRepr::Kcl(_, None) | ModuleRepr::Foreign(_, None) | ModuleRepr::Dummy => {}
363            }
364        }
365        // Take from the module artifacts so that we don't try to process them
366        // again next time due to execution caching.
367        new_commands.extend(self.global.root_module_artifacts.process_commands());
368        // Note: These will get re-processed, but since we're just adding them
369        // to a map, it's fine.
370        new_exec_artifacts.extend(self.global.root_module_artifacts.artifacts.clone());
371        let new_responses = engine.take_responses().await;
372
373        // Move the artifacts into ExecState global to simplify cache
374        // management.
375        self.global.artifacts.artifacts.extend(new_exec_artifacts);
376
377        let initial_graph = self.global.artifacts.graph.clone();
378
379        // Build the artifact graph.
380        let graph_result = crate::execution::artifact::build_artifact_graph(
381            &new_commands,
382            &new_responses,
383            program,
384            &mut self.global.artifacts.artifacts,
385            initial_graph,
386        );
387
388        let artifact_graph = graph_result?;
389        self.global.artifacts.graph = artifact_graph;
390
391        Ok(())
392    }
393
394    #[cfg(not(feature = "artifact-graph"))]
395    pub(crate) async fn build_artifact_graph(
396        &mut self,
397        _engine: &Arc<Box<dyn EngineManager>>,
398        _program: NodeRef<'_, crate::parsing::ast::types::Program>,
399    ) -> Result<(), KclError> {
400        Ok(())
401    }
402}
403
404impl GlobalState {
405    fn new(settings: &ExecutorSettings) -> Self {
406        let mut global = GlobalState {
407            path_to_source_id: Default::default(),
408            module_infos: Default::default(),
409            artifacts: Default::default(),
410            root_module_artifacts: Default::default(),
411            mod_loader: Default::default(),
412            errors: Default::default(),
413            id_to_source: Default::default(),
414        };
415
416        let root_id = ModuleId::default();
417        let root_path = settings.current_file.clone().unwrap_or_default();
418        global.module_infos.insert(
419            root_id,
420            ModuleInfo {
421                id: root_id,
422                path: ModulePath::Local {
423                    value: root_path.clone(),
424                },
425                repr: ModuleRepr::Root,
426            },
427        );
428        global
429            .path_to_source_id
430            .insert(ModulePath::Local { value: root_path }, root_id);
431        global
432    }
433
434    pub(super) fn filenames(&self) -> IndexMap<ModuleId, ModulePath> {
435        self.path_to_source_id.iter().map(|(k, v)| ((*v), k.clone())).collect()
436    }
437
438    pub(super) fn get_source(&self, id: ModuleId) -> Option<&ModuleSource> {
439        self.id_to_source.get(&id)
440    }
441}
442
443impl ArtifactState {
444    #[cfg(feature = "artifact-graph")]
445    pub fn cached_body_items(&self) -> usize {
446        self.graph.item_count
447    }
448
449    pub(crate) fn clear(&mut self) {
450        #[cfg(feature = "artifact-graph")]
451        {
452            self.artifacts.clear();
453            self.graph.clear();
454        }
455    }
456}
457
458impl ModuleArtifactState {
459    pub(crate) fn clear(&mut self) {
460        #[cfg(feature = "artifact-graph")]
461        {
462            self.artifacts.clear();
463            self.unprocessed_commands.clear();
464            self.commands.clear();
465            self.operations.clear();
466        }
467    }
468
469    #[cfg(not(feature = "artifact-graph"))]
470    pub(crate) fn extend(&mut self, _other: ModuleArtifactState) {}
471
472    /// When self is a cached state, extend it with new state.
473    #[cfg(feature = "artifact-graph")]
474    pub(crate) fn extend(&mut self, other: ModuleArtifactState) {
475        self.artifacts.extend(other.artifacts);
476        self.unprocessed_commands.extend(other.unprocessed_commands);
477        self.commands.extend(other.commands);
478        self.operations.extend(other.operations);
479    }
480
481    // Move unprocessed artifact commands so that we don't try to process them
482    // again next time due to execution caching.  Returns a clone of the
483    // commands that were moved.
484    #[cfg(feature = "artifact-graph")]
485    pub(crate) fn process_commands(&mut self) -> Vec<ArtifactCommand> {
486        let unprocessed = std::mem::take(&mut self.unprocessed_commands);
487        let new_module_commands = unprocessed.clone();
488        self.commands.extend(unprocessed);
489        new_module_commands
490    }
491}
492
493impl ModuleState {
494    pub(super) fn new(path: ModulePath, memory: Arc<ProgramMemory>, module_id: Option<ModuleId>) -> Self {
495        ModuleState {
496            id_generator: IdGenerator::new(module_id),
497            stack: memory.new_stack(),
498            pipe_value: Default::default(),
499            being_declared: Default::default(),
500            module_exports: Default::default(),
501            explicit_length_units: false,
502            path,
503            settings: MetaSettings {
504                default_length_units: Default::default(),
505                default_angle_units: Default::default(),
506                kcl_version: "0.1".to_owned(),
507            },
508            artifacts: Default::default(),
509            allowed_warnings: Vec::new(),
510            denied_warnings: Vec::new(),
511        }
512    }
513
514    pub(super) fn variables(&self, main_ref: EnvironmentRef) -> IndexMap<String, KclValue> {
515        self.stack
516            .find_all_in_env(main_ref)
517            .map(|(k, v)| (k.clone(), v.clone()))
518            .collect()
519    }
520}
521
522#[derive(Debug, Default, Clone, Deserialize, Serialize, PartialEq, Eq, ts_rs::TS, JsonSchema)]
523#[ts(export)]
524#[serde(rename_all = "camelCase")]
525pub struct MetaSettings {
526    pub default_length_units: types::UnitLen,
527    pub default_angle_units: types::UnitAngle,
528    pub kcl_version: String,
529}
530
531impl MetaSettings {
532    pub(crate) fn update_from_annotation(
533        &mut self,
534        annotation: &crate::parsing::ast::types::Node<Annotation>,
535    ) -> Result<bool, KclError> {
536        let properties = annotations::expect_properties(annotations::SETTINGS, annotation)?;
537
538        let mut updated_len = false;
539        for p in properties {
540            match &*p.inner.key.name {
541                annotations::SETTINGS_UNIT_LENGTH => {
542                    let value = annotations::expect_ident(&p.inner.value)?;
543                    let value = types::UnitLen::from_str(value, annotation.as_source_range())?;
544                    self.default_length_units = value;
545                    updated_len = true;
546                }
547                annotations::SETTINGS_UNIT_ANGLE => {
548                    let value = annotations::expect_ident(&p.inner.value)?;
549                    let value = types::UnitAngle::from_str(value, annotation.as_source_range())?;
550                    self.default_angle_units = value;
551                }
552                annotations::SETTINGS_VERSION => {
553                    let value = annotations::expect_number(&p.inner.value)?;
554                    self.kcl_version = value;
555                }
556                name => {
557                    return Err(KclError::new_semantic(KclErrorDetails::new(
558                        format!(
559                            "Unexpected settings key: `{name}`; expected one of `{}`, `{}`",
560                            annotations::SETTINGS_UNIT_LENGTH,
561                            annotations::SETTINGS_UNIT_ANGLE
562                        ),
563                        vec![annotation.as_source_range()],
564                    )));
565                }
566            }
567        }
568
569        Ok(updated_len)
570    }
571}