kcl_lib/execution/
state.rs

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

kcl_lib/execution/
state.rs
