leo_package/

package.rs

// Copyright (C) 2019-2026 Provable Inc.
// This file is part of the Leo library.

// The Leo library is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.

// The Leo library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.

// You should have received a copy of the GNU General Public License
// along with the Leo library. If not, see <https://www.gnu.org/licenses/>.

use crate::*;

use leo_ast::DiGraph;
use leo_errors::Result;
use leo_span::Symbol;

use indexmap::{IndexMap, map::Entry};
use snarkvm::prelude::anyhow;
use std::path::{Path, PathBuf};

/// Either the bytecode of an Aleo program (if it was a network dependency) or
/// a path to its source (if it was local).
#[derive(Clone, Debug)]
pub enum ProgramData {
    Bytecode(String),
    /// For a local dependency, `directory` is the directory of the package
    /// For a test dependency, `directory` is the directory of the test file.
    SourcePath {
        directory: PathBuf,
        source: PathBuf,
    },
}

/// A Leo package.
#[derive(Clone, Debug)]
pub struct Package {
    /// The directory on the filesystem where the package is located, canonicalized.
    pub base_directory: PathBuf,

    /// A topologically sorted list of all compilation units in this package, whether
    /// dependencies or the main program.
    ///
    /// Any unit's dependent unit will appear before it, so that compiling
    /// them in order should give access to all stubs necessary to compile each
    /// compilation unit.
    pub compilation_units: Vec<CompilationUnit>,

    /// The manifest file of this package.
    pub manifest: Manifest,

    /// The dependency graph of the package.
    pub dep_graph: DiGraph<Symbol>,
}

impl Package {
    /// The root of the build directory.
    ///
    /// This is the single place that knows where build artifacts are rooted;
    /// every per-unit path below is composed from it.
    pub fn build_directory(&self) -> PathBuf {
        self.base_directory.join(BUILD_DIRECTORY)
    }

    /// The package's own compilation unit, identified via the manifest.
    /// Robust under `--build-tests` (unlike `compilation_units.last()`).
    pub fn primary_unit(&self) -> Option<&CompilationUnit> {
        let primary = bare_unit_name(&self.manifest.program);
        self.compilation_units.iter().find(|u| !u.kind.is_test() && bare_unit_name(&u.name.to_string()) == primary)
    }

    /// The `build/<name>/` directory for a single compilation unit - a program,
    /// library, or test - whether it is this package's own unit, a local
    /// dependency, or a fetched network import.
    pub fn unit_build_directory(&self, name: &str) -> PathBuf {
        self.build_directory().join(bare_unit_name(name))
    }

    /// Path to a unit's compiled Aleo bytecode: `build/<name>/<name>.aleo`.
    /// Only programs and tests produce bytecode; libraries do not.
    pub fn unit_bytecode_path(&self, name: &str) -> PathBuf {
        let bare = bare_unit_name(name);
        self.unit_build_directory(name).join(format!("{bare}.aleo"))
    }

    /// Path to a unit's Leo ABI: `build/<name>/abi.json`.
    pub fn unit_abi_path(&self, name: &str) -> PathBuf {
        self.unit_build_directory(name).join(ABI_FILENAME)
    }

    /// Path to a unit's interface ABI directory: `build/<name>/interfaces/`.
    /// Both programs and libraries can declare interfaces.
    pub fn unit_interfaces_directory(&self, name: &str) -> PathBuf {
        self.unit_build_directory(name).join(INTERFACES_DIRNAME)
    }

    /// Path to a unit's AST-snapshot directory: `build/<name>/snapshots/`.
    /// Populated only when a snapshot CLI flag is set; created lazily by the
    /// compiler on the first write, so absent on builds that don't request snapshots.
    pub fn unit_snapshots_directory(&self, name: &str) -> PathBuf {
        self.unit_build_directory(name).join(SNAPSHOTS_DIRNAME)
    }

    pub fn source_directory(&self) -> PathBuf {
        self.base_directory.join(SOURCE_DIRECTORY)
    }

    pub fn tests_directory(&self) -> PathBuf {
        self.base_directory.join(TESTS_DIRECTORY)
    }

