Add EnvironmentLoader filling an Environment from its sources

The core root, then the libraries, then the plain directories are
walked in that order, each .rbs file parsed once with the first
registration winning, and one Source appended per file.

It resolves nothing: add_library takes a directory that already holds
the library's RBS files, and manifest.yaml dependencies are not
expanded -- which is also why loading core does not implicitly add
stringio. load returns what this call read, so a caller loading into a
non-empty environment learns what it added, the one question
env.sources() cannot answer.

parse_one takes only the interners so the loop can later be
parallelised per worker; SignatureNode is not Send and must not escape
it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dak2

rust/ruby-rbs/src/environment/mod.rs

@@ -3,6 +3,7 @@ pub mod source;
 pub use source::{Source, SourceKind};
 
 use crate::interners::Interners;
+use crate::loader::{EnvironmentLoader, LoadError};
 
 /// Owning the interners here gives a single `Environment` value the same
 /// role as the Ruby implementation's global name pool: names interned while
@@ -34,6 +35,12 @@ impl Environment {
     pub(crate) fn add_source(&mut self, source: Source) {
         self.sources.push(source);
     }
+
+    pub fn from_loader(loader: &EnvironmentLoader) -> Result<Environment, LoadError> {
+        let mut env = Environment::new();
+        loader.load(&mut env)?;
+        Ok(env)
+    }
 }
 
 #[cfg(test)]

rust/ruby-rbs/src/lib.rs

@@ -4,5 +4,6 @@ pub(crate) mod file_finder;
 pub mod ids;
 pub mod interner;
 pub mod interners;
+pub mod loader;
 pub mod node;
 pub mod type_name;

rust/ruby-rbs/src/loader/mod.rs

@@ -0,0 +1,172 @@
+use std::collections::HashSet;
+use std::fmt;
+use std::io;
+use std::path::{Path, PathBuf};
+
+use crate::ast::AstConverter;
+use crate::environment::{Environment, Source, SourceKind};
+use crate::file_finder;
+use crate::interners::Interners;
+use crate::node;
+
+#[derive(Debug)]
+#[non_exhaustive]
+pub enum LoadError {
+    Io { path: PathBuf, source: io::Error },
+    Parse { path: PathBuf, message: String },
+}
+
+impl fmt::Display for LoadError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            LoadError::Io { path, source } => {
+                write!(f, "IO error on {}: {}", path.display(), source)
+            }
+            LoadError::Parse { path, message } => {
+                write!(f, "Syntax error in {}: {}", path.display(), message)
+            }
+        }
+    }
+}
+
+impl std::error::Error for LoadError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            LoadError::Io { source, .. } => Some(source),
+            _ => None,
+        }
+    }
+}
+
+/// Corresponds to one entry of the array `RBS::EnvironmentLoader#load`
+/// returns, at file rather than declaration granularity.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LoadedFile {
+    pub path: PathBuf,
+    pub kind: SourceKind,
+}
+
+/// Mirrors `RBS::EnvironmentLoader`.
+///
+/// Unlike the Ruby implementation, this does not resolve gem names or
+/// versions to directories, and does not expand `manifest.yaml`
+/// dependencies: callers (Ruby's `Repository#lookup` / `gem_sig_path`) pass
+/// already-resolved paths to [`EnvironmentLoader::add_library`]. Loading
+/// core does not implicitly add `stringio` either — that dependency is the
+/// caller's responsibility, same as any other library.
+pub struct EnvironmentLoader {
+    core_root: Option<PathBuf>,
+    libs: Vec<(String, PathBuf)>,
+    dirs: Vec<PathBuf>,
+}
+
+impl EnvironmentLoader {
+    pub fn new(core_root: Option<PathBuf>) -> Self {
+        EnvironmentLoader {
+            core_root,
+            libs: Vec::new(),
+            dirs: Vec::new(),
+        }
+    }
+
+    pub fn add_library(mut self, name: &str, path: PathBuf) -> Self {
+        self.libs.push((name.to_string(), path));
+        self
+    }
+
+    pub fn add_dir(mut self, path: PathBuf) -> Self {
+        self.dirs.push(path);
+        self
+    }
+
+    /// Returns what this call read, in the order it read it, so a caller
+    /// appending to a non-empty `env` still learns what it added. On `Err` the
+    /// sources read before the failure are already in `env`, same as the Ruby
+    /// implementation adding sources as it walks the directories.
+    pub fn load(&self, env: &mut Environment) -> Result<Vec<LoadedFile>, LoadError> {
+        let mut loaded = Vec::new();
+        let mut seen_files: HashSet<PathBuf> = HashSet::new();
+
+        for (kind, dir) in self.each_dir() {
+            let files = file_finder::each_file(dir, kind.skips_hidden()).map_err(|source| {
+                LoadError::Io {
+                    path: dir.to_path_buf(),
+                    source,
+                }
+            })?;
+
+            for path in files {
+                if !seen_files.insert(path.clone()) {
+                    continue;
+                }
+                let source = parse_one(&path, &kind, env.interners_mut())?;
+                env.add_source(source);
+                loaded.push(LoadedFile {
+                    path,
+                    kind: kind.clone(),
+                });
+            }
+        }
+
+        Ok(loaded)
+    }
+
+    fn each_dir(&self) -> impl Iterator<Item = (SourceKind, &Path)> {
+        let core = self
+            .core_root
+            .iter()
+            .map(|path| (SourceKind::Core, path.as_path()));
+        let libs = self.libs.iter().map(|(name, path)| {
+            let kind = SourceKind::Library {
+                name: name.clone(),
+                path: path.clone(),
+            };
+            (kind, path.as_path())
+        });
+        let dirs = self
+            .dirs
+            .iter()
+            .map(|path| (SourceKind::Dir { path: path.clone() }, path.as_path()));
+
+        core.chain(libs).chain(dirs)
+    }
+}
+
+/// Deliberately a free function taking only the interners, so the load loop
+/// can later be parallelised by handing each worker its own [`Interners`].
+/// The parser's `SignatureNode` holds raw pointers and is not `Send`, so it
+/// must not escape this function — only the owned `Source` does.
+pub(crate) fn parse_one(
+    path: &Path,
+    kind: &SourceKind,
+    interners: &mut Interners,
+) -> Result<Source, LoadError> {
+    let content = std::fs::read_to_string(path).map_err(|source| LoadError::Io {
+        path: path.to_path_buf(),
+        source,
+    })?;
+
+    let signature = node::parse(&content).map_err(|message| LoadError::Parse {
+        path: path.to_path_buf(),
+        message,
+    })?;
+
+    let mut converter = AstConverter::new(&mut interners.strings, &mut interners.type_names);
+    let directives = signature
+        .directives()
+        .iter()
+        .map(|node| converter.convert_directive(&node))
+        .collect();
+    let declarations = signature
+        .declarations()
+        .iter()
+        .map(|node| converter.convert_declaration(&node))
+        .collect();
+
+    Ok(Source {
+        path: path.to_path_buf(),
+        directives,
+        declarations,
+        kind: kind.clone(),
+    })
+}

