fix(assembly-syntax): properly handle quoted path components (#2618)

Prior to this commit, when constructing PathBufs from a string
containing quoted components would improperly strip the quotes from
those components, which would result in later iteration over components
of that path treating that part of the path as unquoted. For example,
given the following path string:

`root:root_ns@1.0.0::module::"function::with::quoted::symbol_name"`

Constructing a PathBuf from this string would succeed as expected,
but would encode the path internally as if it had been passed as:

`root:root_ns@1.0.0::module::function::with::quoted::symbol_name`

If we later iterate over components of the path, the part that should
have been treated as a single component, i.e.
`"function::with::quoted::symbol_name`, would instead be treated as
multiple components, e.g. `function`, `with`, `quoted`, and
`symbol_name`.

This commit changes how we handle quoted components in the Components
iterator, so that the quotes are preserved.

Additionally, a new `PathBuf::push_component` method was added, which
allows one to explicitly push a string as a quoted component, ensuring
the component is quoted if not already.

A regression test was added that covers the case where this was
discovered, and further ensures that constructing a PathBuf from a
single string, or building it up via `push_component` produce identical
results.

A related issue was also identified and fixed, namely that internally
the Components iterator was not consuming trailing/leading path
separators after parsing a quoted component, causing unexpected results 
when using `Components::as_path`. This has been fixed, making the
behavior consistent across both quoted and unquoted identifiers.

Author: bitwalker

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.20.4 (Unreleased)
+
+- Fixed issue with handling of quoted components in `PathBuf` [#2618](https://github.com/0xMiden/miden-vm/pull/2618)
+
 ## 0.20.3 (2026-01-27)
 
 - Fixed issue where exports of a Library did not have attributes serialized [#2608](https://github.com/0xMiden/miden-vm/issues/2608)

crates/assembly-syntax/src/ast/path/components.rs

@@ -48,6 +48,16 @@ impl<'a> PathComponent<'a> {
             Self::Normal(id) => id.chars().count(),
         }
     }
+
+    /// Returns true if this path component is a quoted string
+    pub fn is_quoted(&self) -> bool {
+        matches!(self, Self::Normal(component) if component.starts_with('"') && component.ends_with('"'))
+    }
+
+    /// Returns true if this path component requires quoting when displayed/stored as a string
+    pub fn requires_quoting(&self) -> bool {
+        matches!(self, Self::Normal(component) if component.contains("::"))
+    }
 }
 
 impl PartialEq<str> for PathComponent<'_> {
@@ -72,17 +82,25 @@ impl fmt::Display for PathComponent<'_> {
 /// Returns an iterator over the path components represented in the provided source.
 ///
 /// A path consists of at list of components separated by `::` delimiter. A path must contain
-/// at least one component.
+/// at least one component. Path components may be quoted, in which `::` delimiters are ignored.
+/// Quoted path components may also contain characters that are not otherwise valid identifiers in
+/// Miden Assembly.
+///
+/// Note that quoted components may not contain nested quotes - the appearance of a nested quote in
+/// a quoted component will be treated as a closing quote resulting in unexpected behavior or
+/// validation errors as a result.
 ///
 /// # Errors
 ///
 /// Returns an error if:
 ///
 /// * The path is empty.
 /// * Any component of the path is empty.
-/// * Any component is not a valid identifier (quoted or unquoted) in Miden Assembly syntax, i.e.
-///   starts with an ASCII alphabetic character, contains only printable ASCII characters, except
-///   for `::`, which must only be used as a path separator.
+/// * Any quoted component is missing a closing/opening quote (depending on order of iteration)
+/// * Any unquoted component is not a valid identifier (quoted or unquoted) in Miden Assembly
+///   syntax, i.e. starts with an ASCII alphabetic character, contains only printable ASCII
+///   characters, except for `::`, which must only be used as a path separator.
+#[derive(Debug)]
 pub struct Iter<'a> {
     components: Components<'a>,
 }