    /// Create a Leo package by the name `package_name` in a subdirectory of `path`.
    pub fn initialize<P: AsRef<Path>>(package_name: &str, path: P, is_library: bool) -> Result<PathBuf> {
        Self::initialize_impl(package_name, path.as_ref(), is_library)
    }

    fn initialize_impl(package_name: &str, path: &Path, is_library: bool) -> Result<PathBuf> {
        let package_name = if is_library {
            if !crate::is_valid_library_name(package_name) {
                return Err(crate::errors::cli_invalid_package_name("library", package_name).into());
            }

            package_name.to_string()
        } else {
            let program_name =
                if package_name.ends_with(".aleo") { package_name.to_string() } else { format!("{package_name}.aleo") };

            if !crate::is_valid_program_name(&program_name) {
                return Err(crate::errors::cli_invalid_package_name("program", &program_name).into());
            }

            program_name
        };

        let path = path.canonicalize().map_err(|e| crate::errors::failed_path(path.display(), e))?;
        let full_path = path.join(package_name.strip_suffix(".aleo").unwrap_or(&package_name));

        // Verify that there is no existing directory at the path.
        if full_path.exists() {
            return Err(
                crate::errors::failed_to_initialize_package(package_name, &path, "Directory already exists").into()
            );
        }

        // Create the package directory.
        std::fs::create_dir(&full_path)
            .map_err(|e| crate::errors::failed_to_initialize_package(&package_name, &full_path, e))?;

        // Change the current working directory to the package directory.
        std::env::set_current_dir(&full_path)
            .map_err(|e| crate::errors::failed_to_initialize_package(&package_name, &full_path, e))?;

        // Create .gitignore
        const GITIGNORE_TEMPLATE: &str = ".env\n*.avm\n*.prover\n*.verifier\nbuild/\n";
        const GITIGNORE_FILENAME: &str = ".gitignore";

        let gitignore_path = full_path.join(GITIGNORE_FILENAME);
        std::fs::write(gitignore_path, GITIGNORE_TEMPLATE).map_err(crate::errors::io_error_gitignore_file)?;

        // Create manifest
        let manifest = Manifest {
            program: package_name.clone(),
            version: "0.1.0".to_string(),
            description: String::new(),
            license: "MIT".to_string(),
            leo: env!("CARGO_PKG_VERSION").to_string(),
            dependencies: None,
            dev_dependencies: None,
        };

        let manifest_path = full_path.join(MANIFEST_FILENAME);
        manifest.write_to_file(manifest_path)?;

        // Create src/
        let source_path = full_path.join(SOURCE_DIRECTORY);

        std::fs::create_dir(&source_path)
            .map_err(|e| crate::errors::failed_to_create_source_directory(source_path.display(), e))?;

        let name_no_aleo = package_name.strip_suffix(".aleo").unwrap_or(&package_name);

        if is_library {
            // Create lib.leo with a placeholder function.
            let lib_path = source_path.join("lib.leo");

            std::fs::write(&lib_path, lib_template(name_no_aleo)).map_err(|e| {
                crate::errors::util_file_io_error(format_args!("Failed to write `{}`", lib_path.display()), e)
            })?;

            // Create tests directory with a starter test file.
            let tests_path = full_path.join(TESTS_DIRECTORY);

            std::fs::create_dir(&tests_path)
                .map_err(|e| crate::errors::failed_to_create_source_directory(tests_path.display(), e))?;

            let test_file_path = tests_path.join(format!("test_{name_no_aleo}.leo"));

            std::fs::write(&test_file_path, lib_test_template(name_no_aleo)).map_err(|e| {
                crate::errors::util_file_io_error(format_args!("Failed to write `{}`", test_file_path.display()), e)
            })?;
        } else {
            // Create main.leo
            let main_path = source_path.join(MAIN_FILENAME);

            std::fs::write(&main_path, main_template(name_no_aleo)).map_err(|e| {
                crate::errors::util_file_io_error(format_args!("Failed to write `{}`", main_path.display()), e)
            })?;

            // Create tests directory
            let tests_path = full_path.join(TESTS_DIRECTORY);

            std::fs::create_dir(&tests_path)
                .map_err(|e| crate::errors::failed_to_create_source_directory(tests_path.display(), e))?;

            let test_file_path = tests_path.join(format!("test_{name_no_aleo}.leo"));

            std::fs::write(&test_file_path, test_template(name_no_aleo)).map_err(|e| {
                crate::errors::util_file_io_error(format_args!("Failed to write `{}`", test_file_path.display()), e)
            })?;
        }

        Ok(full_path)
    }

