Web Maps skill for Claude Code

#!/usr/bin/env python3
"""Audit a GeoJSON file before putting it on a web map.

Usage:
  python3 geojson_audit.py <file.geojson> [--precision 6] [--expect minLng,minLat,maxLng,maxLat]

--expect is the bbox the data should fall in (e.g. a country). In-range but
swapped [lat, lng] pairs are only detectable against an expected area.

Reports feature counts, bbox, swapped or out-of-range coordinates, coordinate
precision (and bytes saved by trimming), unclosed and mis-wound polygon rings,
null geometries, missing feature ids, and size-based delivery advice.
Exits 1 if any ERROR is found.
"""
import argparse
import json
import re
import sys
from collections import Counter
from pathlib import Path


def iter_positions(geom):
    t, c = geom.get("type"), geom.get("coordinates")
    if t == "Point":
        yield c
    elif t in ("MultiPoint", "LineString"):
        yield from c
    elif t in ("MultiLineString", "Polygon"):
        for part in c:
            yield from part
    elif t == "MultiPolygon":
        for poly in c:
            for ring in poly:
                yield from ring
    elif t == "GeometryCollection":
        for g in geom.get("geometries", []):
            yield from iter_positions(g)


def iter_rings(geom):
    t, c = geom.get("type"), geom.get("coordinates")
    if t == "Polygon":
        for i, ring in enumerate(c):
            yield i == 0, ring
    elif t == "MultiPolygon":
        for poly in c:
            for i, ring in enumerate(poly):
                yield i == 0, ring
    elif t == "GeometryCollection":
        for g in geom.get("geometries", []):
            yield from iter_rings(g)


def signed_area(ring):
    s = 0.0
    for (x1, y1, *_), (x2, y2, *_) in zip(ring, ring[1:]):
        s += x1 * y2 - x2 * y1
    return s / 2


