Add glob helper for path expansion

Cargo.toml

@@ -15,6 +15,7 @@ miette = { version = "7.6.0", features = ["fancy"] }
 sha2 = "0.10"
 itoa = "1"
 itertools = "0.12"
+glob = "0.3.3"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["fmt"] }
 serde_json = "1"

docs/netsuke-design.md

@@ -732,13 +732,21 @@ providing a secure bridge to the underlying system.
   error if the variable is undefined or contains invalid UTF-8 to ensure
   manifests fail fast on missing inputs.
 
-- `glob(pattern: &str) -> Result<Vec<String>, Error>`: A function that performs
-  file path globbing. This is a critical feature for any modern build tool,
-  allowing users to easily specify sets of source files (e.g., `src/**/*.c`).
-  The results are returned sorted lexicographically and symlinks are followed
-  to keep builds deterministic. This function bridges a key feature gap, as
-  Ninja itself does not support globbing.[^3]
-
+- `glob(pattern: &str) -> Result<Vec<String>, Error>`: Expand filesystem
+  patterns (e.g., `src/**/*.c`) into a list of matched paths. Results are
+  yielded in lexicographic order by the iterator and returned unchanged.
+  Symlinks are followed by the `glob` crate by default. Matching is case-
+  sensitive on all platforms. `glob_with` enforces
+  `require_literal_separator = true` internally, so wildcards do not cross path
+  separators unless `**` is used. Callers may use `/` or `\` in patterns; these
+  are normalised to the host platform before matching. Results contain only
+  files (directories are ignored) and path separators are normalised to `/`.
+  Leading-dot entries are matched by wildcards. Empty results are represented
+  as `[]`. Invalid patterns surface as `SyntaxError`; filesystem iteration
+  errors surface as `InvalidOperation`, matching minijinja error semantics.
+  On Unix, backslash escapes for glob metacharacters (`[`, `]`, `{`, `}`) are
+  preserved during separator normalisation.
+  This fills a Ninja gap since Ninja itself does not support globbing.[^3]
 - `python_version(requirement: &str) -> Result<bool, Error>`: An example of a
   domain-specific helper function that demonstrates the extensibility of this
   architecture. This function would execute `python --version` or

docs/roadmap.md

@@ -104,8 +104,8 @@ configurations with variables, control flow, and custom functions.
   - [x] Implement the essential custom Jinja function env(var_name) to read
     system environment variables.
 
-  - [ ] Implement the critical glob(pattern) custom function to perform file
-    path globbing, with results sorted lexicographically.
+  - [x] Implement the critical glob(pattern) custom function to perform file
+     path globbing, with results sorted lexicographically.
 
   - [ ] Support user-defined Jinja macros declared in a top-level macros list,
     registering them with the environment before rendering.

src/manifest.rs

@@ -3,8 +3,9 @@
 //! This module parses a `Netsukefile` without relying on a global Jinja
 //! preprocessing pass. The YAML is parsed first and Jinja expressions are
 //! evaluated only within string values or the `foreach` and `when` keys. It
-//! exposes an `env()` function to surface environment variables, failing fast
-//! when values are missing or invalid.
+//! exposes `env()` to read environment variables and `glob()` to expand
+//! filesystem patterns during template evaluation. Both helpers fail fast when
+//! inputs are missing or patterns are invalid.
 
 use crate::{
     ast::{NetsukeManifest, Recipe, StringOrList, Target, Vars},
@@ -119,13 +120,15 @@ fn map_yaml_error(err: YamlError, src: &str, name: &str) -> YamlDiagnostic {
 ///
 /// # Examples
 ///
+/// The [`EnvLock`](test_support::env_lock::EnvLock) guard serialises access to
+/// the process environment so tests do not interfere with each other.
+///
 /// ```rust,ignore
-/// // SAFETY: Process environment mutation is unsafe in Rust 2024. Examples and
-/// // tests serialise access with an environment lock and restore prior state to
-/// // avoid races and leaks.
-/// unsafe { std::env::set_var("FOO", "bar"); }
+/// use test_support::env_lock::EnvLock;
+/// let _guard = EnvLock::acquire();
+/// std::env::set_var("FOO", "bar");
 /// assert_eq!(env("FOO").unwrap(), "bar");