    /// Examine the Leo package at `path` to create a `Package`, but don't find dependencies.
    ///
    /// This may be useful if you just need other information like the manifest file.
    pub fn from_directory_no_graph<P: AsRef<Path>, Q: AsRef<Path>>(
        path: P,
        home_path: Q,
        network: Option<NetworkName>,
        endpoint: Option<&str>,
        network_retries: u32,
    ) -> Result<Self> {
        Self::from_directory_impl(
            path.as_ref(),
            home_path.as_ref(),
            /* build_graph */ false,
            /* with_tests */ false,
            /* no_cache */ false,
            /* no_local */ false,
            network,
            endpoint,
            network_retries,
        )
    }

    /// Examine the Leo package at `path` to create a `Package`, including all its dependencies,
    /// obtaining dependencies from the file system or network and topologically sorting them.
    pub fn from_directory<P: AsRef<Path>, Q: AsRef<Path>>(
        path: P,
        home_path: Q,
        no_cache: bool,
        no_local: bool,
        network: Option<NetworkName>,
        endpoint: Option<&str>,
        network_retries: u32,
    ) -> Result<Self> {
        Self::from_directory_impl(
            path.as_ref(),
            home_path.as_ref(),
            /* build_graph */ true,
            /* with_tests */ false,
            no_cache,
            no_local,
            network,
            endpoint,
            network_retries,
        )
    }

    /// Examine the Leo package at `path` to create a `Package`, including all its dependencies
    /// and its tests, obtaining dependencies from the file system or network and topologically sorting them.
    pub fn from_directory_with_tests<P: AsRef<Path>, Q: AsRef<Path>>(
        path: P,
        home_path: Q,
        no_cache: bool,
        no_local: bool,
        network: Option<NetworkName>,
        endpoint: Option<&str>,
        network_retries: u32,
    ) -> Result<Self> {
        Self::from_directory_impl(
            path.as_ref(),
            home_path.as_ref(),
            /* build_graph */ true,
            /* with_tests */ true,
            no_cache,
            no_local,
            network,
            endpoint,
            network_retries,
        )
    }

    pub fn test_files(&self) -> impl Iterator<Item = PathBuf> {
        let path = self.tests_directory();
        // This allocation isn't ideal but it's not performance critical and
        // easily resolves lifetime issues.
        let data: Vec<PathBuf> = Self::files_with_extension(&path, "leo").collect();
        data.into_iter()
    }

    fn files_with_extension(path: &Path, extension: &'static str) -> impl Iterator<Item = PathBuf> {
        path.read_dir()
            .ok()
            .into_iter()
            .flatten()
            .flat_map(|maybe_filename| maybe_filename.ok())
            .filter(|entry| entry.file_type().ok().map(|filetype| filetype.is_file()).unwrap_or(false))
            .flat_map(move |entry| {
                let path = entry.path();
                if path.extension().is_some_and(|e| e == extension) { Some(path) } else { None }
            })
    }

