feat: add lineariza and build functionality to driver

Author: LesterEvSe

src/driver/linearization.rs

@@ -6,8 +6,6 @@
 //! Because we do not need to enforce strict local precedence, a standard post-order
 //! DFS is a better option.
 
-// TODO: Remove this once the code is actively used.
-#![allow(dead_code)]
 use std::collections::HashSet;
 use std::fmt;
 
@@ -16,7 +14,7 @@ use crate::driver::DependencyGraph;
 /// This is a core component of the [`DependencyGraph`].
 impl DependencyGraph {
     /// Returns the deterministic, BOTTOM-UP load order of dependencies.
-    pub fn linearize(&self) -> Result<Vec<usize>, LinearizationError> {
+    pub(crate) fn linearize(&self) -> Result<Vec<usize>, LinearizationError> {
         let mut visited = HashSet::new();
         let mut visiting = Vec::new();
         let mut order = Vec::new();

src/driver/mod.rs

@@ -1,4 +1,95 @@
+//! The `driver` module is responsible for module resolution and dependency management.
+//!
+//! Our compiler operates in a strict pipeline: `Lexer -> Parser -> Driver -> AST`.
+//! While the Parser only understands a single file at a time, the Driver processes
+//! multiple files, resolves their dependencies, and converts them into a unified
+//! structure ready for final AST construction.
+//!
+//! # Package Management & Distribution
+//!
+//! SimplicityHL is currently **transport-agnostic**, meaning it does not provide its own
+//! package registry. Developers can use existing ecosystems to distribute `.simf` modules.
+//!
+//! ## Distributing via crates.io
+//!
+//! 1. **Publishing:** Create a Rust library (`cargo new --lib`), and place
+//!    your `.simf` files inside it. Then publish the crate to `crates.io`.
+//!
+//! 2. **Downloading:** In the consuming Rust project, add the published crate to
+//!    your `Cargo.toml`. Running `cargo build` forces Cargo to download the files
+//!    to your global registry cache.
+//!
+//! 3. **Locating:** Find the exact path to the downloaded crate package on your system.
+//!    *(e.g., `~/.cargo/registry/src/index.crates.io-<hash>/simplicity-calculator-0.1.0/`)*
+//!
+//! 4. **Linking:** Pass this path to the compiler using
+//!    the `--lib` flag, assigning it a custom alias:
+//!    ``` text
+//!    simc path/to/main.simf --lib calc=~/.cargo/registry/src/.../simplicity-calculator-0.1.0/
+//!    ```
+//!
+//! 5. **Importing:** Inside your `main.simf`, start with the assigned alias (`calc`).
+//!    If the `.simf` file is nested inside subdirectories, the path must reflect
+//!    that folder structure. Follow the alias with the directory names, the target
+//!    filename, and finally the items to import:
+//!    ``` text
+//!    // If `calculator.simf` is directly in the library's root:
+//!    use calc::calculator::{add_32, subtract_32};
+//!
+//!    // If `calculator.simf` is nested inside a `utils` directory:
+//!    use calc::utils::calculator::{add_32, subtract_32};
+//!    ```
+//!
+//! ## Distributing via npm
+//!
+//! NPM can also be used as a simple file delivery system for SimplicityHL,
+//! which is especially useful for developers working in web environments.
+//!
+//! 1. **Publishing:** Create a directory, generate a `package.json` file
+//!    (`npm init -y`), place your `.simf` files inside, and run `npm publish`.
+//!
+//! 2. **Downloading:** In the consuming project's directory, run
+//!    `npm install <package-name>`. NPM will download the files locally.
+//!
+//! 3. **Locating:** The `.simf` files will be placed inside the standard
+//!    `node_modules` directory at `./node_modules/<package-name>/`.
+//!
+//! 4. **Linking:** Pass this local path to the Simplicity compiler using
+//!    the `--lib` flag, assigning it a custom alias:
+//!    ``` text
+//!    simc main.simf --lib calc=./node_modules/simplicity-calculator/
+//!    ```
+//!
+//! 5. **Importing:** Inside your `main.simf`, use the alias exactly as
+//!    you would with any other dependency:
+//!    ``` text
+//!    use calc::calculator::{add_32, subtract_32};
+//!    ```
+//!
+//! # Architecture
+//!
+//! ## Dependency Graph & Linearization
+//!
+//! The driver parses the root file and recursively discovers all imported modules
+//! to build a Directed Acyclic Graph (DAG) of the project's dependencies. Because
+//! the final AST requires a flat array of items, the driver applies a deterministic
+//! linearization strategy to this DAG. This safely flattens the multi-file project
+//! into a single, logically ordered sequence, strictly enforcing visibility rules
+//! and preventing duplicate imports.
+//!
+//! ## Project Structure & Entry Point
+//!
+//! SimplicityHL does not define a "project root" directory. Instead, the compiler
+//! relies on a single entry point: the file passed as the first positional argument.
+//! This file must contain the `main` function, which serves as the program's
+//! starting point.
+//!
+//! External libraries are explicitly linked using the `--lib` flag. The driver
+//! resolves and parses these external files relative to the entry point during
+//! the dependency graph construction.
+
 mod linearization;
+mod resolve_order;
 
 use std::collections::{HashMap, HashSet, VecDeque};
 use std::path::PathBuf;