Improve deprecated attribute extraction and support record form (#8396)

* improve deprecated attribute extraction and support record form

- Enhance `findDeprecatedAttribute` to extract the `reason` from record-form `@deprecated` attributes.
- Ensure deprecated attribute extraction works regardless of attribute order by reversing the list in `newDeclared`.
- Update tests and expected outputs to reflect improved deprecated reason extraction, including record-form deprecations.

* Update CHANGELOG.md

---------

Co-authored-by: Christoph Knittel <ck@cca.io>

Author: aspeddro

CHANGELOG.md

@@ -33,6 +33,7 @@
 - Resolve workspace dependencies in editor analysis. https://github.com/rescript-lang/rescript/pull/8392
 - Build system: Add OpenTelemetry tracing support for cli commands. https://github.com/rescript-lang/rescript/pull/8370
 - Use a single vendored @rescript/react package across the repo. https://github.com/rescript-lang/rescript/pull/7525
+- Improve deprecated attribute extraction and support record form. https://github.com/rescript-lang/rescript/pull/8396
 
 #### :house: Internal
 

analysis/src/ProcessAttributes.ml

@@ -22,15 +22,25 @@ let rec findDeprecatedAttribute attributes =
   match attributes with
   | [] -> None
   | ( {Asttypes.txt = "deprecated"},
-      PStr
-        [
-          {
-            pstr_desc =
-              Pstr_eval ({pexp_desc = Pexp_constant (Pconst_string (msg, _))}, _);
-          };
-        ] )
-    :: _ ->
-    Some msg
+      PStr [{pstr_desc = Pstr_eval ({pexp_desc = expr}, _)}] )
+    :: _ -> (
+    match expr with
+    (* Simple deprecated attr @deprecated("message") *)
+    | Pexp_constant (Pconst_string (_msg, _)) -> Some _msg
+    (* deprecated attr with record *)
+    | Pexp_record (fields, _) ->
+      let reason = ref "" in
+
+      fields
+      |> List.iter (fun {lid = {txt}; x} ->
+             match (txt, x) with
+             | ( Lident "reason",
+                 {pexp_desc = Pexp_constant (Pconst_string (msg, _))} ) ->
+               reason := msg
+             | _ -> ());
+
+      Some !reason
+    | _ -> None)
   | ({Asttypes.txt = "deprecated"}, _) :: _ -> Some ""
   | _ :: rest -> findDeprecatedAttribute rest
 
@@ -41,7 +51,7 @@ let newDeclared ~item ~extent ~name ~stamp ~modulePath isExported attributes =
     extentLoc = extent;
     isExported;
     modulePath;
