feat(no-unused-props): add allowUnusedNestedProperties option

.changeset/fancy-trams-create.md

@@ -0,0 +1,5 @@
+---
+'eslint-plugin-svelte': minor
+---
+
+feat(no-unused-props): add `allowUnusedNestedProperties` option

docs/rules/no-unused-props.md

@@ -163,13 +163,16 @@ Note: Properties of class types are not checked for usage, as they might be used
     "ignoreTypePatterns": [],
     // Patterns to ignore when checking for unused props
     "ignorePropertyPatterns": [],
+    // Whether to allow unused nested properties
+    "allowUnusedNestedProperties": false
   }]
 }
 ```
 
 - `checkImportedTypes` ... Controls whether to check properties from types defined in external files. Default is `false`, meaning the rule only checks types defined within the component file itself. When set to `true`, the rule will also check properties from imported and extended types.
 - `ignoreTypePatterns` ... Regular expression patterns for type names to exclude from checks. Default is `[]` (no exclusions). Most useful when `checkImportedTypes` is `true`, allowing you to exclude specific imported types (like utility types or third-party types) from being checked.
 - `ignorePropertyPatterns` ... Regular expression patterns for property names to exclude from unused checks. Default is `[]` (no exclusions). Most useful when `checkImportedTypes` is `true`, allowing you to ignore specific properties from external types that shouldn't trigger warnings.
+- `allowUnusedNestedProperties` ... Controls whether to allow unused nested properties. Default is `false`, meaning the rule will report unused properties from nested objects.
 
 Examples:
 
@@ -219,6 +222,21 @@ Examples:
 </script>
 ```
 
+```svelte
+<!-- ✓ Good Example with allowUnusedNestedProperties: true -->
+<script lang="ts">
+  /* eslint svelte/no-unused-props: ["error", { "allowUnusedNestedProperties": true }] */
+  interface Props {
+    user: {
+      name: string;
+      age: number; // Won't be reported as unused
+    };
+  }
+  let { user }: Props = $props();
+  console.log(user.name);
+</script>
+```
+
 ## :gear: Required Configuration
 
 This rule requires `@typescript-eslint/parser` to work. Please refer to the [User Guide](../user-guide.md) for more information.

packages/eslint-plugin-svelte/src/rule-types.ts

@@ -537,6 +537,7 @@ type SvelteNoUnusedProps = []|[{
   checkImportedTypes?: boolean
   ignoreTypePatterns?: string[]
   ignorePropertyPatterns?: string[]
+  allowUnusedNestedProperties?: boolean
 }]
 // ----- svelte/no-useless-mustaches -----
 type SvelteNoUselessMustaches = []|[{

packages/eslint-plugin-svelte/src/rules/no-unused-props.ts

@@ -37,6 +37,10 @@
 							type: 'string'
 						},
 						default: []
+					},
+					allowUnusedNestedProperties: {
+						type: 'boolean',
+						default: false
 					}
 				},
 				additionalProperties: false
@@ -70,11 +74,11 @@
 
 		const options = context.options[0] ?? {};
 
 		// TODO: Remove in v4
 		// MEMO: `ignorePatterns` was a property that only existed from v3.2.0 to v3.2.2.
 		// From v3.3.0, it was replaced with `ignorePropertyPatterns` and `ignoreTypePatterns`.
 		if (options.ignorePatterns != null && !isRemovedWarningShown) {
 			console.warn(
 				'eslint-plugin-svelte: The `ignorePatterns` option in the `no-unused-props` rule has been removed. Please use `ignorePropertyPatterns` or/and `ignoreTypePatterns` instead.'
 			);
 			isRemovedWarningShown = true;
@@ -342,7 +346,10 @@
 			return usedProps.size === 0;
 		}
 
-		function normalizeUsedPaths(paths: PropertyPathArray[]): PropertyPathArray[] {
+		function normalizeUsedPaths(
+			paths: PropertyPathArray[],
+			allowUnusedNestedProperties: boolean
+		): PropertyPathArray[] {
 			const normalized: PropertyPathArray[] = [];
 			for (const path of paths.sort((a, b) => a.length - b.length)) {
 				if (path.length === 0) continue;
@@ -351,7 +358,11 @@
 				}
 				normalized.push(path);
 			}
-			return normalized;
+			return normalized.map((path) => {
+				// If we allow unused nested properties, only return first level properties
+				if (allowUnusedNestedProperties) return [path[0]];
+				return path;
+			});
 		}
 
 		return {
@@ -396,7 +407,10 @@
 
 				checkUnusedProperties({
 					propsType,
-					usedPropertyPaths: normalizeUsedPaths(usedPropertyPathsArray).map((pathArray) => {
+					usedPropertyPaths: normalizeUsedPaths(
+						usedPropertyPathsArray,
+						options.allowUnusedNestedProperties
+					).map((pathArray) => {
 						return pathArray.join('.');
 					}),
 					declaredPropertyNames,

packages/eslint-plugin-svelte/tests/fixtures/rules/no-unused-props/valid/nested-unused-config.json

@@ -0,0 +1,7 @@
+{
+	"options": [
+		{
+			"allowUnusedNestedProperties": true
+		}
+	]
+}

packages/eslint-plugin-svelte/tests/fixtures/rules/no-unused-props/valid/nested-unused-input.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+	interface Props {
+		user: {
+			name: string;
+			location: string;
+		};
+	}
+	let props: Props = $props();
+	console.log(props.user.name);
+</script>

packages/eslint-plugin-svelte/tests/fixtures/rules/no-unused-props/valid/nested-unused2-config.json

@@ -0,0 +1,7 @@
+{
+	"options": [
+		{
+			"allowUnusedNestedProperties": true
+		}
+	]
+}

packages/eslint-plugin-svelte/tests/fixtures/rules/no-unused-props/valid/nested-unused2-input.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+	interface Props {
+		user: {
+			name: string;
+			age: number; // Won't be reported as unused
+		};
+	}
+	let { user }: Props = $props();
+	console.log(user.name);
+</script>