feat(lint): update docs & diagnostic for lint/nursery/noProto (#8414)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: Bertie690

.changeset/fast-spoons-float.md

@@ -0,0 +1,7 @@
+---
+"@biomejs/biome": patch
+---
+
+Updated the documentation & diagnostic message for `lint/nursery/noProto`, mentioning the reasons for its longstanding deprecation and why more modern alternatives are preferred.
+
+Notably, the rule clearly states that using `__proto__` inside object literal definitions is still allowed, being a standard way to set the prototype of a newly created object.

crates/biome_configuration/src/analyzer/linter/rules.rs

@@ -7,11 +7,27 @@ use biome_rowan::{AstNode, declare_node_union};
 use biome_rule_options::no_proto::NoProtoOptions;
 
 declare_lint_rule! {
-    /// Disallow the use of the `__proto__` property.
+    /// Disallow the use of the deprecated `__proto__` object property.
     ///
-    /// The use of `__proto__` for getting or setting the prototype of an object
-    /// is deprecated. Use `Object.getPrototypeOf()` or
-    /// `Object.setPrototypeOf()` instead.
+    /// [`Object.prototype.__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto)
+    /// is a special accessor used to get or set the prototype of an object. \
+    ///
+    /// However, it has been **deprecated** since _ECMAScript 2009_, being much slower and much less reliable than its
+    /// modern counterparts [`Object.getPrototypeOf()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getPrototypeOf)
+    /// and [`Object.setPrototypeOf()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/setPrototypeOf).
+    ///
+    /// Since it is a regular property on `Object.prototype`,
+    /// `__proto__` **will not work** on `null`-prototype objects that do not extend from `Object.prototype`
+    /// nor ones having created their own `__proto__` properties via `Object.defineProperty`.
+    ///
+    /// As such, this rule encourages the use of `Object.getPrototypeOf()` and `Object.setPrototypeOf()`
+    /// in lieu of directly accessing `__proto__`.
+    ///
+    /// :::info
+    /// Note that this does **not** check for the use of `__proto__` inside object literal definitions
+    /// to set a newly created object's prototype, \
+    /// which is standard practice and well-optimized in modern browsers.
+    /// :::
     ///
     /// ## Examples
     ///
@@ -34,6 +50,15 @@ declare_lint_rule! {
     /// ```js
     /// Object.setPrototypeOf(obj, b);
     /// ```
+    ///
+    /// ```js
+    /// // This sets `foo`'s prototype to `null` (similar to `Object.create`), and is
+    /// // well-defined across browsers.
+    /// const foo = {
+    ///   __proto__: null,
+    ///   a: 1,
+    /// }
+    /// ```
     pub NoProto {
         version: "2.3.8",
         name: "noProto",
@@ -105,14 +130,16 @@ impl Rule for NoProto {
             rule_category!(),
             node.range(),
             markup! {
-                "Unexpected use of "<Emphasis>"__proto__"</Emphasis>"."
+                "Avoid use of the deprecated "<Emphasis>"__proto__"</Emphasis>" accessor."
             },
         )
             .note(markup! {
-                "The use of "<Emphasis>"__proto__"</Emphasis>" for getting or setting the prototype of an object is deprecated."
+                <Emphasis>"Object.prototype.__proto__"</Emphasis>" is an outdated way to get or set an object's prototype,"
+                "\nhaving been "<Emphasis>"deprecated in 2009"</Emphasis>" for being inefficient and unreliable."
             })
             .note(markup! {
-                "Use "<Emphasis>"Object.getPrototypeOf()"</Emphasis>" or "<Emphasis>"Object.setPrototypeOf()"</Emphasis>" instead."
+                <Emphasis>"Object.getPrototypeOf()"</Emphasis>" and "<Emphasis>"Object.setPrototypeOf()"</Emphasis>" "
+                "are modern alternatives that work on all objects and are more performant."
             })
         )
     }

crates/biome_js_analyze/src/lint/nursery/no_proto.rs

@@ -15,42 +15,44 @@ const d = obj["__proto__"];
 ```
 invalid.js:1:1 lint/nursery/noProto ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  i Unexpected use of __proto__.
+  i Avoid use of the deprecated __proto__ accessor.
   
   > 1 │ obj.__proto__ = a;
       │ ^^^^^^^^^^^^^
     2 │ obj["__proto__"] = b;
     3 │ const c = obj.__proto__;
   
-  i The use of __proto__ for getting or setting the prototype of an object is deprecated.
+  i Object.prototype.__proto__ is an outdated way to get or set an object's prototype,
+    having been deprecated in 2009 for being inefficient and unreliable.
   
-  i Use Object.getPrototypeOf() or Object.setPrototypeOf() instead.
+  i Object.getPrototypeOf() and Object.setPrototypeOf() are modern alternatives that work on all objects and are more performant.
   
 
 ```
 
 ```
 invalid.js:2:1 lint/nursery/noProto ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  i Unexpected use of __proto__.
+  i Avoid use of the deprecated __proto__ accessor.
   
     1 │ obj.__proto__ = a;
   > 2 │ obj["__proto__"] = b;
       │ ^^^^^^^^^^^^^^^^
     3 │ const c = obj.__proto__;
     4 │ const d = obj["__proto__"];
   
-  i The use of __proto__ for getting or setting the prototype of an object is deprecated.
+  i Object.prototype.__proto__ is an outdated way to get or set an object's prototype,
+    having been deprecated in 2009 for being inefficient and unreliable.
   
-  i Use Object.getPrototypeOf() or Object.setPrototypeOf() instead.
+  i Object.getPrototypeOf() and Object.setPrototypeOf() are modern alternatives that work on all objects and are more performant.
   
 
 ```
 
 ```
 invalid.js:3:11 lint/nursery/noProto ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  i Unexpected use of __proto__.
+  i Avoid use of the deprecated __proto__ accessor.
   
     1 │ obj.__proto__ = a;
     2 │ obj["__proto__"] = b;
@@ -59,27 +61,29 @@ invalid.js:3:11 lint/nursery/noProto ━━━━━━━━━━━━━━
     4 │ const d = obj["__proto__"];
     5 │ 
   
-  i The use of __proto__ for getting or setting the prototype of an object is deprecated.
+  i Object.prototype.__proto__ is an outdated way to get or set an object's prototype,
+    having been deprecated in 2009 for being inefficient and unreliable.
   
-  i Use Object.getPrototypeOf() or Object.setPrototypeOf() instead.
+  i Object.getPrototypeOf() and Object.setPrototypeOf() are modern alternatives that work on all objects and are more performant.
   
 
 ```
 
 ```
 invalid.js:4:11 lint/nursery/noProto ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  i Unexpected use of __proto__.
+  i Avoid use of the deprecated __proto__ accessor.
   
     2 │ obj["__proto__"] = b;
     3 │ const c = obj.__proto__;
   > 4 │ const d = obj["__proto__"];
       │           ^^^^^^^^^^^^^^^^
     5 │ 
   
-  i The use of __proto__ for getting or setting the prototype of an object is deprecated.
+  i Object.prototype.__proto__ is an outdated way to get or set an object's prototype,
+    having been deprecated in 2009 for being inefficient and unreliable.
   
-  i Use Object.getPrototypeOf() or Object.setPrototypeOf() instead.
+  i Object.getPrototypeOf() and Object.setPrototypeOf() are modern alternatives that work on all objects and are more performant.
   
 
 ```

crates/biome_js_analyze/tests/specs/nursery/noProto/invalid.js.snap

@@ -1,3 +1,8 @@
 /* should not generate diagnostics */
+
 const a = Object.getPrototypeOf(obj);
+const b = {
+	__proto__: a,
+	val: 12
+}
 Object.setPrototypeOf(obj, b);

crates/biome_js_analyze/tests/specs/nursery/noProto/valid.js

@@ -5,7 +5,12 @@ expression: valid.js
 # Input
 ```js
 /* should not generate diagnostics */
+
 const a = Object.getPrototypeOf(obj);
+const b = {
+	__proto__: a,
+	val: 12
+}
 Object.setPrototypeOf(obj, b);
 
 ```