Add Leo Library Support - Part 1 (#29196)

* Library packages with consts only. Part 1.

* Address review comments

---------

Co-authored-by: Mohammad Fawaz <mohammadfawaz@gmail.com>

Author: mohammadfawaz

crates/abi/src/lib.rs

@@ -248,6 +248,8 @@ fn is_record(comp_ty: &ast::CompositeType, ctx: &Ctx) -> bool {
                 .flat_map(|scope| scope.composites.iter())
                 .find(|(sym, _)| *sym == name)
                 .map(|(_, c)| c.is_record),
+
+            ast::Stub::FromLibrary { .. } => None,
         };
         if let Some(is_record) = found {
             return is_record;
@@ -288,7 +290,7 @@ pub fn prune_non_interface_types(program: &mut abi::Program) {
     let mut used_types: HashSet<abi::Path> = HashSet::new();
 
     // Extract program name without .aleo suffix for comparison
-    let program_name = program.program.strip_suffix(".aleo").unwrap_or(&program.program);
+    let program_name = &program.program;
 
     // Phase 1: Collect from interface items
     for transition in &program.transitions {

crates/ast/src/common/location.rs

@@ -13,6 +13,7 @@
 
 // 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::ProgramId;
 
 use itertools::Itertools;
 use leo_span::Symbol;
@@ -22,8 +23,7 @@ use std::fmt::Display;
 
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Location {
-    /// The program name. e.g. `credits`.
-    /// Note. This does not include the `.aleo` network suffix.
+    /// The program name. e.g. `credits.aleo` or `my_library`.
     pub program: Symbol,
     /// The absolute path to the item that this `Location` points to.
     pub path: Vec<Symbol>,
@@ -37,14 +37,14 @@ impl Location {
 
 impl Display for Location {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{}.aleo/{}", self.program, self.path.iter().format("::"))
+        write!(f, "{}/{}", self.program, self.path.iter().format("::"))
     }
 }
 
 impl<N: Network> From<Locator<N>> for Location {
     fn from(locator: Locator<N>) -> Self {
         Location {
-            program: Symbol::intern(&locator.program_id().name().to_string()),
+            program: ProgramId::from(locator.program_id()).as_symbol(),
             path: vec![Symbol::intern(&locator.resource().to_string())],
         }
     }

crates/ast/src/common/mod.rs

@@ -35,6 +35,9 @@ pub use path::*;
 mod positive_number;
 pub use positive_number::*;
 
+mod program_id;
+pub use program_id::*;
+
 mod network_name;
 pub use network_name::*;
 

crates/ast/src/common/path.rs

@@ -14,10 +14,11 @@
 // 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::{Expression, Identifier, Location, Node, NodeID, simple_node_impl};
+use crate::{Expression, Identifier, Location, Node, NodeID, ProgramId, simple_node_impl};
 
 use leo_span::{Span, Symbol};
 
+use indexmap::IndexSet;
 use itertools::Itertools;
 use serde::{Deserialize, Serialize};
 use std::{fmt, hash::Hash};
@@ -26,7 +27,7 @@ use std::{fmt, hash::Hash};
 #[derive(Clone, Hash, Eq, PartialEq, Serialize, Deserialize)]
 pub struct Path {
     /// The program this path belongs to, if set by the user
-    user_program: Option<Identifier>,
+    user_program: Option<ProgramId>,
 
     /// The qualifying namespace segments written by the user, excluding the item itself.
     /// e.g., in `foo::bar::baz`, this would be `[foo, bar]`.
@@ -63,7 +64,7 @@ impl Path {
     /// - `span`: The source code span for this path.
     /// - `id`: The node ID.
     pub fn new(
-        user_program: Option<Identifier>,
+        user_program: Option<ProgramId>,
         qualifier: Vec<Identifier>,
         identifier: Identifier,
         span: Span,
@@ -93,12 +94,12 @@ impl Path {
     }
 
     /// Returns the optional program identifier.
-    pub fn user_program(&self) -> Option<&Identifier> {
+    pub fn user_program(&self) -> Option<&ProgramId> {
         self.user_program.as_ref()
     }
 
     /// Returns `self` after setting it `user_program` field to `user_program`.
-    pub fn with_user_program(mut self, user_program: Identifier) -> Self {
+    pub fn with_user_program(mut self, user_program: ProgramId) -> Self {
         self.user_program = Some(user_program);
         self
     }
@@ -131,7 +132,7 @@ impl Path {
     /// 3. None (unresolved or local)
     pub fn program(&self) -> Option<Symbol> {
         if let Some(id) = &self.user_program {
-            return Some(id.name);
+            return Some(id.as_symbol());
         }
 
         match &self.target {
@@ -215,35 +216,79 @@ impl Path {
         Self { user_program, qualifier, identifier, target, span, id }
     }
 
-    /// Resolves this path as a global path using the current module context.
+    /// Resolves this path as a global path within the current module context.
     ///
-    /// This method constructs an absolute global `Location` by combining:
-    ///   1) the current module path,
-    ///   2) any user-written qualifier segments, and
-    ///   3) the final identifier.
+    /// This function converts a user-written path into a fully qualified
+    /// [`PathTarget::Global`] by determining which program the path belongs to
+    /// and constructing the corresponding module path.
     ///
-    /// The resolution only affects the `target` field and preserves
-    /// the original user-written syntax of the path.
-    pub fn resolve_as_global_in_module<I>(self, program: Symbol, current_module: I) -> Self
+    /// Resolution follows two main cases:
+    ///
+    /// 1. **External library access**
+    ///    If the path does not explicitly specify a program (`user_program` is `None`)
+    ///    and the first qualifier segment matches a known external library name,
+    ///    that segment is interpreted as the target program. The remaining qualifier
+    ///    segments and identifier form the path inside that program.
+    ///
+    /// 2. **Local or explicitly-qualified program access**
+    ///    Otherwise, the path is resolved relative to the current module context.
+    ///    The final location is constructed by combining:
+    ///      - the current module path,
+    ///      - any user-written qualifier segments, and
+    ///      - the final identifier.
+    ///
+    /// If the user explicitly wrote a program (via `user_program`), it overrides
+    /// the default `program` parameter. Otherwise, the current program is used.
+    ///
+    /// Importantly, this transformation **does not modify the user-written syntax**
+    /// (`user_program`, `qualifier`, `identifier`). It only determines the internal
+    /// `target` used during later compilation stages.
+    pub fn resolve_as_global_in_module<I>(
+        self,
+        program: Symbol,
+        external_libs: &IndexSet<Symbol>,
+        current_module: I,
+    ) -> Self
     where
         I: IntoIterator<Item = Symbol>,
     {
         let Path { user_program, qualifier, identifier, span, id, .. } = self;
 
-        let mut path: Vec<Symbol> = Vec::new();
-
-        // 1. Current module
-        path.extend(current_module);
-
-        // 2. User-written qualifier
-        path.extend(qualifier.iter().map(|id| id.name));
-
-        // 3. Final identifier
-        path.push(identifier.name);
-
-        let target = PathTarget::Global(Location { program: user_program.map(|id| id.name).unwrap_or(program), path });
-
-        Self { user_program, qualifier, identifier, target, span, id }
+        // Case 1: The path starts with a known external library name and the user
+        // did not explicitly specify a program. In this situation we interpret
+        // the first qualifier segment as the program name.
+        if let Some(first) = qualifier.first()
+            && user_program.is_none()
+            && external_libs.contains(&first.name)
+        {
+            // Build the path within the external library by skipping the
+            // first qualifier (the library name itself).
+            let mut path: Vec<Symbol> = qualifier.iter().skip(1).map(|id| id.name).collect();
+            path.push(identifier.name);
+
+            let target = PathTarget::Global(Location { program: first.name, path });
+
+            Self { user_program: None, qualifier, identifier, target, span, id }
+        } else {
+            // Case 2: Resolve relative to the current module.
+            //
+            // Construct the path by concatenating:
+            //   current_module + user qualifier + identifier.
+            let mut path: Vec<Symbol> = Vec::new();
+            path.extend(current_module);
+            path.extend(qualifier.iter().map(|id| id.name));
+            path.push(identifier.name);
+
+            // Determine which program this location belongs to:
+            //   - use the explicitly written program if provided
+            //   - otherwise fall back to the current program.
+            let target = PathTarget::Global(Location {
+                program: user_program.map(|id| id.as_symbol()).unwrap_or(program),
+                path,
+            });
+
+            Self { user_program, qualifier, identifier, target, span, id }
+        }
     }
 }
 
@@ -253,12 +298,12 @@ impl fmt::Display for Path {
         let program: Option<Symbol> = self
             .user_program
             .as_ref()
-            .map(|id| id.name) // Convert Identifier -> Symbol
+            .map(|id| id.as_symbol()) // Convert Identifier -> Symbol
             .or_else(|| self.try_global_location().map(|global| global.program));
 
         // Program prefix
         if let Some(program) = program {
-            write!(f, "{}.aleo/", program)?;
+            write!(f, "{}/", program)?;
         }
 
         // Qualifiers

crates/ast/src/program/program_id.rs crates/ast/src/common/program_id.rscrates/ast/src/program/program_id.rs renamed to crates/ast/src/common/program_id.rs

@@ -17,7 +17,7 @@
 use crate::{Identifier, NetworkName};
 
 use core::fmt;
-use leo_span::Symbol;
+use leo_span::{Span, Symbol};
 use serde::{Deserialize, Serialize};
 use snarkvm::{
     console::program::ProgramID,
@@ -35,6 +35,14 @@ pub struct ProgramId {
 }
 
 impl ProgramId {
+    pub fn span(&self) -> Span {
+        Span::new(self.name.span.lo, self.network.span.hi)
+    }
+
+    pub fn as_symbol(&self) -> Symbol {
+        Symbol::intern(&self.to_string())
+    }
+
     /// Initializes a new `ProgramId` from a string, using a network parameter to validate using snarkVM.
     pub fn from_str_with_network(string: &str, network: NetworkName) -> Result<Self> {
         match network {

crates/ast/src/composite/mod.rs

@@ -17,7 +17,7 @@
 pub mod member;
 pub use member::*;
 
-use crate::{ConstParameter, Identifier, Indent, Mode, Node, NodeID, Type};
+use crate::{ConstParameter, Identifier, Indent, Mode, Node, NodeID, ProgramId, Type};
 use leo_span::{Span, Symbol};
 
 use itertools::Itertools;
@@ -68,7 +68,7 @@ impl Composite {
         self.identifier.name
     }
 
-    pub fn from_external_record<N: Network>(input: &RecordType<N>, program: Symbol) -> Self {
+    pub fn from_external_record<N: Network>(input: &RecordType<N>, program_id: ProgramId) -> Self {
         let mut members = Vec::with_capacity(input.entries().len() + 1);
         members.push(Member {
             mode: if input.owner().is_private() { Mode::Public } else { Mode::Private },
@@ -81,9 +81,9 @@ impl Composite {
             mode: if input.owner().is_public() { Mode::Public } else { Mode::Private },
             identifier: Identifier::from(id),
             type_: match entry {
-                Public(t) => Type::from_snarkvm(t, program),
-                Private(t) => Type::from_snarkvm(t, program),
-                Constant(t) => Type::from_snarkvm(t, program),
+                Public(t) => Type::from_snarkvm(t, program_id),
+                Private(t) => Type::from_snarkvm(t, program_id),
+                Constant(t) => Type::from_snarkvm(t, program_id),
             },
             span: Default::default(),
             id: Default::default(),
@@ -98,7 +98,7 @@ impl Composite {
         }
     }
 
-    pub fn from_snarkvm<N: Network>(input: &StructType<N>, program: Symbol) -> Self {
+    pub fn from_snarkvm<N: Network>(input: &StructType<N>, program: ProgramId) -> Self {
         Self {
             identifier: Identifier::from(input.name()),
             const_parameters: Vec::new(),