feat(metadata): analyze and test the examples directory only for the root project

Author: dalance

crates/metadata/src/lockfile.rs

@@ -282,8 +282,13 @@ impl Lockfile {
             for lock in locks {
                 let metadata = self.get_metadata(&lock.source)?;
                 let path = metadata.project_path();
+                // Analyzed only for the build root (`Metadata::paths`).
+                let examples = path.join("examples");
 
                 for src in &veryl_path::gather_files_with_extension(&path, "veryl", false)? {
+                    if src.starts_with(&examples) {
+                        continue;
+                    }
                     let Ok(rel) = src.strip_prefix(&path) else {
                         return Err(MetadataError::InvalidSourceLocation(src.clone()));
                     };
@@ -297,6 +302,7 @@ impl Lockfile {
                         src: src.to_path_buf(),
                         dst,
                         map,
+                        example: false,
                     });
                 }
             }

crates/metadata/src/metadata.rs

@@ -339,15 +339,33 @@ impl Metadata {
         };
         let mut explicit_routed = canonical_files.as_ref().map(|v| vec![false; v.len()]);
 
-        for source in &sources {
-            let src_base = base.join(source);
+        // `examples/` is reserved; dependency source collection
+        // (`Lockfile::paths`) skips it entirely.
+        let examples_base = base.join("examples");
+        if let Some(source) = sources
+            .iter()
+            .find(|x| base.join(x).starts_with(&examples_base))
+        {
+            return Err(MetadataError::ReservedSourceDir(base.join(source)));
+        }
 
+        let mut source_dirs: Vec<(PathBuf, bool)> =
+            sources.iter().map(|x| (base.join(x), false)).collect();
+        if examples_base.exists() {
+            source_dirs.push((examples_base.clone(), true));
+        }
+
+        for (src_base, is_example) in source_dirs {
             let src_files = if let Some(cf) = canonical_files.as_ref() {
                 // Only keep files that live under this source dir; other
-                // source dirs in `sources` will pick them up.
+                // source dirs in `sources` will pick them up. Files under
+                // `examples/` belong to the examples dir only, even when a
+                // source dir contains it.
                 let mut ret = Vec::new();
                 for (i, path) in cf.iter().enumerate() {
-                    if path.starts_with(&src_base) {
+                    if path.starts_with(&src_base)
+                        && (is_example || !path.starts_with(&examples_base))
+                    {
                         ret.push(path.clone());
                         if let Some(ref mut flags) = explicit_routed {
                             flags[i] = true;
@@ -356,7 +374,12 @@ impl Metadata {
                 }
                 ret
             } else {
-                veryl_path::gather_files_with_extension(&src_base, "veryl", symlink)?
+                let mut files =
+                    veryl_path::gather_files_with_extension(&src_base, "veryl", symlink)?;
+                if !is_example {
+                    files.retain(|x| !x.starts_with(&examples_base));
+                }
+                files
             };
 
             for src in src_files {
@@ -400,6 +423,7 @@ impl Metadata {
                     src: src.to_path_buf(),
                     dst,
                     map,
+                    example: is_example,
                 });
             }
         }

crates/metadata/src/metadata_error.rs

@@ -31,6 +31,15 @@ pub enum MetadataError {
     #[error("source file \"{0}\" is outside the project")]
     InvalidSourceLocation(PathBuf),
 
+    #[diagnostic(
+        code(MetadataError::ReservedSourceDir),
+        help("remove it from [build] sources")
+    )]
+    #[error(
+        "\"{0}\" cannot be used as a source directory: `examples/` is reserved and analyzed automatically for the root project"
+    )]
+    ReservedSourceDir(PathBuf),
+
     #[diagnostic(code(MetadataError::Git), help(""))]
     #[error("git operation failure: {0}")]
     Git(Box<dyn std::error::Error + Sync + Send>),

crates/metadata/src/tests.rs

@@ -746,3 +746,138 @@ fn lockfile_save_is_atomic() {
         r.join().unwrap();
     }
 }
