Implement package root layers with file collation support (#1152)

Branched from #1151 
Part of #1148

Author: lionel-

crates/ark/src/lsp/diagnostics.rs

@@ -170,7 +170,7 @@ pub(crate) fn generate_diagnostics(
     if let Some(SourceRoot::Package(root)) = &state.root {
         // Add symbols from `importFrom()` directives
         for import in &root.namespace.imports {
-            context.workspace_symbols.insert(import.clone());
+            context.workspace_symbols.insert(import.name.clone());
         }
 
         // Add symbols from `import()` directives

crates/oak_index/src/external.rs

@@ -2,6 +2,7 @@ use std::collections::HashMap;
 
 use biome_rowan::TextRange;
 use oak_package::library::Library;
+use oak_package::package_namespace::Namespace;
 use url::Url;
 
 use crate::semantic_index::DirectiveKind;
@@ -107,3 +108,27 @@ pub fn file_layers(file: Url, index: &SemanticIndex) -> Vec<BindingSource> {
 
     layers
 }
+
+/// Build the root layers for a package from its NAMESPACE.
+///
+/// These go at the back of every file's scope chain:
+/// - `PackageImports` from `importFrom()` directives (name → package)
+/// - `PackageExports` from `import()` directives
+pub fn package_root_layers(namespace: &Namespace) -> Vec<BindingSource> {
+    let mut layers = Vec::new();
+
+    if !namespace.imports.is_empty() {
+        let map = namespace
+            .imports
+            .iter()
+            .map(|imp| (imp.name.clone(), imp.package.clone()))
+            .collect();
+        layers.push(BindingSource::PackageImports(map));
+    }
+
+    for pkg in &namespace.package_imports {
+        layers.push(BindingSource::PackageExports(pkg.clone()));
+    }
+
+    layers
+}

crates/oak_index/tests/external.rs

@@ -7,12 +7,14 @@ use biome_rowan::TextRange;
 use biome_rowan::TextSize;
 use oak_index::builder::build;
 use oak_index::external::file_layers;
+use oak_index::external::package_root_layers;
 use oak_index::external::resolve_external_name;
 use oak_index::external::BindingSource;
 use oak_index::external::ExternalDefinition;
 use oak_package::library::Library;
 use oak_package::package::Package;
 use oak_package::package_description::Description;
+use oak_package::package_namespace::Import;
 use oak_package::package_namespace::Namespace;
 use url::Url;
 
@@ -368,11 +370,11 @@ fn test_chained_scope_predecessor_files() {
     scope.extend(file_layers(file_url("a.R"), &index_a));
 
     // Resolve from predecessor file b
+    // Predecessor file export from b.R
     let result = resolve_external_name(&library, &scope, "helper_b");
-    assert!(matches!(
-        result,
-        Some(ExternalDefinition::ProjectFile { .. })
-    ));
+    assert_matches!(result, Some(ExternalDefinition::ProjectFile { file, .. }) => {
+        assert_eq!(file, file_url("b.R"));
+    });
 
     // Resolve from predecessor file a
     let result = resolve_external_name(&library, &scope, "helper_a");
@@ -391,3 +393,166 @@ fn test_chained_scope_predecessor_files() {
         })
     );
 }
+
+// --- root_layers ---
+
+#[test]
+fn test_root_layers_from_namespace_imports() {
+    let ns = Namespace {
+        package_imports: vec!["rlang".to_string(), "cli".to_string()],
+        ..Default::default()
+    };
+    let layers = package_root_layers(&ns);
+    assert_eq!(layers.len(), 2);
+    assert_matches!(&layers[0], BindingSource::PackageExports(pkg) => {
+        assert_eq!(pkg, "rlang");
+    });
+    assert_matches!(&layers[1], BindingSource::PackageExports(pkg) => {
+        assert_eq!(pkg, "cli");
+    });
+}
+
+#[test]
+fn test_root_layers_empty_namespace() {
+    let ns = Namespace::default();
+    let layers = package_root_layers(&ns);
+    assert!(layers.is_empty());
+}
+
+#[test]
+fn test_root_layers_includes_importfrom() {
+    let ns = Namespace {
+        imports: vec![
+            Import {
+                name: "median".to_string(),
+                package: "stats".to_string(),
+            },
+            Import {
+                name: "head".to_string(),
+                package: "utils".to_string(),
+            },
+        ],
+        ..Default::default()
+    };
+    let layers = package_root_layers(&ns);
+    assert_eq!(layers.len(), 1);
+    assert_matches!(&layers[0], BindingSource::PackageImports(map) => {
+        assert_eq!(map.get("median").unwrap(), "stats");
+        assert_eq!(map.get("head").unwrap(), "utils");
+    });
+}
+
+#[test]
+fn test_root_layers_importfrom_before_package_exports() {
+    let ns = Namespace {
+        imports: vec![Import {
+            name: "filter".to_string(),
+            package: "stats".to_string(),
+        }],
+        package_imports: vec!["dplyr".to_string()],
+        ..Default::default()
+    };
+    let layers = package_root_layers(&ns);
+    assert_eq!(layers.len(), 2);
+    assert_matches!(&layers[0], BindingSource::PackageImports(_));
+    assert_matches!(&layers[1], BindingSource::PackageExports(pkg) => {
+        assert_eq!(pkg, "dplyr");
+    });
+}
+
+// --- scope chain assembly ---
+
+#[test]
+fn test_scope_chain_combines_predecessors_and_root() {
+    let library = test_library(vec![
+        ("rlang", vec!["sym", "expr"]),
+        ("dplyr", vec!["filter", "mutate"]),
+    ]);
+
+    let index_a = index_source("helper_a <- 1");
+    let index_b = index_source("library(dplyr)\nhelper_b <- 2");
+
+    let ns = Namespace {
+        package_imports: vec!["rlang".to_string()],
+        ..Default::default()
+    };
+
+    let mut scope = Vec::new();
+    scope.extend(file_layers(file_url("b.R"), &index_b));
+    scope.extend(file_layers(file_url("a.R"), &index_a));
+    scope.extend(package_root_layers(&ns));
+
+    // Predecessor file export
+    let result = resolve_external_name(&library, &scope, "helper_b");
+    assert_eq!(
+        result,
+        Some(ExternalDefinition::ProjectFile {
+            file: file_url("b.R"),
+            name: "helper_b".to_string(),
+            range: range(15, 23),
+        })
+    );
+
+    // Predecessor library() directive
+    let result = resolve_external_name(&library, &scope, "filter");
+    assert_eq!(
+        result,
+        Some(ExternalDefinition::Package {
+            package: "dplyr".to_string(),
+            name: "filter".to_string(),
+        })
+    );
+
+    // Root layer (NAMESPACE import)
+    let result = resolve_external_name(&library, &scope, "sym");
+    assert_eq!(
+        result,
+        Some(ExternalDefinition::Package {
+            package: "rlang".to_string(),
+            name: "sym".to_string(),
+        })
+    );
+
+    // Miss
+    assert_eq!(resolve_external_name(&library, &scope, "unknown"), None);
+}
+
+#[test]
+fn test_scope_chain_predecessors_shadow_root() {
+    let library = test_library(vec![("rlang", vec!["expr"])]);
+
+    let index = index_source("expr <- function() NULL");
+
+    let ns = Namespace {
+        package_imports: vec!["rlang".to_string()],
+        ..Default::default()
+    };
+
+    let mut scope = Vec::new();
+    scope.extend(file_layers(file_url("utils.R"), &index));
+    scope.extend(package_root_layers(&ns));
+
+    // File export shadows the rlang root layer
+    let result = resolve_external_name(&library, &scope, "expr");
+    assert!(matches!(
+        result,
+        Some(ExternalDefinition::ProjectFile { .. })
+    ));
+}
+
+#[test]
+fn test_scope_chain_later_predecessor_shadows_earlier() {
+    // b.R is loaded after a.R, so b.R's layers come first in the scope
+    // and its `helper` should shadow a.R's `helper`.
+    let index_a = index_source("helper <- 1");
+    let index_b = index_source("helper <- 2");
+
+    let mut scope = Vec::new();
+    scope.extend(file_layers(file_url("b.R"), &index_b));
+    scope.extend(file_layers(file_url("a.R"), &index_a));
+
+    let result = resolve_external_name(&empty_library(), &scope, "helper");
+    assert_matches!(result, Some(ExternalDefinition::ProjectFile { file, .. }) => {
+        assert_eq!(file, file_url("b.R"));
+    });
+}

crates/oak_package/src/collation.rs

@@ -0,0 +1,93 @@
+use std::collections::HashSet;
+
+use crate::package_description::Description;
+
+/// Determine the order in which R source files should be loaded.
+///
+/// If the DESCRIPTION has a `Collate` field, its whitespace-separated
+/// file list is used. Otherwise files are sorted in C locale order
+/// (byte-wise, same as R's default).
+pub fn collation_order(description: &Description, files: &[String]) -> Vec<String> {
+    description
+        .collate()
+        .map(|collate| {
+            let available: HashSet<&str> = files.iter().map(|s| s.as_str()).collect();
+            collate
+                .into_iter()
+                .filter(|name| available.contains(name.as_str()))
+                .collect()
+        })
+        .unwrap_or_else(|| {
+            let mut sorted = files.to_vec();
+            sorted.sort();
+            sorted
+        })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::package_description::Description;
+
+    fn desc_with_collate(collate: &str) -> Description {
+        let raw = format!("Package: test\nVersion: 1.0\nCollate: {collate}");
+        Description::parse(&raw).unwrap()
+    }
+
+    fn desc_without_collate() -> Description {
+        Description::parse("Package: test\nVersion: 1.0").unwrap()
+    }
+
+    #[test]
+    fn test_collate_field_determines_order() {
+        let desc = desc_with_collate("zzz.R aaa.R bbb.R");
+        let files = vec!["aaa.R".into(), "bbb.R".into(), "zzz.R".into()];
+        assert_eq!(collation_order(&desc, &files), vec![
+            "zzz.R", "aaa.R", "bbb.R"
+        ]);
+    }
+
+    #[test]
+    fn test_alphabetical_without_collate() {
+        let desc = desc_without_collate();
+        let files = vec!["zzz.R".into(), "aaa.R".into(), "bbb.R".into()];
+        assert_eq!(collation_order(&desc, &files), vec![
+            "aaa.R", "bbb.R", "zzz.R"
+        ]);
+    }
+
+    #[test]
+    fn test_collate_ignores_missing_files() {
+        let desc = desc_with_collate("aaa.R missing.R bbb.R");
+        let files = vec!["aaa.R".into(), "bbb.R".into()];
+        assert_eq!(collation_order(&desc, &files), vec!["aaa.R", "bbb.R"]);
+    }
+
+    #[test]
+    fn test_collate_multiline() {
+        // DCF continuation lines have leading whitespace, which the DCF parser
+        // preserves. split_whitespace handles this naturally.
+        let desc = desc_with_collate("aaa.R\n    bbb.R\n    zzz.R");
+        let files = vec!["aaa.R".into(), "bbb.R".into(), "zzz.R".into()];
+        assert_eq!(collation_order(&desc, &files), vec![
+            "aaa.R", "bbb.R", "zzz.R"
+        ]);
+    }
+
+    #[test]
+    fn test_empty_r_files() {
+        let desc = desc_without_collate();
+        let files: Vec<String> = vec![];
+        assert_eq!(collation_order(&desc, &files), Vec::<String>::new());
+    }
+
+    #[test]
+    fn test_alphabetical_is_byte_order() {
+        let desc = desc_without_collate();
+        // Uppercase sorts before lowercase in C locale (byte order)
+        let files = vec!["aaa.R".into(), "BBB.R".into(), "ccc.R".into()];
+        assert_eq!(collation_order(&desc, &files), vec![
+            "BBB.R", "aaa.R", "ccc.R"
+        ]);
+    }
+}

crates/oak_package/src/lib.rs

@@ -1,3 +1,4 @@
+pub mod collation;
 pub mod library;
 pub mod package;
 pub mod package_description;

crates/oak_package/src/library.rs

@@ -81,6 +81,7 @@ mod tests {
     use tempfile::TempDir;
 
     use super::*;
+    use crate::package_namespace::Import;
 
     // Helper to create a temporary package directory with DESCRIPTION and NAMESPACE
     fn create_temp_package(
@@ -136,6 +137,9 @@ importFrom(pkg, baz)
 
         // Namespace is parsed
         assert_eq!(pkg.namespace.exports, vec!["bar", "foo"]);
-        assert_eq!(pkg.namespace.imports, vec!["baz"]);
+        assert_eq!(pkg.namespace.imports, vec![Import {
+            name: "baz".to_string(),
+            package: "pkg".to_string()
+        }]);
     }
 }

crates/oak_package/src/package_description.rs

@@ -77,6 +77,13 @@ impl Description {
             fields,
         })
     }
+
+    /// Parse the `Collate` field, if present, returning the whitespace-separated
+    /// file names in the order specified.
+    pub fn collate(&self) -> Option<Vec<String>> {
+        let collate = self.fields.get("Collate")?;
+        Some(collate.split_whitespace().map(|s| s.to_string()).collect())
+    }
 }
 
 /// Parse a DCF (Debian Control File) format string into a key-value map.