feat(json_analyze): implement noTopLevelLiterals

.changeset/sour-beds-juggle.md

@@ -0,0 +1,11 @@
+---
+"@biomejs/biome": patch
+---
+
+Added the nursery rule [`noTopLevelLiterals`](https://biomejs.dev/linter/rules/no-top-level-literals/). It requires the root-level value to be an array or object.
+
+**Invalid:**
+
+```json
+"just a string"
+```

crates/biome_json_analyze/src/lint/nursery/no_top_level_literals.rs

@@ -0,0 +1,100 @@
+use biome_analyze::{
+    Ast, Rule, RuleDiagnostic, RuleSource, context::RuleContext, declare_lint_rule,
+};
+use biome_console::markup;
+use biome_json_syntax::{AnyJsonValue, JsonRoot};
+use biome_rowan::AstNode;
+use biome_rule_options::no_top_level_literals::NoTopLevelLiteralsOptions;
+
+declare_lint_rule! {
+    /// Require the JSON top-level value to be an array or object.
+    ///
+    /// The JSON specification technically allows any JSON value (object, array, string, number, boolean, or null) to be used as the top-level element of a JSON document.
+    /// However, some older JSON parsers, especially those created before [RFC 7158](https://datatracker.ietf.org/doc/html/rfc7158)/[4627](https://datatracker.ietf.org/doc/html/rfc4627) was fully adopted, only support objects or arrays as the root element.
+    ///
+    /// Additionally, some security practices (such as those preventing JSON hijacking attacks) rely on the assumption that the top-level value is an object or array.
+    /// Using an object or array at the top level also provides better extensibility for your data structures over time.
+    ///
+    /// ## Examples
+    ///
+    /// ### Invalid
+    ///
+    /// ```json,expect_diagnostic
+    /// "just a string"
+    /// ```
+    ///
+    /// ```json,expect_diagnostic
+    /// 42
+    /// ```
+    ///
+    /// ```json,expect_diagnostic
+    /// true
+    /// ```
+    ///
+    /// ```json,expect_diagnostic
+    /// null
+    /// ```
+    ///
+    /// ### Valid
+    ///
+    /// ```json
+    /// {
+    ///   "property": "value",
+    ///   "otherProperty": 123
+    /// }
+    /// ```
+    ///
+    /// ```json
+    /// ["element", "anotherElement"]
+    /// ```
+    ///
+    /// ```json
+    /// {}
+    /// ```
+    ///
+    /// ```json
+    /// []
+    /// ```
+    ///
+    pub NoTopLevelLiterals {
+        version: "next",
+        name: "noTopLevelLiterals",
+        language: "json",
+        recommended: false,
+        sources: &[RuleSource::EslintJson("top-level-interop").same()],
+    }
+}
+
+impl Rule for NoTopLevelLiterals {
+    type Query = Ast<JsonRoot>;
+    type State = ();
+    type Signals = Option<Self::State>;
+    type Options = NoTopLevelLiteralsOptions;
+
+    fn run(ctx: &RuleContext<Self>) -> Self::Signals {
+        let node = ctx.query();
+        let value = node.value().ok()?;
+
+        match value {
+            AnyJsonValue::JsonObjectValue(_) => None,
+            AnyJsonValue::JsonArrayValue(_) => None,
+            _ => Some(()),
+        }
+    }
+
+    fn diagnostic(ctx: &RuleContext<Self>, _state: &Self::State) -> Option<RuleDiagnostic> {
+        let span = ctx.query().range();
+        Some(
+            RuleDiagnostic::new(
+                rule_category!(),
+                span,
+                markup! {
+                    "Expected the top-level value to be an array or object."
+                },
+            )
+            .note(markup! {
+                "Some JSON parsers only support objects or arrays as the root element. Wrap your value in an array or object to ensure compatibility."
+            }),
+        )
+    }
+}

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/invalid/boolean.json

@@ -0,0 +1 @@
+true

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/invalid/boolean.json.snap

@@ -0,0 +1,26 @@
+---
+source: crates/biome_json_analyze/tests/spec_tests.rs
+expression: boolean.json
+---
+# Input
+```json
+true
+
+```
+
+# Diagnostics
+```
+boolean.json:1:1 lint/nursery/noTopLevelLiterals ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Expected the top-level value to be an array or object.
+
+  > 1 │ true
+      │ ^^^^
+    2 │ 
+
+  i Some JSON parsers only support objects or arrays as the root element. Wrap your value in an array or object to ensure compatibility.
+
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+
+
+```

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/invalid/null.json

@@ -0,0 +1 @@
+null

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/invalid/null.json.snap

@@ -0,0 +1,26 @@
+---
+source: crates/biome_json_analyze/tests/spec_tests.rs
+expression: null.json
+---
+# Input
+```json
+null
+
+```
+
+# Diagnostics
+```
+null.json:1:1 lint/nursery/noTopLevelLiterals ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Expected the top-level value to be an array or object.
+
+  > 1 │ null
+      │ ^^^^
+    2 │ 
+
+  i Some JSON parsers only support objects or arrays as the root element. Wrap your value in an array or object to ensure compatibility.
+
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+
+
+```

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/invalid/number.json

@@ -0,0 +1 @@
+42

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/invalid/number.json.snap

@@ -0,0 +1,26 @@
+---
+source: crates/biome_json_analyze/tests/spec_tests.rs
+expression: number.json
+---
+# Input
+```json
+42
+
+```
+
+# Diagnostics
+```
+number.json:1:1 lint/nursery/noTopLevelLiterals ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Expected the top-level value to be an array or object.
+
+  > 1 │ 42
+      │ ^^
+    2 │ 
+
+  i Some JSON parsers only support objects or arrays as the root element. Wrap your value in an array or object to ensure compatibility.
+
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+
+
+```

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/invalid/string.json

@@ -0,0 +1 @@
+"just a string"

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/invalid/string.json.snap

@@ -0,0 +1,26 @@
+---
+source: crates/biome_json_analyze/tests/spec_tests.rs
+expression: string.json
+---
+# Input
+```json
+"just a string"
+
+```
+
+# Diagnostics
+```
+string.json:1:1 lint/nursery/noTopLevelLiterals ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i Expected the top-level value to be an array or object.
+
+  > 1 │ "just a string"
+      │ ^^^^^^^^^^^^^^^
+    2 │ 
+
+  i Some JSON parsers only support objects or arrays as the root element. Wrap your value in an array or object to ensure compatibility.
+
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+
+
+```

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/valid/array.json

@@ -0,0 +1,5 @@
+[
+  "one",
+  "two",
+  "three"
+]

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/valid/array.json.snap

@@ -0,0 +1,13 @@
+---
+source: crates/biome_json_analyze/tests/spec_tests.rs
+expression: array.json
+---
+# Input
+```json
+[
+  "one",
+  "two",
+  "three"
+]
+
+```

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/valid/empty-array.json

@@ -0,0 +1 @@
+[]

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/valid/empty-array.json.snap

@@ -0,0 +1,9 @@
+---
+source: crates/biome_json_analyze/tests/spec_tests.rs
+expression: empty-array.json
+---
+# Input
+```json
+[]
+
+```

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/valid/empty-object.json

@@ -0,0 +1 @@
+{}

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/valid/empty-object.json.snap

@@ -0,0 +1,9 @@
+---
+source: crates/biome_json_analyze/tests/spec_tests.rs
+expression: empty-object.json
+---
+# Input
+```json
+{}
+
+```

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/valid/object.json

@@ -0,0 +1,5 @@
+{
+  "one": "value",
+  "two": "value",
+  "three": "value"
+}

crates/biome_json_analyze/tests/specs/nursery/noTopLevelLiterals/valid/object.json.snap

@@ -0,0 +1,13 @@
+---
+source: crates/biome_json_analyze/tests/spec_tests.rs
+expression: object.json
+---
+# Input
+```json
+{
+  "one": "value",
+  "two": "value",
+  "three": "value"
+}
+
+```

crates/biome_rule_options/src/lib.rs

@@ -228,6 +228,7 @@ pub mod no_template_curly_in_string;
 pub mod no_ternary;
 pub mod no_then_property;
 pub mod no_this_in_static;
+pub mod no_top_level_literals;
 pub mod no_ts_ignore;
 pub mod no_unassigned_variables;
 pub mod no_undeclared_dependencies;

crates/biome_rule_options/src/no_top_level_literals.rs

@@ -0,0 +1,6 @@
+use biome_deserialize_macros::{Deserializable, Merge};
+use serde::{Deserialize, Serialize};
+#[derive(Default, Clone, Debug, Deserialize, Deserializable, Merge, Eq, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "camelCase", deny_unknown_fields, default)]
+pub struct NoTopLevelLiteralsOptions {}