fix(hir): honor lexical fetch bindings

changelog.d/10887-node-fetch-shadowed-global.md

@@ -0,0 +1,3 @@
+Fixed calls through a lexical `fetch` binding, including node-fetch's default
+export, being mistaken for the global Web Fetch API and routing the returned
+userland response through native response-handle methods.

crates/perry-hir/src/destructuring/helpers.rs

@@ -36,12 +36,24 @@ pub(crate) fn collect_static_object_pattern_keys(props: &[ast::ObjectPatProp]) -
 /// (Without narrowing the access went through generic PropertyGet → handle
 /// dispatch → js_fetch_response_status, so the bug only surfaced inside an
 /// `if r !== null/undefined` block.)
-pub(crate) fn get_fetch_module(expr: &ast::Expr) -> Option<&'static str> {
+pub(crate) fn get_fetch_module(
+    ctx: &crate::lower::LoweringContext,
+    expr: &ast::Expr,
+) -> Option<&'static str> {
     if let ast::Expr::Call(call_expr) = expr {
         if let ast::Callee::Expr(callee_expr) = &call_expr.callee {
             if let ast::Expr::Ident(ident) = callee_expr.as_ref() {
                 return match ident.sym.as_ref() {
-                    "fetch" | "fetchWithAuth" | "fetchPostWithAuth" => Some("fetch"),
+                    // A lexical `fetch` binding shadows the Web Fetch global.
+                    // In particular, node-fetch's default export is routinely
+                    // imported under this name; tagging its Promise result as
+                    // a native Response reroutes `response.text()` into the
+                    // native handle FFI and rejects with "Invalid response
+                    // handle". The named helper conventions below are Perry's
+                    // explicit wrappers and intentionally retain their native
+                    // result contract.
+                    "fetch" if !ctx.shadows_unqualified_global("fetch") => Some("fetch"),
+                    "fetchWithAuth" | "fetchPostWithAuth" => Some("fetch"),
                     _ => None,
                 };
             }

crates/perry-hir/src/destructuring/var_decl/native_fetch.rs

@@ -189,7 +189,7 @@ pub(crate) fn register_native_fetch_and_streams(
         }
 
         // Check for: const response = fetch(url) / fetchWithAuth(url, auth) / fetchPostWithAuth(url, auth, body)
-        if let Some(module) = get_fetch_module(init_expr) {
+        if let Some(module) = get_fetch_module(ctx, init_expr) {
             ctx.register_native_instance(
                 name.to_string(),
                 module.to_string(),
@@ -198,7 +198,7 @@ pub(crate) fn register_native_fetch_and_streams(
         }
         // Check for: const response = await fetch(url) / await fetchWithAuth(...) / await fetchPostWithAuth(...)
         else if let ast::Expr::Await(await_expr) = init_expr.as_ref() {
-            if let Some(module) = get_fetch_module(&await_expr.arg) {
+            if let Some(module) = get_fetch_module(ctx, &await_expr.arg) {
                 ctx.register_native_instance(
                     name.to_string(),
                     module.to_string(),

crates/perry-hir/src/lower/tests.rs

@@ -15,6 +15,27 @@ fn make_ctx() -> LoweringContext {
     LoweringContext::new("test.ts")
 }
 
+#[test]
+fn a_lexical_fetch_result_is_not_registered_as_a_native_response() {
+    let source = r#"
+        function fetch(_url: string) {
+            return Promise.resolve({ text() { return "userland"; } });
+        }
+        async function run() {
+            const response = await fetch("http://localhost/");
+            return response.text();
+        }
+    "#;
+    let module = perry_parser::parse_typescript(source, "fetch-shadow.ts").expect("source parses");
+    let hir =
+        super::lower_module(&module, "fetch-shadow", "fetch-shadow.ts").expect("source lowers");
+    let dump = format!("{hir:?}");
+    assert!(
+        !dump.contains("NativeMethodCall { module: \"fetch\", class_name: Some(\"Response\")"),
+        "a lexical fetch function must keep userland Response dispatch: {dump}"
+    );
+}
+
 mod instanceof_rhs;
 mod literal_shape;