Add SourceMap::resolve_span for resolving global span locations (#2559)

* Add resolve_span

* Make doc shorter

* fmt

* Shorten doc

* Simplify downcasting in tests

Author: PhoebeSzmucer

crates/wit-parser/src/ast.rs

@@ -1946,6 +1946,29 @@ impl SourceMap {
         return msg;
     }
 
+    /// Resolves a global `span` to a location within a single source file.
+    ///
+    /// Returns the path the source was registered with and the span's byte
+    /// range (UTF-8) relative to that file's contents. Returns `None` if
+    /// `span` is unknown or does not fall within any source in this map.
+    pub fn resolve_span(&self, span: Span) -> Option<SpanLocation<'_>> {
+        if !span.is_known() || span.start() >= self.offset {
+            return None;
+        }
+        let src = self.source_for_offset(span.start());
+        // Exclude the synthetic `\n` appended by `push_str` so that spans
+        // pointing at eof resolve to an empty range at the end of the file.
+        let len = src.contents.len() - 1;
+        let start = src.to_relative_offset(span.start()).min(len);
+        let end = usize::try_from(span.end().saturating_sub(src.offset))
+            .unwrap()
+            .clamp(start, len);
+        Some(SpanLocation {
+            path: &src.path,
+            range: start..end,
+        })
+    }
+
     /// Renders a span as a human-readable location string (e.g., "file.wit:10:5").
     pub fn render_location(&self, span: Span) -> String {
         if !span.is_known() {
@@ -1983,6 +2006,15 @@ impl SourceMap {
     }
 }
 
+/// A [`Span`] resolved to a location within a single source file.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SpanLocation<'a> {
+    /// The path of the source, as it was registered with the [`SourceMap`].
+    pub path: &'a str,
+    /// The byte range (UTF-8) within the file's contents.
+    pub range: core::ops::Range<usize>,
+}
+
 impl Source {
     fn to_relative_offset(&self, offset: u32) -> usize {
         usize::try_from(offset - self.offset).unwrap()

crates/wit-parser/src/lib.rs

@@ -44,7 +44,7 @@ pub mod abi;
 mod ast;
 pub use ast::error::*;
 pub use ast::lex::Span;
-pub use ast::{ItemName, SourceMap};
+pub use ast::{ItemName, SourceMap, SpanLocation};
 pub use ast::{ParsedUsePath, parse_use_path};
 mod sizealign;
 pub use sizealign::*;

crates/wit-parser/tests/downcast.rs

@@ -6,15 +6,14 @@ use wit_parser::{
     ParseError, ParseErrorKind, Resolve, ResolveError, ResolveErrorKind, UnresolvedPackageGroup,
 };
 
-fn outer_resolve_error(err: &anyhow::Error) -> &ResolveError {
+fn resolve_error(err: &anyhow::Error) -> &ResolveError {
     err.downcast_ref::<ResolveError>()
-        .expect("expected the outermost error to be a ResolveError")
+        .expect("expected error to downcast to ResolveError")
 }
 
-fn parse_error_in_chain(err: &anyhow::Error) -> &ParseError {
-    err.chain()
-        .find_map(|layer| layer.downcast_ref::<ParseError>())
-        .expect("expected a ParseError somewhere in the error chain")
+fn parse_error(err: &anyhow::Error) -> &ParseError {
+    err.downcast_ref::<ParseError>()
+        .expect("expected error to downcast to ParseError")
 }
 
 #[test]
@@ -26,7 +25,7 @@ fn push_str_returns_downcastable_error() {
             "package foo:foo;\nworld w { import some:dependency/iface; }",
         )
         .expect_err("expected resolve to fail");
-    let re = outer_resolve_error(&err);
+    let re = resolve_error(&err);
     assert!(
         matches!(re.kind(), ResolveErrorKind::PackageNotFound { .. }),
         "expected PackageNotFound, got: {:?}",
@@ -40,7 +39,7 @@ fn push_file_returns_downcastable_error() {
     let err = resolve
         .push_file("tests/ui/parse-fail/unresolved-interface4.wit")
         .expect_err("expected resolve to fail");
-    let re = outer_resolve_error(&err);
+    let re = resolve_error(&err);
     assert!(
         matches!(re.kind(), ResolveErrorKind::PackageNotFound { .. }),
         "expected PackageNotFound, got: {:?}",
@@ -54,7 +53,7 @@ fn push_dir_returns_downcastable_error() {
     let err = resolve
         .push_dir("tests/ui/parse-fail/bad-pkg6")
         .expect_err("expected resolve to fail");
-    let re = outer_resolve_error(&err);
+    let re = resolve_error(&err);
     assert!(
         matches!(re.kind(), ResolveErrorKind::PackageNotFound { .. }),
         "expected PackageNotFound, got: {:?}",
@@ -68,7 +67,7 @@ fn push_str_parse_error_is_downcastable() {
     let err = resolve
         .push_str("test.wit", "package foo:foo;\nworld w { not-a-keyword }")
         .expect_err("expected parse to fail");
-    let pe = parse_error_in_chain(&err);
+    let pe = parse_error(&err);
     // Spans must be valid against `resolve.source_map` after the failure-path
     // merge, so highlighting against it should not panic and should include
     // the file and line.
@@ -99,7 +98,7 @@ fn parse_error_spans_are_adjusted_after_earlier_pushes() {
             "package foo:second;\nworld w { not-a-keyword }",
         )
         .expect_err("expected parse to fail");
-    let pe = parse_error_in_chain(&err);
+    let pe = parse_error(&err);
     // The failing package's sources land at a nonzero offset in
     // `resolve.source_map` because `first.wit` was merged before it, so this
     // only points at the right file and line if the error's spans were
@@ -121,14 +120,14 @@ fn push_file_parse_error_is_downcastable() {
     let err = resolve
         .push_file("tests/ui/parse-fail/bad-function.wit")
         .expect_err("expected parse to fail");
-    parse_error_in_chain(&err);
+    parse_error(&err);
 }
 
 #[test]
 fn parse_dir_parse_error_is_downcastable() {
     let err = UnresolvedPackageGroup::parse_dir("tests/ui/parse-fail/multi-file-missing-delimiter")
         .expect_err("expected parse to fail");
-    parse_error_in_chain(&err);
+    parse_error(&err);
     // The source map is discarded on failure, but the rendered location must
     // be preserved in the error's message.
     assert!(

crates/wit-parser/tests/spans.rs

@@ -0,0 +1,73 @@
+//! Tests for `SourceMap::resolve_span`, which resolves a global `Span` to a
+//! file path and file-local byte range.
+
+use wit_parser::{ParseError, Resolve, SourceMap, UnresolvedPackageGroup};
+
+#[test]
+fn resolve_span_in_single_file() {
+    let contents = "package foo:foo;\nworld w { not-a-keyword }";
+    let (map, err) =
+        UnresolvedPackageGroup::parse("test.wit", contents).expect_err("expected parse to fail");
+    let loc = map
+        .resolve_span(err.kind().span())
+        .expect("span should resolve");
+    assert_eq!(loc.path, "test.wit");
+    assert_eq!(&contents[loc.range.clone()], "not-a-keyword");
+}
+
+#[test]
+fn resolve_span_in_second_file() {
+    let mut map = SourceMap::default();
+    map.push_str("a.wit", "package foo:foo;\ninterface a {}\n");
+    let b = "interface b { type t = nonexistent; }";
+    map.push_str("b.wit", b);
+    let (map, err) = map.parse().expect_err("expected parse to fail");
+    let loc = map
+        .resolve_span(err.kind().span())
+        .expect("span should resolve");
+    assert_eq!(loc.path, "b.wit");
+    assert_eq!(&b[loc.range.clone()], "nonexistent");
+}
+
+#[test]
+fn resolve_span_at_eof() {
+    let contents = "package foo:foo;\nworld w {";
+    let (map, err) =
+        UnresolvedPackageGroup::parse("test.wit", contents).expect_err("expected parse to fail");
+    let loc = map
+        .resolve_span(err.kind().span())
+        .expect("span should resolve");
+    assert_eq!(loc.path, "test.wit");
+    // The source map appends a synthetic newline internally and eof spans
+    // point at it; they must resolve to an empty range at the real length.
+    assert_eq!(loc.range, contents.len()..contents.len());
+}
+
+#[test]
+fn resolve_span_not_in_map() {
+    let contents = "package foo:foo;\nworld w { not-a-keyword }";
+    let (_, err) =
+        UnresolvedPackageGroup::parse("test.wit", contents).expect_err("expected parse to fail");
+    let other = SourceMap::default();
+    assert!(other.resolve_span(err.kind().span()).is_none());
+}
+
+#[test]
+fn resolve_span_against_resolve_source_map() {
+    let mut resolve = Resolve::new();
+    let contents = "package foo:foo;\nworld w { not-a-keyword }";
+    let err = resolve
+        .push_str("test.wit", contents)
+        .expect_err("expected parse to fail");
+    let pe = err
+        .downcast_ref::<ParseError>()
+        .expect("expected error to downcast to ParseError");
+    // The failure-path merge keeps spans valid against `resolve.source_map`,
+    // so resolution against it must find the right file and range.
+    let loc = resolve
+        .source_map
+        .resolve_span(pe.kind().span())
+        .expect("span should resolve");
+    assert_eq!(loc.path, "test.wit");
+    assert_eq!(&contents[loc.range.clone()], "not-a-keyword");
+}