@@ -92,7 +110,10 @@ impl<'a> Iter<'a> {
         Self {
             components: Components {
                 path,
+                original: path,
+                front_pos: 0,
                 front: State::Start,
+                back_pos: path.len(),
                 back: State::Body,
             },
         }
@@ -139,12 +160,16 @@ impl<'a> DoubleEndedIterator for Iter<'a> {
 }
 
 /// The underlying path component iterator used by [Iter]
+#[derive(Debug)]
 struct Components<'a> {
+    original: &'a str,
     /// The path left to parse components from
     path: &'a str,
     // To support double-ended iteration, these states keep tack of what has been produced from
     // each end
+    front_pos: usize,
     front: State,
+    back_pos: usize,
     back: State,
 }
 
@@ -155,9 +180,9 @@ enum State {
     // We're parsing components of the path
     Body,
     // We've started parsing a quoted component
-    QuoteOpened,
+    QuoteOpened(usize),
     // We've parsed a quoted component
-    QuoteClosed,
+    QuoteClosed(usize),
     // We're at the end of the path
     Done,
 }
@@ -167,7 +192,7 @@ impl<'a> Components<'a> {
         match (self.front, self.back) {
             (State::Done, _) => true,
             (_, State::Done) => true,
-            (State::Body | State::QuoteOpened | State::QuoteClosed, State::Start) => true,
+            (State::Body | State::QuoteOpened(_) | State::QuoteClosed(_), State::Start) => true,
             (..) => false,
         }
     }
