Add validate_expression_tool for Mapbox expression validation

[mattpodwysocki]

Summary

Adds a comprehensive offline Mapbox expression validation tool that checks style expressions for correctness without requiring API access.

Features

• ✅ Validates 90+ Mapbox expression operators:

  • Decision: case, match, coalesce
  • Lookup: get, has, in, index-of, length, slice
  • Math: +, -, *, /, %, ^, min, max, round, floor, ceil, abs, sqrt, log10, log2, ln, e, pi
  • Comparison: ==, !=, >, <, >=, <=
  • Logical: !, all, any
  • String: concat, downcase, upcase
  • Color: rgb, rgba, to-rgba
  • Type conversion: array, boolean, number, string, to-boolean, to-color, to-number, to-string, typeof
  • Interpolation: interpolate, step
  • Feature data: get, has, feature-state, geometry-type, id, properties
  • Camera: zoom, pitch, distance-from-center
  • Variable binding: let, var

• ✅ Comprehensive validation checks:

  • Expression syntax (array format, string operators)
  • Operator validity
  • Argument count validation for each operator
  • Recursive validation of nested expressions
  • Expression depth analysis (warns about deeply nested expressions)

• ✅ Structured validation results:

  • valid boolean flag
  • errors array (critical issues)
  • warnings array (non-critical issues like deep nesting)
  • info array (informational messages)
  • metadata object (expressionType, returnType, depth)

• ✅ Developer-friendly:

  • Detailed error messages with expression paths
  • Actionable suggestions for fixing issues
  • Accepts both JSON strings and expression arrays as input

Implementation Details

• Architecture: Extends BaseTool (offline, no HttpRequest dependency)
• Testing: 25 comprehensive test cases covering:
  • Literal expressions (strings, numbers, booleans)
  • Valid expressions (all operator categories)
  • Invalid expressions (syntax errors, unknown operators, wrong argument counts)
  • Nested expressions
  • Error handling
  • Metadata validation
• Documentation: Added to README with examples and usage patterns

Test Results

All 395 tests pass ✅

Example Usage

{
  "expression": ["case", ["==", ["get", "type"], "park"], "green", "gray"]
}

Returns:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "info": [],
  "metadata": {
    "expressionType": "case",
    "depth": 1
  }
}

Error Example

{
  "expression": ["unknown_operator", "value"]
}

Returns:

{
  "valid": false,
  "errors": [
    {
      "severity": "error",
      "message": "Unknown expression operator: \"unknown_operator\"",
      "path": "[0]",
      "suggestion": "Use a valid Mapbox expression operator (e.g., \"get\", \"case\", \"match\")"
    }
  ]
}

Testing

---

Test 1: Valid Simple Expression ✅

Validate this Mapbox expression:

  ["get", "name"]

Expected: Valid - gets the "name" property from a feature

---

Test 2: Valid Conditional Expression ✅

Can you validate this expression?

  ["case",
    ["==", ["get", "type"], "park"], "green",
    ["==", ["get", "type"], "water"], "blue",
    "gray"
  ]

Expected: Valid - conditional styling based on feature type

---

Test 3: Valid Math Expression ✅

Validate this:

  ["*", ["get", "population"], 0.001]

Expected: Valid - multiplies population by 0.001

---

Test 4: Invalid Operator ❌

Check this expression:

  ["unknown_operator", "value"]

Expected:

• Invalid
• Error: Unknown expression operator "unknown_operator"
• Suggestion: Use valid operators like "get", "case", "match"

---

Test 5: Wrong Argument Count ❌

Is this valid?

  ["get"]

Expected:

• Invalid
• Error: Operator "get" requires at least 1 argument, got 0
• Suggestion: "get" expects arguments like ["get", "propertyName"]

---

Test 6: Valid Interpolation Expression ✅

Validate this interpolation:

  ["interpolate",
    "linear",
    ["zoom"],
    10, 1,
    15, 5,
    20, 10
  ]

Expected: Valid - interpolates circle radius based on zoom level

---

Test 7: Nested Expression with Error ❌

Check this nested expression:

  ["case",
    ["bad_operator", ["get", "type"]],
    "red",
    "blue"
  ]

Expected:

• Invalid
• Error: Unknown operator "bad_operator" in nested expression
• Shows path to where the error occurs

---

Test 8: Valid String Expression ✅

Validate:

  ["concat", "Street: ", ["get", "street_name"]]

Expected: Valid - concatenates strings for labels

---

Test 9: Valid Color Expression ✅

Is this valid?

  ["rgb", 255, 100, 50]

Expected: Valid - creates RGB color

---

Test 10: Complex Valid Expression ✅

Validate this complex expression:

  ["interpolate",
    ["exponential", 1.5],
    ["get", "population"],
    0, ["rgb", 255, 255, 178],
    100000, ["rgb", 254, 204, 92],
    1000000, ["rgb", 253, 141, 60],
    10000000, ["rgb", 227, 26, 28]
  ]

Expected: Valid - data-driven color based on population with exponential interpolation

Related

Part of a series of offline validation tools being added to the server:

• 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)
• This PR: validate_expression_tool