[tools] Add compare_styles_tool for style comparison

[mattpodwysocki]

Summary

Implements a comprehensive style comparison tool that performs deep structural comparison of two Mapbox styles, identifying additions, removals, and modifications.

Key Features

• Deep Object Comparison: Recursively compares nested structures with detailed diff reporting
• Layer Comparison by ID: Compares layers by their ID property rather than array index
• Metadata Filtering: Optional ignoreMetadata flag to ignore metadata fields (id, owner, created, modified, draft, visibility)
• Flexible Input: Accepts JSON strings or objects for both styles
• Structured Output: Returns differences with JSON paths, types (added/removed/modified), and descriptive messages

Implementation Details

• Extends BaseTool for offline operation (no API calls required)
• Special handling for Mapbox style layers ensures correct comparison even when layer order changes
• Comprehensive error handling for invalid JSON input
• Full Zod schema validation for inputs and outputs

Testing

• 16 comprehensive test cases covering:
  • Tool metadata validation
  • Identical styles detection
  • Property differences (added, removed, modified)
  • Layer differences with ID-based comparison
  • Metadata handling with ignoreMetadata flag
  • JSON string input parsing
  • Error handling for invalid JSON
  • Nested property change detection
  • Summary statistics validation

All tests passing ✅

Documentation

Added comprehensive README documentation for all three validation tools:

• validate_geojson_tool (PR Add validate_geojson_tool for offline GeoJSON validation #50)
• validate_expression_tool (PR Add validate_expression_tool for Mapbox expression validation #51)
• compare_styles_tool (this PR)

Each tool is documented with parameters, features, return values, and example prompts.

Testing

Test 1: Identical Styles

Purpose: Verify that two identical styles are detected as identical

Prompt to Claude:
Compare these two Mapbox styles using compare_styles_tool:

Style A:

  {
    "version": 8,
    "name": "Basic Style",
    "sources": {
      "mapbox-streets": {
        "type": "vector",
        "url": "mapbox://mapbox.mapbox-streets-v8"
      }
    },
    "layers": [
      {
        "id": "background",
        "type": "background",
        "paint": {"background-color": "#f0f0f0"}
      }
    ]
  }

Style B: (same as Style A)

  {
    "version": 8,
    "name": "Basic Style",
    "sources": {
      "mapbox-streets": {
        "type": "vector",
        "url": "mapbox://mapbox.mapbox-streets-v8"
      }
    },
    "layers": [
      {
        "id": "background",
        "type": "background",
        "paint": {"background-color": "#f0f0f0"}
      }
    ]
  }

Expected Result:

• identical: true
• differences: []
• summary.totalDifferences: 0

---

Test 2: Color Change in Layer

Purpose: Detect a modified paint property

Prompt to Claude:
Compare these two styles where the background color changed:

Style A:

  {
    "version": 8,
    "name": "Test Style",
    "sources": {},
    "layers": [
      {
        "id": "background",
        "type": "background",
        "paint": {"background-color": "#f0f0f0"}
      }
    ]
  }

Style B:

  {
    "version": 8,
    "name": "Test Style",
    "sources": {},
    "layers": [
      {
        "id": "background",
        "type": "background",
        "paint": {"background-color": "#e0e0e0"}
      }
    ]
  }

Expected Result:

• identical: false
• differences should contain one item with:
  • path: "layers.background.paint.background-color"
  • type: "modified"
  • valueA: "#f0f0f0"
  • valueB: "#e0e0e0"
• summary.modified: 1

---

Test 3: Layer Added

Purpose: Detect when a new layer is added

Prompt to Claude:
Compare these styles where Style B has an additional water layer:

Style A:

  {
    "version": 8,
    "name": "Test",
    "sources": {"mapbox-streets": {"type": "vector", "url": "mapbox://mapbox.mapbox-streets-v8"}},
    "layers": [
      {"id": "background", "type": "background", "paint": {"background-color": "#fff"}}
    ]
  }

Style B:

  {
    "version": 8,
    "name": "Test",
    "sources": {"mapbox-streets": {"type": "vector", "url": "mapbox://mapbox.mapbox-streets-v8"}},
    "layers": [
      {"id": "background", "type": "background", "paint": {"background-color": "#fff"}},
      {"id": "water", "type": "fill", "source": "mapbox-streets", "source-layer": "water", "paint": {"fill-color": "#a0c8f0"}}
    ]
  }

Expected Result:

• identical: false
• differences should show the water layer was added
• summary.added: 1 (or more depending on how it counts nested properties)

---

Test 4: Layer Removed

Purpose: Detect when a layer is removed

Prompt to Claude:
Compare these styles where the water layer was removed in Style B:

Style A:

  {
    "version": 8,
    "name": "Test",
    "sources": {"mapbox-streets": {"type": "vector", "url": "mapbox://mapbox.mapbox-streets-v8"}},
    "layers": [
      {"id": "background", "type": "background", "paint": {"background-color": "#fff"}},
      {"id": "water", "type": "fill", "source": "mapbox-streets", "source-layer": "water", "paint": {"fill-color": "#a0c8f0"}}
    ]
  }

Style B:

  {
    "version": 8,
    "name": "Test",
    "sources": {"mapbox-streets": {"type": "vector", "url": "mapbox://mapbox.mapbox-streets-v8"}},
    "layers": [
      {"id": "background", "type": "background", "paint": {"background-color": "#fff"}}
    ]
  }

Expected Result:

• identical: false
• differences should show the water layer was removed
• summary.removed: 1 (or more)

---

Test #5: Metadata Changes with ignoreMetadata=true

Purpose: Verify that metadata fields can be ignored

Prompt to Claude:
Compare these styles with ignoreMetadata=true. They differ only in metadata:

Style A:

  {
    "version": 8,
    "id": "style-v1",
    "owner": "user1",
    "created": "2024-01-01",
    "modified": "2024-01-01",
    "name": "Test Style",
    "sources": {},
    "layers": []
  }

Style B:

  {
    "version": 8,
    "id": "style-v2",
    "owner": "user2",
    "created": "2024-01-02",
    "modified": "2024-01-02",
    "name": "Test Style",
    "sources": {},
    "layers": []
  }

Use ignoreMetadata: true

Expected Result:

• identical: true (because metadata is ignored)
• differences: []

---

Test #6: Metadata Changes with ignoreMetadata=false

Purpose: Verify that metadata differences are detected when not ignored

Prompt to Claude:
Compare the same styles from Test #5, but with ignoreMetadata=false or omitted.

Expected Result:

• identical: false
• differences should show changes to id, owner, created, modified fields
• summary.modified: 4 (one for each metadata field)

---

Test #7: Layer Reordering (ID-based comparison)

Purpose: Verify that layers are compared by ID, not array position

Prompt to Claude:
Compare these styles where layers are in different order:

Style A:

  {
    "version": 8,
    "name": "Test",
    "sources": {"mapbox-streets": {"type": "vector", "url": "mapbox://mapbox.mapbox-streets-v8"}},
    "layers": [
      {"id": "water", "type": "fill", "source": "mapbox-streets", "source-layer": "water", "paint": {"fill-color": "#a0c8f0"}},
      {"id": "background", "type": "background", "paint": {"background-color": "#fff"}}
    ]
  }

Style B:

  {
    "version": 8,
    "name": "Test",
    "sources": {"mapbox-streets": {"type": "vector", "url": "mapbox://mapbox.mapbox-streets-v8"}},
    "layers": [
      {"id": "background", "type": "background", "paint": {"background-color": "#fff"}},
      {"id": "water", "type": "fill", "source": "mapbox-streets", "source-layer": "water", "paint": {"fill-color": "#a0c8f0"}}
    ]
  }

Expected Result:

• identical: true (layers are the same, just reordered)
• OR if order matters, should show modifications to layer positions

---

Related PRs

Part of the offline validation tools initiative:

• Add validate_style_tool for offline Mapbox style validation #49 - validate_style_tool (merged)
• Add validate_geojson_tool for offline GeoJSON validation #50 - validate_geojson_tool (in review)
• Add validate_expression_tool for Mapbox expression validation #51 - validate_expression_tool (in review)
• This PR - compare_styles_tool