@@ -177,12 +202,17 @@ impl<'a> Iterator for Components<'a> {
     type Item = Result<PathComponent<'a>, PathError>;
 
     fn next(&mut self) -> Option<Self::Item> {
-        while !self.finished() {
+        // This is used when consuming a quoted item, to hold the result of the QuoteOpened state
+        // until we've finished transitioning through the QuoteClosed state. It is never used
+        // otherwise.
+        let mut quote_opened = None;
+        while !self.finished() || quote_opened.is_some() {
             match self.front {
                 State::Start => match self.path.strip_prefix("::") {
                     Some(rest) => {
                         self.path = rest;
                         self.front = State::Body;
+                        self.front_pos += 2;
                         return Some(Ok(PathComponent::Root));
                     },
                     None if self.path.starts_with(Path::KERNEL_PATH)
@@ -197,18 +227,21 @@ impl<'a> Iterator for Components<'a> {
                 },
                 State::Body => {
                     if let Some(rest) = self.path.strip_prefix('"') {
-                        self.front = State::QuoteOpened;
+                        self.front = State::QuoteOpened(self.front_pos);
+                        self.front_pos += 1;
                         self.path = rest;
                         continue;
                     }
                     match self.path.split_once("::") {
                         Some(("", rest)) => {
                             self.path = rest;
+                            self.front_pos += 2;
                             return Some(Err(PathError::InvalidComponent(
                                 crate::ast::IdentError::Empty,
                             )));
                         },
                         Some((component, rest)) => {
+                            self.front_pos += component.len() + 2;
                             if rest.is_empty() {
                                 self.path = "::";
                             } else {
@@ -233,40 +266,55 @@ impl<'a> Iterator for Components<'a> {
                             {
                                 return Some(Err(err));
                             }
+                            self.front_pos += component.len();
                             return Some(Ok(PathComponent::Normal(component)));
                         },
                     }
                 },
-                State::QuoteOpened => match self.path.split_once('"') {
+                State::QuoteOpened(opened_at) => match self.path.split_once('"') {
                     Some(("", rest)) => {
                         self.path = rest;
-                        self.front = State::QuoteClosed;
-                        return Some(Err(PathError::EmptyComponent));
+                        self.front = State::QuoteClosed(self.front_pos);
+                        self.front_pos += 1;
+                        quote_opened = Some(Err(PathError::EmptyComponent));
                     },
                     Some((quoted, rest)) => {
                         self.path = rest;
-                        self.front = State::QuoteClosed;
-                        return Some(Ok(PathComponent::Normal(quoted)));
+                        self.front_pos += quoted.len();
+                        self.front = State::QuoteClosed(self.front_pos);
+                        self.front_pos += 1;
+                        let quoted = &self.original[opened_at..self.front_pos];
+                        quote_opened = Some(Ok(PathComponent::Normal(quoted)));
                     },
                     None => {
                         self.front = State::Done;
+                        self.front_pos += self.path.len();
                         return Some(Err(PathError::UnclosedQuotedComponent));
                     },
                 },
-                State::QuoteClosed => {
+                State::QuoteClosed(_) => {
                     if self.path.is_empty() {
                         self.front = State::Done;
-                        continue;
+                    } else {
+                        match self.path.strip_prefix("::") {
+                            Some(rest) => {
+                                self.path = rest;
+                                self.front = State::Body;
+                                self.front_pos += 2;
+                            },
+                            // If we would raise an error, but we have a quoted component to return
+                            // first, leave the state untouched, return the quoted component, and we
+                            // will return here on the next call to `next_back`
+                            None if quote_opened.is_some() => (),
+                            None => {
+                                self.front = State::Done;
+                                return Some(Err(PathError::MissingPathSeparator));
+                            },
+                        }
                     }
-                    match self.path.strip_prefix("::") {
-                        Some(rest) => {
-                            self.path = rest;
-                            self.front = State::Body;
-                        },
-                        None => {
-                            self.front = State::Done;
-                            return Some(Err(PathError::MissingPathSeparator));
-                        },
+
+                    if quote_opened.is_some() {
+                        return quote_opened;
                     }
                 },
                 State::Done => break,
@@ -279,13 +327,20 @@ impl<'a> Iterator for Components<'a> {
 
 impl<'a> DoubleEndedIterator for Components<'a> {
     fn next_back(&mut self) -> Option<Self::Item> {
-        while !self.finished() {
+        // This is used when consuming a quoted item, to hold the result of the QuoteClosed state
+        // until we've finished transitioning through the QuoteOpened state. It is never used
+        // otherwise.
+        let mut quote_closed = None;
+        while !self.finished() || quote_closed.is_some() {
             match self.back {
                 State::Start => {
                     self.back = State::Done;
                     match self.path {
                         "" => break,
-                        "::" => return Some(Ok(PathComponent::Root)),
+                        "::" => {
+                            self.back_pos = 0;
+                            return Some(Ok(PathComponent::Root));
+                        },
                         other => {
                             assert!(
                                 other.starts_with(Path::KERNEL_PATH)
@@ -298,16 +353,19 @@ impl<'a> DoubleEndedIterator for Components<'a> {
                 },
                 State::Body => {
                     if let Some(rest) = self.path.strip_suffix('"') {
-                        self.back = State::QuoteClosed;
+                        self.back = State::QuoteClosed(self.back_pos);
+                        self.back_pos -= 1;
                         self.path = rest;
                         continue;
                     }
                     match self.path.rsplit_once("::") {
                         Some(("", "")) => {
                             self.back = State::Start;
+                            self.back_pos -= 2;
                             continue;
                         },
                         Some((prefix, component)) => {
+                            self.back_pos -= component.len() + 2;
                             if prefix.is_empty() {
                                 self.path = "::";
                                 self.back = State::Start;
@@ -334,6 +392,7 @@ impl<'a> DoubleEndedIterator for Components<'a> {
                             } else {
                                 self.path = "";
                             }
+                            self.back_pos = 0;
                             if let Err(err) =
                                 Ident::validate(component).map_err(PathError::InvalidComponent)
                             {
@@ -343,38 +402,52 @@ impl<'a> DoubleEndedIterator for Components<'a> {
                         },
                     }
                 },
-                State::QuoteOpened => {
+                State::QuoteOpened(_) => {
                     if self.path.is_empty() {
                         self.back = State::Start;
-                        continue;
+                    } else {
+                        match self.path.strip_suffix("::") {
+                            Some("") => {
+                                self.back = State::Start;
+                                self.back_pos -= 2;
+                            },
+                            Some(rest) => {
+                                self.back_pos -= 2;
+                                self.path = rest;
+                                self.back = State::Body;
+                            },
+                            // If we would raise an error, but we have a quoted component to return
+                            // first, leave the state untouched, return the quoted component, and we
+                            // will return here on the next call to `next_back`
+                            None if quote_closed.is_some() => (),
+                            None => {
+                                self.back = State::Done;
+                                return Some(Err(PathError::MissingPathSeparator));
+                            },
+                        }
                     }
-                    match self.path.strip_suffix("::") {
-                        Some("") => {
-                            self.back = State::Start;
-                        },
-                        Some(rest) => {
-                            self.path = rest;
-                            self.back = State::Body;
-                        },
-                        None => {
-                            self.back = State::Done;
-                            return Some(Err(PathError::MissingPathSeparator));
-                        },
+
+                    if quote_closed.is_some() {
+                        return quote_closed;
                     }
                 },
-                State::QuoteClosed => match self.path.rsplit_once('"') {
+                State::QuoteClosed(closed_at) => match self.path.rsplit_once('"') {
                     Some((rest, "")) => {
+                        self.back_pos -= 1;
                         self.path = rest;
-                        self.back = State::QuoteOpened;
-                        return Some(Err(PathError::EmptyComponent));
+                        self.back = State::QuoteOpened(self.back_pos);
+                        quote_closed = Some(Err(PathError::EmptyComponent));
                     },
                     Some((rest, quoted)) => {
+                        self.back_pos -= quoted.len() + 1;
+                        let quoted = &self.original[self.back_pos..closed_at];
                         self.path = rest;
-                        self.back = State::QuoteOpened;
-                        return Some(Ok(PathComponent::Normal(quoted)));
+                        self.back = State::QuoteOpened(self.back_pos);
+                        quote_closed = Some(Ok(PathComponent::Normal(quoted)));
                     },
                     None => {
                         self.back = State::Done;
+                        self.back_pos = 0;
                         return Some(Err(PathError::UnclosedQuotedComponent));
                     },
                 },
@@ -518,29 +591,29 @@ mod tests {
     #[test]
     fn path_with_quoted_component() {
         let mut components = Iter::new("\"foo\"");
-        assert_matches!(components.next(), Some(Ok(PathComponent::Normal("foo"))));
+        assert_matches!(components.next(), Some(Ok(PathComponent::Normal("\"foo\""))));
         assert_matches!(components.next(), None);
     }
 
     #[test]
     fn path_with_quoted_component_back() {
         let mut components = Iter::new("\"foo\"");
-        assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("foo"))));
+        assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("\"foo\""))));
         assert_matches!(components.next_back(), None);
     }
 
     #[test]
     fn nested_path_with_quoted_component() {
         let mut components = Iter::new("foo::\"bar\"");
         assert_matches!(components.next(), Some(Ok(PathComponent::Normal("foo"))));
-        assert_matches!(components.next(), Some(Ok(PathComponent::Normal("bar"))));
+        assert_matches!(components.next(), Some(Ok(PathComponent::Normal("\"bar\""))));
         assert_matches!(components.next(), None);
     }
 
     #[test]
     fn nested_path_with_quoted_component_back() {
         let mut components = Iter::new("foo::\"bar\"");
-        assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("bar"))));
+        assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("\"bar\""))));
         assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("foo"))));
         assert_matches!(components.next_back(), None);
     }
@@ -549,7 +622,7 @@ mod tests {
     fn nested_path_with_interspersed_quoted_component() {
         let mut components = Iter::new("foo::\"bar\"::baz");
         assert_matches!(components.next(), Some(Ok(PathComponent::Normal("foo"))));
-        assert_matches!(components.next(), Some(Ok(PathComponent::Normal("bar"))));
+        assert_matches!(components.next(), Some(Ok(PathComponent::Normal("\"bar\""))));
         assert_matches!(components.next(), Some(Ok(PathComponent::Normal("baz"))));
         assert_matches!(components.next(), None);
     }
@@ -558,7 +631,7 @@ mod tests {
     fn nested_path_with_interspersed_quoted_component_back() {
         let mut components = Iter::new("foo::\"bar\"::baz");
         assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("baz"))));
-        assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("bar"))));
+        assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("\"bar\""))));
         assert_matches!(components.next_back(), Some(Ok(PathComponent::Normal("foo"))));
         assert_matches!(components.next_back(), None);
     }