docs(semantic): document with statement limitation in is_global_reference

crates/oxc_semantic/src/is_global_reference.rs

@@ -2,7 +2,28 @@ use oxc_ast::ast::{Expression, IdentifierReference};
 
 use crate::{ReferenceId, Scoping};
 
-/// Checks whether the a identifier reference is a global value or not.
+/// Checks whether an identifier reference is a global value or not.
+///
+/// # Limitation: `with` statements
+///
+/// This check does not correctly handle references inside `with` statements.
+/// Inside a `with` block, unresolved references may resolve to properties of
+/// the `with` object at runtime, but this function will incorrectly return
+/// `true` for such references.
+///
+/// ```js
+/// const foo = { Object: class { /* ... */ } }
+/// with (foo) { console.log(new Object()) }
+/// //                           ^^^^^^ This `Object` is NOT a global reference,
+/// //                                  but `is_global_reference` returns `true`.
+/// ```
+///
+/// This is acceptable because:
+/// 1. `with` statements are forbidden in strict mode
+/// 2. Bundlers like Rolldown don't support `with` statements
+/// 3. The minifier bails out when `with` statements are present
+///
+/// See: <https://github.com/oxc-project/oxc/issues/8365>
 pub trait IsGlobalReference {
     fn is_global_reference(&self, scoping: &Scoping) -> bool;
     fn is_global_reference_name(&self, name: &str, scoping: &Scoping) -> bool;