Initial Commit
This commit is contained in:
217
openspec/changes/enterprise-geo/proposal.md
Normal file
217
openspec/changes/enterprise-geo/proposal.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# 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`.
|
||||
78
openspec/changes/enterprise-geo/tasks.md
Normal file
78
openspec/changes/enterprise-geo/tasks.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# Tasks: enterprise-geo
|
||||
|
||||
**Change ID**: enterprise-geo
|
||||
**Package**: `@suaveplan/geo`
|
||||
**Target path**: `universal/geo/geo`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create `universal/geo/geo/` with `src/`, `tests/`, `src/__benchmarks__/` and all feature subdirectories per the layout in `proposal.md`.
|
||||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, correct `exports` map, `dependencies`, and `devDependencies`.
|
||||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types + errors
|
||||
|
||||
- [ ] `src/types/common.ts` — `LatLng`, `LatLngAlt`, `BoundingBox`, `GeocodeAdapter` (interface), `GeocodeResult`, `AddressComponents`, `GeocodeOptions`, `ReverseGeocodeOptions`, `CacheOptions`, `SearchOptions`.
|
||||
- [ ] `src/types/common.md` (≥200 words, both examples, API reference).
|
||||
- [ ] `src/error-codes.ts` — `GeoErrorCode` (6 codes), metadata, register, eager call.
|
||||
- [ ] `src/constants/index.ts` — `EARTH_RADIUS_M = 6_371_000`, `DEG_TO_RAD = Math.PI / 180`.
|
||||
- [ ] `src/types/schemas.ts` + `schemas.md` — Zod schemas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Core modules
|
||||
|
||||
- [ ] **`src/distance/haversine/`** — `haversineDistance(a, b): number`: validates coordinates (throws `GEO_INVALID_COORDINATE` if out of range), applies Haversine formula. `bearing(from, to)`, `midpoint(a, b)`, `destination(from, bearing, distanceM)`. Tests: London→Paris distance ≈138 000 m ±100 m, same point = 0, antipodal ~20 000 000 m, bearing N/E/S/W, midpoint symmetric.
|
||||
- [ ] **`src/distance/vincenty/`** — `vincentyDistance(a, b): number`: Vincenty direct formula for more accurate long-distance calculation; degrades to Haversine for antipodal inputs. Tests: same reference cities as haversine; compare to Haversine — should differ by < 1% for ≤500 km, potentially more for longer.
|
||||
- [ ] **`src/geometry/bounding-box/`** — `boundingBoxFromPoints`, `expandBoundingBox`, `boundingBoxesIntersect`, `pointInBoundingBox`. Tests: single point, two-point expansion, crossing antimeridian (handled by clamping), intersect/disjoint, point on edge.
|
||||
- [ ] **`src/geometry/polygon/`** — `polygonArea(ring)`, `pointInPolygon(point, ring)`. Tests: unit square area = 1 m² (approx), large polygon, point inside/outside/on edge (treated as inside), concave polygon.
|
||||
- [ ] **`src/geometry/geojson/`** — `toGeoJsonPoint`, `toGeoJsonLineString`, `toGeoJsonPolygon`, `fromGeoJsonPoint`. Tests: round-trip, valid GeoJSON output.
|
||||
- [ ] **`src/clustering/grid-cluster/`** — `gridCluster(points, cellSizeMetres)`: buckets points by grid cell; returns array of clusters (each cluster = array of points). Tests: all same cell → 1 cluster, scattered → N clusters, cell size covers all → 1 cluster.
|
||||
- [ ] **`src/clustering/kmeans-cluster/`** — `kMeansCluster(points, k, maxIterations)`: standard k-means with random initialisation (seeded via injectable RNG for tests), Haversine distance metric. Tests: k=1 returns all in one cluster, k=N with N distinct points returns N clusters, convergence within maxIterations.
|
||||
- [ ] **`src/geocoding/geocode-adapter/`** — `GeocodeAdapter` interface + `GeocodeResult` type + Zod schemas.
|
||||
- [ ] **`src/geocoding/cached-geocode/`** — `createCachedGeocodeAdapter(inner, options)`: LRU cache (Map with insertion-order eviction, size limit). Tests: cache hit on second call, cache miss calls inner, TTL expiry triggers re-fetch.
|
||||
|
||||
---
|
||||
|
||||
## 4. OTel instrumentation
|
||||
|
||||
- [ ] Span `geo.geocode` with attribute `geo.provider`; counter `geo.geocode_total`; histogram `geo.geocode_duration_ms`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Property-based tests (`tests/property.test.ts`)
|
||||
|
||||
- [ ] Distance symmetry: `haversineDistance(a, b) === haversineDistance(b, a)` for arbitrary valid coordinates.
|
||||
- [ ] Bounding-box expansion monotonicity: `expandBoundingBox(box, d)` ⊇ `expandBoundingBox(box, d-1)` for all d > 0.
|
||||
- [ ] Point-in-polygon consistency: `pointInPolygon(p, ring)` is consistent with winding direction for arbitrary convex polygons.
|
||||
|
||||
---
|
||||
|
||||
## 6. Benchmarks (`src/__benchmarks__/geo.bench.ts`)
|
||||
|
||||
- [ ] `haversineDistance` 1 000 000 calls.
|
||||
- [ ] `gridCluster` for 10 000 random points.
|
||||
- [ ] `pointInPolygon` for a 100-vertex polygon 100 000 calls.
|
||||
|
||||
---
|
||||
|
||||
## 7. Docs + verify
|
||||
|
||||
- [ ] One `.md` per implementation file (≥200 words, both examples, API reference). Root `README.md`.
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/geo` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/geo` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/geo`.
|
||||
- [ ] Archive: `openspec/archive/2026-04-24-enterprise-geo/`.
|
||||
Reference in New Issue
Block a user