-/// unsafe { std::env::remove_var("FOO"); }
+/// std::env::remove_var("FOO");
 /// ```
 fn env_var(name: &str) -> std::result::Result<String, Error> {
     match std::env::var(name) {
@@ -141,6 +144,126 @@ fn env_var(name: &str) -> std::result::Result<String, Error> {
     }
 }
 
+/// Process a single glob entry and normalise its output.
+///
+/// Returns the entry path when it points to a file, skipping directories.
+/// Requires matched paths to be valid UTF-8; output is normalised to use
+/// forward slashes.
+///
+/// # Examples
+///
+/// ```rust,ignore
+/// use glob::glob;
+/// let entry = glob("Cargo.toml").unwrap().next().unwrap();
+/// let path = process_glob_entry(entry, "Cargo.toml")
+///     .unwrap()
+///     .unwrap();
+/// assert!(path.ends_with("Cargo.toml"));
+/// ```
+fn process_glob_entry(
+    entry: std::result::Result<std::path::PathBuf, glob::GlobError>,
+    pattern: &str,
+) -> std::result::Result<Option<String>, Error> {
+    match entry {
+        Ok(path) => {
+            // Query metadata early to surface filesystem errors promptly.
+            let meta = path.metadata().map_err(|e| {
+                Error::new(
+                    ErrorKind::InvalidOperation,
+                    format!("glob failed for '{pattern}': {e}"),
+                )
+            })?;
+            if !meta.is_file() {
+                return Ok(None);
+            }
+            // Reject non-UTF-8 paths to avoid lossy round-trips and ensure
+            // manifests remain deterministic.
+            let s = path.to_str().ok_or_else(|| {
+                Error::new(
+                    ErrorKind::InvalidOperation,
+                    format!("glob matched a non-UTF-8 path: {}", path.display()),
+                )
+            })?;
+            Ok(Some(s.replace('\\', "/")))
+        }
+        Err(e) => Err(Error::new(
+            ErrorKind::InvalidOperation,
+            format!("glob failed for '{pattern}': {e}"),
+        )),
+    }
+}
+
+/// Expand a glob pattern into a list of matching paths with deterministic ordering.
+///
+/// Results are returned in lexicographic order to keep builds deterministic.
+/// Invalid patterns or filesystem errors surface as Jinja evaluation errors so
+/// manifests fail fast when input is incorrect.
+///
+/// # Errors
+///
+/// Returns an error if the glob pattern is invalid, a directory cannot be
+/// read, or a matched path is not valid UTF-8.
+/// Matching is case-sensitive on all platforms, wildcards do not cross path
+/// separators (use `**` to span directories), and leading-dot entries are
+/// matched by wildcards.
+/// Convert `/` and `\` to the host separator while preserving escapes for
+/// glob metacharacters on Unix.
+fn normalise_separators(pattern: &str) -> String {
+    let native = std::path::MAIN_SEPARATOR;
+    #[cfg(unix)]
+    {
+        let mut out = String::with_capacity(pattern.len());
+        let mut it = pattern.chars().peekable();
+        while let Some(c) = it.next() {
+            if c == '\\' && matches!(it.peek(), Some('[' | ']' | '{' | '}')) {
+                out.push('\\');
+                continue;
+            }
+            if c == '/' || c == '\\' {
+                out.push(native);
+            } else {
+                out.push(c);
+            }
+        }
+        out
+    }
+    #[cfg(not(unix))]
+    {
+        pattern.replace('/', &native.to_string())
+    }
+}
+
+fn glob_paths(pattern: &str) -> std::result::Result<Vec<String>, Error> {
+    use glob::{MatchOptions, glob_with};
+
+    // Enforce shell-like semantics:
+    // - patterns are case-sensitive,
+    // - wildcards do not cross path separators,
+    // - dotfiles are matched by default.
+    let opts = MatchOptions {
+        case_sensitive: true,
+        require_literal_separator: true,
+        require_literal_leading_dot: false,
+    };
+
+    // Normalise separators so `/` and `\\` behave the same on all platforms.
+    let normalized = normalise_separators(pattern);
+
+    let entries = glob_with(&normalized, opts).map_err(|e| {
+        Error::new(
+            ErrorKind::SyntaxError,
+            format!("invalid glob pattern '{pattern}': {e}"),
+        )
+    })?;
+    let mut paths = Vec::new();
+    for entry in entries {
+        if let Some(p) = process_glob_entry(entry, pattern)? {
+            paths.push(p);
+        }
+    }
+    Ok(paths)
+}
+
 /// Parse a manifest string using Jinja for value templating.
 ///
 /// The input YAML must be valid on its own. Jinja expressions are evaluated
@@ -155,8 +278,9 @@ fn from_str_named(yaml: &str, name: &str) -> Result<NetsukeManifest> {
 
     let mut jinja = Environment::new();
     jinja.set_undefined_behavior(UndefinedBehavior::Strict);
-    // Expose a strict environment variable accessor to templates.
+    // Expose custom helpers to templates.
     jinja.add_function("env", |name: String| env_var(&name));
+    jinja.add_function("glob", |pattern: String| glob_paths(&pattern));
 
     if let Some(vars) = doc.get("vars").and_then(|v| v.as_mapping()).cloned() {
         for (k, v) in vars {

src/manifest/tests.rs

@@ -18,3 +18,28 @@ fn yaml_hint_needles_are_lowercase() {
         );
     }
 }
+
+#[test]
+fn glob_paths_invalid_pattern_sets_syntax_error() {
+    let err = super::glob_paths("[").expect_err("expected pattern error");
+    assert_eq!(err.kind(), minijinja::ErrorKind::SyntaxError);
+}
+
+#[cfg(unix)]
+#[test]
+fn normalise_separators_preserves_bracket_escape() {
+    assert_eq!(super::normalise_separators("\\["), "\\[");
+}
+
+#[test]
+fn glob_paths_ignores_directories() {
+    let dir = tempfile::tempdir().expect("temp dir");
+    std::fs::create_dir(dir.path().join("sub")).expect("create dir");
+    std::fs::write(dir.path().join("a.txt"), "a").expect("write file");
+    let pattern = format!("{}/{}", dir.path().display(), "*");
+    let out = super::glob_paths(&pattern).expect("glob ok");
+    assert_eq!(
+        out,
+        vec![format!("{}/a.txt", dir.path().display()).replace('\\', "/")]
+    );
+}

tests/data/glob.yml

@@ -0,0 +1,5 @@
+netsuke_version: 1.0.0
+targets:
+  - foreach: glob('tests/data/glob_files/*.txt')
+    name: "{{ item | replace('tests/data/glob_files/', '') | replace('.txt', '.out') }}"
+    command: "echo {{ item }}"

tests/data/glob_files/a.txt

@@ -0,0 +1 @@
+a

tests/data/glob_files/b.txt

@@ -0,0 +1 @@
+b

tests/data/glob_invalid.yml

@@ -0,0 +1,5 @@
+netsuke_version: 1.0.0
+targets:
+  - foreach: glob('[')  # intentional: unmatched '[' to trigger a glob parse error
+    name: broken
+    command: "echo hi"

tests/data/glob_windows.yml

@@ -0,0 +1,5 @@
+netsuke_version: 1.0.0
+targets:
+  - foreach: glob('tests\\data\\glob_files\\*.txt')
+    name: "{{ item | replace('tests/data/glob_files/', '') | replace('.txt', '.out') }}"
+    command: "echo {{ item }}"

tests/features/manifest.feature

@@ -91,6 +91,32 @@ Feature: Manifest Parsing
     And the target 2 command is "echo 'bar'"
     And the target 2 index is 1
 
+  Scenario: Generating targets with glob
+    Given the manifest file "tests/data/glob.yml" is parsed
+    When the manifest is checked
+    Then the manifest has 2 targets
+    And the target 1 name is "a.out"
+    And the target 1 index is 0
+    And the target 2 name is "b.out"
+    And the target 2 index is 1
+
+  Scenario: Generating targets with glob using Windows separators
+    Given the manifest file "tests/data/glob_windows.yml" is parsed
+    When the manifest is checked
+    Then the manifest has 2 targets
+    And the target 1 name is "a.out"
+    And the target 2 name is "b.out"
+    And the target 1 index is 0
+    And the target 2 index is 1
+
+  Scenario: Parsing fails for an invalid glob pattern
+    Given the manifest file "tests/data/glob_invalid.yml" is parsed
+    When the parsing result is checked
+    Then parsing the manifest fails
+    And the error message contains "glob pattern"
+
+
+
   Scenario: Parsing fails when a foreach expression is not iterable
     Given the manifest file "tests/data/foreach_invalid.yml" is parsed
     When the parsing result is checked