-    deprecated = findDeprecatedAttribute attributes;
+    deprecated = findDeprecatedAttribute (List.rev attributes);
     docstring =
       (match findDocAttribute attributes with
       | None -> []

tests/analysis_tests/tests/src/expected/Completion.res.txt

@@ -53,7 +53,7 @@ Path
     "kind": 12,
     "tags": [1],
     "detail": "t<'a> => 'a",
-    "documentation": {"kind": "markdown", "value": "Deprecated: \n\n\n`getExn(value)` throws an exception if `null`, otherwise returns the value.\n\n```rescript\nNull.getExn(Null.make(3)) == 3\n\nswitch Null.getExn(%raw(\"'ReScript'\")) {\n| exception Invalid_argument(_) => assert(false)\n| value => value == \"ReScript\"\n}\n\nswitch Null.getExn(%raw(\"null\")) {\n| exception Invalid_argument(_) => assert(true)\n| _ => assert(false)\n}\n```\n\n## Exceptions\n\n- Throws `Invalid_argument` if `value` is `null`\n"},
+    "documentation": {"kind": "markdown", "value": "Deprecated: Use `getOrThrow` instead\n\n\n`getExn(value)` throws an exception if `null`, otherwise returns the value.\n\n```rescript\nNull.getExn(Null.make(3)) == 3\n\nswitch Null.getExn(%raw(\"'ReScript'\")) {\n| exception Invalid_argument(_) => assert(false)\n| value => value == \"ReScript\"\n}\n\nswitch Null.getExn(%raw(\"null\")) {\n| exception Invalid_argument(_) => assert(true)\n| _ => assert(false)\n}\n```\n\n## Exceptions\n\n- Throws `Invalid_argument` if `value` is `null`\n"},
     "sortText": "getExn",
     "insertText": "->Null.getExn",
     "additionalTextEdits": [{
@@ -137,7 +137,7 @@ Path
     "kind": 12,
     "tags": [1],
     "detail": "(t<'a>, 'b, 'a => 'b) => 'b",
-    "documentation": {"kind": "markdown", "value": "Deprecated: \n\n"},
+    "documentation": {"kind": "markdown", "value": "Deprecated: Use mapOr instead\n\n"},
     "sortText": "mapWithDefault",
     "insertText": "->Null.mapWithDefault",
     "additionalTextEdits": [{
@@ -149,7 +149,7 @@ Path
     "kind": 12,
     "tags": [1],
     "detail": "(t<'a>, 'a) => 'a",
-    "documentation": {"kind": "markdown", "value": "Deprecated: \n\n"},
+    "documentation": {"kind": "markdown", "value": "Deprecated: Use getOr instead\n\n"},
     "sortText": "getWithDefault",
     "insertText": "->Null.getWithDefault",
     "additionalTextEdits": [{
@@ -249,7 +249,7 @@ Path
     "kind": 12,
     "tags": [1],
     "detail": "t<'a> => 'a",
-    "documentation": {"kind": "markdown", "value": "Deprecated: \n\n\n`getExn(value)` throws an exception if `null` or `undefined`, otherwise returns the value.\n\n```rescript\nswitch Nullable.getExn(%raw(\"'Hello'\")) {\n| exception Invalid_argument(_) => assert(false)\n| value => value == \"Hello\"\n}\n\nswitch Nullable.getExn(%raw(\"null\")) {\n| exception Invalid_argument(_) => assert(true)\n| _ => assert(false)\n}\n\nswitch Nullable.getExn(%raw(\"undefined\")) {\n| exception Invalid_argument(_) => assert(true)\n| _ => assert(false)\n}\n```\n\n## Exceptions\n\n- Throws `Invalid_argument` if `value` is `null` or `undefined`\n"},
+    "documentation": {"kind": "markdown", "value": "Deprecated: Use `getOrThrow` instead\n\n\n`getExn(value)` throws an exception if `null` or `undefined`, otherwise returns the value.\n\n```rescript\nswitch Nullable.getExn(%raw(\"'Hello'\")) {\n| exception Invalid_argument(_) => assert(false)\n| value => value == \"Hello\"\n}\n\nswitch Nullable.getExn(%raw(\"null\")) {\n| exception Invalid_argument(_) => assert(true)\n| _ => assert(false)\n}\n\nswitch Nullable.getExn(%raw(\"undefined\")) {\n| exception Invalid_argument(_) => assert(true)\n| _ => assert(false)\n}\n```\n\n## Exceptions\n\n- Throws `Invalid_argument` if `value` is `null` or `undefined`\n"},
     "sortText": "getExn",
     "insertText": "->Nullable.getExn",
     "additionalTextEdits": [{
@@ -333,7 +333,7 @@ Path
     "kind": 12,
     "tags": [1],
     "detail": "(t<'a>, 'b, 'a => 'b) => 'b",
-    "documentation": {"kind": "markdown", "value": "Deprecated: \n\n"},
+    "documentation": {"kind": "markdown", "value": "Deprecated: Use mapOr instead\n\n"},
     "sortText": "mapWithDefault",
     "insertText": "->Nullable.mapWithDefault",
     "additionalTextEdits": [{
@@ -345,7 +345,7 @@ Path
     "kind": 12,
     "tags": [1],
     "detail": "(t<'a>, 'a) => 'a",
-    "documentation": {"kind": "markdown", "value": "Deprecated: \n\n"},
+    "documentation": {"kind": "markdown", "value": "Deprecated: Use getOr instead\n\n"},
     "sortText": "getWithDefault",
     "insertText": "->Nullable.getWithDefault",
     "additionalTextEdits": [{

tests/analysis_tests/tests/src/expected/CompletionInferValues.res.txt

@@ -329,25 +329,25 @@ Path t
     "kind": 12,
     "tags": [1],
     "detail": "(int, ~radix: int) => string",
-    "documentation": {"kind": "markdown", "value": "Deprecated: \n\n\n`toStringWithRadix(n, ~radix)` return a `string` representing the given value.\n`~radix` specifies the radix base to use for the formatted number.\nSee [`Number.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString)\non MDN.\n\n## Examples\n\n```rescript\nInt.toStringWithRadix(6, ~radix=2) // \"110\"\nInt.toStringWithRadix(373592855, ~radix=16) // \"16449317\"\nInt.toStringWithRadix(123456, ~radix=36) // \"2n9c\"\n```\n\n## Exceptions\n\n`RangeError`: if `radix` is less than 2 or greater than 36.\n"}
+    "documentation": {"kind": "markdown", "value": "Deprecated: Use `toString` instead\n\n\n`toStringWithRadix(n, ~radix)` return a `string` representing the given value.\n`~radix` specifies the radix base to use for the formatted number.\nSee [`Number.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toString)\non MDN.\n\n## Examples\n\n```rescript\nInt.toStringWithRadix(6, ~radix=2) // \"110\"\nInt.toStringWithRadix(373592855, ~radix=16) // \"16449317\"\nInt.toStringWithRadix(123456, ~radix=36) // \"2n9c\"\n```\n\n## Exceptions\n\n`RangeError`: if `radix` is less than 2 or greater than 36.\n"}
   }, {
     "label": "Int.toExponentialWithPrecision",
     "kind": 12,
     "tags": [1],
     "detail": "(int, ~digits: int) => string",
-    "documentation": {"kind": "markdown", "value": "Deprecated: \n\n\n`toExponential(n, ~digits)` return a `string` representing the given value in\nexponential notation. `digits` specifies how many digits should appear after\nthe decimal point. See [`Number.toExponential`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential)\non MDN.\n\n## Examples\n\n```rescript\nInt.toExponentialWithPrecision(77, ~digits=2) // \"7.70e+1\"\nInt.toExponentialWithPrecision(5678, ~digits=2) // \"5.68e+3\"\n```\n\n## Exceptions\n\n- `RangeError`: If `digits` less than 0 or greater than 10.\n"}
+    "documentation": {"kind": "markdown", "value": "Deprecated: Use `toExponential` instead\n\n\n`toExponential(n, ~digits)` return a `string` representing the given value in\nexponential notation. `digits` specifies how many digits should appear after\nthe decimal point. See [`Number.toExponential`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toExponential)\non MDN.\n\n## Examples\n\n```rescript\nInt.toExponentialWithPrecision(77, ~digits=2) // \"7.70e+1\"\nInt.toExponentialWithPrecision(5678, ~digits=2) // \"5.68e+3\"\n```\n\n## Exceptions\n\n- `RangeError`: If `digits` less than 0 or greater than 10.\n"}
   }, {
     "label": "Int.toFixedWithPrecision",
     "kind": 12,
     "tags": [1],
     "detail": "(int, ~digits: int) => string",
-    "documentation": {"kind": "markdown", "value": "Deprecated: \n\n\n`toFixedWithPrecision(n, ~digits)` return a `string` representing the given\nvalue using fixed-point notation. `digits` specifies how many digits should\nappear after the decimal point. See [`Number.toFixed`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed)\non MDN.\n\n## Examples\n\n```rescript\nInt.toFixedWithPrecision(300, ~digits=4) // \"300.0000\"\nInt.toFixedWithPrecision(300, ~digits=1) // \"300.0\"\n```\n\n## Exceptions\n\n- `RangeError`: If `digits` is less than 0 or larger than 100.\n"}
+    "documentation": {"kind": "markdown", "value": "Deprecated: Use `toFixed` instead\n\n\n`toFixedWithPrecision(n, ~digits)` return a `string` representing the given\nvalue using fixed-point notation. `digits` specifies how many digits should\nappear after the decimal point. See [`Number.toFixed`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed)\non MDN.\n\n## Examples\n\n```rescript\nInt.toFixedWithPrecision(300, ~digits=4) // \"300.0000\"\nInt.toFixedWithPrecision(300, ~digits=1) // \"300.0\"\n```\n\n## Exceptions\n\n- `RangeError`: If `digits` is less than 0 or larger than 100.\n"}
   }, {
     "label": "Int.toPrecisionWithPrecision",
     "kind": 12,
     "tags": [1],
     "detail": "(int, ~digits: int) => string",
-    "documentation": {"kind": "markdown", "value": "Deprecated: \n\n\n`toPrecisionWithPrecision(n, ~digits)` return a `string` representing the giver value with\nprecision. `digits` specifies the number of significant digits. See [`Number.toPrecision`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) on MDN.\n\n## Examples\n\n```rescript\nInt.toPrecisionWithPrecision(100, ~digits=2) // \"1.0e+2\"\nInt.toPrecisionWithPrecision(1, ~digits=2) // \"1.0\"\n```\n\n## Exceptions\n\n- `RangeError`: If `digits` is not between 1 and 100 (inclusive).\n  Implementations are allowed to support larger and smaller values as well.\n  ECMA-262 only requires a precision of up to 21 significant digits.\n"}
+    "documentation": {"kind": "markdown", "value": "Deprecated: Use `toPrecision` instead\n\n\n`toPrecisionWithPrecision(n, ~digits)` return a `string` representing the giver value with\nprecision. `digits` specifies the number of significant digits. See [`Number.toPrecision`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toPrecision) on MDN.\n\n## Examples\n\n```rescript\nInt.toPrecisionWithPrecision(100, ~digits=2) // \"1.0e+2\"\nInt.toPrecisionWithPrecision(1, ~digits=2) // \"1.0\"\n```\n\n## Exceptions\n\n- `RangeError`: If `digits` is not between 1 and 100 (inclusive).\n  Implementations are allowed to support larger and smaller values as well.\n  ECMA-262 only requires a precision of up to 21 significant digits.\n"}
   }, {
     "label": "Int.toPrecision",
     "kind": 12,