def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("file", type=Path)
    ap.add_argument("--precision", type=int, default=6, help="target decimal places (default 6, ~0.1 m)")
    ap.add_argument("--expect", help="expected bbox minLng,minLat,maxLng,maxLat")
    a = ap.parse_args()

    errors, warns = [], []
    expect = None
    if a.expect:
        try:
            expect = [float(v) for v in a.expect.split(",")]
            assert len(expect) == 4
        except (ValueError, AssertionError):
            print("ERROR  --expect must be minLng,minLat,maxLng,maxLat")
            sys.exit(1)
    outside_expect = swapped_inside = 0
    try:
        raw = a.file.read_text(encoding="utf-8")
        data = json.loads(raw)
    except (OSError, json.JSONDecodeError, UnicodeDecodeError) as e:
        print(f"ERROR  cannot read GeoJSON: {e}")
        sys.exit(1)
    size = len(raw.encode("utf-8"))

    if data.get("type") == "FeatureCollection":
        features = data.get("features", [])
    elif data.get("type") == "Feature":
        features = [data]
    elif "coordinates" in data or data.get("type") == "GeometryCollection":
        features = [{"type": "Feature", "geometry": data, "properties": {}}]
    else:
        print("ERROR  not a GeoJSON object (no FeatureCollection/Feature/geometry type)")
        sys.exit(1)
    if "crs" in data:
        warns.append("top-level 'crs' member found: RFC 7946 GeoJSON must be WGS84 lon/lat; reproject if this is not EPSG:4326")

    types = Counter()
    null_geoms = missing_id = string_coords = 0
    out_of_range = swapped_hint = 0
    total_pos = 0
    max_dp = 0
    excess_chars = 0
    minx = miny = float("inf")
    maxx = maxy = float("-inf")
    unclosed = bad_winding = 0

    for f in features:
        g = f.get("geometry")
        if f.get("id") is None and not (f.get("properties") or {}).get("id"):
            missing_id += 1
        if not g:
            null_geoms += 1
            continue
        types[g.get("type")] += 1
        for pos in iter_positions(g):
            total_pos += 1
            if len(pos) < 2:
                errors.append(f"position with fewer than 2 values: {pos}")
                continue
            x, y = pos[0], pos[1]
            if isinstance(x, str) or isinstance(y, str):
                string_coords += 1
                continue
            minx, maxx, miny, maxy = min(minx, x), max(maxx, x), min(miny, y), max(maxy, y)
            if expect:
                inside = lambda lx, ly: expect[0] <= lx <= expect[2] and expect[1] <= ly <= expect[3]
                if not inside(x, y):
                    outside_expect += 1
                    if inside(y, x):
                        swapped_inside += 1
            if not (-180 <= x <= 180 and -90 <= y <= 90):
                out_of_range += 1
                if -90 <= x <= 90 and -180 <= y <= 180:
                    swapped_hint += 1
            for v in (x, y):
                r = repr(float(v))
                m = re.search(r"\.(\d+)$", r)
                if m:
                    dp = len(m.group(1))
                    max_dp = max(max_dp, dp)
                    if dp > a.precision:
                        excess_chars += dp - a.precision
        for exterior, ring in iter_rings(g):
            if len(ring) < 4 or ring[0][:2] != ring[-1][:2]:
                unclosed += 1
                continue
            area = signed_area(ring)
            # RFC 7946: exterior counterclockwise (positive), holes clockwise (negative)
            if (exterior and area < 0) or (not exterior and area > 0):
                bad_winding += 1

    n = len(features)
    print(f"File       {a.file}  ({size / 1024:.1f} KB)")
    print(f"Features   {n}  " + ", ".join(f"{t}: {c}" for t, c in types.most_common()))
    print(f"Positions  {total_pos}")
    if total_pos and minx != float("inf"):
        print(f"BBox       [{minx:.5f}, {miny:.5f}, {maxx:.5f}, {maxy:.5f}]  (lng/lat)")
    print(f"Precision  max {max_dp} decimal places")

    if string_coords:
        errors.append(f"{string_coords} positions have string coordinates — parse to numbers")
    if out_of_range:
        msg = f"{out_of_range} positions outside lon [-180,180] / lat [-90,90]"
        if swapped_hint == out_of_range:
            msg += " — all would be valid if swapped: coordinates are probably [lat, lng]; GeoJSON needs [lng, lat]"
        elif abs(minx) > 1000 or abs(maxx) > 1000:
            msg += " — values look like projected meters (e.g. EPSG:3857); reproject to EPSG:4326"
        errors.append(msg)
    if expect and outside_expect:
        if swapped_inside == outside_expect:
            errors.append(f"{outside_expect} positions fall outside --expect but inside it when swapped: coordinates are [lat, lng]; GeoJSON needs [lng, lat]")
        else:
            errors.append(f"{outside_expect} positions fall outside the expected bbox ({swapped_inside} would fit if swapped)")
    if unclosed:
        errors.append(f"{unclosed} polygon rings are unclosed or have fewer than 4 positions")
    if bad_winding:
        warns.append(f"{bad_winding} rings violate RFC 7946 winding (exterior CCW, holes CW); most renderers cope, some tools do not")
    if null_geoms:
        warns.append(f"{null_geoms} features have null geometry and will not render")
    if missing_id and n:
        warns.append(f"{missing_id}/{n} features lack an id — feature-state hover/selection needs id, promoteId or generateId")
    if excess_chars:
        saved = excess_chars  # one byte per trimmed digit (ASCII)
        warns.append(f"trimming to {a.precision} dp saves ~{saved / 1024:.1f} KB ({saved / size:.0%} of file)")

    points = types.get("Point", 0) + types.get("MultiPoint", 0)
    if size > 5 * 1024 * 1024 or points > 50_000:
        warns.append("large dataset: build vector tiles (tippecanoe → PMTiles) instead of shipping raw GeoJSON")
    elif points > 500:
        warns.append(f"{points} points: render as a GeoJSON layer with clustering, not DOM markers")
    elif size > 1024 * 1024:
        warns.append("over 1 MB: serve gzip/brotli compressed and consider simplifying geometry (mapshaper)")

    print()
    for w in warns:
        print(f"WARN   {w}")
    for e in errors:
        print(f"ERROR  {e}")
    print(f"\n{len(errors)} error(s), {len(warns)} warning(s)")
    sys.exit(1 if errors else 0)


if __name__ == "__main__":
    main()