+
+const EXAMPLES_TOML: &str = r#"
+[project]
+name = "test"
+version = "0.1.0"
+
+[build]
+sources = ["src"]
+target = {type = "directory", path = "target"}
+"#;
+
+fn create_metadata_with_examples() -> (Metadata, TempDir) {
+    let tempdir = tempfile::tempdir().unwrap();
+    let metadata = create_project(tempdir.path(), "test", EXAMPLES_TOML, false);
+    let project_path = metadata.project_path();
+    fs::create_dir_all(project_path.join("src")).unwrap();
+    fs::write(project_path.join("src/a.veryl"), "module A {}\n").unwrap();
+    fs::create_dir_all(project_path.join("examples")).unwrap();
+    fs::write(project_path.join("examples/ex.veryl"), "module Ex {}\n").unwrap();
+
+    (metadata, tempdir)
+}
+
+#[test]
+fn paths_include_root_examples() {
+    let (mut metadata, _tempdir) = create_metadata_with_examples();
+
+    let paths = metadata.paths::<&str>(&[], false, false).unwrap();
+    assert_eq!(paths.len(), 2);
+
+    let src = paths.iter().find(|x| x.src.ends_with("a.veryl")).unwrap();
+    let example = paths.iter().find(|x| x.src.ends_with("ex.veryl")).unwrap();
+    assert!(!src.example);
+    assert!(example.example);
+}
+
+#[test]
+fn paths_include_examples_with_default_sources() {
+    // The default `sources = [""]` walks the whole project.
+    let toml = r#"
+[project]
+name = "test"
+version = "0.1.0"
+
+[build]
+target = {type = "directory", path = "target"}
+"#;
+    let tempdir = tempfile::tempdir().unwrap();
+    let mut metadata = create_project(tempdir.path(), "test", toml, false);
+    let project_path = metadata.project_path();
+    fs::create_dir_all(project_path.join("src")).unwrap();
+    fs::write(project_path.join("src/a.veryl"), "module A {}\n").unwrap();
+    fs::create_dir_all(project_path.join("examples")).unwrap();
+    fs::write(project_path.join("examples/ex.veryl"), "module Ex {}\n").unwrap();
+
+    let paths = metadata.paths::<&str>(&[], false, false).unwrap();
+    assert_eq!(paths.len(), 2);
+
+    let src = paths.iter().find(|x| x.src.ends_with("a.veryl")).unwrap();
+    let example = paths.iter().find(|x| x.src.ends_with("ex.veryl")).unwrap();
+    assert!(!src.example);
+    assert!(example.example);
+}
+
+#[test]
+fn sources_under_examples_are_rejected() {
+    for source in ["examples", "examples/sub"] {
+        let toml = format!(
+            r#"
+[project]
+name = "test"
+version = "0.1.0"
+
+[build]
+sources = ["src", "{source}"]
+target = {{type = "directory", path = "target"}}
+"#
+        );
+        let tempdir = tempfile::tempdir().unwrap();
+        let mut metadata = create_project(tempdir.path(), "test", &toml, false);
+        let project_path = metadata.project_path();
+        fs::create_dir_all(project_path.join("src")).unwrap();
+        fs::write(project_path.join("src/a.veryl"), "module A {}\n").unwrap();
+        fs::create_dir_all(project_path.join("examples/sub")).unwrap();
+        fs::write(project_path.join("examples/ex.veryl"), "module Ex {}\n").unwrap();
+
+        let result = metadata.paths::<&str>(&[], false, false);
+        assert!(matches!(result, Err(MetadataError::ReservedSourceDir(_))));
+    }
+}
+
+#[test]
+fn paths_route_explicit_example_file() {
+    let (mut metadata, _tempdir) = create_metadata_with_examples();
+    let file = metadata.project_path().join("examples/ex.veryl");
+
+    let paths = metadata.paths(&[file], false, false).unwrap();
+    assert_eq!(paths.len(), 1);
+    assert!(paths[0].example);
+}
+
+#[test]
+fn lockfile_paths_exclude_dependency_examples() {
+    let tempdir = tempfile::tempdir().unwrap();
+
+    let dep_path = tempdir.path().join("dep");
+    fs::create_dir_all(dep_path.join("src")).unwrap();
+    fs::create_dir_all(dep_path.join("examples")).unwrap();
+    fs::write(
+        dep_path.join("Veryl.toml"),
+        r#"
+[project]
+name = "dep"
+version = "0.1.0"
+"#,
+    )
+    .unwrap();
+    fs::write(dep_path.join("src/a.veryl"), "module A {}\n").unwrap();
+    fs::write(dep_path.join("examples/ex.veryl"), "module Ex {}\n").unwrap();
+
+    let main_toml = r#"
+[project]
+name = "main"
+version = "0.1.0"
+
+[dependencies]
+dep = {path = "../dep"}
+"#;
+    let metadata = create_project(tempdir.path(), "main", main_toml, false);
+
+    let lockfile = Lockfile::new(&metadata).unwrap();
+    let paths = lockfile.paths(Path::new("target")).unwrap();
+    assert!(paths.iter().any(|x| x.src.ends_with("a.veryl")));
+    assert!(!paths.iter().any(|x| x.src.ends_with("ex.veryl")));
+}

crates/path/src/lib.rs

@@ -14,6 +14,8 @@ pub struct PathSet {
     pub src: PathBuf,
     pub dst: PathBuf,
     pub map: PathBuf,
+    /// Analyzed like sources but excluded from emit and filelist.
+    pub example: bool,
 }
 
 pub fn cache_path() -> PathBuf {

crates/std/src/lib.rs

@@ -56,6 +56,7 @@ pub fn paths(base_dst: &Path) -> Result<Vec<PathSet>, PathError> {
             src: src.to_path_buf(),
             dst,
             map,
+            example: false,
         });
     }