[Theme Check] Add check for duplicate settings id's (#696)

Closes Shopify/developer-tools-team#263

Implements a new validation check to prevent duplicate setting IDs across theme configurations. This helps theme developers identify and fix duplicate IDs early in development, preventing potential conflicts and overrides.

The implementation includes:
- New JSONCheckDefinition for unique setting ID validation
- Test coverage for valid and invalid theme configurations
- Detection logic for finding duplicate IDs in settings schema

See:
Ticket: 49020903
Shopify/cli#4187

## What are you adding in this PR?

This PR adds a new theme check validator that detects duplicate setting IDs in theme configurations. The validator scans settings_schema.json files and reports an error when it finds multiple settings using the same ID value, preventing potential runtime conflicts.
Key changes:

- New UniqueSettingIds check that validates setting ID uniqueness
- Integration with the existing theme checker infrastructure
- Test coverage for both valid and invalid scenarios
- Error reporting with precise location information

## What's next? Any followup issues?

Potential follow-ups:
- Consider extending the check to validate uniqueness across sections
- Add documentation for theme developers about ID uniqueness requirements
- Consider adding quick-fix suggestions for duplicate IDs

## What did you learn?

Working with AST traversal for JSON validation showed that we need a consistent approach to handle nested property validation. The existing node type checks provided a good pattern to follow.

## Before you deploy

<!-- Delete the checklists you don't need -->

<!-- Check changes -->
- [x] This PR includes a new checks or changes the configuration of a check
- [x] I included a minor bump `changeset`
- [x] It's in the `allChecks` array in `src/checks/index.ts`
- [x] I ran `yarn build` and committed the updated configuration files

Author: zacariec

.changeset/late-pears-check.md

@@ -0,0 +1,5 @@
+---
+'@shopify/theme-check-common': minor
+---
+
+Add unique settings ID validator to prevent duplicate IDs in theme configurations

packages/theme-check-common/src/checks/index.ts

@@ -45,6 +45,7 @@ import { ValidSchemaName } from './valid-schema-name';
 import { ValidStaticBlockType } from './valid-static-block-type';
 import { VariableName } from './variable-name';
 import { AppBlockMissingSchema } from './app-block-missing-schema';
+import { UniqueSettingIds } from './unique-settings-id';
 
 export const allChecks: (LiquidCheckDefinition | JSONCheckDefinition)[] = [
   AppBlockValidTags,
@@ -80,6 +81,7 @@ export const allChecks: (LiquidCheckDefinition | JSONCheckDefinition)[] = [
   TranslationKeyExists,
   UnclosedHTMLElement,
   UndefinedObject,
+  UniqueSettingIds,
   UniqueStaticBlockId,
   UnknownFilter,
   UnusedAssign,

packages/theme-check-common/src/checks/unique-settings-id/index.spec.ts

@@ -0,0 +1,24 @@
+import { expect, describe, it } from 'vitest';
+import { UniqueSettingIds } from './index';
+import { highlightedOffenses, runJSONCheck } from '../../test';
+import { invalidJson, validJson } from './test-data';
+
+describe('Module: UniqueSettingIds', () => {
+  it("Should report an error for duplicate id's in settings_schema (0)", async () => {
+    const offenses = await runJSONCheck(UniqueSettingIds, invalidJson, 'file.json');
+
+    expect(offenses).to.have.length(1);
+    expect(offenses[0].message).to.equal('Duplicate setting id found: "nosto_account_id"');
+
+    const highlights = highlightedOffenses({ 'file.json': invalidJson }, offenses);
+
+    expect(highlights).to.have.length(1);
+    expect(highlights[0]).to.equal('"id": "nosto_account_id"');
+  });
+
+  it('should not report any errors for valid file', async () => {
+    const offenses = await runJSONCheck(UniqueSettingIds, validJson);
+
+    expect(offenses).to.be.empty;
+  });
+});

packages/theme-check-common/src/checks/unique-settings-id/index.ts

@@ -0,0 +1,84 @@
+import {
+  isArrayNode,
+  isLiteralNode,
+  isObjectNode,
+  isPropertyNode,
+  Severity,
+  SourceCodeType,
+} from '../../types';
+
+import type { ArrayNode, PropertyNode, JSONCheckDefinition } from '../../types';
+
+export const UniqueSettingIds: JSONCheckDefinition = {
+  meta: {
+    code: 'UniqueSettingId',
+    name: 'Prevent duplicate Ids in setting_schema',
+    docs: {
+      description: 'This check is aimed at eliminating duplicate Ids in settings_schema.json',
+      recommended: true,
+      // url: 'https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/valid-schema',
+    },
+    type: SourceCodeType.JSON,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    return {
+      async onCodePathEnd(file) {
+        if (isArrayNode(file.ast)) {
+          const settingIds: PropertyNode[] = [];
+
+          /* Find and loop through all of our nodes that have an id value and find their key value */
+          for (const child of file.ast.children) {
+            if (isObjectNode(child) && child.children) {
+              const settingsNode = child.children.find((node) => node.key.value === 'settings');
+
+              if (settingsNode && settingsNode.value && isArrayNode(settingsNode.value)) {
+                for (const setting of settingsNode.value.children) {
+                  if (isObjectNode(setting) && setting.children) {
+                    const idNode = setting.children.find((node) => node.key.value === 'id');
+                    if (isPropertyNode(idNode)) {
+                      settingIds.push(idNode);
+                    }
+                  }
+                }
+              }
+            }
+          }
+
+          /* Check for dupes */
+          const idMap = new Map<string, PropertyNode[]>();
+          for (const node of settingIds) {
+            if (isLiteralNode(node.value)) {
+              const id = node.value.value;
+              if (typeof id === 'string') {
+                if (!idMap.has(id)) {
+                  idMap.set(id, []);
+                }
+                idMap.get(id)!.push(node);
+              }
+            }
+          }
+
+          const duplicates: [string, PropertyNode[]][] = Array.from(idMap.entries()).filter(
+            ([_, nodes]) => nodes.length > 1,
+          );
+
+          if (duplicates.length > 0) {
+            for (const [id, nodes] of duplicates) {
+              const lastNodeFound = nodes[nodes.length - 1];
+
+              context.report({
+                message: `Duplicate setting id found: "${id}"`,
+                startIndex: lastNodeFound.loc.start.offset,
+                endIndex: lastNodeFound.loc.end.offset,
+              });
+            }
+          }
+        }
+      },
+    };
+  },
+};