feat: add build_order function, refactor and test it

Author: LesterEvSe

src/driver/mod.rs

@@ -5,9 +5,10 @@ use std::collections::{HashMap, VecDeque};
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 
-use crate::error::ErrorCollector;
-use crate::parse::{self, ParseFromStrWithErrors};
+use crate::error::{ErrorCollector, Span};
+use crate::parse::{self, ParseFromStrWithErrors, Visibility};
 use crate::resolution::LibConfig;
+use crate::str::Identifier;
 
 /// Represents a single, isolated file in the SimplicityHL project.
 /// In this architecture, a file and a module are the exact same thing.
@@ -22,13 +23,22 @@ pub struct Module {
 pub struct ProjectGraph {
     /// Arena Pattern: the data itself lives here.
     /// A flat vector guarantees that module data is stored contiguously in memory.
-    pub modules: Vec<Module>,
+    pub(self) modules: Vec<Module>,
+
+    /// The configuration environment.
+    /// Used to resolve xternal library dependencies and invoke their associated functions.
+    pub config: Arc<LibConfig>,
 
     /// Fast lookup: File Path -> Module ID.
     /// A reverse index mapping absolute file paths to their internal IDs.
     /// This solves the duplication problem, ensuring each file is only parsed once.
     pub lookup: HashMap<PathBuf, usize>,
 
+    /// Fast lookup: Module ID -> File Path.
+    /// A direct index mapping internal IDs back to their absolute file paths.
+    /// This serves as the exact inverse of the `lookup` map.
+    pub paths: Vec<PathBuf>,
+
     /// The Adjacency List: Defines the Directed acyclic Graph (DAG) of imports.
     ///
     /// The Key (`usize`) is the ID of a "Parent" module (the file doing the importing).
@@ -39,6 +49,18 @@ pub struct ProjectGraph {
     pub dependencies: HashMap<usize, Vec<usize>>,
 }
 
+#[derive(Clone, Debug)]
+pub struct Resolution {
+    pub visibility: Visibility,
+}
+
+pub struct Program {
+    //pub graph: ProjectGraph,
+    pub items: Arc<[parse::Item]>,
+    pub scope_items: Vec<HashMap<Identifier, Resolution>>,
+    pub span: Span,
+}
+
 #[derive(Debug)]
 pub enum C3Error {
     CycleDetected(Vec<usize>),
@@ -91,15 +113,16 @@ fn merge(mut seqs: Vec<Vec<usize>>) -> Option<Vec<usize>> {
 }
 
 impl ProjectGraph {
-    pub fn new(lib_cfg: &LibConfig, root_program: &parse::Program) -> Result<Self, String> {
+    pub fn new(config: Arc<LibConfig>, root_program: &parse::Program) -> Result<Self, String> {
         let mut modules: Vec<Module> = vec![Module {
             parsed_program: root_program.clone(),
         }];
         let mut lookup: HashMap<PathBuf, usize> = HashMap::new();
+        let mut paths: Vec<PathBuf> = vec![config.root_path.clone()];
         let mut dependencies: HashMap<usize, Vec<usize>> = HashMap::new();
 
         let root_id = 0;
-        lookup.insert(lib_cfg.root_path.clone(), root_id);
+        lookup.insert(config.root_path.clone(), root_id);
         dependencies.insert(root_id, Vec::new());
 
         // Implementation of the standard BFS algorithm with memoization and queue
@@ -112,7 +135,7 @@ impl ProjectGraph {
 
             for elem in current_program.items() {
                 if let parse::Item::Use(use_decl) = elem {
-                    if let Ok(path) = lib_cfg.get_full_path(use_decl) {
+                    if let Ok(path) = config.get_full_path(use_decl) {
                         pending_imports.push(path);
                     }
                 }
@@ -140,6 +163,7 @@ impl ProjectGraph {
                     parsed_program: program,
                 });
                 lookup.insert(path.clone(), last_ind);
+                paths.push(path.clone());
                 dependencies.entry(curr_id).or_default().push(last_ind);
 
                 queue.push_back(last_ind);
@@ -148,7 +172,9 @@ impl ProjectGraph {
 
         Ok(Self {
             modules,
+            config,
             lookup,
+            paths,
             dependencies,
         })
     }
@@ -212,4 +238,115 @@ impl ProjectGraph {
 
         Ok(result)
     }
+
+    fn process_use_item(
+        scope_items: &mut [HashMap<Identifier, Resolution>],
+        file_id: usize,
+        ind: usize,
+        elem: &Identifier,
+        use_decl_visibility: Visibility,
+    ) -> Result<(), String> {
+        if matches!(
+            scope_items[ind][elem].visibility,
+            parse::Visibility::Private
+        ) {
+            return Err(format!(
+                "Function {} is private and cannot be used.",
+                elem.as_inner()
+            ));
+        }
+
+        scope_items[file_id].insert(
+            elem.clone(),
+            Resolution {
+                visibility: use_decl_visibility,
+            },
+        );
+
+        Ok(())
+    }
+
+    fn register_def(
+        items: &mut Vec<parse::Item>,
+        scope: &mut HashMap<Identifier, Resolution>,
+        item: &parse::Item,
+        name: Identifier,
+        vis: &parse::Visibility,
+    ) {
+        items.push(item.clone());
+        scope.insert(
+            name,
+            Resolution {
+                visibility: vis.clone(),
+            },
+        );
+    }
+
+    // TODO: @LesterEvSe, consider processing more than one error at a time
+    fn build_program(&self, order: &Vec<usize>) -> Result<Program, String> {
+        let mut items: Vec<parse::Item> = Vec::new();
+        let mut scope_items: Vec<HashMap<Identifier, Resolution>> =
+            vec![HashMap::new(); order.len()];
+
+        for &file_id in order {
+            let program_items = self.modules[file_id].parsed_program.items();
+
+            for elem in program_items {
+                match elem {
+                    parse::Item::Use(use_decl) => {
+                        let full_path = self.config.get_full_path(use_decl)?;
+                        let ind = self.lookup[&full_path];
+                        let visibility = use_decl.visibility();
+
+                        let use_targets = match use_decl.items() {
+                            parse::UseItems::Single(elem) => std::slice::from_ref(elem),
+                            parse::UseItems::List(elems) => elems.as_slice(),
+                        };
+
+                        for target in use_targets {
+                            ProjectGraph::process_use_item(
+                                &mut scope_items,
+                                file_id,
+                                ind,
+                                target,
+                                visibility.clone(),
+                            )?;
+                        }
+                    }
+                    parse::Item::TypeAlias(alias) => {
+                        Self::register_def(
+                            &mut items,
+                            &mut scope_items[file_id],
+                            elem,
+                            alias.name().clone().into(),
+                            alias.visibility(),
+                        );
+                    }
+                    parse::Item::Function(function) => {
+                        Self::register_def(
+                            &mut items,
+                            &mut scope_items[file_id],
+                            elem,
+                            function.name().clone().into(),
+                            function.visibility(),
+                        );
+                    }
+                    parse::Item::Module => {}
+                }
+            }
+        }
+
+        Ok(Program {
+            items: items.into(),
+            scope_items,
+            span: *self.modules[0].parsed_program.as_ref(),
+        })
+    }
+
+    pub fn resolve_complication_order(&self) -> Result<Program, String> {
+        // TODO: @LesterEvSe, resolve errors more appropriately
+        let mut order = self.c3_linearize().unwrap();
+        order.reverse();
+        self.build_program(&order)
+    }
 }

src/driver/tests.rs

@@ -20,7 +20,7 @@ fn create_simf_file(dir: &Path, rel_path: &str, content: &str) -> PathBuf {
 
 // Helper to mock the initial root program parsing
 fn parse_root(path: &Path) -> parse::Program {
-    parse_and_get_program(path).expect("Root parsing failed")
+    parse_and_get_program(path).unwrap()
 }
 
 /// Initializes a graph environment for testing.
@@ -51,8 +51,8 @@ fn setup_graph(files: Vec<(&str, &str)>) -> (ProjectGraph, HashMap<String, usize
     let root_p = root_path.expect("main.simf must be defined in file list");
     let root_program = parse_root(&root_p);
 
-    let config = LibConfig::new(lib_map, &root_p);
-    let graph = ProjectGraph::new(&config, &root_program).unwrap();
+    let config = Arc::from(LibConfig::new(lib_map, &root_p));
+    let graph = ProjectGraph::new(config, &root_program).unwrap();
 
     // Create a lookup map for tests: "A.simf" -> FileID
     let mut file_ids = HashMap::new();
@@ -87,7 +87,7 @@ mod graph_construction_and_dependency_resolution {
 
         assert!(
             graph.dependencies[&root_id].contains(&math_id),
-            "Root (main.simf) should depend on Math (main.simf)"
+            "Root (main.simf) should depend on Math (math.simf)"
         );
     }
 
@@ -230,6 +230,124 @@ mod c3_linearization {
     }
 }
 
+#[cfg(test)]
+mod visibility_and_access_control {
+    use super::*;
+
+    #[test]
+    fn test_local_definitions_visibility() {
+        // Scenario:
+        // main.simf defines a private function and a public function.
+        // Expected: Both should appear in the scope with correct visibility.
+
+        let (graph, ids, _dir) = setup_graph(vec![(
+            "main.simf",
+            "fn private_fn() {} pub fn public_fn() {}",
+        )]);
+
+        let root_id = ids["main"];
+        let order = vec![root_id]; // Only one file
+
+        let program = graph
+            .build_program(&order)
+            .expect("Failed to build program");
+        let scope = &program.scope_items[root_id];
+
+        // Check private function
+        let private_res = scope
+            .get(&Identifier::from("private_fn"))
+            .expect("private_fn missing");
+        assert_eq!(private_res.visibility, Visibility::Private);
+
+        // Check public function
+        let public_res = scope
+            .get(&Identifier::from("public_fn"))
+            .expect("public_fn missing");
+        assert_eq!(public_res.visibility, Visibility::Public);
+    }
+
+    #[test]
+    fn test_pub_use_propagation() {
+        // Scenario: Re-exporting.
+        // 1. A.simf defines `pub fn foo`.
+        // 2. B.simf imports it and re-exports it via `pub use`.
+        // 3. main.simf imports it from B.
+        // Expected: B's scope must contain `foo` marked as Public.
+
+        let (graph, ids, _dir) = setup_graph(vec![
+            ("libs/lib/A.simf", "pub fn foo() {}"),
+            ("libs/lib/B.simf", "pub use lib::A::foo;"),
+            ("main.simf", "use lib::B::foo;"),
+        ]);
+
+        let id_a = ids["A"];
+        let id_b = ids["B"];
+        let id_root = ids["main"];
+
+        // Manual topological order: A -> B -> Root
+        let order = vec![id_a, id_b, id_root];
+
+        let program = graph
+            .build_program(&order)
+            .expect("Failed to build program");
+
+        // Check B's scope
+        let scope_b = &program.scope_items[id_b];
+        let foo_in_b = scope_b
+            .get(&Identifier::from("foo"))
+            .expect("foo missing in B");
+
+        // This is the critical check: Did `pub use` make it Public in B?
+        assert_eq!(
+            foo_in_b.visibility,
+            Visibility::Public,
+            "B should re-export foo as Public"
+        );
+
+        // Check Root's scope
+        let scope_root = &program.scope_items[id_root];
+        let foo_in_root = scope_root
+            .get(&Identifier::from("foo"))
+            .expect("foo missing in Root");
+
+        // Root imported it via `use` (not pub use), so it should be Private in Root
+        assert_eq!(
+            foo_in_root.visibility,
+            Visibility::Private,
+            "Root should have foo as Private"
+        );
+    }
+
+    #[test]
+    fn test_private_import_encapsulation_error() {
+        // Scenario: Access violation.
+        // 1. A.simf defines `pub fn foo`.
+        // 2. B.simf imports it via `use` (Private import).
+        // 3. main.simf tries to import `foo` from B.
+        // Expected: Error, because B did not re-export foo.
+
+        let (graph, ids, _dir) = setup_graph(vec![
+            ("libs/lib/A.simf", "pub fn foo() {}"),
+            ("libs/lib/B.simf", "use lib::A::foo;"), // <--- Private binding!
+            ("main.simf", "use lib::B::foo;"),       // <--- Should fail
+        ]);
+
+        let id_a = ids["A"];
+        let id_b = ids["B"];
+        let id_root = ids["main"];
+
+        // Order: A -> B -> Root
+        let order = vec![id_a, id_b, id_root];
+
+        let result = graph.build_program(&order);
+
+        assert!(
+            result.is_err(),
+            "Build should fail when importing a private binding"
+        );
+    }
+}
+
 #[cfg(test)]
 mod error_diganostic_and_terminal_formatting {
     use super::*;
@@ -247,8 +365,8 @@ mod error_diganostic_and_terminal_formatting {
         lib_map.insert("std".to_string(), temp_dir.path().join("libs/std"));
 
         let root_program = parse_root(&root_path);
-        let config = LibConfig::new(lib_map, &root_path);
-        let result = ProjectGraph::new(&config, &root_program);
+        let config = Arc::from(LibConfig::new(lib_map, &root_path));
+        let result = ProjectGraph::new(config, &root_program);
 
         assert!(result.is_err(), "Should fail for missing file");
         let err_msg = result.err().unwrap();

src/lib.rs

@@ -59,8 +59,13 @@ impl TemplateProgram {
         let parse_program = parse::Program::parse_from_str_with_errors(&file, &mut error_handler);
 
         if let Some(program) = parse_program {
-            let _ = if let Some(lib_cfg) = lib_cfg {
-                Some(ProjectGraph::new(lib_cfg, &program)?)
+            // TODO: Consider a proper resolution strategy later.
+            let _: Option<driver::Program> = if let Some(cfg) = lib_cfg {
+                let config_arc = Arc::new(cfg.clone());
+                let graph = ProjectGraph::new(config_arc, &program)?;
+
+                // TODO: Perhaps add an `error_handler` here, too.
+                Some(graph.resolve_complication_order()?)
             } else {
                 None
             };