Skip to main content

nu_protocol/engine/
state_working_set.rs

1use crate::{
2    BlockId, Category, CompileError, Config, DeclId, FileId, GetSpan, Module, ModuleId, OverlayId,
3    ParseError, ParseWarning, ResolvedImportPattern, ResolvedSpan, Signature, Span, SpanId, Type,
4    TypeAlias, TypeAliasId, TypeSet, Value, VarId, VirtualPathId,
5    ast::Block,
6    engine::{
7        BoundNames, BracketTable, CachedFile, Command, CommandType, EngineState, OverlayFrame,
8        ScopeBindings, ScopeFrame, StateDelta, Variable, VirtualPath, Visibility, VisibilityStack,
9        description::build_desc, engine_state::FileHint, signature_cache::SignatureCache,
10    },
11};
12use core::panic;
13use std::{
14    collections::{HashMap, HashSet},
15    path::{Path, PathBuf},
16    sync::Arc,
17};
18
19#[cfg(feature = "plugin")]
20use crate::{PluginIdentity, PluginRegistryItem, RegisteredPlugin};
21
22/// A temporary extension to the global state. This handles bridging between the global state and the
23/// additional declarations and scope changes that are not yet part of the global scope.
24///
25/// This working set is created by the parser as a way of handling declarations and scope changes that
26/// may later be merged or dropped (and not merged) depending on the needs of the code calling the parser.
27pub struct StateWorkingSet<'a> {
28    pub permanent_state: &'a EngineState,
29    pub delta: StateDelta,
30    pub files: FileStack,
31    /// Whether or not predeclarations are searched when looking up a command (used with aliases)
32    pub search_predecls: bool,
33    /// When true, `use` / `export use` / `overlay use` / `module <file>` parse as
34    /// syntax only and do not load modules from disk or the virtual filesystem.
35    /// The REPL highlighter sets this so typing `use std` does not parse-time-load
36    /// the standard library on every keystroke.
37    pub skip_module_load: bool,
38    /// Set when [`skip_module_load`](Self::skip_module_load) left a module
39    /// unloaded, so what it would have imported is missing from the parse.
40    pub skipped_module_load: bool,
41    pub parse_errors: Vec<ParseError>,
42    pub parse_warnings: Vec<ParseWarning>,
43    pub compile_errors: Vec<CompileError>,
44    /// Whether the lexer records and uses [`bracket_tables`](Self::bracket_tables) to skip over
45    /// nested groups. Always on; it only changes how fast the lexer is, never what it produces,
46    /// so tests turn it off to show that a parse comes out the same both ways.
47    pub lex_once: bool,
48    /// Bracket tables of the files being parsed, innermost last, when [`lex_once`](Self::lex_once)
49    /// is on. nu-parser's lexer records one when it lexes a whole file of 1 KiB to 16 MiB (a parsed
50    /// script or a module file), later lexes of parts of that file use it, and nu-parser drops it
51    /// when it finishes parsing the file. Files nest only through `use` and `source`, so this is a
52    /// short list.
53    pub bracket_tables: Vec<BracketTable>,
54    /// The span of the body of the `def` being parsed. `parse_def` compiles the body itself once it
55    /// has closed the body's scope, so the closure parser leaves the closure with this span
56    /// uncompiled instead of compiling it a first time.
57    pub def_body_span: Option<Span>,
58    /// The index in `delta.files` of the file the last span lookup found (see
59    /// [`Self::get_span_contents`]).
60    last_file_hit: FileHint,
61}
62
63impl<'a> StateWorkingSet<'a> {
64    pub fn new(permanent_state: &'a EngineState) -> Self {
65        // Initialize the file stack with the top-level file.
66        let files = if let Some(file) = permanent_state.file.clone() {
67            FileStack::with_file(file)
68        } else {
69            FileStack::new()
70        };
71
72        Self {
73            delta: StateDelta::new(permanent_state),
74            permanent_state,
75            files,
76            search_predecls: true,
77            skip_module_load: false,
78            skipped_module_load: false,
79            parse_errors: vec![],
80            parse_warnings: vec![],
81            compile_errors: vec![],
82            lex_once: true,
83            bracket_tables: vec![],
84            def_body_span: None,
85            last_file_hit: FileHint::default(),
86        }
87    }
88
89    pub fn permanent(&self) -> &EngineState {
90        self.permanent_state
91    }
92
93    pub fn error(&mut self, parse_error: ParseError) {
94        self.parse_errors.push(parse_error)
95    }
96
97    pub fn warning(&mut self, parse_warning: ParseWarning) {
98        self.parse_warnings.push(parse_warning)
99    }
100
101    pub fn num_files(&self) -> usize {
102        self.delta.num_files() + self.permanent_state.num_files()
103    }
104
105    pub fn num_virtual_paths(&self) -> usize {
106        self.delta.num_virtual_paths() + self.permanent_state.num_virtual_paths()
107    }
108
109    pub fn num_vars(&self) -> usize {
110        self.delta.num_vars() + self.permanent_state.num_vars()
111    }
112
113    pub fn num_decls(&self) -> usize {
114        self.delta.num_decls() + self.permanent_state.num_decls()
115    }
116
117    pub fn num_blocks(&self) -> usize {
118        self.delta.num_blocks() + self.permanent_state.num_blocks()
119    }
120
121    pub fn num_modules(&self) -> usize {
122        self.delta.num_modules() + self.permanent_state.num_modules()
123    }
124
125    pub fn num_type_aliases(&self) -> usize {
126        self.delta.num_type_aliases() + self.permanent_state.num_type_aliases()
127    }
128
129    pub fn unique_overlay_names(&self) -> HashSet<&[u8]> {
130        let mut names: HashSet<&[u8]> = self.permanent_state.active_overlay_names(&[]).collect();
131
132        for scope_frame in self.delta.scope.iter().rev() {
133            for overlay_id in scope_frame.active_overlays.iter().rev() {
134                let (overlay_name, _) = scope_frame
135                    .overlays
136                    .get(overlay_id.get())
137                    .expect("internal error: missing overlay");
138
139                names.insert(overlay_name);
140                names.retain(|n| !scope_frame.removed_overlays.iter().any(|m| n == m));
141            }
142        }
143
144        names
145    }
146
147    pub fn num_overlays(&self) -> usize {
148        self.unique_overlay_names().len()
149    }
150
151    pub fn add_decl(&mut self, decl: Box<dyn Command>) -> DeclId {
152        let name = decl.name().as_bytes().to_vec();
153
154        self.delta.decls.push(decl);
155        let decl_id = self.num_decls() - 1;
156        let decl_id = DeclId::new(decl_id);
157
158        self.last_overlay_mut().insert_decl(name, decl_id);
159
160        decl_id
161    }
162
163    pub fn use_decls(&mut self, decls: Vec<(Vec<u8>, DeclId)>) {
164        let overlay_frame = self.last_overlay_mut();
165
166        for (name, decl_id) in decls {
167            overlay_frame.insert_decl(name, decl_id);
168            overlay_frame.visibility.use_decl_id(&decl_id);
169        }
170    }
171
172    pub fn use_modules(&mut self, modules: Vec<(Vec<u8>, ModuleId)>) {
173        let overlay_frame = self.last_overlay_mut();
174
175        for (name, module_id) in modules {
176            overlay_frame.insert_module(name, module_id);
177            // overlay_frame.visibility.use_module_id(&module_id);  // TODO: Add hiding modules
178        }
179    }
180
181    pub fn use_type_aliases(&mut self, type_aliases: Vec<(Vec<u8>, TypeAliasId)>) {
182        let overlay_frame = self.last_overlay_mut();
183
184        for (name, type_alias_id) in type_aliases {
185            overlay_frame.type_aliases.insert(name, type_alias_id);
186            overlay_frame.visibility.use_type_alias_id(&type_alias_id);
187        }
188    }
189
190    pub fn use_variables(&mut self, variables: Vec<(Vec<u8>, VarId)>) {
191        for (name, var_id) in variables {
192            self.insert_variable_into_scope(name, var_id);
193        }
194    }
195
196    pub fn add_predecl(&mut self, decl: Box<dyn Command>) -> Option<DeclId> {
197        let name = decl.name().as_bytes().to_vec();
198
199        self.delta.decls.push(decl);
200        let decl_id = self.num_decls() - 1;
201        let decl_id = DeclId::new(decl_id);
202
203        self.delta
204            .last_scope_frame_mut()
205            .predecls
206            .insert(name, decl_id)
207    }
208
209    #[cfg(feature = "plugin")]
210    pub fn find_or_create_plugin(
211        &mut self,
212        identity: &PluginIdentity,
213        make: impl FnOnce() -> Arc<dyn RegisteredPlugin>,
214    ) -> Arc<dyn RegisteredPlugin> {
215        // Check in delta first, then permanent_state
216        if let Some(plugin) = self
217            .delta
218            .plugins
219            .iter()
220            .chain(self.permanent_state.plugins())
221            .find(|p| p.identity() == identity)
222        {
223            plugin.clone()
224        } else {
225            let plugin = make();
226            self.delta.plugins.push(plugin.clone());
227            plugin
228        }
229    }
230
231    #[cfg(feature = "plugin")]
232    pub fn update_plugin_registry(&mut self, item: PluginRegistryItem) {
233        self.delta.plugin_registry_items.push(item);
234    }
235
236    pub fn merge_predecl(&mut self, name: &[u8]) -> Option<DeclId> {
237        self.move_one_predecl_to_overlay(name);
238
239        let overlay_frame = self.last_overlay_mut();
240
241        if let Some(decl_id) = overlay_frame.predecls.remove(name) {
242            overlay_frame.insert_decl(name.into(), decl_id);
243
244            return Some(decl_id);
245        }
246
247        None
248    }
249
250    /// Drop the predeclaration of `name` without defining it, wherever [`Self::merge_predecl`]
251    /// would find it, so that later calls to `name` don't resolve to a declaration without a body.
252    pub fn remove_predecl(&mut self, name: &[u8]) -> Option<DeclId> {
253        self.move_one_predecl_to_overlay(name);
254        self.last_overlay_mut().predecls.remove(name)
255    }
256
257    fn move_one_predecl_to_overlay(&mut self, name: &[u8]) {
258        self.delta
259            .last_scope_frame_mut()
260            .predecls
261            .remove_entry(name)
262            .map(|(name, decl_id)| self.last_overlay_mut().predecls.insert(name, decl_id));
263    }
264
265    /// Hide the declaration `name` from here to the end of the current block.
266    ///
267    /// The hide is recorded in the current scope frame, not in the frame that declared `name`, so
268    /// a `hide` inside a nested block (`do { hide f }`, a command body) doesn't hide `name` in the
269    /// enclosing block.
270    ///
271    /// Returns the declaration that was hidden, or `None` if no declaration `name` was visible.
272    pub fn hide_decl(&mut self, name: &[u8]) -> Option<DeclId> {
273        let mut removed_overlays = vec![];
274        let mut visibility: Visibility = Visibility::new();
275
276        let mut found = None;
277        'frames: for scope_frame in self.delta.scope.iter().rev() {
278            for overlay_id in scope_frame
279                .active_overlay_ids(&mut removed_overlays)
280                .iter()
281                .rev()
282            {
283                let overlay_frame = scope_frame.get_overlay(*overlay_id);
284
285                visibility.append(&overlay_frame.visibility);
286
287                if let Some(decl_id) = overlay_frame.get_decl(name)
288                    && visibility.is_decl_id_visible(&decl_id)
289                {
290                    found = Some(decl_id);
291                    break 'frames;
292                }
293            }
294        }
295        if let Some(decl_id) = found {
296            self.last_overlay_mut().visibility.hide_decl_id(&decl_id);
297            return Some(decl_id);
298        }
299
300        // The permanent state can't be changed, so the hide goes in the current overlay frame too
301        for overlay_frame in self
302            .permanent_state
303            .active_overlays(&removed_overlays)
304            .rev()
305        {
306            visibility.append(&overlay_frame.visibility);
307
308            if let Some(decl_id) = overlay_frame.get_decl(name)
309                && visibility.is_decl_id_visible(&decl_id)
310            {
311                // Hide decl only if it's not already hidden
312                self.last_overlay_mut().visibility.hide_decl_id(&decl_id);
313                return Some(decl_id);
314            }
315        }
316
317        None
318    }
319
320    /// Hide the type alias `name`, the way [`Self::hide_decl`] hides a declaration.
321    ///
322    /// Returns the alias that was hidden, or `None` if no type alias `name` was visible.
323    pub fn hide_type_alias(&mut self, name: &[u8]) -> Option<TypeAliasId> {
324        let mut removed_overlays = vec![];
325        let mut visibility: Visibility = Visibility::new();
326
327        let mut found = None;
328        'frames: for scope_frame in self.delta.scope.iter().rev() {
329            for overlay_id in scope_frame
330                .active_overlay_ids(&mut removed_overlays)
331                .iter()
332                .rev()
333            {
334                let overlay_frame = scope_frame.get_overlay(*overlay_id);
335
336                visibility.append(&overlay_frame.visibility);
337
338                if let Some(type_alias_id) = overlay_frame.type_aliases.get(name).copied()
339                    && visibility.is_type_alias_id_visible(&type_alias_id)
340                {
341                    found = Some(type_alias_id);
342                    break 'frames;
343                }
344            }
345        }
346        if let Some(type_alias_id) = found {
347            self.last_overlay_mut()
348                .visibility
349                .hide_type_alias_id(&type_alias_id);
350            return Some(type_alias_id);
351        }
352
353        // The permanent state can't be changed, so the hide goes in the current overlay frame too
354        for overlay_frame in self
355            .permanent_state
356            .active_overlays(&removed_overlays)
357            .rev()
358        {
359            visibility.append(&overlay_frame.visibility);
360
361            if let Some(type_alias_id) = overlay_frame.type_aliases.get(name).copied()
362                && visibility.is_type_alias_id_visible(&type_alias_id)
363            {
364                self.last_overlay_mut()
365                    .visibility
366                    .hide_type_alias_id(&type_alias_id);
367                return Some(type_alias_id);
368            }
369        }
370
371        None
372    }
373
374    pub fn hide_type_aliases(&mut self, type_aliases: &[Vec<u8>]) {
375        for type_alias in type_aliases {
376            self.hide_type_alias(type_alias);
377        }
378    }
379
380    pub fn hide_decls(&mut self, decls: &[Vec<u8>]) {
381        for decl in decls.iter() {
382            self.hide_decl(decl); // let's assume no errors
383        }
384    }
385
386    pub fn add_block(&mut self, block: Arc<Block>) -> BlockId {
387        log::trace!(
388            "block id={} added, has IR = {:?}",
389            self.num_blocks(),
390            block.ir_block.is_some()
391        );
392
393        self.delta.blocks.push(block);
394
395        BlockId::new(self.num_blocks() - 1)
396    }
397
398    pub fn add_module(&mut self, name: &str, module: Module, comments: Vec<Span>) -> ModuleId {
399        let name = name.as_bytes().to_vec();
400
401        self.delta.modules.push(Arc::new(module));
402        let module_id = self.num_modules() - 1;
403        let module_id = ModuleId::new(module_id);
404
405        if !comments.is_empty() {
406            self.delta
407                .doccomments
408                .add_module_comments(module_id, comments);
409        }
410
411        self.last_overlay_mut().modules.insert(name, module_id);
412
413        module_id
414    }
415
416    /// Define a type alias in the current scope. A later definition of the same name replaces it
417    /// from here on.
418    pub fn add_type_alias(&mut self, type_alias: TypeAlias) -> TypeAliasId {
419        let name = type_alias.name.as_bytes().to_vec();
420
421        self.delta.type_aliases.push(type_alias);
422        let type_alias_id = TypeAliasId::new(self.num_type_aliases() - 1);
423
424        self.last_overlay_mut()
425            .type_aliases
426            .insert(name, type_alias_id);
427
428        type_alias_id
429    }
430
431    /// Record that the block being parsed has a `type` statement for `name` at `span`.
432    ///
433    /// The record lasts as long as the scope frame and is only used to report a use before the
434    /// definition (see [`Self::find_type_predecls`]).
435    pub fn add_type_predecl(&mut self, name: Vec<u8>, span: Span) {
436        self.delta
437            .last_scope_frame_mut()
438            .type_predecls
439            .entry(name)
440            .or_default()
441            .push(span);
442    }
443
444    /// Spans of the `type` statements recorded for `name` by [`Self::add_type_predecl`] in every
445    /// enclosing scope, innermost first.
446    pub fn find_type_predecls<'b>(&'b self, name: &'b [u8]) -> impl Iterator<Item = Span> + 'b {
447        self.delta
448            .scope
449            .iter()
450            .rev()
451            .filter_map(move |scope_frame| scope_frame.type_predecls.get(name))
452            .flatten()
453            .copied()
454    }
455
456    pub fn get_module_comments(&self, module_id: ModuleId) -> Option<&[Span]> {
457        self.delta
458            .doccomments
459            .get_module_comments(module_id)
460            .or_else(|| self.permanent_state.get_module_comments(module_id))
461    }
462
463    pub fn next_span_start(&self) -> usize {
464        let permanent_span_start = self.permanent_state.next_span_start();
465
466        if let Some(cached_file) = self.delta.files.last() {
467            cached_file.covered_span.end
468        } else {
469            permanent_span_start
470        }
471    }
472
473    pub fn files(&self) -> impl DoubleEndedIterator<Item = &CachedFile> {
474        self.permanent_state.files().chain(self.delta.files.iter())
475    }
476
477    pub fn get_contents_of_file(&self, file_id: FileId) -> Option<&[u8]> {
478        if let Some(cached_file) = self.permanent_state.get_file_contents().get(file_id.get()) {
479            return Some(&cached_file.content);
480        }
481        // The index subtraction will not underflow, if we hit the permanent state first.
482        // Check if you try reordering for locality
483        if let Some(cached_file) = self
484            .delta
485            .get_file_contents()
486            .get(file_id.get() - self.permanent_state.num_files())
487        {
488            return Some(&cached_file.content);
489        }
490
491        None
492    }
493
494    #[must_use]
495    pub fn add_file(&mut self, filename: &str, contents: &[u8]) -> FileId {
496        // First, look for the file to see if we already have it
497        for (idx, cached_file) in self.files().enumerate() {
498            if &*cached_file.name == filename && &*cached_file.content == contents {
499                return FileId::new(idx);
500            }
501        }
502
503        let next_span_start = self.next_span_start();
504        let next_span_end = next_span_start + contents.len();
505
506        let covered_span = Span::new(next_span_start, next_span_end);
507
508        self.delta.files.push(CachedFile {
509            name: filename.into(),
510            content: contents.into(),
511            covered_span,
512        });
513
514        FileId::new(self.num_files() - 1)
515    }
516
517    #[must_use]
518    pub fn add_virtual_path(&mut self, name: String, virtual_path: VirtualPath) -> VirtualPathId {
519        self.delta.virtual_paths.push((name, virtual_path));
520
521        VirtualPathId::new(self.num_virtual_paths() - 1)
522    }
523
524    pub fn get_span_for_filename(&self, filename: &str) -> Option<Span> {
525        let predicate = |file: &CachedFile| &*file.name == filename;
526        // search from end to start, in case there're duplicated files with the same name
527        let file_id = self
528            .delta
529            .files
530            .iter()
531            .rposition(predicate)
532            .map(|idx| idx + self.permanent_state.num_files())
533            .or_else(|| self.permanent_state.files().rposition(predicate))?;
534        let file_id = FileId::new(file_id);
535
536        Some(self.get_span_for_file(file_id))
537    }
538
539    /// Panics:
540    /// On invalid `FileId`
541    ///
542    /// Use with care
543    pub fn get_span_for_file(&self, file_id: FileId) -> Span {
544        let result = self
545            .files()
546            .nth(file_id.get())
547            .expect("internal error: could not find source for previously parsed file");
548
549        result.covered_span
550    }
551
552    #[inline]
553    pub fn get_span_contents(&self, span: Span) -> &[u8] {
554        let permanent_end = self.permanent_state.next_span_start();
555        if permanent_end <= span.start
556            && let Some(contents) = self.last_file_hit.contents(&self.delta.files, span)
557        {
558            return contents;
559        }
560
561        // if no files with span were found, fall back on permanent ones
562        self.permanent_state.get_span_contents(span)
563    }
564
565    pub fn enter_scope(&mut self) {
566        self.delta.enter_scope();
567    }
568
569    pub fn exit_scope(&mut self) {
570        self.delta.exit_scope();
571    }
572
573    /// Find the [`DeclId`](crate::DeclId) corresponding to a predeclaration with `name`.
574    pub fn find_predecl(&self, name: &[u8]) -> Option<DeclId> {
575        let mut removed_overlays = vec![];
576
577        for scope_frame in self.delta.scope.iter().rev() {
578            if let Some(decl_id) = scope_frame.predecls.get(name) {
579                return Some(*decl_id);
580            }
581
582            for overlay_frame in scope_frame.active_overlays(&mut removed_overlays).rev() {
583                if let Some(decl_id) = overlay_frame.predecls.get(name) {
584                    return Some(*decl_id);
585                }
586            }
587        }
588
589        None
590    }
591
592    /// Find the [`DeclId`](crate::DeclId) corresponding to a declaration with `name`.
593    ///
594    /// Extends [`EngineState::find_decl`] to also search for predeclarations
595    /// (if [`StateWorkingSet::search_predecls`] is set), and declarations from scopes existing
596    /// only in [`StateDelta`].
597    pub fn find_decl(&self, name: &[u8]) -> Option<DeclId> {
598        let mut removed_overlays = vec![];
599
600        let mut visibility = VisibilityStack::default();
601
602        for scope_frame in self.delta.scope.iter().rev() {
603            if self.search_predecls
604                && let Some(decl_id) = scope_frame.predecls.get(name)
605                && visibility.is_decl_id_visible(decl_id)
606            {
607                return Some(*decl_id);
608            }
609
610            // check overlay in delta
611            for overlay_frame in scope_frame.active_overlays(&mut removed_overlays).rev() {
612                visibility.push(&overlay_frame.visibility);
613
614                if self.search_predecls
615                    && let Some(decl_id) = overlay_frame.predecls.get(name)
616                    && visibility.is_decl_id_visible(decl_id)
617                {
618                    return Some(*decl_id);
619                }
620
621                if let Some(decl_id) = overlay_frame.get_decl(name)
622                    && visibility.is_decl_id_visible(&decl_id)
623                {
624                    return Some(decl_id);
625                }
626            }
627        }
628
629        // check overlay in perma
630        self.permanent_state.find_decl(name, &removed_overlays)
631    }
632
633    /// Find the name of the declaration corresponding to `decl_id`.
634    ///
635    /// Extends [`EngineState::find_decl_name`] to also search for predeclarations (if [`StateWorkingSet::search_predecls`] is set),
636    /// and declarations from scopes existing only in [`StateDelta`].
637    pub fn find_decl_name(&self, decl_id: DeclId) -> Option<&[u8]> {
638        let mut removed_overlays = vec![];
639
640        let mut visibility = VisibilityStack::default();
641
642        for scope_frame in self.delta.scope.iter().rev() {
643            if self.search_predecls {
644                for (name, id) in scope_frame.predecls.iter() {
645                    if id == &decl_id {
646                        return Some(name);
647                    }
648                }
649            }
650
651            // check overlay in delta
652            for overlay_frame in scope_frame.active_overlays(&mut removed_overlays).rev() {
653                visibility.push(&overlay_frame.visibility);
654
655                if self.search_predecls {
656                    for (name, id) in overlay_frame.predecls.iter() {
657                        if id == &decl_id {
658                            return Some(name);
659                        }
660                    }
661                }
662
663                if visibility.is_decl_id_visible(&decl_id) {
664                    for (name, id) in overlay_frame.decls.iter() {
665                        if id == &decl_id {
666                            return Some(name);
667                        }
668                    }
669                }
670            }
671        }
672
673        // check overlay in perma
674        self.permanent_state
675            .find_decl_name(decl_id, &removed_overlays)
676    }
677
678    /// Find the [`ModuleId`](crate::ModuleId) corresponding to `name`.
679    ///
680    /// Extends [`EngineState::find_module`] to also search for ,
681    /// and declarations from scopes existing only in [`StateDelta`].
682    pub fn find_module(&self, name: &[u8]) -> Option<ModuleId> {
683        let mut removed_overlays = vec![];
684
685        for scope_frame in self.delta.scope.iter().rev() {
686            for overlay_frame in scope_frame.active_overlays(&mut removed_overlays).rev() {
687                if let Some(module_id) = overlay_frame.modules.get(name) {
688                    return Some(*module_id);
689                }
690            }
691        }
692
693        for overlay_frame in self
694            .permanent_state
695            .active_overlays(&removed_overlays)
696            .rev()
697        {
698            if let Some(module_id) = overlay_frame.modules.get(name) {
699                return Some(*module_id);
700            }
701        }
702
703        None
704    }
705
706    /// Find the [`TypeAliasId`] of the type alias `name` visible in the current scope.
707    pub fn find_type_alias(&self, name: &[u8]) -> Option<TypeAliasId> {
708        let mut removed_overlays = vec![];
709
710        let mut visibility = VisibilityStack::default();
711
712        for scope_frame in self.delta.scope.iter().rev() {
713            for overlay_frame in scope_frame.active_overlays(&mut removed_overlays).rev() {
714                visibility.push(&overlay_frame.visibility);
715
716                if let Some(type_alias_id) = overlay_frame.type_aliases.get(name)
717                    && visibility.is_type_alias_id_visible(type_alias_id)
718                {
719                    return Some(*type_alias_id);
720                }
721            }
722        }
723
724        self.permanent_state
725            .find_type_alias(name, &removed_overlays)
726    }
727
728    /// Whether `name` is a custom value type that any command declares in its input/output
729    /// types, e.g. `semver` from the built-in `semver` commands or `polars_dataframe` from a
730    /// plugin.
731    ///
732    /// Custom value types aren't registered separately, so this scans every declaration's
733    /// signature (cached for permanent declarations). The parser only calls it for names that
734    /// are neither built-in types nor type aliases.
735    pub fn find_custom_type(&self, name: &[u8]) -> bool {
736        (0..self.num_decls()).map(DeclId::new).any(|decl_id| {
737            self.get_decl_signature_shared(decl_id)
738                .input_output_types
739                .iter()
740                .flat_map(|(input, output)| [input, output])
741                .any(|ty| matches!(ty, Type::Custom(custom) if custom.as_bytes() == name))
742        })
743    }
744
745    pub fn get_type_alias(&self, type_alias_id: TypeAliasId) -> &TypeAlias {
746        let num_permanent_type_aliases = self.permanent_state.num_type_aliases();
747        if type_alias_id.get() < num_permanent_type_aliases {
748            self.permanent_state.get_type_alias(type_alias_id)
749        } else {
750            self.delta
751                .type_aliases
752                .get(type_alias_id.get() - num_permanent_type_aliases)
753                .expect("internal error: missing type alias")
754        }
755    }
756
757    pub fn next_var_id(&self) -> VarId {
758        let num_permanent_vars = self.permanent_state.num_vars();
759        VarId::new(num_permanent_vars + self.delta.vars.len())
760    }
761
762    pub fn list_variables(&self) -> Vec<&[u8]> {
763        let mut removed_overlays = vec![];
764        let mut variables = HashSet::new();
765        for scope_frame in self.delta.scope.iter() {
766            for overlay_frame in scope_frame.active_overlays(&mut removed_overlays) {
767                variables.extend(overlay_frame.vars.keys().map(|k| &k[..]));
768            }
769        }
770
771        let permanent_vars = self
772            .permanent_state
773            .active_overlays(&removed_overlays)
774            .flat_map(|overlay_frame| overlay_frame.vars.keys().map(|k| &k[..]));
775
776        variables.extend(permanent_vars);
777        // A variable that `unlet` hid is still bound in its frame, so while anything is hidden,
778        // list only the names that still resolve.
779        let any_hidden = self
780            .delta
781            .scope
782            .iter()
783            .any(|scope_frame| !scope_frame.hidden_vars.is_empty());
784        variables
785            .into_iter()
786            .filter(|name| !any_hidden || self.find_variable(name).is_some())
787            .collect()
788    }
789
790    pub fn find_variable(&self, name: &[u8]) -> Option<VarId> {
791        let mut name = name.to_vec();
792        if !name.starts_with(b"$") {
793            name.insert(0, b'$');
794        }
795        let mut removed_overlays = vec![];
796        // A variable that `unlet` hid in the scope frame that binds it, or in a frame inside that
797        // one, isn't found, and the lookup doesn't go on to a variable of the same name further
798        // out. A permanent variable is bound outside every frame of the delta.
799        let unless_hidden = |var_id: VarId, binding_frame: usize| {
800            let hidden = self.delta.scope[binding_frame..]
801                .iter()
802                .any(|scope_frame| scope_frame.hidden_vars.contains(&var_id));
803            (!hidden).then_some(var_id)
804        };
805
806        for (frame_idx, scope_frame) in self.delta.scope.iter().enumerate().rev() {
807            for overlay_frame in scope_frame.active_overlays(&mut removed_overlays).rev() {
808                if let Some(var_id) = overlay_frame.vars.get(&name) {
809                    return unless_hidden(*var_id, frame_idx);
810                }
811            }
812        }
813
814        for overlay_frame in self
815            .permanent_state
816            .active_overlays(&removed_overlays)
817            .rev()
818        {
819            if let Some(var_id) = overlay_frame.vars.get(&name) {
820                return unless_hidden(*var_id, 0);
821            }
822        }
823
824        None
825    }
826
827    /// Hide `var_id` for the rest of the current scope frame, as `unlet` does for a constant:
828    /// [`find_variable`](Self::find_variable) no longer finds it under any name, until it's bound
829    /// again. At the top level, merging the delta removes the variable from the overlays, so
830    /// later source can't find it either.
831    pub fn hide_variable(&mut self, var_id: VarId) {
832        self.delta.last_scope_frame_mut().hidden_vars.push(var_id);
833    }
834
835    pub fn find_variable_in_current_frame(&self, name: &[u8]) -> Option<VarId> {
836        let mut removed_overlays = vec![];
837
838        for scope_frame in self.delta.scope.iter().rev().take(1) {
839            for overlay_frame in scope_frame.active_overlays(&mut removed_overlays).rev() {
840                if let Some(var_id) = overlay_frame.vars.get(name) {
841                    return Some(*var_id);
842                }
843            }
844        }
845
846        None
847    }
848
849    pub fn add_variable(&mut self, name: Vec<u8>, span: Span, ty: Type, mutable: bool) -> VarId {
850        let var_id = self.add_variable_without_scope(span, ty, mutable);
851        self.insert_variable_into_scope(name, var_id);
852        var_id
853    }
854
855    /// Like [`add_variable`](Self::add_variable) but does **not** insert the
856    /// name→VarId mapping into the current overlay scope. The caller must
857    /// later call [`insert_variable_into_scope`](Self::insert_variable_into_scope)
858    /// to make the variable visible by name.
859    pub fn add_variable_without_scope(&mut self, span: Span, ty: Type, mutable: bool) -> VarId {
860        let next_id = self.next_var_id();
861        self.delta.vars.push(Variable::new(span, ty, mutable));
862        next_id
863    }
864
865    /// Insert a previously created variable into the current overlay's scope.
866    /// The `name` will have a `$` prefix prepended if it doesn't already have one.
867    pub fn insert_variable_into_scope(&mut self, mut name: Vec<u8>, var_id: VarId) {
868        if !name.starts_with(b"$") {
869            name.insert(0, b'$');
870        }
871        // Record the name on delta variables so `scope variables` can list stack locals
872        // that never enter permanent overlays. Permanent vars keep `name: None` here;
873        // their names remain available through permanent overlay maps.
874        if let Some(var) = self.get_variable_mut(var_id) {
875            var.name = Some(name.clone());
876        }
877        // Binding a variable again, like a module constant imported a second time, undoes an
878        // `unlet` of it in this frame (see `hide_variable`).
879        self.delta
880            .last_scope_frame_mut()
881            .hidden_vars
882            .retain(|hidden| *hidden != var_id);
883        self.last_overlay_mut().insert_variable(name, var_id);
884    }
885
886    pub fn get_env_var(&self, name: &str) -> Option<&Value> {
887        self.permanent_state.get_env_var(name)
888    }
889
890    /// Returns a reference to the config stored at permanent state
891    ///
892    /// At runtime, you most likely want to call [`Stack::get_config()`][super::Stack::get_config()]
893    /// because this method does not capture environment updates during runtime.
894    pub fn get_config(&self) -> &Arc<Config> {
895        &self.permanent_state.config
896    }
897
898    pub fn set_variable_type(&mut self, var_id: VarId, ty: Type) {
899        let num_permanent_vars = self.permanent_state.num_vars();
900        if var_id.get() < num_permanent_vars {
901            panic!("Internal error: attempted to set into permanent state from working set")
902        } else {
903            self.delta.vars[var_id.get() - num_permanent_vars].ty = ty;
904        }
905    }
906
907    pub fn set_variable_const_val(&mut self, var_id: VarId, val: Value) {
908        let num_permanent_vars = self.permanent_state.num_vars();
909        if var_id.get() < num_permanent_vars {
910            panic!("Internal error: attempted to set into permanent state from working set")
911        } else {
912            self.delta.vars[var_id.get() - num_permanent_vars].const_val = Some(val);
913        }
914    }
915
916    pub fn get_variable(&self, var_id: VarId) -> &Variable {
917        let num_permanent_vars = self.permanent_state.num_vars();
918        if var_id.get() < num_permanent_vars {
919            self.permanent_state.get_var(var_id)
920        } else {
921            self.delta
922                .vars
923                .get(var_id.get() - num_permanent_vars)
924                .expect("internal error: missing variable")
925        }
926    }
927
928    /// Mutable access to a variable that still lives in the working-set delta.
929    ///
930    /// Returns `None` for variables that already belong to the permanent engine state.
931    pub fn get_variable_mut(&mut self, var_id: VarId) -> Option<&mut Variable> {
932        let num_permanent_vars = self.permanent_state.num_vars();
933        if var_id.get() < num_permanent_vars {
934            None
935        } else {
936            self.delta.vars.get_mut(var_id.get() - num_permanent_vars)
937        }
938    }
939
940    pub fn get_variable_if_possible(&self, var_id: VarId) -> Option<&Variable> {
941        let num_permanent_vars = self.permanent_state.num_vars();
942        if var_id.get() < num_permanent_vars {
943            Some(self.permanent_state.get_var(var_id))
944        } else {
945            self.delta.vars.get(var_id.get() - num_permanent_vars)
946        }
947    }
948
949    /// Snapshot command/module bindings from the **innermost** scope frame.
950    ///
951    /// # Invariant
952    ///
953    /// Must run on the scope frame that owns the block's locals, **immediately before** the
954    /// matching `exit_scope` (which discards that frame). Call sites:
955    /// `parse_block_expression`, `parse_closure_expression`, and scoped `parse_block`.
956    /// Keep those three call sites explicit so a new scoped construct is forced to opt in.
957    pub fn snapshot_scope_bindings(&self) -> Option<Arc<ScopeBindings>> {
958        let frame = self.delta.last_scope_frame();
959        let mut bindings = ScopeBindings::default();
960        let mut removed_overlays = vec![];
961
962        for overlay in frame.active_overlays(&mut removed_overlays) {
963            bindings.extend_from_overlay(overlay);
964        }
965
966        if bindings.is_empty() {
967            None
968        } else {
969            Some(Arc::new(bindings))
970        }
971    }
972
973    /// The names the innermost scope frame bound since `before`, an earlier copy of that frame.
974    ///
975    /// Returns `None` if the frame changed in a way names don't describe: an overlay was activated
976    /// or removed, a declaration or type alias was hidden, or a variable was `unlet`. The parser's
977    /// block cache records this for an unscoped parse of a file (see [`BoundNames`]).
978    pub fn names_bound_since(&self, before: &ScopeFrame) -> Option<BoundNames> {
979        let after = self.delta.last_scope_frame();
980        if after.active_overlays != before.active_overlays
981            || after.removed_overlays != before.removed_overlays
982            || after.hidden_vars.len() != before.hidden_vars.len()
983        {
984            return None;
985        }
986
987        let mut names = BoundNames::default();
988        for overlay_id in &after.active_overlays {
989            let overlay = after.get_overlay(*overlay_id);
990            let (_, previous) = before.overlays.get(overlay_id.get())?;
991            if overlay.visibility.hides_more_than(&previous.visibility) {
992                return None;
993            }
994            names.decls.extend(
995                overlay
996                    .decls
997                    .iter()
998                    .filter(|(name, id)| previous.decls.get(name) != Some(id))
999                    .map(|(name, id)| (name.clone(), *id)),
1000            );
1001            names.modules.extend(
1002                overlay
1003                    .modules
1004                    .iter()
1005                    .filter(|(name, id)| previous.modules.get(*name) != Some(id))
1006                    .map(|(name, id)| (name.clone(), *id)),
1007            );
1008            names.vars.extend(
1009                overlay
1010                    .vars
1011                    .iter()
1012                    .filter(|(name, id)| previous.vars.get(*name) != Some(id))
1013                    .map(|(name, id)| (name.clone(), *id)),
1014            );
1015            names.type_aliases.extend(
1016                overlay
1017                    .type_aliases
1018                    .iter()
1019                    .filter(|(name, id)| previous.type_aliases.get(*name) != Some(id))
1020                    .map(|(name, id)| (name.clone(), *id)),
1021            );
1022        }
1023        Some(names)
1024    }
1025
1026    /// Bind each name in `names` that doesn't stand for its command, module, variable or type alias
1027    /// here, in the current scope frame, as the parse that recorded `names` did.
1028    ///
1029    /// The block cache calls this when it reuses an unscoped parse of a file, which declares
1030    /// nothing by itself: in another scope than the first parse's, or after a `hide`, the file's
1031    /// names would be missing otherwise.
1032    pub fn bind_names(&mut self, names: &BoundNames) {
1033        let decls = (names.decls.iter())
1034            .filter(|(name, id)| self.find_decl(name) != Some(*id))
1035            .cloned()
1036            .collect();
1037        let modules = (names.modules.iter())
1038            .filter(|(name, id)| self.find_module(name) != Some(*id))
1039            .cloned()
1040            .collect();
1041        let vars = (names.vars.iter())
1042            .filter(|(name, id)| self.find_variable(name) != Some(*id))
1043            .cloned()
1044            .collect();
1045        let type_aliases = (names.type_aliases.iter())
1046            .filter(|(name, id)| self.find_type_alias(name) != Some(*id))
1047            .cloned()
1048            .collect();
1049        self.use_decls(decls);
1050        self.use_modules(modules);
1051        self.use_variables(vars);
1052        self.use_type_aliases(type_aliases);
1053    }
1054
1055    pub fn get_constant(&self, var_id: VarId) -> Result<&Value, ParseError> {
1056        let var = self.get_variable(var_id);
1057
1058        if let Some(const_val) = &var.const_val {
1059            Ok(const_val)
1060        } else {
1061            Err(ParseError::InternalError(
1062                "constant does not have a constant value".into(),
1063                var.declaration_span,
1064            ))
1065        }
1066    }
1067
1068    pub fn get_decl(&self, decl_id: DeclId) -> &dyn Command {
1069        let num_permanent_decls = self.permanent_state.num_decls();
1070        if decl_id.get() < num_permanent_decls {
1071            self.permanent_state.get_decl(decl_id)
1072        } else {
1073            self.delta
1074                .decls
1075                .get(decl_id.get() - num_permanent_decls)
1076                .expect("internal error: missing declaration")
1077                .as_ref()
1078        }
1079    }
1080
1081    pub fn get_decl_mut(&mut self, decl_id: DeclId) -> &mut Box<dyn Command> {
1082        let num_permanent_decls = self.permanent_state.num_decls();
1083        if decl_id.get() < num_permanent_decls {
1084            panic!("internal error: can only mutate declarations in working set")
1085        } else {
1086            self.delta
1087                .decls
1088                .get_mut(decl_id.get() - num_permanent_decls)
1089                .expect("internal error: missing declaration")
1090        }
1091    }
1092
1093    pub fn get_signature(&self, decl: &dyn Command) -> Signature {
1094        if let Some(block_id) = decl.block_id() {
1095            *self.get_block(block_id).signature.clone()
1096        } else {
1097            decl.signature()
1098        }
1099    }
1100
1101    /// Shared version of [`StateWorkingSet::get_signature`] for the declaration `decl_id`.
1102    ///
1103    /// Permanent declarations are built once and then returned from a cache on the
1104    /// [`EngineState`]; declarations in the delta are rebuilt on every call, exactly like
1105    /// `get_signature`, because `def` replaces a predeclaration's signature in place while parsing.
1106    pub fn get_signature_shared(&self, decl_id: DeclId) -> Arc<Signature> {
1107        if decl_id.get() >= self.permanent_state.num_decls() {
1108            return Arc::new(self.get_signature(self.get_decl(decl_id)));
1109        }
1110        self.permanent_state.get_signature_shared(decl_id)
1111    }
1112
1113    /// Shared version of `Command::signature()` for the declaration `decl_id`, i.e. the
1114    /// declaration's own signature rather than the one on its block.
1115    ///
1116    /// Cached for permanent declarations, rebuilt on every call for delta declarations. A
1117    /// declaration without a block has no other signature, so this shares the one
1118    /// [`StateWorkingSet::get_signature_shared`] returns instead of building and caching a copy.
1119    pub fn get_decl_signature_shared(&self, decl_id: DeclId) -> Arc<Signature> {
1120        if self.get_decl(decl_id).block_id().is_none() {
1121            return self.get_signature_shared(decl_id);
1122        }
1123        if decl_id.get() >= self.permanent_state.num_decls() {
1124            return Arc::new(self.get_decl(decl_id).signature());
1125        }
1126        let mut cache = SignatureCache::lock(&self.permanent_state.signature_cache.declared);
1127        Arc::clone(
1128            cache
1129                .entry(decl_id)
1130                .or_insert_with(|| Arc::new(self.get_decl(decl_id).signature())),
1131        )
1132    }
1133
1134    /// The output type of a call to `decl_id` whose pipeline input is `input_type`, as the parser
1135    /// assigns it when it parses the call: what the effective signature of `decl_id` (see
1136    /// [`StateWorkingSet::get_signature_shared`]) gives for the input with `Nothing` added to it,
1137    /// so that commands which ignore their input still type-check.
1138    ///
1139    /// `signature` is that effective signature, which the caller already has. It is only used for
1140    /// delta declarations, whose output type is computed on every call. For permanent declarations
1141    /// the answer is remembered per input type (see [`EngineState`]'s signature cache), so it is
1142    /// computed from the cached effective signature of `decl_id` instead of from `signature`,
1143    /// because the cache is keyed by the declaration alone and must not depend on what a caller
1144    /// passes.
1145    pub fn call_output_type(
1146        &self,
1147        decl_id: DeclId,
1148        signature: &Signature,
1149        input_type: Option<&Type>,
1150    ) -> Option<Type> {
1151        let output_type = |signature: &Signature| {
1152            signature.get_output_type(
1153                input_type
1154                    .map(|ty| ty.clone().union(Type::Nothing))
1155                    .as_ref(),
1156            )
1157        };
1158        if decl_id.get() >= self.permanent_state.num_decls() {
1159            return output_type(signature);
1160        }
1161        SignatureCache::output_type(
1162            &self.permanent_state.signature_cache.call_outputs,
1163            decl_id,
1164            input_type,
1165            || output_type(&self.get_signature_shared(decl_id)),
1166        )
1167    }
1168
1169    /// The output type the declaration's own signature (see
1170    /// [`StateWorkingSet::get_decl_signature_shared`]) gives for `input_type`, as pipeline type
1171    /// checking asks for it. Remembered like [`StateWorkingSet::call_output_type`].
1172    pub fn decl_output_type(&self, decl_id: DeclId, input_type: Option<&Type>) -> Option<Type> {
1173        let compute = || {
1174            self.get_decl_signature_shared(decl_id)
1175                .get_output_type(input_type)
1176        };
1177        if decl_id.get() >= self.permanent_state.num_decls() {
1178            return compute();
1179        }
1180        SignatureCache::output_type(
1181            &self.permanent_state.signature_cache.declared_outputs,
1182            decl_id,
1183            input_type,
1184            compute,
1185        )
1186    }
1187
1188    /// Apply a function to all commands. The function accepts a command name and its DeclId
1189    pub fn traverse_commands(&self, mut f: impl FnMut(&[u8], DeclId)) {
1190        for scope_frame in self.delta.scope.iter().rev() {
1191            for overlay_id in scope_frame.active_overlays.iter().rev() {
1192                let overlay_frame = scope_frame.get_overlay(*overlay_id);
1193
1194                for (name, decl_id) in &overlay_frame.decls {
1195                    if overlay_frame.visibility.is_decl_id_visible(decl_id) {
1196                        f(name, *decl_id);
1197                    }
1198                }
1199            }
1200        }
1201
1202        self.permanent_state.traverse_commands(f);
1203    }
1204
1205    pub fn find_commands_by_predicate(
1206        &self,
1207        mut predicate: impl FnMut(&[u8]) -> bool,
1208        ignore_deprecated: bool,
1209    ) -> Vec<(DeclId, Vec<u8>, Option<String>, CommandType)> {
1210        let mut output = vec![];
1211
1212        self.traverse_commands(|name, decl_id| {
1213            if !predicate(name) {
1214                return;
1215            }
1216            let command = self.get_decl(decl_id);
1217            if ignore_deprecated && command.signature().category == Category::Removed {
1218                return;
1219            }
1220            output.push((
1221                decl_id,
1222                name.to_vec(),
1223                Some(command.description().to_string()),
1224                command.command_type(),
1225            ));
1226        });
1227
1228        output
1229    }
1230
1231    pub fn get_block(&self, block_id: BlockId) -> &Arc<Block> {
1232        let num_permanent_blocks = self.permanent_state.num_blocks();
1233        if block_id.get() < num_permanent_blocks {
1234            self.permanent_state.get_block(block_id)
1235        } else {
1236            self.delta
1237                .blocks
1238                .get(block_id.get() - num_permanent_blocks)
1239                .expect("internal error: missing block")
1240        }
1241    }
1242
1243    pub fn get_module(&self, module_id: ModuleId) -> &Module {
1244        let num_permanent_modules = self.permanent_state.num_modules();
1245        if module_id.get() < num_permanent_modules {
1246            self.permanent_state.get_module(module_id)
1247        } else {
1248            self.delta
1249                .modules
1250                .get(module_id.get() - num_permanent_modules)
1251                .expect("internal error: missing module")
1252        }
1253    }
1254
1255    pub fn get_block_mut(&mut self, block_id: BlockId) -> &mut Block {
1256        let num_permanent_blocks = self.permanent_state.num_blocks();
1257        if block_id.get() < num_permanent_blocks {
1258            panic!("Attempt to mutate a block that is in the permanent (immutable) state")
1259        } else {
1260            self.delta
1261                .blocks
1262                .get_mut(block_id.get() - num_permanent_blocks)
1263                .map(Arc::make_mut)
1264                .expect("internal error: missing block")
1265        }
1266    }
1267
1268    /// Find the overlay corresponding to `name`.
1269    pub fn find_overlay(&self, name: &[u8]) -> Option<&OverlayFrame> {
1270        for scope_frame in self.delta.scope.iter().rev() {
1271            if let Some(overlay_id) = scope_frame.find_overlay(name) {
1272                return Some(scope_frame.get_overlay(overlay_id));
1273            }
1274        }
1275
1276        self.permanent_state
1277            .find_overlay(name)
1278            .map(|id| self.permanent_state.get_overlay(id))
1279    }
1280
1281    pub fn last_overlay_name(&self) -> &[u8] {
1282        let mut removed_overlays = vec![];
1283
1284        for scope_frame in self.delta.scope.iter().rev() {
1285            if let Some(last_name) = scope_frame
1286                .active_overlay_names(&mut removed_overlays)
1287                .iter()
1288                .rev()
1289                .next_back()
1290            {
1291                return last_name;
1292            }
1293        }
1294
1295        self.permanent_state.last_overlay_name(&removed_overlays)
1296    }
1297
1298    pub fn last_overlay(&self) -> &OverlayFrame {
1299        let mut removed_overlays = vec![];
1300
1301        for scope_frame in self.delta.scope.iter().rev() {
1302            if let Some(last_overlay) = scope_frame
1303                .active_overlays(&mut removed_overlays)
1304                .rev()
1305                .next_back()
1306            {
1307                return last_overlay;
1308            }
1309        }
1310
1311        self.permanent_state.last_overlay(&removed_overlays)
1312    }
1313
1314    pub fn last_overlay_mut(&mut self) -> &mut OverlayFrame {
1315        if self.delta.last_overlay_mut().is_none() {
1316            // If there is no overlay, automatically activate the last one
1317            let overlay_frame = self.last_overlay();
1318            let name = self.last_overlay_name().to_vec();
1319            let origin = overlay_frame.origin;
1320            let prefixed = overlay_frame.prefixed;
1321            self.add_overlay(
1322                name,
1323                origin,
1324                ResolvedImportPattern::new(vec![], vec![], vec![], vec![], vec![]),
1325                prefixed,
1326            );
1327        }
1328
1329        self.delta
1330            .last_overlay_mut()
1331            .expect("internal error: missing added overlay")
1332    }
1333
1334    /// Every frame of the overlay `name`, from the permanent state outwards to the current scope.
1335    fn frames_of_overlay<'b>(&'b self, name: &'b [u8]) -> impl Iterator<Item = &'b OverlayFrame> {
1336        let permanent = self
1337            .permanent_state
1338            .find_overlay(name)
1339            .map(|overlay_id| self.permanent_state.get_overlay(overlay_id));
1340
1341        let delta = self.delta.scope.iter().filter_map(move |scope_frame| {
1342            scope_frame
1343                .find_overlay(name)
1344                .map(|overlay_id| scope_frame.get_overlay(overlay_id))
1345        });
1346
1347        permanent.into_iter().chain(delta)
1348    }
1349
1350    /// Collect all decls that belong to an overlay
1351    pub fn decls_of_overlay(&self, name: &[u8]) -> HashMap<Vec<u8>, DeclId> {
1352        self.frames_of_overlay(name)
1353            .flat_map(|overlay_frame| &overlay_frame.decls)
1354            .map(|(decl_key, decl_id)| (decl_key.to_owned(), *decl_id))
1355            .collect()
1356    }
1357
1358    /// Collect all type aliases that belong to an overlay
1359    pub fn type_aliases_of_overlay(&self, name: &[u8]) -> HashMap<Vec<u8>, TypeAliasId> {
1360        self.frames_of_overlay(name)
1361            .flat_map(|overlay_frame| &overlay_frame.type_aliases)
1362            .map(|(alias_name, type_alias_id)| (alias_name.to_owned(), *type_alias_id))
1363            .collect()
1364    }
1365
1366    pub fn add_overlay(
1367        &mut self,
1368        name: Vec<u8>,
1369        origin: ModuleId,
1370        definitions: ResolvedImportPattern,
1371        prefixed: bool,
1372    ) {
1373        let last_scope_frame = self.delta.last_scope_frame_mut();
1374
1375        last_scope_frame
1376            .removed_overlays
1377            .retain(|removed_name| removed_name != &name);
1378
1379        let overlay_id = if let Some(overlay_id) = last_scope_frame.find_overlay(&name) {
1380            last_scope_frame.get_overlay_mut(overlay_id).origin = origin;
1381
1382            overlay_id
1383        } else {
1384            last_scope_frame
1385                .overlays
1386                .push((name, OverlayFrame::from_origin(origin, prefixed)));
1387            OverlayId::new(last_scope_frame.overlays.len() - 1)
1388        };
1389
1390        last_scope_frame
1391            .active_overlays
1392            .retain(|id| id != &overlay_id);
1393        last_scope_frame.active_overlays.push(overlay_id);
1394
1395        self.use_decls(definitions.decls);
1396        self.use_modules(definitions.modules);
1397        self.use_type_aliases(definitions.type_aliases);
1398
1399        let mut constants = vec![];
1400
1401        for (name, const_vid) in definitions.constants {
1402            constants.push((name, const_vid));
1403        }
1404
1405        for (name, const_val) in definitions.constant_values {
1406            let const_var_id =
1407                self.add_variable(name.clone(), Span::unknown(), const_val.get_type(), false);
1408            self.set_variable_const_val(const_var_id, const_val);
1409            constants.push((name, const_var_id));
1410        }
1411        self.use_variables(constants);
1412    }
1413
1414    pub fn remove_overlay(&mut self, name: &[u8], keep_custom: bool) {
1415        let last_scope_frame = self.delta.last_scope_frame_mut();
1416
1417        let maybe_module_id = if let Some(overlay_id) = last_scope_frame.find_overlay(name) {
1418            last_scope_frame
1419                .active_overlays
1420                .retain(|id| id != &overlay_id);
1421
1422            Some(last_scope_frame.get_overlay(overlay_id).origin)
1423        } else {
1424            self.permanent_state
1425                .find_overlay(name)
1426                .map(|id| self.permanent_state.get_overlay(id).origin)
1427        };
1428
1429        if let Some(module_id) = maybe_module_id {
1430            last_scope_frame.removed_overlays.push(name.to_owned());
1431
1432            if keep_custom {
1433                let origin_module = self.get_module(module_id);
1434
1435                let decls = self
1436                    .decls_of_overlay(name)
1437                    .into_iter()
1438                    .filter(|(n, _)| !origin_module.has_decl(n))
1439                    .collect();
1440                let type_aliases = self
1441                    .type_aliases_of_overlay(name)
1442                    .into_iter()
1443                    .filter(|(n, _)| !origin_module.type_aliases.contains_key(n))
1444                    .collect();
1445
1446                self.use_decls(decls);
1447                self.use_type_aliases(type_aliases);
1448            }
1449        }
1450    }
1451
1452    pub fn render(self) -> StateDelta {
1453        self.delta
1454    }
1455
1456    pub fn build_desc(&self, spans: &[Span]) -> (String, String) {
1457        let comment_lines: Vec<&[u8]> = spans
1458            .iter()
1459            .map(|span| self.get_span_contents(*span))
1460            .collect();
1461        build_desc(&comment_lines)
1462    }
1463
1464    pub fn find_block_by_span(&self, span: Span) -> Option<Arc<Block>> {
1465        for block in &self.delta.blocks {
1466            if Some(span) == block.span {
1467                return Some(block.clone());
1468            }
1469        }
1470
1471        for block in self.permanent_state.blocks.iter() {
1472            if Some(span) == block.span {
1473                return Some(block.clone());
1474            }
1475        }
1476
1477        None
1478    }
1479
1480    /// Blocks covering `span`, newest first (delta before permanent).
1481    pub fn blocks_with_span_newest_first(&self, span: Span) -> Vec<Arc<Block>> {
1482        let mut blocks = Vec::new();
1483        for block in self.delta.blocks.iter().rev() {
1484            if block.span == Some(span) {
1485                blocks.push(block.clone());
1486            }
1487        }
1488        for block in self.permanent_state.blocks.iter().rev() {
1489            if block.span == Some(span) {
1490                blocks.push(block.clone());
1491            }
1492        }
1493        blocks
1494    }
1495
1496    /// Identity lookup so a cache hit can keep the existing `BlockId`.
1497    pub fn find_block_id_of(&self, block: &Arc<Block>) -> Option<BlockId> {
1498        for (idx, existing) in self.delta.blocks.iter().enumerate() {
1499            if Arc::ptr_eq(existing, block) {
1500                return Some(BlockId::new(self.permanent_state.num_blocks() + idx));
1501            }
1502        }
1503        for (idx, existing) in self.permanent_state.blocks.iter().enumerate() {
1504            if Arc::ptr_eq(existing, block) {
1505                return Some(BlockId::new(idx));
1506            }
1507        }
1508        None
1509    }
1510
1511    pub fn find_module_by_span(&self, span: Span) -> Option<ModuleId> {
1512        for (id, module) in self.delta.modules.iter().enumerate() {
1513            if Some(span) == module.span {
1514                return Some(ModuleId::new(self.permanent_state.num_modules() + id));
1515            }
1516        }
1517
1518        for (module_id, module) in self.permanent_state.modules.iter().enumerate() {
1519            if Some(span) == module.span {
1520                return Some(ModuleId::new(module_id));
1521            }
1522        }
1523
1524        None
1525    }
1526
1527    /// Find the file which contains the given [`Span`]
1528    pub fn find_file_by_span(&self, span: Span) -> Option<&CachedFile> {
1529        self.files()
1530            // the span we're looking for is much more likely to be in a recently added file
1531            .rev()
1532            .find(|file| file.covered_span.contains_span(span))
1533    }
1534
1535    pub fn find_virtual_path(&self, name: &str) -> Option<&VirtualPath> {
1536        // Platform appropriate virtual path (slashes or backslashes)
1537        let virtual_path_name = Path::new(name);
1538
1539        for (virtual_name, virtual_path) in self.delta.virtual_paths.iter().rev() {
1540            if Path::new(virtual_name) == virtual_path_name {
1541                return Some(virtual_path);
1542            }
1543        }
1544
1545        for (virtual_name, virtual_path) in self.permanent_state.virtual_paths.iter().rev() {
1546            if Path::new(virtual_name) == virtual_path_name {
1547                return Some(virtual_path);
1548            }
1549        }
1550
1551        None
1552    }
1553
1554    pub fn get_virtual_path(&self, virtual_path_id: VirtualPathId) -> &(String, VirtualPath) {
1555        let num_permanent_virtual_paths = self.permanent_state.num_virtual_paths();
1556        if virtual_path_id.get() < num_permanent_virtual_paths {
1557            self.permanent_state.get_virtual_path(virtual_path_id)
1558        } else {
1559            self.delta
1560                .virtual_paths
1561                .get(virtual_path_id.get() - num_permanent_virtual_paths)
1562                .expect("internal error: missing virtual path")
1563        }
1564    }
1565
1566    pub fn add_span(&mut self, span: Span) -> SpanId {
1567        let num_permanent_spans = self.permanent_state.spans.len();
1568        self.delta.spans.push(span);
1569        SpanId::new(num_permanent_spans + self.delta.spans.len() - 1)
1570    }
1571
1572    pub fn resolve_span<'s>(&'s self, span: Span) -> Option<ResolvedSpan<'s>> {
1573        let cached_file = self.find_file_by_span(span)?;
1574        let file = cached_file.name.as_ref().into();
1575        let span = span.offset(cached_file.covered_span.start);
1576        Some(ResolvedSpan { file, span })
1577    }
1578}
1579
1580impl<'a> GetSpan for &'a StateWorkingSet<'a> {
1581    fn get_span(&self, span_id: SpanId) -> Span {
1582        let num_permanent_spans = self.permanent_state.num_spans();
1583        if span_id.get() < num_permanent_spans {
1584            self.permanent_state.get_span(span_id)
1585        } else {
1586            *self
1587                .delta
1588                .spans
1589                .get(span_id.get() - num_permanent_spans)
1590                .expect("internal error: missing span")
1591        }
1592    }
1593}
1594
1595impl miette::SourceCode for &StateWorkingSet<'_> {
1596    fn read_span<'b>(
1597        &'b self,
1598        span: &miette::SourceSpan,
1599        context_lines_before: usize,
1600        context_lines_after: usize,
1601    ) -> Result<Box<dyn miette::SpanContents<'b> + 'b>, miette::MietteError> {
1602        let debugging = std::env::var("MIETTE_DEBUG").is_ok();
1603        if debugging {
1604            let finding_span = "Finding span in StateWorkingSet";
1605            dbg!(finding_span, span);
1606        }
1607        for cached_file in self.files() {
1608            let (filename, start, end) = (
1609                &cached_file.name,
1610                cached_file.covered_span.start,
1611                cached_file.covered_span.end,
1612            );
1613            if debugging {
1614                dbg!(&filename, start, end);
1615            }
1616            if span.offset() >= start && span.offset() + span.len() <= end {
1617                if debugging {
1618                    let found_file = "Found matching file";
1619                    dbg!(found_file);
1620                }
1621                let our_span = cached_file.covered_span;
1622                // We need to move to a local span because we're only reading
1623                // the specific file contents via self.get_span_contents.
1624                let local_span = (span.offset() - start, span.len()).into();
1625                if debugging {
1626                    dbg!(&local_span);
1627                }
1628                let span_contents = self.get_span_contents(our_span);
1629                if debugging {
1630                    dbg!(String::from_utf8_lossy(span_contents));
1631                }
1632                let span_contents = span_contents.read_span(
1633                    &local_span,
1634                    context_lines_before,
1635                    context_lines_after,
1636                )?;
1637                let content_span = span_contents.span();
1638                // Back to "global" indexing
1639                let retranslated = (content_span.offset() + start, content_span.len()).into();
1640                if debugging {
1641                    dbg!(&retranslated);
1642                }
1643
1644                let data = span_contents.data();
1645                if &**filename == "<cli>" {
1646                    if debugging {
1647                        let success_cli = "Successfully read CLI span";
1648                        dbg!(success_cli, String::from_utf8_lossy(data));
1649                    }
1650                    return Ok(Box::new(miette::MietteSpanContents::new(
1651                        data,
1652                        retranslated,
1653                        span_contents.line(),
1654                        span_contents.column(),
1655                        span_contents.line_count(),
1656                    )));
1657                } else {
1658                    if debugging {
1659                        let success_file = "Successfully read file span";
1660                        dbg!(success_file);
1661                    }
1662                    return Ok(Box::new(miette::MietteSpanContents::new_named(
1663                        (**filename).to_owned(),
1664                        data,
1665                        retranslated,
1666                        span_contents.line(),
1667                        span_contents.column(),
1668                        span_contents.line_count(),
1669                    )));
1670                }
1671            }
1672        }
1673        Err(miette::MietteError::OutOfBounds)
1674    }
1675}
1676
1677/// Files being evaluated, arranged as a stack.
1678///
1679/// The current active file is on the top of the stack.
1680/// When a file source/import another file, the new file is pushed onto the stack.
1681/// Attempting to add files that are already in the stack (circular import) results in an error.
1682///
1683/// Note that file paths are compared without canonicalization, so the same
1684/// physical file may still appear multiple times under different paths.
1685/// This doesn't affect circular import detection though.
1686#[derive(Debug, Default)]
1687pub struct FileStack(Vec<PathBuf>);
1688
1689impl FileStack {
1690    /// Creates an empty stack.
1691    pub fn new() -> Self {
1692        Self(vec![])
1693    }
1694
1695    /// Creates a stack with a single file on top.
1696    ///
1697    /// This is a convenience method that creates an empty stack, then pushes the file onto it.
1698    /// It skips the circular import check and always succeeds.
1699    pub fn with_file(path: PathBuf) -> Self {
1700        Self(vec![path])
1701    }
1702
1703    /// Adds a file to the stack.
1704    ///
1705    /// If the same file is already present in the stack, returns `ParseError::CircularImport`.
1706    pub fn push(&mut self, path: PathBuf, span: Span) -> Result<(), ParseError> {
1707        // Check for circular import.
1708        if let Some(i) = self.0.iter().rposition(|p| p == &path) {
1709            let filenames: Vec<String> = self.0[i..]
1710                .iter()
1711                .chain(std::iter::once(&path))
1712                .map(|p| p.to_string_lossy().to_string())
1713                .collect();
1714            let msg = filenames.join("\nuses ");
1715            return Err(ParseError::CircularImport(msg, span));
1716        }
1717
1718        self.0.push(path);
1719        Ok(())
1720    }
1721
1722    /// Removes a file from the stack and returns its path, or None if the stack is empty.
1723    pub fn pop(&mut self) -> Option<PathBuf> {
1724        self.0.pop()
1725    }
1726
1727    /// Returns the active file (that is, the file on the top of the stack), or None if the stack is empty.
1728    pub fn top(&self) -> Option<&Path> {
1729        self.0.last().map(PathBuf::as_path)
1730    }
1731
1732    /// Returns the parent directory of the active file, or None if the stack is empty
1733    /// or the active file doesn't have a parent directory as part of its path.
1734    pub fn current_working_directory(&self) -> Option<&Path> {
1735        self.0.last().and_then(|path| path.parent())
1736    }
1737}