218 lines
6.2 KiB
Markdown
218 lines
6.2 KiB
Markdown
# OpenSpec Change: enterprise-geo
|
||
|
||
- **Change ID**: enterprise-geo
|
||
- **Package**: `@suaveplan/geo`
|
||
- **Category**: universal
|
||
- **Target path**: `universal/geo/geo`
|
||
- **Status**: IN PROGRESS
|
||
- **Date**: 2026-04-24
|
||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/geo.md`
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
Deliver `@suaveplan/geo` on the genesis branch from scratch at enterprise quality. The package provides geolocation and geospatial utilities: WGS84 coordinate types, Haversine / Vincenty distance calculation, bearing and midpoint computation, bounding-box construction and intersection, GeoJSON feature/geometry construction helpers, point-in-polygon (ray-casting), polygon area calculation, clustering helpers (k-means, grid), geocoding adapter interface with in-memory cache, reverse-geocoding adapter interface, and elevation lookup interface. The main-branch version sat at 99.38% coverage. Genesis adds structured errors, Zod schemas, OTel instrumentation, and property-based tests.
|
||
|
||
---
|
||
|
||
## Current-state audit (genesis)
|
||
|
||
The package does not exist on genesis yet — this is a fresh build.
|
||
|
||
---
|
||
|
||
## Available workspace deps on genesis
|
||
|
||
| Package | Role |
|
||
|---|---|
|
||
| `@suaveplan/error` (`workspace:^`) | `GeoError`; `GEO.*` error codes |
|
||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` |
|
||
| `@suaveplan/retry` (`workspace:^`) | Retry for geocoding adapter network calls |
|
||
| `zod` (`catalog:forms`) | Schema validation |
|
||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||
|
||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).
|
||
|
||
---
|
||
|
||
## Public API surface
|
||
|
||
### Coordinate types
|
||
|
||
```ts
|
||
interface LatLng {
|
||
lat: number // degrees, -90 to 90
|
||
lng: number // degrees, -180 to 180
|
||
}
|
||
|
||
interface LatLngAlt extends LatLng {
|
||
alt?: number // metres above sea level
|
||
}
|
||
|
||
interface BoundingBox {
|
||
north: number
|
||
south: number
|
||
east: number
|
||
west: number
|
||
}
|
||
```
|
||
|
||
### Distance and geometry
|
||
|
||
```ts
|
||
function haversineDistance(a: LatLng, b: LatLng): number // metres
|
||
function vincentyDistance(a: LatLng, b: LatLng): number // metres (more accurate)
|
||
function bearing(from: LatLng, to: LatLng): number // degrees 0–360
|
||
function midpoint(a: LatLng, b: LatLng): LatLng
|
||
function destination(from: LatLng, bearing: number, distance: number): LatLng
|
||
function boundingBoxFromPoints(points: LatLng[]): BoundingBox
|
||
function expandBoundingBox(box: BoundingBox, metres: number): BoundingBox
|
||
function boundingBoxesIntersect(a: BoundingBox, b: BoundingBox): boolean
|
||
function pointInBoundingBox(point: LatLng, box: BoundingBox): boolean
|
||
```
|
||
|
||
### GeoJSON helpers
|
||
|
||
```ts
|
||
function toGeoJsonPoint(point: LatLng): GeoJSON.Point
|
||
function toGeoJsonLineString(points: LatLng[]): GeoJSON.LineString
|
||
function toGeoJsonPolygon(rings: LatLng[][]): GeoJSON.Polygon
|
||
function fromGeoJsonPoint(point: GeoJSON.Point): LatLng
|
||
function polygonArea(ring: LatLng[]): number // square metres (shoelace + WGS84 correction)
|
||
function pointInPolygon(point: LatLng, ring: LatLng[]): boolean // ray-casting
|
||
```
|
||
|
||
### Clustering
|
||
|
||
```ts
|
||
function gridCluster(points: LatLng[], cellSizeMetres: number): LatLng[][]
|
||
function kMeansCluster(points: LatLng[], k: number, maxIterations?: number): LatLng[][]
|
||
```
|
||
|
||
### Adapter interfaces
|
||
|
||
```ts
|
||
interface GeocodeAdapter {
|
||
geocode(address: string, options?: GeocodeOptions): Promise<GeocodeResult[]>
|
||
reverseGeocode(point: LatLng, options?: ReverseGeocodeOptions): Promise<GeocodeResult>
|
||
}
|
||
|
||
interface GeocodeResult {
|
||
address: string
|
||
point: LatLng
|
||
confidence: number // 0–1
|
||
components: AddressComponents
|
||
}
|
||
|
||
function createCachedGeocodeAdapter(
|
||
inner: GeocodeAdapter,
|
||
options?: CacheOptions
|
||
): GeocodeAdapter
|
||
```
|
||
|
||
### Error codes
|
||
|
||
```ts
|
||
type GeoErrorCode =
|
||
| 'GEO_INVALID_COORDINATE'
|
||
| 'GEO_INVALID_POLYGON'
|
||
| 'GEO_GEOCODE_FAILED'
|
||
| 'GEO_REVERSE_GEOCODE_FAILED'
|
||
| 'GEO_CLUSTER_FAILED'
|
||
| 'GEO_ABORTED'
|
||
```
|
||
|
||
---
|
||
|
||
## Genesis additions
|
||
|
||
1. **`GeoError`** extends `SuaveplanError` with six stable codes.
|
||
2. **Zod schemas** for `LatLng`, `LatLngAlt`, `BoundingBox`, `GeocodeResult`, `AddressComponents`, `GeocodeOptions`.
|
||
3. **Vincenty distance** — more accurate than Haversine for long distances; falls back to Haversine for antipodal/degenerate inputs.
|
||
4. **Cached geocode adapter** — wraps any `GeocodeAdapter` with an in-memory LRU cache (default 1 000 entries, TTL 1 hour).
|
||
5. **OTel instrumentation** — span `geo.geocode` with attribute `geo.provider`; counter `geo.geocode_total`; histogram `geo.geocode_duration_ms`.
|
||
6. **Property-based tests** — distance symmetry: `haversineDistance(a,b) === haversineDistance(b,a)`; bounding-box expansion monotonicity; point-in-polygon edge cases (point on edge, winding direction).
|
||
|
||
---
|
||
|
||
## File layout
|
||
|
||
```text
|
||
universal/geo/geo/
|
||
package.json
|
||
tsconfig.json
|
||
vitest.config.ts
|
||
src/
|
||
index.ts
|
||
error-codes.ts
|
||
constants/
|
||
index.ts # EARTH_RADIUS_M, DEG_TO_RAD
|
||
types/
|
||
common.ts
|
||
common.md
|
||
distance/
|
||
haversine/
|
||
haversine.ts
|
||
haversine.md
|
||
haversine.test.ts
|
||
index.ts
|
||
vincenty/
|
||
vincenty.ts
|
||
vincenty.md
|
||
vincenty.test.ts
|
||
index.ts
|
||
geometry/
|
||
bounding-box/
|
||
bounding-box.ts
|
||
bounding-box.md
|
||
bounding-box.test.ts
|
||
index.ts
|
||
polygon/
|
||
polygon.ts
|
||
polygon.md
|
||
polygon.test.ts
|
||
index.ts
|
||
geojson/
|
||
geojson.ts
|
||
geojson.md
|
||
geojson.test.ts
|
||
index.ts
|
||
clustering/
|
||
grid-cluster/
|
||
grid-cluster.ts
|
||
grid-cluster.md
|
||
grid-cluster.test.ts
|
||
index.ts
|
||
kmeans-cluster/
|
||
kmeans-cluster.ts
|
||
kmeans-cluster.md
|
||
kmeans-cluster.test.ts
|
||
index.ts
|
||
geocoding/
|
||
geocode-adapter/
|
||
geocode-adapter.ts
|
||
geocode-adapter.md
|
||
geocode-adapter.types.ts
|
||
geocode-adapter.test.ts
|
||
index.ts
|
||
cached-geocode/
|
||
cached-geocode.ts
|
||
cached-geocode.md
|
||
cached-geocode.test.ts
|
||
index.ts
|
||
__benchmarks__/
|
||
geo.bench.ts
|
||
tests/
|
||
integration.test.ts
|
||
property.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
## Impact
|
||
|
||
**Downstream consumers**: `@suaveplan/ports`, `@suaveplan/tides`, `@suaveplan/heightmap-tiles`, `@suaveplan/osm-buildings`.
|
||
|
||
**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`.
|