Added C3 algorithm

Sdoba16 · LesterEvSe · commit a49865f3dcf6 · 2026-04-09T15:16:26.000+03:00
diff --git a/src/driver/c3_linearization.rs b/src/driver/c3_linearization.rs
@@ -0,0 +1,322 @@
+//! Dependency-Driven C3 Linearization Engine
+//!
+//! This module implements a variant of the C3 Linearization algorithm optimized
+//! specifically for module dependency resolution rather than Object-Oriented
+//! Method Resolution Order (MRO).
+//!
+//! # Architectural Note: Strict vs. Dependency-Driven C3
+//! Standard C3 Linearization (used in Python and Solidity) strictly enforces
+//! *local precedence* by appending the direct parent list to the merge sequences.
+//! If a developer's local import order contradicts the physical dependency graph
+//! (e.g., they import `A` before `B`, but `B` depends on `A`), strict C3 deadlocks
+//! and throws an error to prevent method-overriding paradoxes.
+//!
+//! Because SimplicityHL module imports rely on namespacing/aliasing rather than
+//! inheritance and method overriding, enforcing strict local precedence is unnecessary
+//! and creates a rigid user experience. This implementation deliberately omits the
+//! local precedence constraint.
+//!
+//! # Rationale: Why keep C3 instead of refactoring to pure DFS?
+//!
+//! While cycle detection and topological sorting could theoretically be handled by a
+//! simpler DFS, we must consider the long-term impact on the SimplicityHL ecosystem
+//! and whether strict `InconsistentLinearization` errors will be necessary in the future.
+//!
+//! When deciding how to handle this, we faced two architectural paths:
+//!
+//! 1. **Refactor to DFS:** We strip out C3 now. If Simplicity Devs start writing
+//!    libraries, and we later discover a complex resolution bug that forces us to
+//!    revert back to C3, the sudden change in resolution rules could break existing
+//!    libraries across the ecosystem. This is a highly undesirable risk.
+//!
+//! 2. **Retain a Relaxed C3 (Chosen Path):** We keep the robust C3 merge engine
+//!    but weaken its strict local-precedence restrictions to mimic DFS behavior.
+//!    This allows current tests to pass and provides a forgiving user experience.
+//!    If the relaxed rules are enough, great. If strict C3 constraints are needed
+//!    later, the architectural foundation is already in place, preventing a massive
+//!    and destructive migration for developers.
+//!
+//! By prioritizing the physical graph structure over arbitrary `use` statement
+//! ordering, this "Dependency-Driven" approach provides the following guarantees:
+//!
+//! 1. **Diamond Deduplication:** Shared dependencies are evaluated and loaded exactly once.
+//! 2. **Cycle Detection:** Circular dependencies (`A -> B -> A`) are caught and cleanly rejected.
+//! 3. **Order Forgiveness:** Contradictory local import statements are safely auto-corrected
+//!    to satisfy the structural requirements of the Directed Acyclic Graph.
+
+// TODO: Remove this once the code is actively used.
+#![allow(dead_code)]
+use std::{collections::HashMap, fmt};
+
+use crate::driver::DependencyGraph;
+
+/// This is a core component of the [`DependencyGraph`](super::DependencyGraph).
+impl DependencyGraph {
+    /// Returns the deterministic, BOTTOM-UP load order of dependencies.
+    fn c3_linearize(&self) -> Result<Vec<usize>, C3Error> {
+        let mut order = self.linearize_module(0)?;
+        order.reverse();
+        Ok(order)
+    }
+
+    fn linearize_module(&self, root: usize) -> Result<Vec<usize>, C3Error> {
+        let mut memo = HashMap::new();
+        let mut visiting = Vec::new();
+
+        self.linearize_rec(root, &mut memo, &mut visiting)
+    }
+
+    /// Core recursive DFS for C3 linearization.
+    ///
+    /// - **Memoization (`memo`):** Prevents exponential blowup in diamond dependencies by calculating shared modules exactly once.
+    /// - **Cycle Detection (`visiting`):** Prevents infinite loops by returning an error if the current path repeats a module (e.g., A -> B -> A).
+    ///
+    /// # Returns
+    /// - `Ok(Vec<usize>)`: The deterministic, top-down ordered sequence of dependencies for the module.
+    /// - `Err(C3Error)`: If a circular dependency or unresolvable conflict is detected.
+    fn linearize_rec(
+        &self,
+        module: usize,
+        memo: &mut HashMap<usize, Vec<usize>>,
+        visiting: &mut Vec<usize>,
+    ) -> Result<Vec<usize>, C3Error> {
+        if let Some(result) = memo.get(&module) {
+            return Ok(result.clone());
+        }
+
+        if let Some(cycle_start) = visiting.iter().position(|&m| m == module) {
+            return Err(C3Error::CycleDetected(
+                visiting[cycle_start..]
+                    .iter()
+                    .map(|&id| self.modules[id].source.str_name())
+                    .collect(),
+            ));
+        }
+
+        visiting.push(module);
+
+        let parents = self
+            .dependencies
+            .get(&module)
+            .map_or(&[] as &[usize], |v| v.as_slice());
+
+        let mut seqs: Vec<Vec<usize>> = Vec::with_capacity(parents.len() + 1);
+
+        for &parent in parents {
+            seqs.push(self.linearize_rec(parent, memo, visiting)?);
+        }
+
+        let mut result = vec![module];
+        let merged = c3_merge(seqs).map_err(|conflicts| C3Error::InconsistentLinearization {
+            module: self.modules[module].source.str_name(),
+            conflicts: self.format_conflict_names(conflicts),
+        })?;
+
+        result.extend(merged);
+
+        visiting.pop();
+        memo.insert(module, result.clone());
+
+        Ok(result)
+    }
+
+    /// Helper to convert raw usize conflict sequences into readable module names
+    fn format_conflict_names(&self, conflicts: Vec<Vec<usize>>) -> Vec<Vec<String>> {
+        conflicts
+            .into_iter()
+            .map(|seq| {
+                seq.into_iter()
+                    .map(|id| self.modules[id].source.str_name())
+                    .collect()
+            })
+            .collect()
+    }
+}
+
+/// Merges a list of sequences (parent linearizations) into a single sequence.
+/// The algorithm ensures that the local precedence order of each sequence is preserved.
+fn c3_merge(seqs: Vec<Vec<usize>>) -> Result<Vec<usize>, Vec<Vec<usize>>> {
+    // Convert to a collection of slices. This allows us to "remove" the head
+    // by simply advancing the slice pointer by 1, which is entirely zero-cost.
+    let mut slices: Vec<&[usize]> = seqs.iter().map(AsRef::as_ref).collect();
+    let mut result = Vec::new();
+
+    loop {
+        slices.retain(|s| !s.is_empty());
+        if slices.is_empty() {
+            return Ok(result);
+        }
+
+        let candidate = slices
+            .iter()
+            .map(|s| s[0])
+            .find(|&head| !slices.iter().any(|s| s[1..].contains(&head)));
+
+        let Some(head) = candidate else {
+            let conflicts = slices.into_iter().map(|s| s.to_vec()).collect();
+            return Err(conflicts);
+        };
+
+        result.push(head);
+        for seq in &mut slices {
+            if seq.first() == Some(&head) {
+                *seq = &seq[1..];
+            }
+        }
+    }
+}
+
+#[derive(Debug)]
+enum C3Error {
+    CycleDetected(Vec<String>),
+    /// Error for inconsistent MRO.
+    /// This can happen if the dependency graph has a shape that makes the
+    /// order of parent classes ambiguous.
+    /// Example: A depends on B and C, and B also depends on C.
+    /// The linearization of A is A + merge(linearization(B), linearization(C), [B, C]).
+    /// If B appears before C in one parent's linearization but C appears before B
+    /// in another's, the merge will fail.
+    InconsistentLinearization {
+        module: String,
+        conflicts: Vec<Vec<String>>,
+    },
+}
+
+impl fmt::Display for C3Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            C3Error::CycleDetected(cycle) => {
+                write!(f, "Circular dependency detected: {:?}", cycle.join(" -> "))
+            }
+            C3Error::InconsistentLinearization { module, conflicts } => {
+                writeln!(f, "Inconsistent resolution order for module '{}'", module)?;
+                writeln!(
+                    f,
+                    "The compiler could not resolve the following conflicting import constraints:"
+                )?;
+
+                // Loop through the matrix and print each conflicting sequence
+                for conflict in conflicts {
+                    writeln!(f, "  [{}]", conflict.join(", "))?;
+                }
+
+                write!(
+                    f,
+                    "Try reordering your `use` statements to avoid cross-wiring."
+                )
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::driver::tests::setup_graph;
+
+    use super::*;
+
+    #[test]
+    fn test_c3_simple_import() {
+        let (graph, ids, _dir) = setup_graph(vec![
+            ("main.simf", "use lib::math::some_func;"),
+            ("libs/lib/math.simf", ""),
+        ]);
+
+        let order = graph.c3_linearize().unwrap();
+
+        let root_id = ids["main"];
+        let math_id = ids["math"];
+
+        assert_eq!(order, vec![math_id, root_id]);
+    }
+
+    #[test]
+    fn test_c3_diamond_dependency_deduplication() {
+        // Setup:
+        // root -> imports A, B
+        // A -> imports Common
+        // B -> imports Common
+        // Expected: Common loaded ONLY ONCE.
+
+        let (graph, ids, _dir) = setup_graph(vec![
+            ("main.simf", "use lib::A::foo; use lib::B::bar;"),
+            ("libs/lib/A.simf", "use lib::Common::dummy1;"),
+            ("libs/lib/B.simf", "use lib::Common::dummy2;"),
+            ("libs/lib/Common.simf", ""),
+        ]);
+
+        let order = graph.c3_linearize().unwrap();
+
+        // Verify order using IDs from the helper map
+        let main_id = ids["main"];
+        let a_id = ids["A"];
+        let b_id = ids["B"];
+        let common_id = ids["Common"];
+
+        assert_eq!(order, vec![common_id, b_id, a_id, main_id]);
+    }
+
+    #[test]
+    fn test_c3_detects_cycle() {
+        let (graph, _, _dir) = setup_graph(vec![
+            ("main.simf", "use lib::A::entry;"),
+            ("libs/lib/A.simf", "use lib::B::func;"),
+            ("libs/lib/B.simf", "use lib::A::func;"),
+        ]);
+
+        let order = graph.c3_linearize();
+        assert!(matches!(order, Err(C3Error::CycleDetected { .. })));
+    }
+
+    #[test]
+    fn test_c3_inconsistent_linearization() {
+        // Setup:
+        // `main` declares imports in the local order: A, then B.
+        // However, B internally depends on A.
+        //
+        // Under STRICT C3 Linearization:
+        // This would fail and return `C3Error::InconsistentLinearization`.
+        // The algorithm would deadlock because `main` demands A before B,
+        // but the physical graph demands B wraps A.
+        //
+        // Under our DEPENDENCY-DRIVEN C3 Linearization:
+        // We forgive the local import order of `main`. The algorithm prioritizes
+        // the physical graph structure over the arbitrary order of `use` statements,
+        // successfully auto-correcting the load order to prevent compiler crashes.
+        let (graph, ids, _dir) = setup_graph(vec![
+            ("main.simf", "use lib::A::foo; use lib::B::bar;"),
+            ("libs/lib/A.simf", ""),
+            ("libs/lib/B.simf", "use lib::A::foo;"),
+        ]);
+
+        let order = graph
+            .c3_linearize()
+            .expect("valid dependency DAG should linearize successfully");
+
+        let main_id = ids["main"];
+        let a_id = ids["A"];
+        let b_id = ids["B"];
+
+        assert_eq!(order, vec![a_id, b_id, main_id]);
+    }
+
+    #[test]
+    fn test_c3_allows_valid_parent_chain() {
+        // main imports A, then B; B itself imports A.
+        let (graph, ids, _dir) = setup_graph(vec![
+            ("main.simf", "use lib::A::foo; use lib::B::bar;"),
+            ("libs/lib/A.simf", ""),
+            ("libs/lib/B.simf", "use lib::A::foo;"),
+        ]);
+
+        let order = graph
+            .c3_linearize()
+            .expect("valid dependency DAG should linearize successfully");
+
+        let main_id = ids["main"];
+        let a_id = ids["A"];
+        let b_id = ids["B"];
+
+        assert_eq!(order, vec![a_id, b_id, main_id]);
+    }
+}
diff --git a/src/driver/mod.rs b/src/driver/mod.rs
@@ -1,3 +1,5 @@
+mod c3_linearization;
+
 use std::collections::{HashMap, HashSet, VecDeque};
 use std::path::PathBuf;
 use std::sync::Arc;
@@ -46,6 +48,10 @@ impl CanonSourceFile {
         &self.name
     }
 
+    pub fn str_name(&self) -> String {
+        self.name.as_path().display().to_string()
+    }
+
     pub fn content(&self) -> Arc<str> {
         self.content.clone()
     }
@@ -326,7 +332,7 @@ mod tests {
     /// 3. `TempWorkspace`: The temporary directory instance. This must be kept in scope by the caller so
     ///    the OS doesn't delete the files before the test finishes.
     /// 4. `ErrorCollector`: The handler containing any logged errors, useful fo
-    fn setup_graph_raw(
+    pub(crate) fn setup_graph_raw(
         files: Vec<(&str, &str)>,
     ) -> (
         Option<DependencyGraph>,
@@ -414,7 +420,7 @@ mod tests {
     ///
     /// This function will immediately panic and print the collected errors
     /// to standard error if the parser or graph builder encounters any issues.
-    fn setup_graph(
+    pub(crate) fn setup_graph(
         files: Vec<(&str, &str)>,
     ) -> (DependencyGraph, HashMap<String, usize>, TempWorkspace) {
         let (graph_option, file_ids, ws, handler) = setup_graph_raw(files);