    #[allow(clippy::too_many_arguments)]
    fn from_directory_impl(
        path: &Path,
        home_path: &Path,
        build_graph: bool,
        with_tests: bool,
        no_cache: bool,
        no_local: bool,
        network: Option<NetworkName>,
        endpoint: Option<&str>,
        network_retries: u32,
    ) -> Result<Self> {
        let map_err = |path: &Path, err| {
            crate::errors::util_file_io_error(format_args!("Trying to find path at {}", path.display()), err)
        };

        let path = path.canonicalize().map_err(|err| map_err(path, err))?;

        let manifest = Manifest::read_from_file(path.join(MANIFEST_FILENAME))?;

        let (compilation_units, digraph) = if build_graph {
            let home_path = home_path.canonicalize().map_err(|err| map_err(home_path, err))?;

            let mut map: IndexMap<Symbol, (Dependency, CompilationUnit)> = IndexMap::new();

            let mut digraph = DiGraph::<Symbol>::new(Default::default());

            // Pre-collect all declared dependencies from the manifest tree so that
            // .aleo file import classification doesn't depend on processing order.
            let declared_deps = collect_declared_deps(&path, &manifest, with_tests)?;

            let first_dependency = Dependency {
                name: manifest.program.clone(),
                location: Location::Local,
                path: Some(path.clone()),
                edition: None,
            };

            let test_dependencies: Vec<Dependency> = if with_tests {
                let tests_directory = path.join(TESTS_DIRECTORY);
                let mut test_dependencies: Vec<Dependency> = Self::files_with_extension(&tests_directory, "leo")
                    .map(|path| Dependency {
                        // We just made sure it has a ".leo" extension.
                        name: format!("{}.aleo", crate::filename_no_leo_extension(&path).unwrap()),
                        edition: None,
                        location: Location::Test,
                        path: Some(path.to_path_buf()),
                    })
                    .collect();
                if let Some(deps) = manifest.dev_dependencies.as_ref() {
                    test_dependencies.extend(deps.iter().cloned());
                }
                test_dependencies
            } else {
                Vec::new()
            };

            for dependency in test_dependencies.into_iter().chain(std::iter::once(first_dependency.clone())) {
                Self::graph_build(
                    &home_path,
                    network,
                    endpoint,
                    &first_dependency,
                    dependency,
                    &mut map,
                    &mut digraph,
                    no_cache,
                    no_local,
                    network_retries,
                    &declared_deps,
                )?;
            }

            let ordered_dependency_symbols =
                digraph.post_order().map_err(|_| crate::errors::circular_dependency_error())?;

            (
                ordered_dependency_symbols.into_iter().map(|symbol| map.swap_remove(&symbol).unwrap().1).collect(),
                digraph,
            )
        } else {
            (Vec::new(), DiGraph::default())
        };

        Ok(Package { base_directory: path, compilation_units, manifest, dep_graph: digraph })
    }

    #[allow(clippy::too_many_arguments)]
    fn graph_build(
        home_path: &Path,
        network: Option<NetworkName>,
        endpoint: Option<&str>,
        main_program: &Dependency,
        new: Dependency,
        map: &mut IndexMap<Symbol, (Dependency, CompilationUnit)>,
        graph: &mut DiGraph<Symbol>,
        no_cache: bool,
        no_local: bool,
        network_retries: u32,
        declared_deps: &IndexMap<Symbol, Dependency>,
    ) -> Result<()> {
        let name_symbol = symbol(&new.name)?;

        let unit = match map.entry(name_symbol) {
            Entry::Occupied(occupied) => {
                // We've already visited this dependency. Just make sure it's compatible with
                // the one we already have.
                let existing_dep = &occupied.get().0;
                assert_eq!(new.name, existing_dep.name);
                if new.location != existing_dep.location
                    || new.path != existing_dep.path
                    || new.edition != existing_dep.edition
                {
                    return Err(crate::errors::conflicting_dependency(existing_dep, new).into());
                }
                return Ok(());
            }
            Entry::Vacant(vacant) => {
                let unit = match (new.path.as_ref(), new.location) {
                    (Some(path), Location::Local) if !no_local => {
                        // It's a local dependency.
                        if path.extension().and_then(|p| p.to_str()) == Some("aleo") && path.is_file() {
                            CompilationUnit::from_aleo_path(name_symbol, path, declared_deps)?
                        } else {
                            CompilationUnit::from_package_path(name_symbol, path)?
                        }
                    }
                    (Some(path), Location::Test) => {
                        // It's a test dependency - the path points to the source file,
                        // not a package.
                        CompilationUnit::from_test_path(path, main_program.clone())?
                    }
                    (_, Location::Network) | (Some(_), Location::Local) => {
                        // It's a network dependency.
                        let Some(endpoint) = endpoint else {
                            return Err(anyhow!("An endpoint must be provided to fetch network dependencies.").into());
                        };
                        let Some(network) = network else {
                            return Err(anyhow!("A network must be provided to fetch network dependencies.").into());
                        };
                        CompilationUnit::fetch(
                            name_symbol,
                            new.edition,
                            home_path,
                            network,
                            endpoint,
                            no_cache,
                            network_retries,
                        )?
                    }
                    (_, Location::Workspace) => {
                        return Err(anyhow!(
                            "Workspace dependency `{}` was not resolved before graph building. This is a compiler bug.",
                            new.name
                        )
                        .into());
                    }
                    _ => return Err(anyhow!("Invalid dependency data for {} (path must be given).", new.name).into()),
                };

                vacant.insert((new, unit.clone()));

                unit
            }
        };

        graph.add_node(name_symbol);

        for dependency in unit.dependencies.iter() {
            let dependency_symbol = symbol(&dependency.name)?;
            graph.add_edge(name_symbol, dependency_symbol);
            Self::graph_build(
                home_path,
                network,
                endpoint,
                main_program,
                dependency.clone(),
                map,
                graph,
                no_cache,
                no_local,
                network_retries,
                declared_deps,
            )?;
        }

        Ok(())
    }
}

