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

kcl_lib/execution/
state.rs
