Preserve literal Unix backslashes in glob result paths (#990)

docs/developers-guide.md

@@ -6816,10 +6816,13 @@ The private `GlobExpansion::into_template_paths` method is the adapter between
 the filesystem query and Jinja values that may later be interpolated into shell
 commands. It accepts only non-empty paths made from ASCII letters, digits, `/`,
 `:`, comma, full stop, underscore, and hyphen. Any whitespace, control
-character, non-ASCII byte, or other punctuation returns a MiniJinja
-`InvalidOperation` error before `foreach` receives the value. This policy is
-Jinja-specific: `glob_paths` retains its filesystem-query contract and returns
-all matching UTF-8 file paths without applying shell-safety validation.
+character, non-ASCII byte, backslash, or other punctuation returns a MiniJinja
+`InvalidOperation` error before `foreach` receives the value. A Unix filename
+containing a literal backslash is rejected here rather than rewritten into an
+accepted directory path, so the value that reaches `foreach` is always the file
+the metadata check selected. This policy is Jinja-specific: `glob_paths`
+retains its filesystem-query contract and returns all matching UTF-8 file paths
+without applying shell-safety validation, leaving quoting to direct callers.
 
 ### Base-directory seam
 
@@ -6839,11 +6842,20 @@ working-directory state during glob expansion.
   retains the unescaped path for result rebasing. `open_root_dir` receives
   `None` for this prepared search because the base is already embedded.
 
-The focused base and property tests cover no-double-base, symlinked base,
-base-path metacharacters, canonicalization failure, nested and parent-relative
-results, absolute patterns, and forward-slash output. Run
-`make bench-glob-expansion` alongside the relevant tests when changing this hot
-path.
+Result normalization happens after capability validation and must not change
+the identity of the matched file. `strip_base` follows the same `cfg(unix)`
+split as `normalize.rs`: on Windows and other platforms where a backslash is a
+separator, it rewrites `\\` to `/`; on Unix, where a backslash is an ordinary
+filename character, it returns the matched spelling unchanged. Rewriting a Unix
+backslash would report a file the capability walk never selected, and a name
+such as `part\..\other.txt` would become the parent-directory traversal
+`part/../other.txt`. Do not reintroduce an unconditional replacement.
+
+The focused base, property, and identity tests cover no-double-base, symlinked
+base, base-path metacharacters, canonicalization failure, nested and
+parent-relative results, absolute patterns, forward-slash directory separators,
+and preserved literal Unix backslashes. Run `make bench-glob-expansion`
+alongside the relevant tests when changing this hot path.
 
 The adjacent configuration-discovery seam keeps its ownership boundary clear:
 `-C/--directory` anchors manifest lookup and automatic project discovery.

docs/netsuke-design.md

@@ -1400,34 +1400,41 @@ providing a secure bridge to the underlying system.
   `require_literal_separator = true` internally, so wildcards do not cross path
   separators unless `**` is used. Callers may use `/` or `\\` in patterns;
   these are normalized to the host platform before matching. Results contain
-  only files (directories are ignored) and path separators are normalized to
-  `/`. Leading-dot entries are matched by wildcards. Empty results are
-  represented as `[]`. The manifest parse boundary supplies the manifest
-  directory or workspace root to `glob_paths(pattern, base)` and internal
-  `expand_glob(pattern, base)`: relative patterns, including parent-relative
-  ones, resolve from that root and retain their pattern-relative spelling after
-  base stripping, while absolute patterns remain absolute. With an injected
-  manifest root, this expansion does not read or mutate process-global
-  working-directory state. `from_str_with_env` passes `manifest_root: None`, so
-  unbased relative patterns resolve from the process working directory. 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 normalization. A backslash before `*` or `?` is kept only
-  when the wildcard is trailing or followed by an alphanumeric, `_`, or `-`;
-  otherwise it becomes a path separator so `config\*.yml` maps to
-  `config/*.yml`. On Windows, backslash escapes are not supported. This
-  provides globbing support not available in Ninja itself, which does not
-  support globbing.[^3]
+  only files (directories are ignored). On Windows and other platforms where a
+  backslash is a separator, result separators are normalized to `/`; on Unix,
+  where a backslash is an ordinary filename character, a literal backslash in a
+  matched filename is preserved. Each returned path therefore names exactly the
+  file that passed the capability metadata check. Leading-dot entries are
+  matched by wildcards. Empty results are represented as `[]`. The manifest
+  parse boundary supplies the manifest directory or workspace root to
+  `glob_paths(pattern, base)` and internal `expand_glob(pattern, base)`:
+  relative patterns, including parent-relative ones, resolve from that root and
+  retain their pattern-relative spelling after base stripping, while absolute
+  patterns remain absolute. With an injected manifest root, this expansion does
+  not read or mutate process-global working-directory state.
+  `from_str_with_env` passes `manifest_root: None`, so unbased relative
+  patterns resolve from the process working directory. 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
+  normalization. A backslash before `*` or `?` is kept only when the wildcard
+  is trailing or followed by an alphanumeric, `_`, or `-`; otherwise it becomes
+  a path separator so `config\*.yml` maps to `config/*.yml`. On Windows,
+  backslash escapes are not supported. This provides globbing support not
+  available in Ninja itself, which does not support globbing.[^3]
 
   The Rust query returns those UTF-8 paths unchanged. The Jinja `glob()`
   adapter adds the narrower command-safety boundary: it exposes a result only
   when every path is a portable unquoted shell word made from ASCII letters,
   digits, `/`, `:`, comma, full stop, underscore, or hyphen. Other matches fail
   manifest loading rather than entering `foreach` variables and potentially
-  reaching command or script recipes as executable shell syntax. This private
-  adapter predicate is owned by manifest templating; graph-path escaping and
-  direct Rust callers must retain their existing, context-specific policies.
+  reaching command or script recipes as executable shell syntax. A Unix
+  filename containing a literal backslash reaches this adapter unchanged and is
+  rejected, rather than being rewritten into a directory separator that would
+  name a different file. Direct Rust callers receive the exact matched filename
+  and remain responsible for quoting it. This private adapter predicate is
+  owned by manifest templating; graph-path escaping and direct Rust callers
+  must retain their existing, context-specific policies.
 
   The metadata check that filters directories out of the results runs through a
   capability opened at the pattern's literal directory prefix (`src/` for

docs/users-guide.md

@@ -817,7 +817,9 @@ portable unquoted shell word. ASCII letters, digits, `/`, `:`, comma, full
 stop, underscore, and hyphen are accepted; whitespace, control characters, and
 shell punctuation are rejected. This prevents an untrusted checkout filename
 from becoming shell syntax when `item` is interpolated into a `command` or
-`script`.
+`script`. On Unix, a matched filename that contains a literal backslash makes
+`glob()` fail with this shell-quoting error; the backslash is preserved rather
+than rewritten into a directory separator.
 
 ### Define reusable macros
 

src/manifest/glob/mod.rs

@@ -12,7 +12,9 @@
 //! - `base` canonicalizes an injected base into a glob-compatible path.
 //! - `normalize` maps separators onto the platform's and, on Unix, rewrites
 //!   backslash escapes into the bracket classes the `glob` crate understands.
-//!   [`GlobPattern`] pairs the caller's text with that normalized form.
+//!   It also rebases a matched path into the caller's spelling with the same
+//!   platform rule. [`GlobPattern`] pairs the caller's text with that
+//!   normalized form.
 //! - `walk` owns the filesystem side: it computes the pattern's literal
 //!   directory prefix, opens a capability-scoped `cap_std` handle there, and
 //!   runs the metadata check that filters each match.
@@ -46,7 +48,7 @@ use base::PreparedGlob;
 use camino::{Utf8Path, Utf8PathBuf};
 pub(super) use diagnostics::expand_manifest_template_glob;
 use errors::{GlobErrorContext, GlobErrorType, GlobExpansionFailure, create_glob_error};
-use normalize::normalize_separators;
+use normalize::{normalize_separators, strip_base};
 use validate::validate_brace_matching;
 use walk::{open_root_dir, process_glob_entry};
 
@@ -369,21 +371,6 @@ fn expand_prepared_glob(
     })
 }
 
