fix(ext/web): friendlier URLPattern construction errors (#35102)

## Problem

When `URLPattern` construction fails, the underlying
[`urlpattern`](https://crates.io/crates/urlpattern) crate surfaces an
opaque message with no indication of which input value was bad or how to
fix it. The common trigger (reported in #25965) is a file-router route
like Fresh's `[:slug].tsx`, which expands to a `::slug` pathname:

```
error: Uncaught (in promise) TypeError: tokenizer error: invalid name; must be at least length 1 (at char 1)
        path: new URLPattern({ pathname }),
```

You can't tell from that which component (`pathname`) was at fault, what
its value was, or what to do about it.

## Change

Enrich the error thrown from `op_urlpattern_parse`
(`ext/web/urlpattern.rs`):

- Echo the offending component value.
- Point a caret at the failing character — only for init objects with a
single component set, since the crate's reported position is relative to
a single parsed component string, not the whole constructor string.
- Add a hint for the most common mistake: a `:` that does not start a
valid named group.

For `new URLPattern({ pathname: "/::slug" })` the message is now:

```
Failed to parse pathname from "/::slug": tokenizer error: invalid name; must be at least length 1 (at char 1)

  /::slug
   ^

  hint: ":" starts a named group and must be followed by a name (a letter or "_", then letters, digits or "_"). To match a literal ":", escape it as "\:".
```

Valid patterns are unaffected, and the existing crate message is
preserved as the leading line so nothing that parsed it loses
information.

## Tests

Added unit tests in `tests/unit/urlpattern_test.ts` covering both the
init-object (with caret) and constructor-string (no caret) paths. WPT
`urlpattern` tests assert only on the thrown error *type*, not its
message, so they are unaffected.

Closes #25965

Closes denoland/divybot#542

Co-authored-by: divybot <divybot@users.noreply.github.com>
Co-authored-by: Divy Srivastava <me@littledivy.com>

Author: divybot

ext/web/urlpattern.rs

@@ -4,8 +4,99 @@ use deno_core::op2;
 use serde::Serialize;
 use urlpattern::quirks;
 use urlpattern::quirks::StringOrInit;
+use urlpattern::quirks::UrlPatternInit;
 
-deno_error::js_error_wrapper!(urlpattern::Error, UrlPatternError, "TypeError");
+#[derive(Debug, thiserror::Error, deno_error::JsError)]
+#[class(type)]
+#[error("{0}")]
+pub struct UrlPatternError(String);
+
+impl From<urlpattern::Error> for UrlPatternError {
+  fn from(err: urlpattern::Error) -> Self {
+    UrlPatternError(err.to_string())
+  }
+}
+
+/// Turns an opaque `urlpattern` crate error into an actionable message by
+/// echoing the offending pattern, pointing a caret at the failing character,
+/// and adding a hint for the most common mistake (a `:` that does not start a
+/// valid named group, e.g. file-router syntax like `[:slug]`).
+fn enrich_url_pattern_error(
+  err: urlpattern::Error,
+  input: &StringOrInit,
+) -> UrlPatternError {
+  let message = err.to_string();
+
+  // Tokenizer errors carry the (char) position of the offending token.
+  let pos = match err {
+    urlpattern::Error::Tokenizer(_, pos) => Some(pos),
+    _ => None,
+  };
+
+  // Determine which pattern string the error refers to, and whether the
+  // reported position reliably indexes into it. The crate parses each URL
+  // component separately, so `pos` is relative to a single component string.
+  // For an init object with exactly one component set we can attribute the
+  // error to it and render a caret. For a constructor string `pos` is relative
+  // to whichever component the string expanded to, not the whole string, so we
+  // echo the input but cannot place a caret.
+  let (pattern, caret_pos) = match input {
+    StringOrInit::String(s) => (Some(("URLPattern", s.as_str())), None),
+    StringOrInit::Init(init) => (single_init_component(init), pos),
+  };
+
+  let Some((name, pattern)) = pattern else {
+    return UrlPatternError(message);
+  };
+
+  let mut out = format!("Failed to parse {name} from \"{pattern}\": {message}");
+
+  if let Some(pos) = caret_pos {
+    out.push_str("\n\n  ");
+    out.push_str(pattern);
+    out.push_str("\n  ");
+    // `pos` is a count of chars; pattern inputs are practically ASCII, so a
+    // space per preceding char aligns the caret under the offending one.
+    for _ in 0..pos {
+      out.push(' ');
+    }
+    out.push('^');
+  }
+
+  if message.contains("invalid name") {
+    out.push_str(
+      "\n\n  hint: \":\" starts a named group and must be followed by a name \
+       (a letter or \"_\", then letters, digits or \"_\"). To match a literal \
+       \":\", escape it as \"\\:\".",
+    );
+  }
+
+  UrlPatternError(out)
+}
+
+/// Returns the single set component of a `UrlPatternInit` (with its field name),
+/// or `None` if zero or more than one component is set.
+fn single_init_component(
+  init: &UrlPatternInit,
+) -> Option<(&'static str, &str)> {
+  let components: [(&'static str, &Option<String>); 8] = [
+    ("protocol", &init.protocol),
+    ("username", &init.username),
+    ("password", &init.password),
+    ("hostname", &init.hostname),
+    ("port", &init.port),
+    ("pathname", &init.pathname),
+    ("search", &init.search),
+    ("hash", &init.hash),
+  ];
+  let mut set = components
+    .iter()
+    .filter_map(|(name, value)| value.as_deref().map(|value| (*name, value)));
+  match (set.next(), set.next()) {
+    (Some(only), None) => Some(only),
+    _ => None,
+  }
+}
 
 /// Lean version of UrlPatternComponent that excludes the unused `matcher` field.
 #[derive(Serialize)]
@@ -49,9 +140,11 @@ pub fn op_urlpattern_parse(
   #[serde] options: urlpattern::UrlPatternOptions,
 ) -> Result<UrlPatternResult, UrlPatternError> {
   let init =
-    quirks::process_construct_pattern_input(input, base_url.as_deref())?;
+    quirks::process_construct_pattern_input(input.clone(), base_url.as_deref())
+      .map_err(|e| enrich_url_pattern_error(e, &input))?;
 
-  let pattern = quirks::parse_pattern(init, options)?;
+  let pattern = quirks::parse_pattern(init, options)
+    .map_err(|e| enrich_url_pattern_error(e, &input))?;
 
   Ok(UrlPatternResult {
     protocol: pattern.protocol.into(),

tests/unit/urlpattern_test.ts

@@ -1,5 +1,5 @@
 // Copyright 2018-2026 the Deno authors. MIT license.
-import { assert, assertEquals } from "./test_util.ts";
+import { assert, assertEquals, assertThrows } from "./test_util.ts";
 import { assertType, IsExact } from "@std/testing/types";
 
 Deno.test(function urlPatternFromString() {
@@ -73,3 +73,41 @@ Deno.test(function urlPatternIgnoreCase() {
   assert(p.test("/test", "http://localhost"));
   assert(p.test("/TeSt", "http://localhost"));
 });
+
+Deno.test(function urlPatternInvalidNameError() {
+  // A ":" not followed by a valid group name (e.g. file-router syntax such as
+  // `[:slug]` expanding to `::slug`) should produce an actionable error that
+  // echoes the offending component, points a caret at it, and includes a hint.
+  const err = assertThrows(
+    () => new URLPattern({ pathname: "/::slug" }),
+    TypeError,
+  ) as TypeError;
+  assert(
+    err.message.includes('Failed to parse pathname from "/::slug"'),
+    `missing component context: ${err.message}`,
+  );
+  assert(err.message.includes("^"), `missing caret: ${err.message}`);
+  assert(
+    err.message.includes('hint: ":" starts a named group'),
+    `missing hint: ${err.message}`,
+  );
+});
+
+Deno.test(function urlPatternInvalidNameErrorFromString() {
+  // For a constructor string we cannot reliably map the position back to the
+  // full input, but the input and hint should still be surfaced.
+  const err = assertThrows(
+    () => new URLPattern("https://example.com/::slug"),
+    TypeError,
+  ) as TypeError;
+  assert(
+    err.message.includes(
+      'Failed to parse URLPattern from "https://example.com/::slug"',
+    ),
+    `missing input context: ${err.message}`,
+  );
+  assert(
+    err.message.includes('hint: ":" starts a named group'),
+    `missing hint: ${err.message}`,
+  );
+});