@myrobotaxi/contracts 0.3.0 → 0.4.0

package/CONTRIBUTING.md

@@ -11,8 +11,8 @@ This means any schema change requires:
 1. Open a PR in [`myrobotaxi/telemetry`](https://github.com/myrobotaxi/telemetry) that edits the source `.schema.json` file under `docs/contracts/schemas/`. Get it reviewed and merged.
 2. Open a paired PR in this repo that:
    - Copies the new schema file from the telemetry repo into `schemas/`
-   - Runs `npm run codegen` to regenerate `src/generated/`
-   - Commits the regenerated `.ts` files
+   - Runs `npm run codegen` to regenerate `src/generated/` and `npm run codegen:swift` to regenerate `Sources/MyRobotaxiContracts/Generated/`
+   - Commits the regenerated `.ts` and `.swift` files
    - Bumps the version per the [versioning policy](#versioning-policy)
 
 Until [Phase 2](#phase-2-migration-authoring-home) ships, this paired-PR convention is enforced by review (no automation).
@@ -40,9 +40,20 @@ The MyRoboTaxi schemas use these non-standard keywords:
 | `x-encrypted` / `x-encrypted-at-rest` | AES-256-GCM at rest |
 | `x-tesla-proto-field` | Source Tesla protobuf field number |
 
-The codegen pipeline (`scripts/codegen.mjs`) **folds these into TSDoc comments** at generation time, so they survive into the consumer's editor as `@classification "P0"` annotations.
+The codegen pipeline (`scripts/codegen.mjs`) **folds these into TSDoc comments** at generation time, so they survive into the consumer's editor as `@classification "P0"` annotations. The Swift pipeline (`scripts/codegen-swift.mjs`) does the same folding into SwiftDoc (`///`) comments.
 
-If you add a new `x-*` keyword to a schema, add it to the `ANNOTATIONS` array in `scripts/codegen.mjs` and re-run `npm run codegen`.
+If you add a new `x-*` keyword to a schema, add it to the `ANNOTATIONS` array in **both** `scripts/codegen.mjs` and `scripts/codegen-swift.mjs`, then re-run `npm run codegen` and `npm run codegen:swift`.
+
+## Swift codegen pipeline
+
+The repo doubles as a Swift package (`Package.swift` at the root, product `MyRobotaxiContracts`). Swift types are generated from the same `schemas/*.json` source of truth:
+
+- **Generator**: `scripts/codegen-swift.mjs` — a small custom Node script (zero npm dependencies; runs without `npm ci`). One `Codable`/`Equatable`/`Sendable` struct per root schema object and per `$defs` entry (websocket-protocol.md §9.2); string enums become Swift `enum ...: String` with wire raw values.
+- **Output**: `Sources/MyRobotaxiContracts/Generated/*.swift` — **committed**, never hand-edited (same rule as `src/generated/`). Regeneration is deterministic: emission order follows the schema JSON, so re-running on an unchanged schema is a no-op diff.
+- **Hand-written support code**: `Sources/MyRobotaxiContracts/JSONValue.swift` (arbitrary-JSON enum used for `WebSocketEnvelope.payload` and `VehicleUpdatePayload.fields`) is NOT generated and may be edited.
+- **Regenerate**: `npm run codegen:swift` after any schema change, and commit the result alongside the regenerated TypeScript.
+- **CI**: the `swift` job on `macos-latest` runs `swift build`, `swift test`, then `npm run codegen:swift` and fails on drift in `Sources/MyRobotaxiContracts/Generated/` — mirroring the TypeScript `codegen-drift` job.
+- **Consumption**: Swift consumers resolve the package by git URL + tag (`from: "0.x.y"`); there is no Swift registry publish. The `v0.x.y` git tags pushed for npm releases are also what SwiftPM resolves against, so the versioning policy above applies to the Swift surface too.
 
 ## Release process
 

package/README.md

@@ -28,7 +28,7 @@ import { schemas } from '@myrobotaxi/contracts';
 // schemas.vehicleState, schemas.wsMessages, schemas.wsEnvelope
 ```
 
-Raw JSON for non-JS consumers (Go, Swift):
+Raw JSON for non-JS consumers (Go):
 
 ```
 ./node_modules/@myrobotaxi/contracts/schemas/vehicle-state.schema.json
@@ -36,6 +36,40 @@ Raw JSON for non-JS consumers (Go, Swift):
 ./node_modules/@myrobotaxi/contracts/schemas/ws-envelope.schema.json
 ```
 
+## Swift
+
+This repo is also a Swift package (`MyRobotaxiContracts`) with **pre-generated `Codable`/`Sendable` structs** under `Sources/MyRobotaxiContracts/Generated/` — produced by `scripts/codegen-swift.mjs` and committed for diff review, exactly like the TypeScript types. Swift consumers resolve by git URL + semver tag (no registry publish).
+
+In your `Package.swift`:
+
+```swift
+dependencies: [
+  .package(url: "https://github.com/myrobotaxi/contracts.git", from: "0.4.0")
+],
+targets: [
+  .target(
+    name: "MyApp",
+    dependencies: [.product(name: "MyRobotaxiContracts", package: "contracts")]
+  )
+]
+```
+
+Usage:
+
+```swift
+import MyRobotaxiContracts
+
+let state = try JSONDecoder().decode(VehicleState.self, from: snapshotData)
+let envelope = try JSONDecoder().decode(WebSocketEnvelope.self, from: frameData)
+if envelope.type == .vehicleUpdate { /* decode VehicleUpdatePayload from envelope.payload */ }
+```
+
+The same custom annotations are folded into the generated SwiftDoc comments, so `grep '@classification "P1"'` works inside the checked-out package too. Wire enums (`status`, `chargeState`, `MessageType`, error codes, …) generate as Swift `enum ...: String` with wire raw values; nullable / non-required schema fields are Swift optionals. The intentionally-open wire positions — `WebSocketEnvelope.payload` and `VehicleUpdatePayload.fields` — are typed via the hand-written `JSONValue` enum, which preserves explicit JSON `null`s (required for atomic-group clears per NFR-3.9).
+
+## Tool choice (Swift): custom generator
+
+Like the TypeScript side, the Swift generator is a small custom script (`scripts/codegen-swift.mjs`, no `quicktype`): it keeps the annotation-folding grep affordance, emits exactly one type per root schema and per `$defs` entry (websocket-protocol.md §9.2), needs no npm install (zero dependencies), and is deterministic so CI can diff the committed output.
+
 ## What's in the generated TypeScript
 
 Custom JSON Schema annotations from the source schemas — `x-classification`, `x-atomic-group`, `x-unit`, `x-encrypted`, `x-tesla-proto-field` — are folded into the generated TSDoc comments at codegen time. This means consumers can `grep '@classification "P1"'` inside their `node_modules` to find every sensitive field without leaving their editor.
@@ -82,12 +116,16 @@ A planned follow-up moves the schema authoring home from `telemetry/docs/contrac
 ```bash
 npm install
 npm run codegen        # regenerate src/generated/ from schemas/
+npm run codegen:swift  # regenerate Sources/MyRobotaxiContracts/Generated/ from schemas/
 npm run typecheck
 npm run test
 npm run build          # tsup → dist/
+
+swift build            # Swift package
+swift test
 ```
 
-CI runs `codegen` and fails if `src/generated/` drifts from the schemas — every schema bump must be paired with a regenerate-and-commit.
+CI runs both codegens and fails if `src/generated/` or `Sources/MyRobotaxiContracts/Generated/` drifts from the schemas — every schema bump must be paired with a regenerate-and-commit (both languages).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myrobotaxi/contracts",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Canonical wire-protocol schemas for the MyRoboTaxi platform. JSON Schema (draft-2020-12) + pre-generated TypeScript types. Consumed by SDKs (TS, Swift) and the Go telemetry server.",
   "license": "MIT",
   "repository": {
@@ -52,6 +52,7 @@
   ],
   "scripts": {
     "codegen": "node scripts/codegen.mjs",
+    "codegen:swift": "node scripts/codegen-swift.mjs",
     "build": "tsup",
     "clean": "rm -rf dist coverage",
     "lint": "eslint .",