Implement Linearization for dependency resolution

[LesterEvSe]

This PR introduces the Linearization algorithm to manage module dependencies. It handles complex dependency topologies, detects cycles, and ensures strict, deterministic load ordering.

[KyrylR]

Is this up to date: #238?

[LesterEvSe]

Is this up to date: #238?

Yes, but it is much more optimized and has been refactored extensively

[KyrylR]

From what I understand the C3 should merge each parent linearization plus the raw parents list, otherwise the direct parent order is never part of the constraints. With the current code, parents [A, B] and linearizations [A] / [B, A] produce [B, A], even though that order contradicts the explicit parent list.

[KyrylR]

    #[test]
    fn test_c3_rejects_conflicting_direct_parent_order() {
        // main declares parents in the order [A, B].
        // But B itself depends on A, so B's linearization is [B, A].
        //
        // True C3 must merge:
        //   [A]
        //   [B, A]
        //   [A, B]   <- the raw parent list
        //
        // That merge has no valid head, so this must be rejected as inconsistent.
        let (graph, _, _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();

        assert!(
            matches!(order, Err(C3Error::InconsistentLinearization { .. })),
            "expected inconsistent linearization, got {order:?}"
        );
    }

[LesterEvSe]

Fixed and added a new test. I accidentally missed adding the parents' order to the sequences when I refactored the code

[LesterEvSe]

Update: I was mistaken in my previous comment. The test_c3_allows_valid_parent_chain() proves that we cannot enforce strict C3 parent order without breaking valid module imports. I have retained the 'Dependency-Driven' C3 approach and added a top-level docstring to formally document this architectural decision

[LesterEvSe]

Update 2: Taking this logic a step further—since we explicitly do not want to enforce strict local precedence for module imports, carrying the C3 is actually unnecessary. A standard post-order DFS provides this as well, but without overhead

[KyrylR]

matches! just returns a boolean... the result is discarded here

[KyrylR]

    #[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![main_id, b_id, a_id]);
    }

Now the valid import sequence is rejected

[KyrylR]

Also, is it expected that the order is top-down?

[KyrylR]

Give a link in the rust doc to the parent structure pls

[LesterEvSe]

Also, is it expected that the order is top-down?

I have decided to move order.reverse() directly to the c3_linearize() function. So now it is bottom-up at this stage

[KyrylR]

ACK 9ca524c