Refactor stdlib path helpers

Cargo.toml

@@ -12,18 +12,25 @@ include = [
 ]
 license = "ISC"
 
+[features]
+default = []
+legacy-digests = ["sha1", "md5"]
+
 [dependencies]
 clap = { version = "4.5.0", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }
 serde_yml = "0.0.12"
-minijinja = "2.11.0"
+minijinja = { version = "2.11.0", features = ["loader"] }
 cap-std = { version = "3.4.4", features = ["fs_utf8"] }
-camino = "1.1.12"
+camino = "1.2.0"
 semver = { version = "1", features = ["serde"] }
 anyhow = "1"
 thiserror = "1"
 miette = { version = "7.6.0", features = ["fancy"] }
+digest = "0.10"
 sha2 = "0.10"
+sha1 = { version = "0.10", optional = true }
+md5 = { package = "md-5", version = "0.10", optional = true }
 itoa = "1"
 itertools = "0.12"
 glob = "0.3.3"

docs/netsuke-design.md

@@ -828,9 +828,9 @@ The `dir`, `file`, and `symlink` tests use `cap_std`'s UTF-8-capable
 operand's [`FileType`][filetype]. Because this lookup does not follow links,
 `symlink` tests never report a file or directory for the same path. On Unix the
 `pipe`, `block_device`, `char_device`, and legacy `device` tests also probe the
-metadata. On non-Unix targets only `pipe` and `device` are registered; both
-always return `false` so templates remain portable. Missing paths evaluate to
-`false`, while I/O errors raise a template error.
+metadata. On non-Unix targets these predicates are stubbed to always return
+`false` so templates remain portable. Missing paths evaluate to `false`, while
+I/O errors raise a template error.
 
 [cap-symlink]:
 https://docs.rs/cap-std/latest/cap_std/fs_utf8/struct.Dir.html#method.symlink_metadata
@@ -867,6 +867,27 @@ All built-in filters use `snake_case`. The `camel_case` helper is provided in
 place of `camelCase` so naming remains consistent with `snake_case` and
 `kebab-case`.
 
+Implementation notes:
+
+- Filters rely on `cap-std` directories opened with ambient authority for
+  file-system work. Callers must ensure that templates granted access to the
+  stdlib are trusted to read from the process' working tree.
+- `realpath` canonicalises the parent directory before joining the resolved
+  entry so results are absolute and symlink-free.
+- `contents` and `linecount` currently support UTF-8 input; other encodings are
+  rejected with an explicit error. `contents` streams data from the ambient
+  file-system, so consumers should guard access carefully when evaluating
+  untrusted templates.
+- `hash` and `digest` accept `sha256` (default) and `sha512`. Legacy
+  algorithms `sha1` and `md5` are cryptographically broken and are disabled by
+  default; enabling them requires the `legacy-digests` Cargo feature and should
+  only be done for compatibility with existing ecosystems.
+- `expanduser` mirrors shell semantics by inspecting `HOME`, `USERPROFILE`,
+  and on Windows the `HOMEDRIVE`/`HOMEPATH` or `HOMESHARE` fallbacks.
+  Platform-specific forms such as `~user` remain unsupported.
+- `with_suffix` removes dotted suffix segments (default `n = 1`) before
+  appending the provided suffix.
+
 #### Generic collection filters
 
 | Filter                            | Purpose                                      |

docs/roadmap.md

@@ -159,7 +159,7 @@ library, and CLI ergonomics.
   - [x] Implement the basic file-system tests (`dir`, `file`, `symlink`,
     `pipe`, `block_device`, `char_device`, legacy `device`). *(done)*
 
-  - [ ] Implement the path and file filters (basename, dirname, with_suffix,
+  - [x] Implement the path and file filters (basename, dirname, with_suffix,
     realpath, contents, hash, etc.).
 
   - [ ] Implement the generic collection filters (`uniq`, `flatten`,

src/ir/graph.rs

@@ -62,6 +62,7 @@ pub struct BuildEdge {
 ///
 /// ```
 /// use netsuke::ir::IrGenError;
+/// use serde::ser::Error as _;
 ///
 /// fn describe(err: IrGenError) -> String {
 ///     match err {
@@ -86,6 +87,7 @@ pub enum IrGenError {
     ///
     /// ```
     /// use netsuke::ir::IrGenError;
+    /// use serde::ser::Error as _;
     ///
     /// let err = IrGenError::RuleNotFound {
     ///     target_name: "app".into(),
@@ -107,6 +109,7 @@ pub enum IrGenError {
     ///
     /// ```
     /// use netsuke::ir::IrGenError;
+    /// use serde::ser::Error as _;
     ///
     /// let err = IrGenError::MultipleRules {
     ///     target_name: "lib".into(),
@@ -129,6 +132,7 @@ pub enum IrGenError {
     ///
     /// ```
     /// use netsuke::ir::IrGenError;
+    /// use serde::ser::Error as _;
     ///
     /// let err = IrGenError::EmptyRule { target_name: "docs".into() };
     /// assert_eq!(
@@ -143,6 +147,7 @@ pub enum IrGenError {
     ///
     /// ```
     /// use netsuke::ir::IrGenError;
+    /// use serde::ser::Error as _;
     ///
     /// let err = IrGenError::DuplicateOutput {
     ///     outputs: vec!["obj.o".into()],
@@ -162,6 +167,7 @@ pub enum IrGenError {
     /// ```
     /// use camino::Utf8PathBuf;
     /// use netsuke::ir::IrGenError;
+    /// use serde::ser::Error as _;
     ///
     /// let err = IrGenError::CircularDependency {
     ///     cycle: vec![Utf8PathBuf::from("a"), Utf8PathBuf::from("a")],
@@ -184,6 +190,7 @@ pub enum IrGenError {
     ///
     /// ```
     /// use netsuke::ir::IrGenError;
+    /// use serde::ser::Error as _;
     ///
     /// let source = serde_json::Error::custom("invalid action");
     /// let err = IrGenError::ActionSerialisation(source);
@@ -196,6 +203,7 @@ pub enum IrGenError {
     ///
     /// ```
     /// use netsuke::ir::IrGenError;
+    /// use serde::ser::Error as _;
     ///
     /// let err = IrGenError::InvalidCommand {
     ///     command: "echo $in".into(),