fn main_template(name: &str) -> String {
    format!(
        r#"// The '{name}' program.
program {name}.aleo {{
    // This is the constructor for the program.
    // The constructor allows you to manage program upgrades.
    // It is called when the program is deployed or upgraded.
    // It is currently configured to **prevent** upgrades.
    // Other configurations include:
    //  - @admin(address="aleo1...")
    //  - @checksum(mapping="credits.aleo/fixme", key="0field")
    //  - @custom
    // For more information, please refer to the documentation: `https://docs.leo-lang.org/guides/upgradability`
    @noupgrade
    constructor() {{}}

    fn main(public a: u32, b: u32) -> u32 {{
        let c: u32 = a + b;
        return c;
    }}
}}
"#
    )
}

fn test_template(name: &str) -> String {
    format!(
        r#"// The 'test_{name}' test program.
import {name}.aleo;
program test_{name}.aleo {{
    @test
    @should_fail
    fn test_main_fails() {{
        let result: u32 = {name}.aleo::main(2u32, 3u32);
        assert_eq(result, 3u32);
    }}

    @noupgrade
    constructor() {{}}
}}
"#
    )
}

fn lib_template(name: &str) -> String {
    format!(
        r#"// The '{name}' library.

// Returns the identity of x.
fn example(x: u32) -> u32 {{
    return x;
}}
"#
    )
}

fn lib_test_template(name: &str) -> String {
    format!(
        r#"// The 'test_{name}' test program.
program test_{name}.aleo {{
    @test
    fn test_example() {{
        assert_eq({name}::example(42u32), 42u32);
    }}

    @noupgrade
    constructor() {{}}
}}
"#
    )
}

/// Walk the manifest tree and collect all declared dependencies.
///
/// This gives `parse_dependencies_from_aleo` full knowledge of which programs are
/// declared as local dependencies, regardless of the order they appear in the manifest.
/// Without this, `.aleo` file imports are classified against a snapshot of
/// already-processed dependencies, requiring the user to list them in topological order.
fn collect_declared_deps(
    root_path: &Path,
    manifest: &Manifest,
    with_tests: bool,
) -> Result<IndexMap<Symbol, Dependency>> {
    let mut declared = IndexMap::new();
    collect_declared_deps_recursive(root_path, manifest, with_tests, &mut declared)?;
    Ok(declared)
}