-/// Remove an injected base directory from a matched path, restoring the
-/// pattern-relative spelling the caller supplied.
-///
-/// Only relative patterns with an injected base are affected: `strip` is
-/// `Some` exactly when the matcher ran against `base.join(pattern)`, so every
-/// match starts with `base` and the lexical strip cannot fail in a way that
-/// would drop real matches. The fallback returns the path unchanged.
-fn strip_base(base: Option<&Utf8Path>, path: &Utf8Path) -> String {
-    let relative = base
-        .and_then(|dir| path.strip_prefix(dir).ok())
-        .unwrap_or(path);
-    // Format once, after any lexical base stripping, so a matched path does
-    // not first allocate a normalized String only to allocate again to rebase.
-    relative.as_str().replace('\\', "/")
-}
 #[cfg(test)]
 mod tests;
 

src/manifest/glob/normalize.rs

@@ -1,4 +1,6 @@
-//! Separator and escape normalisation for glob patterns.
+//! Separator and escape normalisation for glob patterns and matched paths.
+
+use camino::Utf8Path;
 
 /// Normalise forward slashes in a glob `pattern` to the platform separator.
 ///
@@ -157,3 +159,34 @@ fn handle_escaped_char(it: &mut std::iter::Peekable<std::str::Chars<'_>>, out: &
 fn is_wildcard_continuation_char(ch: char) -> bool {
     ch.is_alphanumeric() || ch == '-' || ch == '_'
 }
+
+/// Remove an injected base directory from a matched path, restoring the
+/// pattern-relative spelling the caller supplied.
+///
+/// Only relative patterns with an injected base are affected: the base is
+/// present exactly when the matcher ran against `base.join(pattern)`, so every
+/// match starts with it and the lexical strip cannot drop real matches. The
+/// fallback returns the path unchanged.
+///
+/// Separator normalisation is platform-aware, like the pattern side above. On
+/// Windows a backslash is a directory separator, so it is rendered as `/` for
+/// the portable spelling callers expect. On Unix a backslash is an ordinary
+/// filename character: rewriting it would report a different file from the one
+/// the capability metadata check selected, and a name such as
+/// `part\..\other.txt` would become the traversal `part/../other.txt`. The
+/// Unix branch therefore returns the checked spelling unchanged.
+pub(super) fn strip_base(base: Option<&Utf8Path>, path: &Utf8Path) -> String {
+    let relative = base
+        .and_then(|dir| path.strip_prefix(dir).ok())
+        .unwrap_or(path);
+    // Format once, after any lexical base stripping, so a matched path does
+    // not first allocate a normalized String only to allocate again to rebase.
+    #[cfg(unix)]
+    {
+        relative.as_str().to_owned()
+    }
+    #[cfg(not(unix))]
+    {
+        relative.as_str().replace('\\', "/")
+    }
+}

src/manifest/glob/tests/base/property.rs

@@ -7,7 +7,9 @@
 //! the fixture files spelled relative to the pattern, two distinct bases
 //! never cross-contaminate, an absolute pattern ignores the base, a
 //! parent-relative pattern keeps its `..` spelling, `None` retains the
-//! unbased behaviour, and produced paths always use forward slashes.
+//! unbased behaviour, and produced directory separators always use forward
+//! slashes. A literal Unix backslash is a filename character rather than a
+//! separator, so `identity` pins its preservation separately.
 //!
 //! Each case builds a disposable temporary fixture tree and invokes the
 //! production `glob_paths` function; the environment and working directory of
@@ -235,7 +237,10 @@ fn none_base_keeps_absolute_results() -> Result<()> {
     Ok(())
 }
 
-/// Every produced path uses forward slashes on every platform.
+/// Produced directory separators use forward slashes on every platform.
+///
+/// This covers real directory components only; a literal Unix backslash inside
+/// a filename is not a separator and is preserved unchanged.
 #[test]
 fn results_use_forward_slashes() -> Result<()> {
     let temp = tempdir()?;

src/manifest/glob/tests/identity.rs

@@ -0,0 +1,106 @@
+//! Regression tests for the identity of Unix paths containing a literal
+//! backslash.
+//!
+//! On Unix a backslash is an ordinary filename character, not a separator.
+//! Result rebasing must therefore return the exact name that passed the
+//! capability metadata check. Rewriting the backslash would report the match
+//! under a different identity, and a name such as `part\..\other.txt` would
+//! become the parent-directory traversal `part/../other.txt` that the checked
+//! filesystem path never contained.
+//!
+//! Each case builds a disposable fixture and invokes the production
+//! [`super::super::glob_paths`] boundary; neither the environment nor the
+//! working directory of the test process is mutated.
+
+#[cfg(unix)]
+use super::super::glob_paths;
+#[cfg(unix)]
+use anyhow::{Context, Result, ensure};
+#[cfg(unix)]
+use camino::Utf8Path;
+#[cfg(unix)]
+use tempfile::tempdir;
+#[cfg(unix)]
+use test_support::fs as test_fs;
+
+/// A literal backslash stays in the returned name rather than addressing a
+/// different file that the capability check never saw.
+#[cfg(unix)]
+#[test]
+fn glob_paths_preserves_a_literal_backslash_filename() -> Result<()> {
+    let temp = tempdir()?;
+    test_fs::create_dir(temp.path().join("nested"))?;
+    test_fs::write(temp.path().join("nested").join("leaf.txt"), "decoy")?;
+    test_fs::write(temp.path().join(r"nested\leaf.txt"), "attacker")?;
+    let base = Utf8Path::from_path(temp.path()).context("temporary paths must be UTF-8")?;
+
+    let results = glob_paths("*.txt", Some(base))?;
+
+    ensure!(
+        results == vec![r"nested\leaf.txt".to_owned()],
+        "a literal backslash must be preserved, got {results:?}"
+    );
+    let returned = results
+        .first()
+        .context("the matched literal-backslash file must be returned")?;
+    let contents = test_fs::read_to_string(base.join(returned))?;
+    ensure!(
+        contents == "attacker",
+        "the returned path must name the matched file, not the {contents:?} decoy"
+    );
+    Ok(())
+}
+
+/// A literal `..` spelled between backslashes stays part of one filename
+/// component; it must not become parent-directory traversal after rebasing.
+#[cfg(unix)]
+#[test]
+fn glob_paths_does_not_introduce_parent_traversal() -> Result<()> {
+    let temp = tempdir()?;
+    test_fs::create_dir(temp.path().join("part"))?;
+    test_fs::write(temp.path().join("other.txt"), "decoy")?;
+    test_fs::write(temp.path().join(r"part\..\other.txt"), "attacker")?;
+    let base = Utf8Path::from_path(temp.path()).context("temporary paths must be UTF-8")?;
+
+    // Match only the literal-backslash name: the decoy that a rewritten
+    // separator would reach is `other.txt`, and it must not be a legitimate
+    // match of the pattern.
+    let results = glob_paths("part*", Some(base))?;
+
+    ensure!(
+        results == vec![r"part\..\other.txt".to_owned()],
+        "the literal backslash spelling must survive, got {results:?}"
+    );
+    let returned = results
+        .first()
+        .context("the matched literal-backslash file must be returned")?;
+    ensure!(
+        !returned.contains("/../"),
+        "rebasing must not create a parent-directory component: {returned:?}"
+    );
+    let contents = test_fs::read_to_string(base.join(returned))?;
+    ensure!(
+        contents == "attacker",
+        "the returned path must name the matched file, not the {contents:?} decoy"
+    );
+    Ok(())
+}
+
+/// An absolute pattern with no injected base also keeps the literal
+/// backslash, so direct callers see the identity the walk selected.
+#[cfg(unix)]
+#[test]
+fn glob_paths_preserves_a_literal_backslash_in_an_absolute_match() -> Result<()> {
+    let temp = tempdir()?;
+    test_fs::write(temp.path().join(r"nested\leaf.txt"), "attacker")?;
+    let pattern = format!("{}/*.txt", temp.path().display());
+
+    let results = glob_paths(&pattern, None)?;
+
+    let expected = format!(r"{}/nested\leaf.txt", temp.path().display());
+    ensure!(
+        results == vec![expected],
+        "the absolute match must keep its literal backslash, got {results:?}"
+    );
+    Ok(())
+}

src/manifest/glob/tests/mod.rs

@@ -5,14 +5,16 @@
 //! [`capability`] covers the capability handle the metadata checks run
 //! through, [`diagnostics`] covers the counters and events it records,
 //! [`property`] covers the prefix and relativisation invariants the fixed
-//! cases are examples of, [`base`] covers the injected base directory that
-//! anchors relative patterns, and [`base::property`] exercises those anchoring
-//! invariants through the production [`super::glob_paths`] boundary across
-//! arbitrary safe nesting.
+//! cases are examples of, [`identity`] pins the returned spelling of Unix
+//! filenames that contain a literal backslash, [`base`] covers the injected
+//! base directory that anchors relative patterns, and [`base::property`]
+//! exercises those anchoring invariants through the production
+//! [`super::glob_paths`] boundary across arbitrary safe nesting.
 
 mod base;
 mod capability;
 mod diagnostics;
 mod expansion;
+mod identity;
 mod pattern;
 mod property;