rust/ruby-rbs/tests/loader.rs

@@ -0,0 +1,182 @@
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use ruby_rbs::ast::{Declaration, Directive};
+use ruby_rbs::environment::{Environment, SourceKind};
+use ruby_rbs::loader::{EnvironmentLoader, LoadError};
+
+fn repo_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("../..")
+}
+
+fn stdlib_dir(name: &str) -> PathBuf {
+    repo_root().join("stdlib").join(name).join("0")
+}
+
+fn lib(name: &str) -> SourceKind {
+    SourceKind::Library {
+        name: name.to_string(),
+        path: stdlib_dir(name),
+    }
+}
+
+fn tree(files: &[(&str, &str)]) -> tempfile::TempDir {
+    let dir = tempfile::tempdir().unwrap();
+    for (path, content) in files {
+        let path = dir.path().join(path);
+        fs::create_dir_all(path.parent().unwrap()).unwrap();
+        fs::write(path, content).unwrap();
+    }
+    dir
+}
+
+#[test]
+fn loads_registered_sources_in_registration_order() {
+    let loader = EnvironmentLoader::new(Some(repo_root().join("core")))
+        .add_library("bigdecimal-math", stdlib_dir("bigdecimal-math"))
+        .add_library("bigdecimal", stdlib_dir("bigdecimal"));
+
+    let mut env = Environment::new();
+    let loaded = loader.load(&mut env).unwrap();
+
+    assert_eq!(loaded.first().unwrap().kind, SourceKind::Core);
+    let first_math = loaded
+        .iter()
+        .position(|f| f.kind == lib("bigdecimal-math"))
+        .unwrap();
+    let first_dep = loaded
+        .iter()
+        .position(|f| f.kind == lib("bigdecimal"))
+        .unwrap();
+    assert!(first_math < first_dep);
+    assert_eq!(env.sources().len(), loaded.len());
+    assert!(!env.interners().strings.is_empty());
+}
+
+#[test]
+fn from_loader_is_the_primary_entry_point() {
+    let dir = tree(&[("a.rbs", "class Foo\nend\n")]);
+
+    let loader = EnvironmentLoader::new(None).add_dir(dir.path().to_path_buf());
+    let env = Environment::from_loader(&loader).unwrap();
+
+    assert_eq!(env.sources().len(), 1);
+}
+
+#[test]
+fn files_are_loaded_once_first_wins() {
+    let dir = tree(&[("a.rbs", "class Foo\nend\n")]);
+
+    let loader = EnvironmentLoader::new(None)
+        .add_dir(dir.path().to_path_buf())
+        .add_dir(dir.path().to_path_buf());
+
+    let mut env = Environment::new();
+    let loaded = loader.load(&mut env).unwrap();
+
+    assert_eq!(loaded.len(), 1);
+    assert_eq!(env.sources().len(), 1);
+}
+
+#[test]
+fn load_reports_only_what_this_call_added() {
+    let first = tree(&[("a.rbs", "class Foo\nend\n")]);
+    let second = tree(&[("b.rbs", "class Bar\nend\n")]);
+
+    let mut env = Environment::new();
+    EnvironmentLoader::new(None)
+        .add_dir(first.path().to_path_buf())
+        .load(&mut env)
+        .unwrap();
+    let loaded = EnvironmentLoader::new(None)
+        .add_dir(second.path().to_path_buf())
+        .load(&mut env)
+        .unwrap();
+
+    assert_eq!(env.sources().len(), 2);
+    let [only] = loaded.as_slice() else {
+        panic!("expected one loaded file, got {loaded:?}");
+    };
+    assert!(only.path.ends_with("b.rbs"));
+}
+
+#[test]
+fn explicit_dirs_do_not_skip_underscore_directories() {
+    let dir = tree(&[("_private/a.rbs", "class Foo\nend\n")]);
+
+    let loader = EnvironmentLoader::new(None).add_dir(dir.path().to_path_buf());
+
+    let mut env = Environment::new();
+    let loaded = loader.load(&mut env).unwrap();
+
+    assert_eq!(loaded.len(), 1);
+}
+
+#[test]
+fn parse_errors_carry_the_file_path() {
+    let dir = tree(&[("broken.rbs", "class\n")]);
+
+    let loader = EnvironmentLoader::new(None).add_dir(dir.path().to_path_buf());
+
+    let mut env = Environment::new();
+    let error = loader.load(&mut env).unwrap_err();
+
+    assert!(matches!(
+        error,
+        LoadError::Parse { ref path, .. } if path.ends_with("broken.rbs")
+    ));
+}
+
+#[test]
+fn loaded_sources_carry_converted_declarations_and_directives() {
+    let dir = tree(&[(
+        "person.rbs",
+        "use Foo::Bar\n\nclass Person\n  def name: () -> String\nend\n",
+    )]);
+
+    let loader = EnvironmentLoader::new(None).add_dir(dir.path().to_path_buf());
+    let env = Environment::from_loader(&loader).unwrap();
+
+    let source = &env.sources()[0];
+    assert!(source.path.ends_with("person.rbs"));
+    assert!(matches!(source.directives.as_slice(), [Directive::Use(_)]));
+
+    let [Declaration::Class(class)] = source.declarations.as_slice() else {
+        panic!(
+            "expected one class declaration, got {:?}",
+            source.declarations
+        );
+    };
+    // Names stay as written; Ruby absolutises them in `insert_rbs_decl`.
+    let interners = env.interners();
+    assert_eq!(
+        interners.type_names.display(class.name, &interners.strings),
+        "Person"
+    );
+    assert_eq!(class.members.len(), 1);
+}
+
+#[test]
+fn library_dirs_skip_underscore_directories() {
+    let dir = tree(&[
+        ("gem1/1.2.3/a.rbs", "class Person\nend\n"),
+        ("gem1/1.2.3/_private/b.rbs", "class Person::Internal\nend\n"),
+    ]);
+
+    let loader = EnvironmentLoader::new(None).add_library("gem1", dir.path().join("gem1/1.2.3"));
+
+    let mut env = Environment::new();
+    let loaded = loader.load(&mut env).unwrap();
+
+    let [only] = loaded.as_slice() else {
+        panic!("expected one loaded file, got {loaded:?}");
+    };
+    assert!(only.path.ends_with("a.rbs"));
+    assert_eq!(
+        only.kind,
+        SourceKind::Library {
+            name: "gem1".to_string(),
+            path: dir.path().join("gem1/1.2.3"),
+        }
+    );
+}