fn collect_declared_deps_recursive(
    base_path: &Path,
    manifest: &Manifest,
    include_dev: bool,
    declared: &mut IndexMap<Symbol, Dependency>,
) -> Result<()> {
    let deps = manifest.dependencies.iter().flatten();
    let dev: Vec<&Dependency> =
        if include_dev { manifest.dev_dependencies.iter().flatten().collect() } else { Vec::new() };
    for dep in deps.chain(dev) {
        let dep = canonicalize_dependency_path_relative_to(base_path, dep.clone())?;
        // Resolve workspace deps early - converts to Location::Local with an absolute path.
        let dep = if dep.location == Location::Workspace { resolve_workspace_dependency(base_path, dep)? } else { dep };
        let sym = symbol(&dep.name)?;
        // Only recurse into newly discovered dependencies to avoid infinite
        // recursion on circular manifests (cycles are caught later by
        // `DiGraph::post_order`).
        let Entry::Vacant(e) = declared.entry(sym) else {
            continue;
        };
        e.insert(dep.clone());
        if dep.location == Location::Local
            && let Some(path) = &dep.path
        {
            let manifest_path = path.join(MANIFEST_FILENAME);
            if path.is_dir() && manifest_path.exists() {
                let child = Manifest::read_from_file(manifest_path)?;
                // dev_dependencies are not transitive.
                collect_declared_deps_recursive(path, &child, false, declared)?;
            }
        }
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    fn dummy_package(base: &str) -> Package {
        Package {
            base_directory: PathBuf::from(base),
            compilation_units: Vec::new(),
            manifest: Manifest {
                program: "demo.aleo".to_string(),
                version: "0.1.0".to_string(),
                description: String::new(),
                license: "MIT".to_string(),
                leo: "0.0.0".to_string(),
                dependencies: None,
                dev_dependencies: None,
            },
            dep_graph: DiGraph::default(),
        }
    }

    #[test]
    fn bare_unit_name_strips_aleo_suffix() {
        assert_eq!(crate::bare_unit_name("token.aleo"), "token");
        assert_eq!(crate::bare_unit_name("token"), "token");
        assert_eq!(crate::bare_unit_name("credits.aleo"), "credits");
    }

    #[test]
    fn unit_paths_are_keyed_by_bare_name() {
        let pkg = dummy_package("/tmp/demo");
        // The directory key is the bare compilation unit name, accepting input
        // with or without the `.aleo` suffix.
        assert_eq!(pkg.unit_build_directory("token.aleo"), PathBuf::from("/tmp/demo/build/token"));
        assert_eq!(pkg.unit_build_directory("token"), PathBuf::from("/tmp/demo/build/token"));
        assert_eq!(pkg.unit_bytecode_path("token.aleo"), PathBuf::from("/tmp/demo/build/token/token.aleo"));
        assert_eq!(pkg.unit_abi_path("token"), PathBuf::from("/tmp/demo/build/token/abi.json"));
        assert_eq!(pkg.unit_interfaces_directory("token"), PathBuf::from("/tmp/demo/build/token/interfaces"));
        assert_eq!(pkg.unit_snapshots_directory("token"), PathBuf::from("/tmp/demo/build/token/snapshots"));
    }

    #[test]
    fn libraries_are_keyed_like_programs() {
        // A library is keyed by its name exactly like a program: a library
        // `my_lib` declaring interfaces gets `build/my_lib/interfaces/`.
        let pkg = dummy_package("/tmp/demo");
        assert_eq!(pkg.unit_build_directory("my_lib"), PathBuf::from("/tmp/demo/build/my_lib"));
        assert_eq!(pkg.unit_interfaces_directory("my_lib"), PathBuf::from("/tmp/demo/build/my_lib/interfaces"));
    }

    #[test]
    fn build_directory_is_the_single_root() {
        let pkg = dummy_package("/tmp/demo");
        assert_eq!(pkg.build_directory(), PathBuf::from("/tmp/demo/build"));
        // Every per-unit path is rooted at `build_directory()`, the single layout seam.
        assert!(pkg.unit_bytecode_path("x").starts_with(pkg.build_directory()));
        assert!(pkg.unit_interfaces_directory("credits.aleo").starts_with(pkg.build_directory()));
    }
}